87 lines
2.7 KiB
Go
87 lines
2.7 KiB
Go
// 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
|