argument

Argument

A declarative Go library for parsing command-line arguments and environment variables into structs using struct tags. Perfect for building CLI applications with clean configuration management.

Features

• 🏷️ Declarative: Use struct tags to define argument names, environment variables, and defaults
• 🔄 Multiple Sources: Supports command-line arguments, environment variables, and default values
• 📋 Slice Support: Parse comma-separated values into slices with configurable separators
• 🔧 Custom Parsing: Implement encoding.TextUnmarshaler for complex parsing logic
• ⚡ Zero Dependencies: Minimal external dependencies for core functionality
• ✅ Type Safe: Supports all common Go types including pointers for optional values
• 🕐 Extended Duration: Enhanced time.Duration parsing with support for days and weeks
• 🧪 Well Tested: Comprehensive test suite with BDD-style tests

Installation

go get github.com/bborbe/argument/v2

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/bborbe/argument/v2"
)

func main() {
    var config struct {
        Username string `arg:"username" env:"USERNAME" default:"guest"`
        Password string `arg:"password" env:"PASSWORD"`
        Port     int    `arg:"port" env:"PORT" default:"8080"`
        Debug    bool   `arg:"debug" env:"DEBUG"`
    }
    
    ctx := context.Background()
    if err := argument.Parse(ctx, &config); err != nil {
        log.Fatalf("Failed to parse arguments: %v", err)
    }
    
    fmt.Printf("Starting server on port %d for user %s\n", config.Port, config.Username)
}

Usage Examples

Basic Configuration

type Config struct {
    Host     string `arg:"host" env:"HOST" default:"localhost"`
    Port     int    `arg:"port" env:"PORT" default:"8080"`
    LogLevel string `arg:"log-level" env:"LOG_LEVEL" default:"info"`
}

var config Config
err := argument.Parse(context.Background(), &config)

Run with: ./app -host=0.0.0.0 -port=9090 -log-level=debug

Optional Values with Pointers

type DatabaseConfig struct {
    Host     string  `arg:"db-host" env:"DB_HOST" default:"localhost"`
    Port     int     `arg:"db-port" env:"DB_PORT" default:"5432"`
    Timeout  *int    `arg:"timeout" env:"DB_TIMEOUT"`        // Optional
    MaxConns *int    `arg:"max-conns" env:"DB_MAX_CONNS"`    // Optional
}

Duration with Extended Parsing

type ServerConfig struct {
    ReadTimeout  time.Duration `arg:"read-timeout" env:"READ_TIMEOUT" default:"30s"`
    WriteTimeout time.Duration `arg:"write-timeout" env:"WRITE_TIMEOUT" default:"1m"`
    IdleTimeout  time.Duration `arg:"idle-timeout" env:"IDLE_TIMEOUT" default:"2h"`
    Retention    time.Duration `arg:"retention" env:"RETENTION" default:"30d"`  // 30 days
    BackupFreq   time.Duration `arg:"backup-freq" env:"BACKUP_FREQ" default:"1w"` // 1 week
}

Supported duration units: ns, us, ms, s, m, h, d (days), w (weeks)

Required Fields

type APIConfig struct {
    APIKey   string `arg:"api-key" env:"API_KEY"`           // Required (no default)
    Endpoint string `arg:"endpoint" env:"ENDPOINT"`         // Required (no default)
    Region   string `arg:"region" env:"REGION" default:"us-east-1"`
}

// This will return an error if APIKey or Endpoint are not provided
err := argument.Parse(context.Background(), &config)

Custom Types

You can use custom types (named types with underlying primitive types) for better type safety:

type Username string
type Port int
type IsEnabled bool
type Rate float64

type AppConfig struct {
    Username Username  `arg:"user" env:"USERNAME" default:"guest"`
    Port     Port      `arg:"port" env:"PORT" default:"8080"`
    Debug    IsEnabled `arg:"debug" env:"DEBUG" default:"false"`
    Rate     Rate      `arg:"rate" env:"RATE" default:"1.5"`
}

var config AppConfig
err := argument.Parse(context.Background(), &config)

// Access values with type safety
fmt.Printf("Username: %s\n", string(config.Username))
fmt.Printf("Port: %d\n", int(config.Port)) 
fmt.Printf("Debug: %t\n", bool(config.Debug))
fmt.Printf("Rate: %f\n", float64(config.Rate))

Custom types work with all supported underlying types:

