writ

This example uses writ.New() to build a command from the Greeter's struct fields. The resulting *writ.Command decodes and updates the Greeter's fields in-place. The Command.ExitHelp() method is used to display help content if --help is specified, or if invalid input arguments are received.

package main

import (
	"fmt"
	"github.com/bobziuchkovski/writ"
	"strings"
)

type Greeter struct {
	HelpFlag  bool   `flag:"help" description:"Display this help message and exit"`
	Verbosity int    `flag:"v, verbose" description:"Display verbose output"`
	Name      string `option:"n, name" default:"Everyone" description:"The person or people to greet"`
}

// This example uses writ.New() to build a command from the Greeter's
// struct fields.  The resulting *writ.Command decodes and updates the
// Greeter's fields in-place.  The Command.ExitHelp() method is used to
// display help content if --help is specified, or if invalid input
// arguments are received.
func main() {
	greeter := &Greeter{}
	cmd := writ.New("greeter", greeter)
	cmd.Help.Usage = "Usage: greeter [OPTION]... MESSAGE"
	cmd.Help.Header = "Greet users, displaying MESSAGE"

	// Use cmd.Decode(os.Args[1:]) in a real application
	_, positional, err := cmd.Decode([]string{"-vvv", "--name", "Sam", "How's it going?"})
	if err != nil || greeter.HelpFlag {
		cmd.ExitHelp(err)
	}

	message := strings.Join(positional, " ")
	fmt.Printf("Hi %s! %s\n", greeter.Name, message)
	if greeter.Verbosity > 0 {
		fmt.Printf("I'm feeling re%slly chatty today!\n", strings.Repeat("a", greeter.Verbosity))
	}

	

Output:

This example demonstrates some of the convenience features offered by writ. It uses writ's support for io types and default values to ensure the Input and Output fields are initialized. These default to stdin and stdout due to the default:"-" field tags. The user may specify -i or -o to read from or write to a file. Similarly, the Replacements map is initialized with key=value pairs for every -r/--replace option the user specifies.

package main

import (
	"bufio"
	"errors"
	"fmt"
	"github.com/bobziuchkovski/writ"
	"io"
	"os"
	"strings"
)

type ReplacerCmd struct {
	Input        io.Reader         `option:"i" description:"Read input values from FILE (default: stdin)" default:"-" placeholder:"FILE"`
	Output       io.WriteCloser    `option:"o" description:"Write output to FILE (default: stdout)" default:"-" placeholder:"FILE"`
	Replacements map[string]string `option:"r, replace" description:"Replace occurrences of ORIG with NEW" placeholder:"ORIG=NEW"`
	HelpFlag     bool              `flag:"h, help" description:"Display this help text and exit"`
}

// This example demonstrates some of the convenience features offered by writ.
// It uses writ's support for io types and default values to ensure the Input
// and Output fields are initialized.  These default to stdin and stdout due
// to the default:"-" field tags.  The user may specify -i or -o to read from
// or write to a file.  Similarly, the Replacements map is initialized with
// key=value pairs for every -r/--replace option the user specifies.
func main() {
	replacer := &ReplacerCmd{}
	cmd := writ.New("replacer", replacer)
	cmd.Help.Usage = "Usage: replacer [OPTION]..."
	cmd.Help.Header = "Perform text replacement according to the -r/--replace option"
	cmd.Help.Footer = "By default, replacer reads from stdin and write to stdout.  Use the -i and -o options to override."

	// Decode input arguments
	_, positional, err := cmd.Decode(os.Args[1:])
	if err != nil || replacer.HelpFlag {
		cmd.ExitHelp(err)
	}
	if len(positional) > 0 {
		cmd.ExitHelp(errors.New("replacer does not accept positional arguments"))
	}

	// At this point, the ReplacerCmd's Input, Output, and Replacements fields are all
	// known-valid and initialized, so we can run the replacement.
	err = replacer.Replace()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
		os.Exit(1)
	}
}

// The Replace() method performs the input/output replacements, but is
// not relevant to the example itself.
func (r ReplacerCmd) Replace() error {
	var pairs []string
	for k, v := range r.Replacements {
		pairs = append(pairs, k, v)
	}
	replacer := strings.NewReplacer(pairs...)
	scanner := bufio.NewScanner(r.Input)
	for scanner.Scan() {
		line := scanner.Text()
		_, err := io.WriteString(r.Output, replacer.Replace(line)+"\n")
		if err != nil {
			return err
		}
	}
	err := scanner.Err()
	if err != nil {
		return err
	}
	return r.Output.Close()

	// Help Output:
	// Usage: replacer [OPTION]...
	// Perform text replacement according to the -r/--replace option
	//
	// Available Options:
	//   -i FILE                   Read input values from FILE (default: stdin)
	//   -o FILE                   Write output to FILE (default: stdout)
	//   -r, --replace=ORIG=NEW    Replace occurrences of ORIG with NEW
	//   -h, --help                Display this help text and exit
	//
	// By default, replacer reads from stdin and write to stdout.  Use the -i and -o options to override.
}

Output:

This example demonstrates explicit Command and Option creation, along with explicit option grouping. It checks the host platform and dynamically adds a --bootloader option if the example is run on Linux. The same result could be achieved by using writ.New() to construct a Command, and then adding the platform-specific option to the resulting Command directly.

package main

import (
	"github.com/bobziuchkovski/writ"
	"os"
	"runtime"
)

type Config struct {
	help       bool
	verbosity  int
	bootloader string
}

