# YAGTF

Yet Another Golang Time Formatter

## English Documentation

### Tradition Mode

Directly using the format string like 'yyyy-MM-dd HH:mm:ss'. It will be translated into advanced mode format string by simply string replacing.

Just for compatibility, not recommend for complex format.

Symbols:


|Symbol      | Function Description                  | Will Be Replaced To         | Output Example   |
|:-:         | :-:                                   | :-:                         | :-:              |
|yyyy        | long year                             | <year>                | 2019             |
|yy          | short year                            | <shortYear>           | 96               |
|MM          | month with zero fill                  | <month>               | 02               |
|M3          | month in English abbr.                | <monthAbbr>           | Jan              |
|M09         | month in English with zero fill       | <monthName>           | January          |
|M9          | month in English without zero fill    | <monthNameNoFill>     | January          |
|M           | month without zero fill               | <monthNoFill>         | 2                |
|dd          | day with zero fill                    | <day>                 | 05               |
|d           | day without zero fill                 | <dayNoFill>           | 5                |
|HH          | 24h hour with zero fill               | <hour24>              | 13               |
|hh          | 12h hour with zero fill               | <hour12>              | 01               |
|H           | 24h hour without zero fill            | <hour24NoFill>        | 13               |
|h           | 12h hour without zero fill            | <hour12NoFill>        | 1                |
|mm          | minute with zero fill                 | <minute>              | 01               |
|ss          | second with zero fill                 | <second>              | 05               |
|E09         | weekday in English with zero fill     | <weekdayName>         | Monday           |
|E9          | weekday in English without zero fill  | <weekdayNameNoFill>   | Monday           |
|E3          | weekday in English abbr.              | <weekdayAbbr>         | Mon              |
|A           | AM/PM                                 | <ampm>                | AM               |
|S1          | millisecond                           | <ms>                  | 026              |
|S2          | microsecond                           | <us>                  | 114514           |
|S3          | nanosecond                            | <ns>                  | 019810019        |
|Z           | timezone abbr.                        | <timezoneAbbr>        | CST              |
|z           | timezone UTC offset                   | <timezone>            | +0800            |

Examples:

`yyyy-MM-dd HH:mm:ss` -> `2000-02-15 19:27:35`

`yy M3 dd E09 hh:mm:ss.S2 A` -> `96 Nov 14 Thursday  01:05:27.114514 PM`

### Advanced Mode

Start your format string with `!`. If you want to use tradition mode, but your formatting string start with `!`, please start with `!!` to instead of `!`.

(The `!` in middle of string will be auto-escaped)

#### Pure Text

Directly type pure text. For escaping `!`, use `<!>`

Examples:

`hello, gensokyo<!>` -&gt; `hello, gensokyo!`

#### Tag

Use `<` and `>` to wrap the name of tag. For escaping `<` and '>', using `<lt>` and `<gt>`

Examples:

`<year>-<month>-<day>` -&gt; `2019-01-02`

`<lt><hour>:<minute>:<second><gt><!>` -&gt; `<16:05:27>!`

#### Non-display Tags

Some of tags will not be displayed, they just be used for set some options.

Examples:

`<UTC><hour>:<minute>` -&gt; `08:05`

#### Display Tag List

