autostr

README

autostr — Tag-based struct-to-string converter for Go

autostr is a small, reflection-based Go library that automatically converts structs into human-readable strings using struct tags — similar to how encoding/json converts structs into JSON.

It’s designed for logging, debugging, and CLI output when you want control over which fields are shown and how they’re displayed — without writing manual String() methods.

---

Features

• Tag-driven field inclusion (string:"include")
• Custom field labels via tag (display:"Alias")
• Nested struct and pointer traversal
• Optional AutoString() override per type
• Safe cycle detection for linked data
• Configurable separators and zero-value display
• Default configuration with lazy fallback (like http.Client)

---

Example

package main

import (
    "fmt"
    "github.com/azargarov/go-utils/autostr"
)

type Person struct {
    Name string `string:"include" display:"FullName"`
    Age  int    `string:"include"`
    ID   int    // excluded
}

func main() {
    p := Person{Name: "Alice", Age: 30}
    fmt.Println(autostr.String(p))
    // Output: FullName: Alice, Age: 30
}

---

Installation

go get github.com/azargarov/go-utils/autostr

Documentation

Overview

Tag-based struct-to-string conversion.

The autostr package provides a reflection-based utility to convert Go structs into human-readable strings using struct tags. It is designed for logging, debugging, and CLI output, offering flexible configuration for field inclusion, naming, formatting, and separators. If a type implements the AutoStringer interface, its AutoString method is used instead of reflection-based conversion.

Example:

type Person struct {
    Name string `string:"include" display:"FullName" format:"%s"`
    Age  int    `string:"include" format:"%d years"`
}
p := Person{Name: "Alice", Age: 30}
fmt.Println(autostr.String(p)) // Output: FullName: Alice, Age: 30 years

Index

• Constants
• func Ptr[T any](v T) *T
• func String(obj any, config ...Config) string
• type AutoStringer
• type Config
  • func DefaultConfig() Config

Constants

const (
	// DefaultIncludeTag is the default struct tag key for including fields in the string output.
	DefaultIncludeTag = "string"
	// DefaultIncludeValue is the default tag value that indicates a field should be included.
	DefaultIncludeValue = "include"
	// DefaultFieldNameTag is the default struct tag key for renaming fields in the output.
	DefaultFieldNameTag = "display"
	// DefaultSeparator is the default separator between fields in the output.
	DefaultSeparator = ", "
	// DefaultFieldValueSeparator is the default separator between field names and their values.
	DefaultFieldValueSeparator = ": "
	// DefaultShowZeroValue determines whether zero values are included by default.
	DefaultShowZeroValue = true
	// DefaultFormat is the default format string for field values when no format tag is specified.
	DefaultFormat = "%v"
	// DefaultFormatTag is the default struct tag key for specifying field value formats.
	DefaultFormatTag = "format"
)

Constants defining default values for configuration.

Functions

func Ptr

func Ptr[T any](v T) *T

Ptr creates a pointer to a value of any type. It is a helper function for setting pointer-based fields in Config, such as Separator or FieldValueSeparator.

Example:

cfg := Config{Separator: Ptr(":")} // Sets Separator to ":"

func String

func String(obj any, config ...Config) string

String converts a value to a human-readable string using struct tags and an optional Config. If the value (or its pointer) implements AutoStringer, its AutoString method is used. If no Config is provided, DefaultConfig is used. The function handles nested structs, pointers, interfaces, and cyclic references safely.

Example:

type Person struct {
    Name string `string:"include" display:"FullName" format:"%s"`
    Age  int    `string:"include" format:"%d years"`
}
p := Person{Name: "Alice", Age: 30}
fmt.Println(String(p)) // Output: FullName: Alice, Age: 30 years

Types

type AutoStringer

type AutoStringer interface {
	AutoString() string
}

AutoStringer defines an interface for types that provide their own string representation. Types implementing AutoStringer will use their AutoString method instead of reflection-based conversion.

type Config

type Config struct {
	IncludeTag          string  // IncludeTag specifies the struct tag key for including fields (default: "string").
	IncludeValue        string  // IncludeValue specifies the tag value that includes a field (default: "include").
	FieldNameTag        string  // FieldNameTag specifies the struct tag key for renaming fields (default: "display").
	FieldValueSeparator *string // FieldValueSeparator is the separator between field names and values (default: ": ").
	Separator           *string // Separator is the separator between fields (default: ", ").
	ShowZeroValue       bool    // ShowZeroValue determines whether zero-value fields are included (default: true).
	FormatTag           string  // FormatTag specifies the struct tag key for formatting field values (default: "format").
	PrettyPrint         bool    // print multiline values in a pretty way
}

Config defines options for customizing the string conversion process.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with default values for struct-to-string conversion. The defaults are:

• IncludeTag: "string"
• IncludeValue: "include"
• FieldNameTag: "display"
• Separator: ", "
• FieldValueSeparator: ": "
• ShowZeroValue: true
• FormatTag: "format"

Example:

cfg := DefaultConfig()
fmt.Println(String(Person{Name: "Alice", Age: 30}, cfg)) // Output: Name: Alice, Age: 30