# go-pkg/cli

Lightweight, dependency-free command-line argument and option parsing library for Go.

## Overview

This package provides a small, composable CLI parser with support for:
- boolean, string, int, and array/map options
- positional arguments (single and repeating)
- aliases, short flags, defaults and hidden options
- validation for incompatible options and custom "special" values
- automatic usage and version printing

See the core parser implementation in [`parser.go`](parser.go) and the high-level API in [`cli.go`](cli.go).

## Features

- Option types: [`AddBoolOpt`](opt-bool.go), [`AddStringOpt`](opt-string.go), [`AddIntOpt`](opt-int.go), [`AddStringArrayOpt`](opt-string-array.go), [`AddIntArrayOpt`](opt-int-array.go), [`AddStringMapOpt`](opt-string-map.go)
- Positional args: [`AddStringArg`](arg-string.go), [`AddStringArrayArg`](arg-string-array.go)
- Usage & version output: [`CliParser.Usage`](cli-usage.go), [`CliParser.PrintVersion`](cli-version.go)
- Option tracing via [`CliParser.TraceOptions`](cli.go) and [`SimpleOptionTracer`](simple-opt-tracer.go)
- Programmatic option setting: [`SetOptionValue`](opt-manager.go)

## Quick start

Example: define options and parse argv

```go
package main

import (
  "fmt"
  "git.portale-stac.it/go-pkg/cli"
)

func main() {
  var parser cli.CliParser
  parser.Init([]string{"prog", "--debug", "--config", "app.yaml", "input.txt"}, "$VER:prog,0.1.0,2025,email:$")

  // define target variables and options
  var debug bool
  var config string
  var inputs []string

  parser.AddBoolOpt("debug", "d", &debug, "Enable debug")
  parser.AddStringOpt("config", "c", &config, "app.yaml", "Config file")
  parser.AddStringArrayArg("files", true, &inputs, "Input files")

  // print usage: parser.Usage() - see [`CliParser.Usage`](cli-usage.go)
  if err := parser.Parse(); err != nil {
    fmt.Println("parse error:", err)
    return
  }

  fmt.Println("debug:", debug)
  fmt.Println("config:", config)
  fmt.Println("inputs:", inputs)
}
```

Refer to the unit test for a realistic example: [`cli_test.go`](cli_test.go).

## API Reference

Key types and methods:
- [`CliParser`](cli.go) — main parser type
- [`CliParser.Init`](cli.go) — initialize with argv and version
- [`CliParser.Parse`](cli.go) — run parsing
- Option constructors: [`AddBoolOpt`](opt-bool.go), [`AddStringOpt`](opt-string.go), [`AddIntOpt`](opt-int.go), [`AddStringArrayOpt`](opt-string-array.go), [`AddIntArrayOpt`](opt-int-array.go), [`AddStringMapOpt`](opt-string-map.go)
- Arg constructors: [`AddStringArg`](arg-string.go), [`AddStringArrayArg`](arg-string-array.go)
- Utilities: [`TraceOptions`](cli.go), [`SetOptionValue`](opt-manager.go), [`SimpleOptionTracer`](simple-opt-tracer.go)

For implementation details, consult:
- parser internals: [`parser.go`](parser.go)
- option base helpers: [`opt-base.go`](opt-base.go)
- usage/version printing: [`cli-usage.go`](cli-usage.go), [`cli-version.go`](cli-version.go)

## License

This project is licensed under the terms in [LICENSE](LICENSE).

## Contributing

Open issues or pull requests are welcome. Run and extend the tests in [`cli_test.go`](cli_test.go) when making changes.