cmdos

README

cmdos

A flag and subcommand library

package main

import (
	"fmt"
	"os"

	"codeberg.org/roble/cmdos"
)

type rootCmd struct{}

func (*rootCmd) Info() cmdos.Info {
	return cmdos.Info{
		Name:        "mycmd",
		Description: "my command",
		Usage:       "mycmd [options]",
	}
}

func (*rootCmd) Flags() []cmdos.Flag {
	return []cmdos.Flag{
		{
			Short:       'h',
			Long:        "help",
			Description: "display help and exit",
		},
		{
			Short:       'a',
			Long:        "addr",
			Description: "listen address",
			Arg:         cmdos.ArgDefault(":8082"),
		},
		{
			Short:       'o',
			Long:        "output",
			Description: "file location to save",
			Arg:         cmdos.ArgRequire(),
		},
	}
}

func (c *rootCmd) Run(vs *cmdos.Values) error {
	var opt struct {
		Help   bool   `cmdos:"help"`
		Addr   string `cmdos:"addr"`
		Output string
	}
	if err := vs.DecodeAll(&opt); err != nil {
		return err
	}

	if opt.Help {
		return cmdos.WriteHelp(os.Stdout, c)
	}

	fmt.Println("addr:", opt.Addr)

	return nil
}

func main() {
	if err := cmdos.Run(new(rootCmd), os.Args[1:]); err != nil {
		fmt.Fprintln(os.Stderr, err)
	}
}

$ cmdostest -h
my command

usage:
  mycmd [options]

options:
  -h, --help  display help and exit
  -a, --addr  listen address
  -o, --output  file location to save

Documentation

Overview

package cmdos is a library for creating CLIs.

Index

• func ArgDefault(val string) flagArg
• func ArgRequire() flagArg
• func Run(c Command, args []string) error
• func WriteHelp(w io.Writer, c Command) error
• type Command
• type Flag
• type HelpTemplate
• type Info
• type Subcommands
• type Values
  • func (v *Values) Args() []string
  • func (v *Values) Count(name string) (int, error)
  • func (v *Values) Decode(dst any) (err error)
  • func (v *Values) Has(name string) (bool, error)

Functions

func ArgDefault

func ArgDefault(val string) flagArg

ArgDefault can be used when you want to give a flag a default value.

func ArgRequire

func ArgRequire() flagArg

ArgRequire can be used to force the user to set a flag on a command.

func Run

func Run(c Command, args []string) error

Run is the main entry point for a cmdos CLI.

func WriteHelp

func WriteHelp(w io.Writer, c Command) error

WriteHelp writes the help info from a Command to a io.Writer.

Types

type Command

type Command interface {
	Info() Info
	Flags() []Flag
	Run(*Values) error
}

Command is an interface for creating a CLI command.

type Flag

type Flag struct {
	Short       rune
	Long        string
	Description string

	Arg flagArg
}

Flag holds info to define a flag on a command.

type HelpTemplate

type HelpTemplate interface {
	HelpTemplate() string
}

HelpTemplate is an optional interface. Implement this method to use a custom template to generate help text.

type Info

type Info struct {
	Name   string
	Usages []string

	Summary     string
	Description string
}

Info contains info about the command we're defining.

type Subcommands

type Subcommands interface {
	Subcommands() []Command
}

Subcommands is an optional interface. Implement this method to register subcommands on a Command.

type Values

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

Values gives you access to flag values.

func (*Values) Args

func (v *Values) Args() []string

Args returns the arguments passed to a command.

func (*Values) Count

func (v *Values) Count(name string) (int, error)

Count returns the amount of times a flag was set.

func (*Values) Decode

func (v *Values) Decode(dst any) (err error)

Decode unmarshals flag values into a dst struct. The dst struct should tag its fields. The tag value should match the name of the flag.

Help bool   `cmdos:"help"`
Addr string `cmdos:"addr"`

func (*Values) Has

func (v *Values) Has(name string) (bool, error)

Has returns whether a flag was set or not.