• string → type Username string
• int, int32, int64, uint, uint64 → type Port int
• bool → type IsEnabled bool
• float64 → type Rate float64

Slice Types

Parse comma-separated values into slices automatically:

type Config struct {
    Hosts    []string  `arg:"hosts" env:"HOSTS" default:"localhost,127.0.0.1"`
    Ports    []int     `arg:"ports" env:"PORTS" separator:":" default:"8080:8081:8082"`
    Prices   []float64 `arg:"prices" default:"9.99,19.99,29.99"`
    Flags    []bool    `arg:"flags" default:"true,false,true"`

    // Custom separator for specific use cases
    Tags     []string  `arg:"tags" separator:"|" default:"prod|api|web"`
}

var config Config
err := argument.Parse(context.Background(), &config)

Run with: ./app -hosts=server1,server2,server3 -ports=8080:9000:9001

Features:

• Default comma separator (,) can be customized with separator: tag
• Automatic whitespace trimming around elements
• Empty string creates empty slice
• Works with custom types: []Username, []Environment, etc.

Custom Parsing with TextUnmarshaler

Implement encoding.TextUnmarshaler for complex parsing logic:

import "encoding"

type Broker string

func (b *Broker) UnmarshalText(text []byte) error {
    value := string(text)
    if !strings.Contains(value, "://") {
        value = "plain://" + value  // Add default schema
    }
    *b = Broker(value)
    return nil
}

type KafkaConfig struct {
    Broker  Broker   `arg:"broker" default:"localhost:9092"`
    Brokers []Broker `arg:"brokers" env:"KAFKA_BROKERS"`  // Works in slices too!
}

var config KafkaConfig
err := argument.Parse(context.Background(), &config)
// broker "localhost:9092" becomes "plain://localhost:9092"
// brokers "kafka1:9092,ssl://kafka2:9093" becomes ["plain://kafka1:9092", "ssl://kafka2:9093"]

Use cases:

• URL validation and normalization
• Default schema/prefix handling
• Complex validation logic
• Format conversion

Supported Types

• Strings: string
• Integers: int, int32, int64, uint, uint64
• Floats: float64
• Booleans: bool
• Durations: time.Duration (with extended parsing)
• Pointers: *string, *int, *float64, etc. (for optional values)
• Slices: []string, []int, []int64, []uint, []uint64, []float64, []bool
• Custom Types: Named types with underlying primitive types
• Custom Parsing: Any type implementing encoding.TextUnmarshaler

Priority Order

Values are applied in the following priority order (higher priority overwrites lower):

1. Default values (from default: tag)
2. Environment variables (from env: tag)
3. Command-line arguments (from arg: tag)

API Documentation

For complete API documentation, visit pkg.go.dev.

Main Functions

• Parse(ctx context.Context, data interface{}) error - Parse arguments and environment variables (quiet mode)
• ParseAndPrint(ctx context.Context, data interface{}) error - Parse and print the final configuration values
• ValidateRequired(ctx context.Context, data interface{}) error - Check that all required fields are set

Command-Line Usage

Your application will automatically support standard Go flag syntax:

# Long form with equals
./app -host=localhost -port=8080

# Long form with space  
./app -host localhost -port 8080

# Boolean flags
./app -debug        # sets debug=true
./app -debug=false  # sets debug=false

Environment Variables

Set environment variables to configure your application:

export HOST=0.0.0.0
export PORT=9090
export DEBUG=true
./app

Error Handling

The library provides detailed error messages for common issues:

err := argument.Parse(ctx, &config)
if err != nil {
    // Errors include context about what failed:
    // - Missing required fields
    // - Type conversion errors  
    // - Invalid duration formats
    log.Fatal(err)
}

Development

Running Tests

make test

Code Generation (Mocks)

make generate

Format Code

make format

Full Development Workflow

make precommit  # Format, generate, test, and check

Linting

make check  # Run vet, errcheck, vulncheck, and security scanners

Version 2 Changes

Version 2.3.0 introduced breaking changes for better library behavior:

• Parse() no longer prints configuration by default (quieter)
• New ParseAndPrint() function when you want to display parsed values
• Focus on library-like behavior vs CLI tool behavior

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing code style
4. Run make precommit to ensure all checks pass
5. Submit a pull request

This project uses:

• Ginkgo/Gomega for BDD-style testing
• Counterfeiter for mock generation
• Standard Go formatting and linting tools

License

This project is licensed under the BSD-style license. See the LICENSE file for details.