initial commit

doc.go

@@ -0,0 +1,86 @@
+// Package timefmt provides tools for building and converting time format strings
+// with human-readable descriptions.
+//
+// It offers a fluent builder API for constructing time formats and can convert
+// between Go's reference time format, LDML (Unicode Locale Data Markup Language)
+// tokens, and plain English descriptions.
+//
+// # Basic Usage
+//
+// Build a time format using the fluent builder:
+//
+//	format := timefmt.NewBuilder().
+//	    Year4().Dash().
+//	    MonthNumeric2().Dash().
+//	    DayNumeric2().
+//	    Build()
+//
+//	fmt.Println(format.GoFormat())      // "2006-01-02"
+//	fmt.Println(format.LDML())          // "yyyy-MM-dd"
+//	fmt.Println(format.Description())   // "Year (4-digit), dash, ..."
+//
+// # Pre-built Formats
+//
+// Common formats are available as package-level constants:
+//
+//	now := time.Now()
+//	fmt.Println(timefmt.ISO8601.Format(now))
+//	fmt.Println(timefmt.DateTime.Format(now))
+//	fmt.Println(timefmt.DateUS.Format(now))
+//
+// # Parsing Existing Formats
+//
+// Parse an existing Go time format string to get human-readable descriptions:
+//
+//	format, err := timefmt.ParseGoFormat("02/01/2006 15:04:05")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//
+//	fmt.Println(format.LDML())         // "dd/MM/yyyy HH:mm:ss"
+//	fmt.Println(format.Description())  // Full English description
+//
+// # Multiple Output Formats
+//
+// Every Format provides three representations:
+//
+//   - GoFormat(): Go's reference time format (e.g., "2006-01-02")
+//   - LDML(): Unicode LDML tokens (e.g., "yyyy-MM-dd")
+//   - Description(): Plain English description
+//
+// This makes it easy to document time formats for both developers and end users.
+//
+// # Use Cases
+//
+// Display format information to users:
+//
+//	format := timefmt.DateOnly
+//	fmt.Printf("Expected format: %s\n", format.Description())
+//	fmt.Printf("Example: %s\n", format.Example())
+//
+// Validate user input with helpful error messages:
+//
+//	if _, err := format.Parse(userInput); err != nil {
+//	    return fmt.Errorf("invalid date. Expected: %s (example: %s)",
+//	        format.Description(), format.Example())
+//	}
+//
+// Generate documentation for configuration:
+//
+//	for name, fmt := range configFormats {
+//	    fmt.Printf("%s: %s (LDML: %s)\n",
+//	        name, fmt.Description(), fmt.LDML())
+//	}
+//
+// # LDML Compatibility
+//
+// The LDML output follows the Unicode LDML standard, making it compatible with:
+//
+//   - ICU (International Components for Unicode)
+//   - Java (SimpleDateFormat, DateTimeFormatter)
+//   - Swift (DateFormatter)
+//   - JavaScript (Moment.js, Day.js, date-fns)
+//   - Most modern date/time libraries
+//
+// This allows seamless integration with systems that use LDML for time formatting.
+package timefmt