initial commit

examples/example_test.go

@@ -0,0 +1,189 @@
+package examples
+
+import (
+	"fmt"
+	"log"
+	"time"
+
+	"git.haelnorr.com/h/timefmt"
+)
+
+// Example demonstrating basic usage of the builder
+func Example_basic() {
+	format := timefmt.NewBuilder().
+		Year4().Dash().
+		MonthNumeric2().Dash().
+		DayNumeric2().
+		Build()
+
+	fmt.Println("Go format:", format.GoFormat())
+	fmt.Println("LDML:", format.LDML())
+	fmt.Println("Description:", format.Description())
+
+	// Output:
+	// Go format: 2006-01-02
+	// LDML: yyyy-MM-dd
+	// Description: Year (4-digit), dash, Month (2-digit), dash, Day (2-digit)
+}
+
+// Example showing how to use pre-built formats
+func Example_prebuilt() {
+	now := time.Date(2026, time.February, 8, 15, 4, 5, 0, time.UTC)
+
+	fmt.Println("ISO8601:", timefmt.ISO8601.Format(now))
+	fmt.Println("DateOnly:", timefmt.DateOnly.Format(now))
+	fmt.Println("DateTime:", timefmt.DateTime.Format(now))
+	fmt.Println("DateUS:", timefmt.DateUS.Format(now))
+	fmt.Println("Kitchen:", timefmt.Kitchen.Format(now))
+
+	// Output:
+	// ISO8601: 2026-02-08T15:04:05Z
+	// DateOnly: 2026-02-08
+	// DateTime: 2026-02-08 15:04:05
+	// DateUS: 02/08/2026
+	// Kitchen: 3:04 PM
+}
+
+// Example parsing an existing Go format string
+func Example_parsing() {
+	format, err := timefmt.ParseGoFormat("02/01/2006 15:04:05")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println("LDML:", format.LDML())
+	fmt.Println("Description:", format.Description())
+
+	// Output:
+	// LDML: dd/MM/yyyy HH:mm:ss
+	// Description: Day (2-digit), slash, Month (2-digit), slash, Year (4-digit), space, Hour (24-hour, 2-digit), colon, Minute (2-digit), colon, Second (2-digit)
+}
+
+// Example creating a complex custom format
+func Example_complex() {
+	format := timefmt.NewBuilder().
+		WeekdayFull().Comma().
+		MonthFull().Space().
+		DayNumeric().Comma().
+		Year4().Space().
+		Literal("at").Space().
+		Hour12().Colon().
+		Minute().Space().
+		AMPM().
+		Build()
+
+	testTime := time.Date(2026, time.February, 8, 15, 4, 5, 0, time.UTC)
+
+	fmt.Println("Formatted:", format.Format(testTime))
+	fmt.Println("LDML:", format.LDML())
+
+	// Output:
+	// Formatted: Sunday, February 8, 2026 at 3:04 PM
+	// LDML: EEEE, MMMM d, yyyy 'at' h:mm a
+}
+
+// Example showing format conversion for user documentation
+func Example_documentation() {
+	// Imagine this comes from user configuration
+	userFormat := "2006-01-02 15:04:05 MST"
+
+	format, err := timefmt.ParseGoFormat(userFormat)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Display to user
+	fmt.Println("Your timestamp format:")
+	fmt.Printf("  Format: %s\n", format.LDML())
+	fmt.Printf("  Example: %s\n", format.Example())
+	fmt.Println()
+	fmt.Println("Detailed breakdown:")
+	fmt.Printf("  %s\n", format.Description())
+
+	// Output:
+	// Your timestamp format:
+	//   Format: yyyy-MM-dd HH:mm:ss zzz
+	//   Example: 2026-02-08 15:04:05 MST
+	//
+	// Detailed breakdown:
+	//   Year (4-digit), dash, Month (2-digit), dash, Day (2-digit), space, Hour (24-hour, 2-digit), colon, Minute (2-digit), colon, Second (2-digit), space, Timezone abbreviation
+}
+
+// Example using format fragments directly
+func Example_fragments() {
+	// Create a format using fragments directly
+	format := timefmt.NewFormat(
+		timefmt.Year4Digit,
+		"/",
+		timefmt.MonthNumeric2,
+		"/",
+		timefmt.DayNumeric2,
+	)
+
+	fmt.Println("Go format:", format.GoFormat())
+	fmt.Println("LDML:", format.LDML())
+
+	// Output:
+	// Go format: 2006/01/02
+	// LDML: yyyy/MM/dd
+}
+
+// Example for form validation error messages
+func Example_validation() {
+	format := timefmt.DateOnly
+
+	// Simulated user input validation
+	userInput := "02-08-2026" // Wrong format
+	_, err := format.Parse(userInput)
+
+	if err != nil {
+		fmt.Printf("Error: Invalid date format\n")
+		fmt.Printf("Expected: %s\n", format.Description())
+		fmt.Printf("Example: %s\n", format.Example())
+	}
+
+	// Output:
+	// Error: Invalid date format
+	// Expected: Year (4-digit), dash, Month (2-digit), dash, Day (2-digit)
+	// Example: 2026-02-08
+}
+
+// Example showing timezone handling
+func Example_timezone() {
+	format := timefmt.NewBuilder().
+		Year4().Dash().MonthNumeric2().Dash().DayNumeric2().
+		Space().
+		Hour24().Colon().Minute().Colon().Second().
+		Space().
+		TimezoneOffsetColon().
+		Build()
+
+	loc := time.FixedZone("EST", -5*3600)
+	t := time.Date(2026, time.February, 8, 15, 4, 5, 0, loc)
+
+	fmt.Println("Formatted:", format.Format(t))
+	fmt.Println("LDML:", format.LDML())
+
+	// Output:
+	// Formatted: 2026-02-08 15:04:05 -05:00
+	// LDML: yyyy-MM-dd HH:mm:ss ZZZZZ
+}
+
+// Example demonstrating millisecond precision
+func Example_subseconds() {
+	format := timefmt.NewBuilder().
+		Hour24().Colon().
+		Minute().Colon().
+		Second().
+		Millisecond().
+		Build()
+
+	t := time.Date(2026, time.February, 8, 15, 4, 5, 123456789, time.UTC)
+
+	fmt.Println("Formatted:", format.Format(t))
+	fmt.Println("Go format:", format.GoFormat())
+
+	// Output:
+	// Formatted: 15:04:05.123
+	// Go format: 15:04:05.000
+}