|Tag                         | Function Description                            | Output Example               |
|:-:                         | :-:                                             | :-:                          |
|&lt;year&gt;                | long year                                       | 2019                         |
|&lt;shortYear&gt;           | short year                                      | 96                           |
|&lt;month&gt;               | month with zero fill                            | 02                           |
|&lt;monthNoFill&gt;         | month without zero fill                         | 2                            |
|&lt;monthAbbr&gt;           | month in English abbr.                          | Jan                          |
|&lt;monthName&gt;           | month in English with zero fill                 | January                      |
|&lt;monthNameNoFill&gt;     | month in English without zero fill              | January                      |
|&lt;day&gt;                 | day with zero fill                              | 05                           |
|&lt;dayNoFill&gt;           | day without zero fill                           | 5                            |
|&lt;hour24&gt;              | 24h hour with zero fill                         | 13                           |
|&lt;hour12&gt;              | 12h hour with zero fill                         | 01                           |
|&lt;hour24NoFill&gt;        | 24h hour without zero fill                      | 13                           |
|&lt;hour12NoFill&gt;        | 12h hour without zero fill                      | 1                            |
|&lt;minute&gt;              | minute with zero fill                           | 01                           |
|&lt;second&gt;              | second with zero fill                           | 05                           |
|&lt;weekday&gt;             | weekday in numberic                             | 1                            |
|&lt;weekdayName&gt;         | weekday in English with zero fill               | Monday                       |
|&lt;weekdayNameNoFill&gt;   | weekday in English without zero fill            | Monday                       |
|&lt;weekdayAbbr&gt;         | weekday in English abbr.                        | Mon                          |
|&lt;ampm&gt;                | AM/PM                                           | AM                           |
|&lt;ms&gt;                  | millisecond                                     | 026                          |
|&lt;us&gt;                  | microsecond                                     | 114514                       |
|&lt;ns&gt;                  | nanosecond                                      | 019810019                    |
|&lt;yearweek&gt;            | the week in this year with zero fill            | 06                           |
|&lt;yearweekNoFill&gt;      | the week in this year without zero fill         | 6                            |
|&lt;yearday&gt;             | the day in this year with zero fill             | 034                          |
|&lt;yeardayNoFill&gt;       | the day in this year without zero fill          | 34                           |
|&lt;timezone&gt;            | timezone UTC offset                             | +0800                        |
|&lt;timezoneAbbr&gt;        | timezone abbr.                                  | CST                          |
|&lt;timezoneSec&gt;         | timezone offset in seconds with zero fill       | 03600                        |
|&lt;timezoneSecNoFill&gt;   | timezone offset in seconds without zero fill    | 3600                         |
|&lt;iso8601date&gt;         | ISO8601 date                                    | 2019-01-01                   |
|&lt;iso8601time&gt;         | ISO8601 time                                    | 19:28:31                     |
|&lt;iso8601full&gt;         | ISO8601 full format                             | 2019-01-01T19:28:31+0800     |
|&lt;common&gt;              | common format                                   | 2019-01-01 19:28:31          |
|&lt;nginx&gt;               | nginx default time format                       | 01/Jan/2019:19:28:31 +0800   |
|&lt;!&gt;                   | exclamation mark                                | !                            |
|&lt;lt&gt;                  | less-than mark                                  | &lt;                         |
|&lt;gt&gt;                  | great-than mark                                 | &gt;                         |
|&lt;q&gt;                   | quote mark                                      | "                            |
|&lt;sq&gt;                  | single quote mark                               | '                            |
|&lt;sp&gt;                  | space                                           |                              |
|&lt;tab&gt;                 | tab                                             |                              |
|&lt;br&gt;                  | linebreak '\n' (valid in multi-line mode only)  |                              |
|&lt;cr&gt;                  | linebreak '\r' (valid in multi-line mode only)  |                              |


#### Alias

|Alias                     | For Tag                        |
|:-:                       | :-:                            |
|&lt;y&gt;                 | &lt;year&gt;                   |
|&lt;sy&gt;                | &lt;shortYear&gt;              |
|&lt;mon&gt;               | &lt;month&gt;                  |
|&lt;monNF&gt;             | &lt;monthNoFill&gt;            |
|&lt;monA&gt;              | &lt;monthAbbr&gt;              |
|&lt;monN&gt;              | &lt;monthName&gt;              |
|&lt;monNNF&gt;            | &lt;monthNameNoFill&gt;        |
|&lt;d&gt;                 | &lt;day&gt;                    |
|&lt;dNF&gt;               | &lt;dayNoFill&gt;              |
|&lt;h24&gt;               | &lt;hour24&gt;                 |
|&lt;h12&gt;               | &lt;hour12&gt;                 |
|&lt;h24NF&gt;             | &lt;hour24NoFill&gt;           |
|&lt;h12NF&gt;             | &lt;hour12NoFill&gt;           |
|&lt;min&gt;               | &lt;minute&gt;                 |
|&lt;s&gt;                 | &lt;second&gt;                 |
|&lt;wd&gt;                | &lt;weekday&gt;                |
|&lt;wdN&gt;               | &lt;weekdayName&gt;            |
|&lt;wdNNF&gt;             | &lt;weekdayNameNoFill&gt;      |
|&lt;wdA&gt;               | &lt;weekdayAbbr&gt;            |
|&lt;yw&gt;                | &lt;yearweek&gt;               |
|&lt;ywNF&gt;              | &lt;yearweekNoFill&gt;         |
|&lt;yd&gt;                | &lt;yearday&gt;                |
|&lt;ydNF&gt;              | &lt;yeardayNoFill&gt;          |
|&lt;tz&gt;                | &lt;timezone&gt;               |
|&lt;tzA&gt;               | &lt;timezoneAbbr&gt;           |
|&lt;tzS&gt;               | &lt;timezoneSec&gt;            |
|&lt;tzSNF&gt;             | &lt;timezoneSecNoFill&gt;      |
|&lt;i8d&gt;               | &lt;iso8601date&gt;            |
|&lt;i8t&gt;               | &lt;iso8601time&gt;            |
|&lt;i8f&gt;               | &lt;iso8601full&gt;            |
|&lt;lf&gt;                | &lt;br&gt;                     |

### Non-display Tag List

|Tag                         | Function Description                       |
|:-:                         | :-:                                        |
|&lt;UTC&gt;                 | use UTC timezone for output                |
|&lt;Local&gt;               | use local timezone for output              |
|&lt;Timezone:&gt;           | *use specified timezone for output         |

 * Instuction For `<Timezone:>` Tag:

Specified timezone to use follow the colon. Using UTC offset format with name followed.

Example:

`<Timezone:+0800CST>` will specified the timezone to CST(+0800) for output.

### External Tags

By Using TimeFormatterEx, you can append your custom tags.

### Using This Package In Go

*Installation*

```
go get git.swzry.com/zry/YAGTF
```

*Coding*

With Basic Formatter

```
package main

import (
	"fmt"
	"git.swzry.com/zry/YAGTF/yagtf/timefmt"
	"time"
)

func main() {
	tf := timefmt.NewDefaultTimeFormatter("!<y>-<mon>-<d> <h24>:<min>:<s> <tz> <tzA>", false)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("!<UTC><y>-<mon>-<d> <h24>:<min>:<s> <tz> <tzA>", false)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("!<Timezone:+0900JST><y>-<mon>-<d> <h24>:<min>:<s><br><tz> <tzA>", true)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("!<Timezone:+0900JST><y>-<mon>-<d> <h24>:<min>:<s><br><tz> <tzA>", false)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("yyyy-MM-dd HH:mm:ss z Z", false)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("!yyyy-MM-dd HH:mm:ss z Z", false)
	fmt.Println(tf.Format(time.Now()))
	tf = timefmt.NewDefaultTimeFormatter("!!yyyy-MM-dd HH:mm:ss z Z", false)
	fmt.Println(tf.Format(time.Now()))
}
```

With TimeFormatterEx:
```
package main

import (
	"fmt"
	"git.swzry.com/zry/YAGTF/yagtf/tfelem"
	"git.swzry.com/zry/YAGTF/yagtf/timefmt"
	"time"
)

func main() {
	printer := timefmt.NewTimePrinterEx()
	parser := timefmt.NewFormatParser(true)
	parser.AddExDataTag("level", func() timefmt.TimeElementEx {
		return tfelem.NewExDataElement(4, "level")
	})
	parser.AddExDataTag("app", func() timefmt.TimeElementEx {
		return tfelem.NewExDataElement(64, "app")
	})
	parser.AddExDataTag("msg", func() timefmt.TimeElementEx {
		return tfelem.NewExDataElement(2048, "msg")
	})
	tf := timefmt.NewTimeFormatterEx(printer, parser, false)
	tf.ParseFormat("![<y>-<mon>-<d> <h24>:<min>:<s> <tz> <tzA>] <lt><level><gt> <app> : <msg>")
	logtest(tf, "INFO", "test1.app", "hello, world")
	logtest(tf, "WARN", "test2.app", "hello, gensokyo")
	logtest(tf, "INFO", "test3.app", "the quick brown fox jumps over a lazy dog.")
	logtest(tf, "INFO", "test4.app", "Unicode Test With Emoji 1:☁⚡🪁🗝️👨, 👨💡, 📍✔️. ⛪❌📍. ☁⚡, ☁⚡⛪, ⛪🔥, 🏢️📍✔️.")
	logtest(tf, "INFO", "test5.app", "Unicode Test With Emoji 2:🇨🇳, 1980 < 📅 < 2015, 👶✖️1 = ✔️; 📅 > 2015, 👶✖️2 = ✔️.")
	logtest(tf, "INFO", "test6.app", "Unicode Test With Emoji 3:👦✂🔌, ⚡👦, 🚑🏥, 😷💉, 😷😱, 👦☠️. 👵🏽😭, 💴⚰️, 👮⚰️❌, 🔥💀->⚱️✔️.")
	logtest(tf, "INFO", "test7.app", "Unicode Test With Emoji 4:👦🚬🚄, 👮🚭, 💴, 👦👿, 👦💣💥🚔, 👮😱, 👮🔫👦, 👦☠️.")
	logtest(tf, "INFO", "test8.app", "Unicode Test With Chinese and Emoji: 魔理沙偷走了重要的📚, 帕秋莉👿.")
}

func logtest(tf *timefmt.TimeFormatterEx, level string, app string, msg string) {
	exdata := make(map[string]string)
	exdata["level"] = level
	exdata["app"] = app
	exdata["msg"] = msg
	fmt.Println(tf.Format(time.Now(), exdata))
}
```

## 中文文档

待完善...