gonsole

README

Gonsole

Gonsole is a Go command line argument parsing library. It provides a configurable parser that reads the given arguments to a map[string]string, checking them against the ones it is told to expect.

Installation

go get github.com/nic-gr/gonsole

Usage

import "github.com/nic-gr/gonsole"

Examples

package main

import (
    "fmt"
    "os"

    "github.com/nic-gr/gonsole"
)

func main() {
    argsMap, err := gonsole.
        NewParser().
        WithProgramName("main.go").
        WithArguments(
            gonsole.Argument{Name: "firstArg"},
            gonsole.Argument{Name: "secondArg"},
            gonsole.Argument{Name: "thirdArg", Default: "42"},
        ).
        WithFlags(
            gonsole.Flag{Name: "-i", Alias: "--inputFile", Required: true},
            gonsole.Flag{Name: "-o", Description: "output file", Default: "/dev/null"},
            gonsole.Flag{Name: "-v", Alias: "--verbose", Boolean: true},
            gonsole.Flag{
                Name: "-g",
                Domain: []string{"Hello", "Hola", "Ciao"},
                Check: func(value string) error {
                    if value != "Hello" {
                        return fmt.Errorf("other languages will be supported soon!")
                    }

                    return nil
                },
            },
        ).
        WithDescription("Gonsole example").
        WithValidation(func(argsMap map[string]string) error {
            _, okG := argsMap["g"]
            _, okV := argsMap["v"]

            if okG && !okV {
                return fmt.Errorf("if the -g flag is provided, the -v (--verbose) flag is mandatory")
            }

            return nil
        }).
        Parse()

    if err != nil {
        fmt.Fprintf(os.Stderr, "%s\n", err.Error())
        os.Exit(1)
    }

    fmt.Println(argsMap)
}

$ go run main.go -i="/proc" -o /media --verbose 12 24
map[firstArg:12 i:/proc inputFile:/proc o:/media secondArg:24 thirdArg:42 v: verbose:]

$ go run main.go -h
usage: main.go [-h, --help] [-i, --inputFile I] [-o O] [-v, --verbose] [-g G] firstArg secondArg thirdArg

Gonsole example

positional arguments:
    firstArg                              
    secondArg                             
    thirdArg (default "42")                 

flags:
    -h, --help                            show this help message and exit
    -i, --inputFile I (required)          
    -o O (default "/dev/null")              output file
    -v, --verbose                         
    -g G (with domain, checked)

License

MIT

Documentation

Overview

Gonsole is a Go command line argument parsing library. It provides a configurable parser that reads the given arguments to a map[string]string, checking them against the ones it is told to expect. As an example, this code sample:

package main

import (
	"fmt"
	"os"

	"github.com/nic-gr/gonsole"
)

func main() {
	argsMap, err := gonsole.
		NewParser().
		WithProgramName("main.go").
		WithArguments(
			gonsole.Argument{Name: "firstArg"},
			gonsole.Argument{Name: "secondArg"},
			gonsole.Argument{Name: "thirdArg", Default: "42"},
		).
		WithFlags(
			gonsole.Flag{Name: "-i", Alias: "--inputFile", Required: true},
			gonsole.Flag{Name: "-o", Description: "output file", Default: "/dev/null"},
			gonsole.Flag{Name: "-v", Alias: "--verbose", Boolean: true},
			gonsole.Flag{
				Name: "-g",
				Domain: []string{"Hello", "Hola", "Ciao"},
				Check: func(value string) error {
					if value != "Hello" {
						return fmt.Errorf("other languages will be supported soon!")
					}

					return nil
				},
			},
		).
		WithDescription("Gonsole example").
		WithValidation(func(argsMap map[string]string) error {
			_, okG := argsMap["g"]
			_, okV := argsMap["v"]

			if okG && !okV {
				return fmt.Errorf("if the -g flag is provided, the -v (--verbose) flag is mandatory")
			}

			return nil
		}).
		Parse()

	if err != nil {
		fmt.Fprintf(os.Stderr, "%s\n", err.Error())
		os.Exit(1)
	}

	fmt.Println(argsMap)
}

Creates the following command line interface:

$ go run main.go -h
usage: main.go [-h, --help] [-i, --inputFile I] [-o O] [-v, --verbose] [-g G] firstArg secondArg thirdArg

Gonsole example

positional arguments:
    firstArg
    secondArg
    thirdArg (default "42")

flags:
    -h, --help                            show this help message and exit
    -i, --inputFile I (required)
    -o O (default "/dev/null")              output file
    -v, --verbose
    -g G (with domain, checked)

Index

• type Argument
• type Flag
• type Parser
  • func NewParser() Parser

Types

type Argument

type Argument struct {
	Name        string
	Required    bool
	Description string
	Default     string
	Domain      []string
	Check       func(string) error
}

Argument is the struct representing a positional argument

type Flag

type Flag struct {
	Name        string
	Alias       string
	Required    bool
	Boolean     bool // a Flag with no value
	Description string
	Default     string
	Domain      []string
	Check       func(string) error
}

Flag is the struct representing a flag, an argument starting with one or more "-"

type Parser

type Parser interface {
	WithHelp(h bool) Parser
	WithUsage(u string) Parser
	WithProgramName(n string) Parser
	WithDescription(d string) Parser
	WithFlags(flags ...Flag) Parser
	WithArguments(arguments ...Argument) Parser
	WithValidation(validationFunc func(map[string]string) error) Parser
	Parse() (map[string]string, error)
}

Parser is the interface that exports the methods of a Gonsole argument parser

func NewParser

func NewParser() Parser

NewParser returns the "zero value" of a Gonsole Parser ready to be configured and used