commando

README

go-commando

A package for building Go command-line applications. Inspired by Command.js.

Contents

• Installation
• Quick Start
• Declaring a Program
• Options
• Action
• Parse
• Name
• Description
• Version
• Help
• Local Development
• Testing
• Conventional Commits
• GitHub Actions

Installation

To install go-commando using Go modules execute:

go get github.com/J-R-Oliver/go-commando

You'll then be able to import go-commando in your code:

import "github.com/J-R-Oliver/go-commando"

Quick Start

go-commando allows you to write code to configure your command line applications. go-commando automates the parsing of options and arguments, and implements a help text option.

An example application can be found in example.go:

package main

import (
    "github.com/J-R-Oliver/go-commando"
)

func main() {
    fileSplitter := func(arguments []string, options map[string]string) {
        // implementation removed for brevity
    }
    
    program := commando.NewProgram()
    
    program.
        Name("file-splitter").
        Description("CLI to split file written in go.").
        Version("1.0.0").
        Option("i", "input", "input", "Input file", "./input.txt").
        Option("o", "output", "output", "Output file", "./output.txt").
        Action(fileSplitter).
        Parse()
}

program contains all the methods required to configure your application. This configuration is used to parse the application inputs and build the help text.

Declaring a program

A new program can be created by calling the NewProgram function.

program := commando.NewProgram()

Options

Options can be configured by calling the Option method. All options are parsed as string variables. An option can be set with a shortOption, longOption, mapKey, description and defaultValue.

program.Option("i", "input", "input", "Input file", "./input.txt")

To configure either a short option only, or long option only, pass "" to the unrequired option type.

program.Option("i", "", "input", "Input file", "./input.txt") // short option
program.Option("", "input", "input", "Input file", "./input.txt") // long option

Action

The action handler receives both the arguments and options given when the application is run. Action is the entry point when building command line applications using commando. arguments is a slice of strings containing all user input when executing application after any options have been parsed. This slice maintains the order of the inputted arguments. options is a map of strings containing options input. Specific options can be accessed using the mapKey set when adding the option.

For example, the following action prints out the arguments and options:

func(arguments []string, options map[string]string) {
    fmt.Println("Arguments:")

    for i, a := range arguments {
        fmt.Printf("\tindex: %d, argument: %s\n", i, a)
    }

    fmt.Println("Options:")

    for k, v := range options {
        fmt.Printf("\tkey: %s, option: %s\n", k, v)
    }
}

Parse

Parse initiates starting the program and should be the final function call on program. Once the desired program configuration has been loaded the action function will be called with the program arguments and options.

Name

Name sets the name of the program, used when creating the -h or --help output, and returns a pointer to the program.

program.Name("file-splitter")

Description

Description sets the description of the program, used when creating the -h or --help output, and returns a pointer to the program.

program.Description("CLI to split file written in go.")

Version

Version sets the version of the program, returned when the application is called with -v or --version, and returns a pointer to the program.

program.Version("1.0.0")

Example console output when application is called with -v:

$ file-splitter -v
1.0.0

Help

Help text is automatically created by go-commando and can be viewed when executing applications with either -h or --help options. The help text is also displayed if an unconfigured option is entered.

$ file-splitter -h
Usage: file-splitter [options] [arguments]

CLI to split file written in go.

Options:
  -i, --input <input>                     Input file (default: "./input.txt")
  -o, --output <output>                   Output file (default: "./output.txt")
  -v, --version                           output the version number
  -h, --help                              display help for command

Local Development

Prerequisites

To install and modify this project you will need to have:

• Go
• Git

Installation

To start, please fork and clone the repository to your local machine.

Testing

All tests have been written using the testing package from the Standard library. To run the tests execute:

go test -v ./...

Code coverage is also measured by using the testing package. To run tests with coverage execute:

go test -coverprofile=coverage.out  ./...

Conventional Commits

This project uses the Conventional Commits specification for commit messages. The specification provides a simple rule set for creating commit messages, documenting features, fixes, and breaking changes in commit messages.

A pre-commit configuration file has been provided to automate commit linting. Ensure that pre-commit has been installed and execute...

pre-commit install

...to add a commit Git hook to your local machine.

An automated pipeline job has been configured to lint commit messages on a push.

GitHub Actions

A CI/CD pipeline has been created using GitHub Actions to automated tasks such as linting and testing.

Build Workflow

The build workflow handles integration tasks. This workflow consists of two jobs, Git and Go, that run in parallel. This workflow is triggered on a push to a branch.

Git

This job automates tasks relating to repository linting and enforcing best practices.

Go

This job automates Go specific tasks.

Release Workflow

The release workflow handles release tasks. This workflow consists of one job, Go Release. This workflow is triggered manually from the GitHub Actions UI.

Go Release

This job automates tasks relating to updating changelog, and publishing GitHub release.

Documentation

Overview

Package commando provides a succinct and simple method for creating command line applications. Primarily commando wraps existing implementations in package flag.

Index

• type Action
• type Program
  • func NewProgram() *Program
  • func (p *Program) Action(action Action) *Program
  • func (p *Program) Description(description string) *Program
  • func (p *Program) Name(name string) *Program
  • func (p *Program) Option(shortOption, longOption, mapKey, description, defaultValue string) *Program
  • func (p *Program) Parse()
  • func (p *Program) Version(version string) *Program

Types

type Action

type Action func(arguments []string, options map[string]string)

Action is a type of function that receives both the arguments and options given when the application is run. Action is the entry point when building command line applications using commando. arguments is a slice of strings containing all user input when executing application after any options have been parsed. This slice maintains the order of the inputted arguments. options is a map of strings containing options input. Specific options can be accessed using the mapKey set when adding the option.

type Program

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

Program represents a command line application.

func NewProgram

func NewProgram() *Program

NewProgram returns a pointer to a new unconfigured program.

func (*Program) Action

func (p *Program) Action(action Action) *Program

Action sets the action function of the program, and returns a pointer to the program.

func (*Program) Description

func (p *Program) Description(description string) *Program

Description sets the description of the program, used when creating the -h or --help output, and returns a pointer to the program.

func (*Program) Name

func (p *Program) Name(name string) *Program

Name sets the name of the program, used when creating the -h or --help output, and returns a pointer to the program.

func (*Program) Option

func (p *Program) Option(shortOption, longOption, mapKey, description, defaultValue string) *Program

Option adds a commandline option, and returns a pointer to the program.

Option takes a shortOption and a longOption string. Commando will automatically add '-' for short options and '--' for long options. Only short or only long options can be configured by passing "" for the unneeded variant.

mapKey is used as the key to store the option input in the map passed to the action function. description is used when creating the -h or --help output. defaultValue will be set in the options map passed to the action function and be overridden by user input.

func (*Program) Parse

func (p *Program) Parse()

Parse initiates starting the program and should be the final function call on program. Once the desired program configuration has been loaded the action function will be called with the program arguments and options.

func (*Program) Version

func (p *Program) Version(version string) *Program

Version sets the version of the program, returned when the application is called with -v or --version, and returns a pointer to the program.