Skip to content

flags Module

The flags module provides a simple command/flag system for Harneet programs.

  • Nested commands (e.g., tool user add)
  • Per-command flags with optional short aliases
  • Global flags that are available to all commands
  • Interleaved command selection (commands can appear anywhere in argv)
  • Ancestor-chain flag lookup (current → parent → … → global)
  • Unknown flags produce errors (e.g., unknown flag: --foo)
  • -- terminator makes the rest positional

Quick Start

Flags Quick Start
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package main
import flags, fmt

// Define commands
flags.Command("tool", "Top-level tool")
flags.Subcommand("tool", "user", "User management", "u")
flags.Subcommand("user", "add", "Add a user", "a")

// Define flags
flags.String("config", "app.yaml", "Config file", "c")     // global
flags.String("name", "", "User name", "n")                 // for current command
flags.Bool("admin", false, "Admin user", "A")              // for current command

// Simulated argv (no program name)
var argv = ["tool", "user", "add", "--name=bob", "-A", "pos1", "pos2"]
flags.Parse(argv)

var sel, _ = flags.Selected()                // ["tool","user","add"]
var name, _ = flags.GetString("name")       // "bob"
var admin, _ = flags.GetBool("admin")       // true
var cfg, _ = flags.GetString("config")      // "app.yaml"
var rest, _ = flags.Args()                   // ["pos1","pos2"]

fmt.Println(sel, name, admin, cfg, rest)

API

  • flags.Command(name, usage [, alias]) – Define a top-level command.
  • flags.Subcommand(parent, name, usage [, alias]) – Define a nested command.
  • flags.String(name, default, usage [, alias]) – Define a string flag.
  • flags.Bool(name, default, usage [, alias]) – Define a boolean flag.
  • flags.Int(name, default, usage [, alias]) – Define an integer flag.
  • flags.Parse(argv array) – Parse args. Commands can be interleaved with flags; the command path is resolved respecting parent relationships.
  • flags.Selected() – Returns the selected command path as an array.
  • flags.Args() – Returns positional arguments for the selected command.
  • flags.GetString/Bool/Int(name) – Get parsed values. Lookup order is current command, then parent(s), then global.
  • flags.Reset() – Reset all definitions and parsed values (handy for tests).

Dispatch (Return-Dispatch pattern)

  • flags.Handle(path array[string], tag any) – Register a handler tag for a command path. The tag is any value your program can switch on.
  • flags.Run(argv array) – Parse and return (selectedPath array, args array, handlerTag any, error). Your program performs the call based on handlerTag.

Usage Patterns

  • Define your command tree upfront, then declare flags for the current context. Global flags are declared at the global context (no current command selected).

  • Populate argv from your environment if needed (e.g., a future os.Args()); for now our examples manually create argv arrays.

  • Short alias flags support -x value and -x=value forms. Booleans support --bool (sets true) and --bool=false.

Examples

See examples/flags/: - nested_commands_basic.ha – Command path selection and command-local flags - alias_and_fallback.ha – Short aliases and fallback to global flags - dispatch_demo.ha – Register tags with flags.Handle, parse with flags.Run, then dispatch in user code