tap

README

Tap - Terminal Argument Parsing

go get github.com/pt-main/tap

Tap is a lightweight, zero-dependency library for building beautiful CLI applications in Go.
It features a simple command-based API, automatic --flag parsing, colored output, and fully customisable help messages.

Features

• Commands with required / optional arguments and unlimited trailing args
• Flag parsing - --flag, --flag=value, --flag:value
• Built‑in colour support - shortcodes like [?GN], [?RD], [?YW] - easy and readable
• Auto‑generated help - groups aliases, shows arguments, respects custom format
• Fully configurable - change the look of help via ParserConfig
• Hide commands from help using DONT_SHOW docstring
• Verbose / debug flags - built‑in --verbose and --debug with conditional printing
• Colours can be disabled globally (color.ColorEnabled = false)

Quick start

Create a simple CLI with a hello command:

package main

import (
	"fmt"

	"github.com/pt-main/tap"
	"github.com/pt-main/tap/color"
)

func helloHandler(p *tap.Parser, args []string) error {
	color.PrintlnColored("[?GN]Hello[?RT], world! Args: %v", args)
	return nil
}

func main() {
	cfg := tap.NewParserConfig("", "", "", "", "", "") // defaults
	p := tap.NewParser("demo", "Demo CLI v1.0", nil, cfg)
	p.AddCommand("hello", helloHandler, "Prints a friendly greeting", nil, nil, true)

	if err := p.Main(); err != nil {
		fmt.Println("Error:", err)
	}
}

Run it:

Commands and arguments

Add a command using AddCommand:

p.AddCommand(
    name               string,
    handler            HandlerFuncType, // func(*Parser, []string) error
    docstring          string,
    requiredArgs       []string,
    optionalArgs       []string,
    unlimitedMaxArgs   bool,
)

• requiredArgs - shown as <arg> in help. The command fails if they are missing.
• optionalArgs - shown as [arg] in help.
• unlimitedMaxArgs - if true, the command accepts any number of trailing arguments.

You can create aliases for existing commands using AddAlias:

p.AddCommand("help", helpHandler, tap.HELP_DOCS, nil, nil, false)
p.AddAlias("h", "help")  // now "h" works exactly like "help"

The alias inherits all properties (handler, arguments, docstring) from the original command.

Example

p.AddCommand("copy",
    copyHandler,
    "Copy source to destination",
    []string{"src", "dst"},  // required
    []string{"force"},       // optional
    false,
)

Help output would show:

copy <src>, <dst>, [force]

Flags

Flags are written as --flag or --key=value (also --key:value).
They are parsed automatically and stored in p.Flags (a map[string]string). A flag without a value gets an empty string.

Built‑in flags:

• --verbose - enables verbose output (messages printed with p.Print("verbose", ...))
• --debug - enables debug output (similar)

Your handlers can read flags directly:

func myHandler(p *tap.Parser, args []string) error {
    if val, ok := p.Flags["output"]; ok {
        fmt.Println("Output file:", val)
    }
    return nil
}

Use p.Print(flag, format, ...) to output messages only when a specific flag (e.g., --verbose or --debug) is present:

func myHandler(p *tap.Parser, args []string) error {
    p.Print("verbose", "Starting with args: %v", args)
    p.Print("debug", "Detailed debug info")
    // ...
}

The output is automatically prefixed with the flag name and coloured.

Colors

You can just write [?COLOR] with uppercased color name from list to set color. Like [?RED] for red.

All colors: Bold, Underline, Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan.

Also you can set color using first and last letters of color. Like [?RD] for red.

Bright variants: [?BRED], [?BRD], ...

Use them with color.PrintlnColored or color.PrintColored:

color.PrintlnColored("[?GN]Success[?RT] - file saved as [?YW]%s[?RT]", filename)

To disable colours globally:

color.ColorEnabled = false

You can set color to string with color.Set:

text := color.Set("[?RD]Test")

(Reset will be auto pasted in the end of text)

Customising the help output

Create a ParserConfig and pass it to NewParser.
All fields support format strings - use %s for the command name or argument list.

cfg := tap.NewParserConfig(
    "[?CN]>>> Command [?RT]%s[?CN] <<<[?RT]",
    "[?CN]Args:[?RT]",
    "    %s",
    "[?CN]Description:[?RT]",
    "    %s",
    "[?CN]---[?RT]",
)
p := tap.NewParser("mycli", "My tool", nil, cfg)

If you pass an empty string for any field, the default (coloured, nice looking) will be used.

Grouping commands / aliases

If multiple commands share the same docstring, they are displayed together in help:

p.AddCommand("help", helpHandler, tap.HELP_DOCS, nil, nil, false)
p.AddCommand("h", helpHandler, tap.HELP_DOCS, nil, nil, false)

Help shows: [help / h]

Hiding commands from help

Use tap.DONT_SHOW as the docstring:

p.AddCommand("internal", internalHandler, tap.DONT_SHOW, nil, nil, false)

This command will work but will never appear in the help output.

Full example

A minimal but complete CLI with multiple commands:

package main

import (
    "fmt"
    "os"
    "github.com/pt-main/tap"
    "github.com/pt-main/tap/color"
)

func main() {
    cfg := tap.NewParserConfig("", "", "", "", "", "")
    p := tap.NewParser("myapp", "My application v0.1", nil, cfg)

    p.AddCommand("greet", func(p *tap.Parser, args []string) error {
        name := "world"
        if len(args) > 0 {
            name = args[0]
        }
        color.PrintlnColored("[?GN]Hello, %s![?RT]", name)
        return nil
    }, "Say hello", []string{}, []string{"name"}, false)

    p.AddCommand("print", func(p *tap.Parser, args []string) error {
        color.PrintlnColored("[?YW]%s[?RT]", args[0])
        return nil
    }, "Print first argument", []string{"text"}, nil, false)

    if err := p.Main(); err != nil {
        fmt.Fprintln(os.Stderr, "Fatal:", err)
        os.Exit(1)
    }
}

License

MIT - see LICENSE file.
Author: Pt

Documentation

Overview

Package tap provides a lightweight command-line argument parser with support for commands, flags, colored output, and customizable help messages.

Index

• Constants
• type HandlerFuncType
• type Parser
  • func NewParser(cli_name string, about string, help_commands []string, config ParserConfig) *Parser
  • func (p *Parser) AddAlias(aliasName, cmdName string) error
  • func (p *Parser) AddCommand(name string, handler HandlerFuncType, docs string, required_args []string, ...)
  • func (p *Parser) Main() error
  • func (p *Parser) Parse(cmdArgs []string) error
  • func (p *Parser) Print(flag string, format string, args ...any)
• type ParserConfig
  • func NewParserConfig(help_command_block_fmt string, help_args_header_block_fmt string, ...) ParserConfig

Constants

const DONT_SHOW = "#[DON'T SHOW]#"

DONT_SHOW is a special docstring value that hides the command from the help output. The command remains functional but will not appear in the auto-generated help.

const HELP_DOCS = "Generate and print help message"

HELP_DOCS is the docstring used by the built‑in help command. Commands sharing this docstring will be grouped together as aliases.

const Version = "1.3.0"

Types

type HandlerFuncType

type HandlerFuncType func(*Parser, []string) error

HandlerFuncType defines the signature for command handler functions. It receives the parser instance and the slice of command arguments. Returns an error if the command execution fails.

type Parser

type Parser struct {
	Flags map[string]string
	Scope core.ScopeType
	// contains filtered or unexported fields
}

Tap - Terminal Argument Parsing

This parser is the main object in tap.

Main methods:

- AddCommand(name string, handler HandlerFuncType)

- Main() - start parser

func NewParser

func NewParser(cli_name string, about string, help_commands []string, config ParserConfig) *Parser

NewParser creates a new Parser instance. Parameters:

• cli_name: name of the CLI application (used in help).
• about: informational text printed when no command is given.
• help_commands: slice of command names that trigger the help handler. If nil, defaults to []string{"help", "h"}.
• config: ParserConfig controlling help message formatting.

Returns a pointer to the initialized Parser.

func (*Parser) AddAlias

func (p *Parser) AddAlias(aliasName, cmdName string) error

func (*Parser) AddCommand

func (p *Parser) AddCommand(
	name string,
	handler HandlerFuncType,
	docs string,
	required_args []string,
	optional_args []string,
	unlimited_max_args bool,
)

AddCommand registers a new command with the parser. Parameters:

• name: command name (string used in CLI).
• handler: function called when the command is invoked.
• docs: description shown in help; use DONT_SHOW to hide the command.
• required_args: slice of required argument names.
• optional_args: slice of optional argument names.
• unlimited_max_args: if true, command accepts any number of trailing arguments.

func (*Parser) Main

func (p *Parser) Main() error

Main is the primary entry point of the parser. It parses os.Args[1:], extracts flags, finds the command, and executes the corresponding handler. Returns an error if no command is provided, the command is unknown, or the handler fails.

func (*Parser) Parse

func (p *Parser) Parse(cmdArgs []string) error

func (*Parser) Print

func (p *Parser) Print(flag string, format string, args ...any)

Print outputs a formatted message only if the given flag (e.g., "debug", "verbose") is enabled. The message can contain color shortcodes. Each newline is prefixed with the flag’s name for alignment.

type ParserConfig

type ParserConfig struct {
	// contains filtered or unexported fields
}

ParserConfig defines the formatting templates for the auto-generated help message. Each field is a format string that may contain "%s" placeholders for dynamic content. If an empty string is passed to NewParserConfig, the corresponding default format will be used.

func NewParserConfig

func NewParserConfig(
	help_command_block_fmt string,
	help_args_header_block_fmt string,
	help_args_data_block_fmt string,
	help_docs_header_block_fmt string,
	help_docs_data_block_fmt string,
	help_end_block_fmt string,
) ParserConfig

NewParserConfig creates a new ParserConfig with the given format strings. Any empty string parameter will be replaced with a sensible default. Parameters:

• help_command_block_fmt: format for the command name block (e.g., "╭─────── Command [%s]").
• help_args_header_block_fmt: format for the arguments section header.
• help_args_data_block_fmt: format for each argument line.
• help_docs_header_block_fmt: format for the description section header.
• help_docs_data_block_fmt: format for each line of the description.
• help_end_block_fmt: format for the closing block.

Returns a populated ParserConfig.