// This example demonstrates explicit Command and Option creation,
// along with explicit option grouping.  It checks the host platform
// and dynamically adds a --bootloader option if the example is run on
// Linux.  The same result could be achieved by using writ.New() to
// construct a Command, and then adding the platform-specific option
// to the resulting Command directly.
func main() {
	config := &Config{}
	cmd := &writ.Command{Name: "explicit"}
	cmd.Help.Usage = "Usage: explicit [OPTION]... [ARG]..."
	cmd.Options = []*writ.Option{
		{
			Names:       []string{"h", "help"},
			Description: "Display this help text and exit",
			Decoder:     writ.NewFlagDecoder(&config.help),
			Flag:        true,
		},
		{
			Names:       []string{"v"},
			Description: "Increase verbosity; may be specified more than once",
			Decoder:     writ.NewFlagAccumulator(&config.verbosity),
			Flag:        true,
			Plural:      true,
		},
	}

	// Note the explicit option grouping.  Using writ.New(), a single option group is
	// created for all options/flags that have descriptions.  Without writ.New(), we
	// need to create the OptionGroup(s) ourselves.
	general := cmd.GroupOptions("help", "v")
	general.Header = "General Options:"
	cmd.Help.OptionGroups = append(cmd.Help.OptionGroups, general)

	// Dynamically add --bootloader on Linux
	if runtime.GOOS == "linux" {
		cmd.Options = append(cmd.Options, &writ.Option{
			Names:       []string{"bootloader"},
			Description: "Use the specified bootloader (grub, grub2, or lilo)",
			Decoder:     writ.NewOptionDecoder(&config.bootloader),
			Placeholder: "NAME",
		})
		platform := cmd.GroupOptions("bootloader")
		platform.Header = "Platform Options:"
		cmd.Help.OptionGroups = append(cmd.Help.OptionGroups, platform)
	}

	// Decode the options
	_, _, err := cmd.Decode(os.Args[1:])
	if err != nil || config.help {
		cmd.ExitHelp(err)
	}

	// Help Output, Linux:
	// General Options:
	//   -h, --help                Display this help text and exit
	//   -v                        Increase verbosity; may be specified more than once
	//
	// Platform Options:
	//   --bootloader=NAME         Use the specified bootloader (grub, grub2, or lilo)
	//
	// Help Output, other platforms:
	// General Options:
	//   -h, --help                Display this help text and exit
	//   -v                        Increase verbosity; may be specified more than once

}

Output:

This example demonstrates subcommands in a busybox style. There's no requirement that subcommands implement the Run() method shown here. It's just an example of how subcommands might be implemented.

package main

import (
	"errors"
	"github.com/bobziuchkovski/writ"
	"os"
)

type GoBox struct {
	Link Link `command:"ln" alias:"link" description:"Create a soft or hard link"`
	List List `command:"ls" alias:"list" description:"List directory contents"`
}

type Link struct {
	HelpFlag bool `flag:"h, help" description:"Display this message and exit"`
	Symlink  bool `flag:"s" description:"Create a symlink instead of a hard link"`
}

type List struct {
	HelpFlag   bool `flag:"h, help" description:"Display this message and exit"`
	LongFormat bool `flag:"l" description:"Use long-format output"`
}

func (g *GoBox) Run(p writ.Path, positional []string) {
	// The user didn't specify a subcommand.  Give them help.
	p.Last().ExitHelp(errors.New("COMMAND is required"))
}

func (l *Link) Run(p writ.Path, positional []string) {
	if l.HelpFlag {
		p.Last().ExitHelp(nil)
	}
	if len(positional) != 2 {
		p.Last().ExitHelp(errors.New("ln requires two arguments, OLD and NEW"))
	}
	// Link operation omitted for brevity.  This would be os.Link or os.Symlink
	// based on the l.Symlink value.
}

func (l *List) Run(p writ.Path, positional []string) {
	if l.HelpFlag {
		p.Last().ExitHelp(nil)
	}
	// Listing operation omitted for brevity.  This would be a call to ioutil.ReadDir
	// followed by conditional formatting based on the l.LongFormat value.
}

// This example demonstrates subcommands in a busybox style.  There's no requirement
// that subcommands implement the Run() method shown here.  It's just an example of
// how subcommands might be implemented.
func main() {
	gobox := &GoBox{}
	cmd := writ.New("gobox", gobox)
	cmd.Help.Usage = "Usage: gobox COMMAND [OPTION]... [ARG]..."
	cmd.Subcommand("ln").Help.Usage = "Usage: gobox ln [-s] OLD NEW"
	cmd.Subcommand("ls").Help.Usage = "Usage: gobox ls [-l] [PATH]..."

	path, positional, err := cmd.Decode(os.Args[1:])
	if err != nil {
		// Using path.Last() here ensures the user sees relevant help for their
		// command selection
		path.Last().ExitHelp(err)
	}

	// At this point, cmd.Decode() has already decoded option values into the gobox
	// struct, including subcommand values.  We just need to dispatch the command.
	// path.String() is guaranteed to represent the user command selection.
	switch path.String() {
	case "gobox":
		gobox.Run(path, positional)
	case "gobox ln":
		gobox.Link.Run(path, positional)
	case "gobox ls":
		gobox.List.Run(path, positional)
	default:
		panic("BUG: Someone added a new command and forgot to add it's path here")
	}

	// Help output, gobox:
	// Usage: gobox COMMAND [OPTION]... [ARG]...
	//
	// Available Commands:
	//   ln                        Create a soft or hard link
	//   ls                        List directory contents
	//
	// Help output, gobox ln:
	// Usage: gobox ln [-s] OLD NEW
	//
	// Available Options:
	//   -h, --help                Display this message and exit
	//   -s                        Create a symlink instead of a hard link
	//
	// Help output, gobox ls:
	// Usage: gobox ls [-l] [PATH]...
	//
	// Available Options:
	//   -h, --help                Display this message and exit
	//   -l                        Use long-format output
}

Output: