(new): prepare v2.1.0 release

- add custom LogLevel constructors and richer color configuration
- support ANSI, 256-color, RGB, and text attributes on LogLevel
- introduce clearer preferred APIs such as NewLogger and SetName
- preserve backward compatibility with deprecated wrappers for v2.0.1 APIs
- restore legacy ColorStringBuilder signatures as compatibility wrappers
- fix newline separator handling in Println-style output
- add tests for color precedence, deprecated aliases, and LogLevel attributes
- update GoDoc and bilingual README documentation

colors.go

@@ -7,8 +7,22 @@ import (
 
 type FgColor uint8
 type BgColor uint8
+type FgColor256 uint8
+type BgColor256 uint8
+type BgColorRGB []uint8
+type FgColorRGB []uint8
 type Attribute uint8
 
+// NewBgColorRGB builds an RGB background color value.
+func NewBgColorRGB(r, g, b uint8) BgColorRGB {
+	return BgColorRGB{r, g, b}
+}
+
+// NewFgColorRGB builds an RGB foreground color value.
+func NewFgColorRGB(r, g, b uint8) FgColorRGB {
+	return FgColorRGB{r, g, b}
+}
+
 const (
 	Reset Attribute = iota
 	Bold
@@ -32,6 +46,7 @@ const (
 	DisableCrossedOut
 )
 const (
+	FgNone          = 0
 	FgBlack FgColor = iota + 30
 	FgRed
 	FgGreen
@@ -43,6 +58,7 @@ const (
 	FgDefault FgColor = 39
 )
 const (
+	BgNone          = 0
 	BgBlack BgColor = iota + 40
 	BgRed
 	BgGreen
@@ -87,51 +103,96 @@ type ColorStringBuilder struct {
 	str string
 }
 
+// NewColorStringBuilder creates a builder for composing ANSI-colored strings.
 func NewColorStringBuilder() *ColorStringBuilder {
 	return &ColorStringBuilder{str: ""}
 }
+
+// AddAttribute appends an ANSI text attribute sequence.
 func (builder *ColorStringBuilder) AddAttribute(attr Attribute) *ColorStringBuilder {
 	builder.str += attr.String()
 	return builder
 }
+
+// AddFgColor appends a basic ANSI foreground color sequence.
 func (builder *ColorStringBuilder) AddFgColor(color FgColor) *ColorStringBuilder {
-	if color == 0 {
+	if color <= 0 {
 		return builder
 	}
 	builder.str += color.String()
 	return builder
 }
+
+// AddBgColor appends a basic ANSI background color sequence.
 func (builder *ColorStringBuilder) AddBgColor(color BgColor) *ColorStringBuilder {
-	if color == 0 {
+	if color <= 0 {
 		return builder
 	}
 	builder.str += color.String()
 	return builder
 }
+
+// AddForeground256Color appends a 256-color foreground sequence.
+func (builder *ColorStringBuilder) AddForeground256Color(color FgColor256) *ColorStringBuilder {
+	builder.str += color.String()
+	return builder
+}
+
+// AddColor256Fg appends a 256-color foreground sequence.
+// Deprecated: use AddForeground256Color. This method will be removed in v3.
 func (builder *ColorStringBuilder) AddColor256Fg(color uint8) *ColorStringBuilder {
-	builder.str += color256Fg(color)
+	return builder.AddForeground256Color(FgColor256(color))
+}
+
+// AddBackground256Color appends a 256-color background sequence.
+func (builder *ColorStringBuilder) AddBackground256Color(color BgColor256) *ColorStringBuilder {
+	builder.str += color.String()
 	return builder
 }
+
+// AddColor256Bg appends a 256-color background sequence.
+// Deprecated: use AddBackground256Color. This method will be removed in v3.
 func (builder *ColorStringBuilder) AddColor256Bg(color uint8) *ColorStringBuilder {
-	builder.str += color256Bg(color)
+	return builder.AddBackground256Color(BgColor256(color))
+}
+
+// AddForegroundRGB appends an RGB foreground sequence.
+func (builder *ColorStringBuilder) AddForegroundRGB(color FgColorRGB) *ColorStringBuilder {
+	builder.str += color.String()
 	return builder
 }
+
+// AddColorRgbFg appends an RGB foreground sequence.
+// Deprecated: use AddForegroundRGB. This method will be removed in v3.
 func (builder *ColorStringBuilder) AddColorRgbFg(r, g, b uint8) *ColorStringBuilder {
-	builder.str += colorRgbFg(r, g, b)
+	return builder.AddForegroundRGB(FgColorRGB{r, g, b})
+}
+
+// AddBackgroundRGB appends an RGB background sequence.
+func (builder *ColorStringBuilder) AddBackgroundRGB(color BgColorRGB) *ColorStringBuilder {
+	builder.str += color.String()
 	return builder
 }
+
+// AddColorRgbBg appends an RGB background sequence.
+// Deprecated: use AddBackgroundRGB. This method will be removed in v3.
 func (builder *ColorStringBuilder) AddColorRgbBg(r, g, b uint8) *ColorStringBuilder {
-	builder.str += colorRgbBg(r, g, b)
-	return builder
+	return builder.AddBackgroundRGB(BgColorRGB{r, g, b})
 }
+
+// AddReset appends the ANSI reset sequence.
 func (builder *ColorStringBuilder) AddReset() *ColorStringBuilder {
 	builder.str += "\x1b[0m"
 	return builder
 }
+
+// AddText appends plain text to the builder.
 func (builder *ColorStringBuilder) AddText(text string) *ColorStringBuilder {
 	builder.str += text
 	return builder
 }
+
+// String returns the built string and appends a reset sequence when needed.
 func (builder *ColorStringBuilder) String() string {
 	if strings.Contains(builder.str, "\x1b[") && !strings.HasSuffix(builder.str, "\x1b[0m") {
 		builder.AddReset()
@@ -139,43 +200,77 @@ func (builder *ColorStringBuilder) String() string {
 	return builder.str
 }
 
+// String returns the ANSI escape sequence for the attribute.
 func (a Attribute) String() string {
 	return fmt.Sprintf("\x1b[%dm", a)
 }
+
+// Uint8 returns the raw attribute value.
 func (a Attribute) Uint8() uint8 {
 	return uint8(a)
 }
+
+// Int returns the raw attribute value as int.
 func (a Attribute) Int() int {
 	return int(a)
 }
+
+// String returns the ANSI escape sequence for the foreground color.
 func (c FgColor) String() string {
 	return fmt.Sprintf("\x1b[%dm", c)
 }
+
+// Uint8 returns the raw foreground color value.
 func (c FgColor) Uint8() uint8 {
 	return uint8(c)
 }
+
+// Int returns the raw foreground color value as int.
 func (c FgColor) Int() int {
 	return int(c)
 }
+
+// String returns the ANSI escape sequence for the background color.
 func (c BgColor) String() string {
 	return fmt.Sprintf("\x1b[%dm", c)
 }
+
+// Uint8 returns the raw background color value.
 func (c BgColor) Uint8() uint8 {
 	return uint8(c)
 }
+
+// Int returns the raw background color value as int.
 func (c BgColor) Int() int {
 	return int(c)
 }
 
-func color256Fg(color uint8) string {
-	return fmt.Sprintf("\x1b[38;5;%dm", color)
-}
-func color256Bg(color uint8) string {
-	return fmt.Sprintf("\x1b[48;5;%dm", color)
-}
-func colorRgbFg(r, g, b uint8) string {
-	return fmt.Sprintf("\x1b[38;2;%d;%d;%dm", r, g, b)
-}
-func colorRgbBg(r, g, b uint8) string {
-	return fmt.Sprintf("\x1b[48;2;%d;%d;%dm", r, g, b)
-}
+// String returns the ANSI escape sequence for the 256-color foreground value.
+func (c FgColor256) String() string { return fmt.Sprintf("\u001B[38;5;%dm", c) }
+
+// Uint8 returns the raw 256-color foreground value.
+func (c FgColor256) Uint8() uint8 { return uint8(c) }
+
+// Int returns the raw 256-color foreground value as int.
+func (c FgColor256) Int() int { return int(c) }
+
+// String returns the ANSI escape sequence for the 256-color background value.
+func (c BgColor256) String() string { return fmt.Sprintf("\u001B[48;5;%dm", c) }
+
+// Uint8 returns the raw 256-color background value.
+func (c BgColor256) Uint8() uint8 { return uint8(c) }
+
+// Int returns the raw 256-color background value as int.
+func (c BgColor256) Int() int { return int(c) }
+
+// String returns the ANSI escape sequence for the RGB foreground value.
+func (c FgColorRGB) String() string { return fmt.Sprintf("\x1b[38;2;%d;%d;%dm", c[0], c[1], c[2]) }
+
+// Uint8 returns the raw RGB foreground components.
+func (c FgColorRGB) Uint8() []uint8 { return c }
+
+// String returns the ANSI escape sequence for the RGB background value.
+func (c BgColorRGB) String() string { return fmt.Sprintf("\x1b[48;2;%d;%d;%dm", c[0], c[1], c[2]) }
+
+// Uint8 returns the raw RGB background components.
+func (c BgColorRGB) Uint8() []uint8 { return c }