command

MakeFixedCommand can be used to construct commands that expect a specific fixed type, and optionally, variadic arguments.

package main

import (
	"context"
	"flag"
	"fmt"
	"os"

	"github.com/djdv/go-filesystem-utils/internal/command"
)

// fixedType is the type our execute function
// expects to always receive when it's called.
// The type will already be populated with default
// values or values parsed from the arguments passed
// to [command.Execute].
type fixedType struct {
	someField int
}

// BindFlags initializes default values for our type
// and gives the [flag] package the ability to overwrite
// them when parsing flags.
func (ft *fixedType) BindFlags(flagSet *flag.FlagSet) {
	const (
		flagName    = "flag"
		flagUsage   = "an example flag"
		flagDefault = 1
	)
	flagSet.IntVar(&ft.someField, flagName, flagDefault, flagUsage)
}

// MakeFixedCommand can be used to construct
// commands that expect a specific fixed type,
// and optionally, variadic arguments.
func main() {
	var (
		cmd     = newFixedCommand()
		cmdArgs = newFixedArgsCommand()
		ctx     = context.TODO()
	)
	if err := cmd.Execute(ctx); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmd.Execute(ctx, "-flag=2"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmdArgs.Execute(ctx, "-flag=3"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmdArgs.Execute(ctx, "-flag=4", "a", "b", "c"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
}

func newFixedCommand() command.Command {
	const (
		name     = "fixed"
		synopsis = "Prints a value."
		usage    = "Call the command with or" +
			" without flags"
	)
	return command.MakeFixedCommand[*fixedType](
		name, synopsis, usage,
		fixedExecute,
	)
}

func fixedExecute(ctx context.Context, settings *fixedType) error {
	fmt.Printf("settings.someField: %d\n", settings.someField)
	return nil
}

func newFixedArgsCommand() command.Command {
	const (
		name     = "fixed-args"
		synopsis = "Prints a value and arguments."
		usage    = "Call the command with or" +
			" without flags or arguments"
	)
	return command.MakeFixedCommand[*fixedType](
		name, synopsis, usage,
		fixedExecuteArgs,
	)
}

func fixedExecuteArgs(ctx context.Context, settings *fixedType, arguments ...string) error {
	if err := fixedExecute(ctx, settings); err != nil {
		return nil
	}
	if len(arguments) > 0 {
		fmt.Printf("arguments: %v\n", arguments)
	}
	return nil
}

Output:

settings.someField: 1
settings.someField: 2
settings.someField: 3
settings.someField: 4
arguments: [a b c]

MakeNiladicCommand can be used to construct basic commands that don't expect additional parameters to be passed to their execute function.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/djdv/go-filesystem-utils/internal/command"
)

// MakeNiladicCommand can be used to construct
// basic commands that don't expect additional
// parameters to be passed to their execute function.
func main() {
	var (
		cmd = newNiladicCommand()
		ctx = context.TODO()
	)
	if err := cmd.Execute(ctx); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
}

func newNiladicCommand() command.Command {
	const (
		name     = "niladic"
		synopsis = "Prints a message."
		usage    = "Call the command with no arguments"
	)
	return command.MakeNiladicCommand(
		name, synopsis, usage,
		niladicExecute,
	)
}

func niladicExecute(context.Context) error {
	fmt.Println("hello!")
	return nil
}

Output:

hello!

MakeVariadicCommand can be used to construct commands that expect a variable amount of parameters.

package main

import (
	"context"
	"flag"
	"fmt"
	"os"
	"strconv"

	"github.com/djdv/go-filesystem-utils/internal/command"
)

type (
	// settings is the type our execute function
	// will construct on its own.
	settings struct {
		someField int
	}
	// Execute expects to receive a list of `option`s
	// that it will apply to the [settings] struct.
	option func(*settings) error
	// options holds individual [option] values
	// and also satisfies the [command.ExecuteType] constraint.
	options []option
)

const variadicFlagDefault = 1

// BindFlags gives the [flag] package the ability to
// append options to our list during flag parsing.
func (ol *options) BindFlags(flagSet *flag.FlagSet) {
	const (
		flagName  = "flag"
		flagUsage = "an example flag"
	)
	flagSet.Func(flagName, flagUsage, func(parameter string) error {
		parsedValue, err := strconv.Atoi(parameter)
		if err != nil {
			return err
		}
		*ol = append(*ol, func(settings *settings) error {
			settings.someField = parsedValue
			return nil
		})
		return nil
	})
}

// MakeVariadicCommand can be used to construct
// commands that expect a variable amount of parameters.
func main() {
	var (
		cmd     = newVariadicCommand()
		cmdArgs = newVariadicArgsCommand()
		ctx     = context.TODO()
	)
	if err := cmd.Execute(ctx); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmd.Execute(ctx, "-flag=2"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmdArgs.Execute(ctx, "-flag=3"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
	if err := cmdArgs.Execute(ctx, "-flag=4", "a", "b", "c"); err != nil {
		fmt.Fprint(os.Stderr, err)
		return
	}
}

func newVariadicCommand() command.Command {
	const (
		name     = "variadic"
		synopsis = "Prints a value."
		usage    = "Call the command with or" +
			" without flags"
	)
	return command.MakeVariadicCommand[options](
		name, synopsis, usage,
		variadicExecute,
	)
}

func variadicExecute(ctx context.Context, options ...option) error {
	settings := settings{
		someField: variadicFlagDefault,
	}
	for _, apply := range options {
		if err := apply(&settings); err != nil {
			return err
		}
	}
	fmt.Printf("settings.someField: %d\n", settings.someField)
	return nil
}

func newVariadicArgsCommand() command.Command {
	const (
		name     = "variadic-args"
		synopsis = "Prints a value and arguments."
		usage    = "Call the command with or" +
			" without flags or arguments"
	)
	return command.MakeVariadicCommand[options](
		name, synopsis, usage,
		variadicExecuteArgs,
	)
}

func variadicExecuteArgs(ctx context.Context, arguments []string, options ...option) error {
	if err := variadicExecute(ctx, options...); err != nil {
		return nil
	}
	if len(arguments) > 0 {
		fmt.Printf("arguments: %v\n", arguments)
	}
	return nil
}

Output:

settings.someField: 1
settings.someField: 2
settings.someField: 3
settings.someField: 4
arguments: [a b c]

Subcommand groups can be useful for defining a section of related commands under a single named group.

package main

import (
	"context"
	"os"

	"github.com/djdv/go-filesystem-utils/internal/command"
)

// Subcommand groups can be useful for defining
// a section of related commands under a single
// named group.
func main() {
	var (
		cmd = newSubcommands()
		ctx = context.TODO()
	)
	// NOTE: text rendering is disabled
	// for `go test`'s output comparison.
	// Normally this can be omitted.
	const (
		helpFlag   = "-help"
		renderFlag = "-video-terminal=false"
	)
	cmd.Execute(ctx, helpFlag, renderFlag)
	cmd.Execute(ctx, "alphabets", helpFlag, renderFlag)
	cmd.Execute(ctx, "numerals", helpFlag, renderFlag)
}

func newSubcommands() command.Command {
	var (
		noopFn      = func(context.Context) error { return nil }
		makeCommand = func(name string) command.Command {
			var (
				synopsis = name + " synopsis"
				usage    = name + " usage"
			)
			return command.MakeNiladicCommand(
				name, synopsis, usage, noopFn,
			)
		}
		// Printer output defaults to [os.Stderr].
		// We set it here only because `go test`
		// compares against [os.Stdout].
		output     = os.Stdout
		cmdOptions = []command.Option{
			command.WithUsageOutput(output),
		}
	)
	return command.SubcommandGroup(
		"main", "Top level group",
		[]command.Command{
			command.SubcommandGroup(
				"alphabets", "Letter group.",
				[]command.Command{
					makeCommand("a"),
					makeCommand("b"),
					makeCommand("c"),
				},
				cmdOptions...,
			),
			command.SubcommandGroup(
				"numerals", "Number group.",
				[]command.Command{
					makeCommand("1"),
					makeCommand("2"),
					makeCommand("3"),
				},
				cmdOptions...,
			),
		},
		cmdOptions...,
	)
}

Output:

Must be called with a subcommand.

Usage:
	main subcommand [flags]
Flags:
  -help
    	prints out this help text
  -video-terminal
    	render text for video terminals
    	(default: true)
Subcommands:
  alphabets - Letter group.
  numerals  - Number group.

Must be called with a subcommand.

Usage:
	alphabets subcommand [flags]
Flags:
  -help
    	prints out this help text
  -video-terminal
    	render text for video terminals
    	(default: true)
Subcommands:
  a - a synopsis
  b - b synopsis
  c - c synopsis

Must be called with a subcommand.

Usage:
	numerals subcommand [flags]
Flags:
  -help
    	prints out this help text
  -video-terminal
    	render text for video terminals
    	(default: true)
Subcommands:
  1 - 1 synopsis
  2 - 2 synopsis
  3 - 3 synopsis