clapper

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2020 License: MIT Imports: 2 Imported by: 4

README

clapper

A simple but powerful Go package to parse command-line arguments getopt(3) style. Designed especially for making CLI based libraries with ease.

go-version

logo

Documentation

pkg.go.dev

Installation

$ go get "github.com/thatisuday/clapper"

Usage

// cmd.go
package main

import (
	"fmt"
	"os"

	"github.com/thatisuday/clapper"
)

func main() {

	// create a new registry
	registry := clapper.NewRegistry()

	// register the root command
	if _, ok := os.LookupEnv("NO_ROOT"); !ok {
		registry.
			Register("").                           // root command
			AddArg("output", "").                   //
			AddFlag("force", "f", true, "").        //
			AddFlag("verbose", "v", true, "").      //
			AddFlag("version", "V", false, "").     //
			AddFlag("dir", "", false, "/var/users") // default value
	}

	// register the `info` sub-command
	registry.
		Register("info").                        // sub-command
		AddArg("username", "").                  //
		AddArg("category", "manager").           // default value
		AddFlag("verbose", "v", true, "").       //
		AddFlag("version", "V", false, "1.0.1"). // default value
		AddFlag("output", "o", false, "./")      // default value

	// register the `ghost` sub-command
	registry.
		Register("ghost")

	// parse command-line arguments
	carg, err := registry.Parse(os.Args[1:])

	// check for error
	if err != nil {
		fmt.Printf("error => %#v\n", err)
		return
	}

	// get executed sub-command name
	fmt.Printf("sub-command => %#v\n", carg.Cmd)

	// get argument values
	for _, v := range carg.Args {
		fmt.Printf("argument-value => %#v\n", v)
	}

	// get flag values
	for _, v := range carg.Flags {
		fmt.Printf("flag-value => %#v\n", v)
	}
}

In the above example, we have registred a root command and an info command. The registry can parse arguments passed to the command that executed this program.

Example 1

When the root command is executed with no command-line arguments.

$ go run cmd.go

sub-command => ""
argument-value => &clapper.Arg{Name:"output", DefaultValue:"", Value:""}
flag-value => &clapper.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:""}
flag-value => &clapper.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:""}
flag-value => &clapper.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"", Value:""}
flag-value => &clapper.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:""}
Example 2

When the root command is executed but not registered.

$ NO_ROOT= go run cmd.go

error => clapper.ErrorUnknownCommand{Name:""}
Example 3

When the root command is executed with short/long flag names as well as by changing the positions of the arguments.

$ go run cmd.go userinfo -V 1.0.1 -v --force --dir ./sub/dir
$ go run cmd.go -V 1.0.1 --verbose --force userinfo --dir ./sub/dir
$ go run cmd.go -V 1.0.1 -v --force --dir ./sub/dir userinfo
$ go run cmd.go --version 1.0.1 --verbose --force --dir ./sub/dir userinfo

sub-command => ""
argument-value => &clapper.Arg{Name:"output", DefaultValue:"", Value:"userinfo"}
flag-value => &clapper.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:"true"}
flag-value => &clapper.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
flag-value => &clapper.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"", Value:"1.0.1"}
flag-value => &clapper.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:"./sub
/dir"}
Example 4

When an unregistered flag is provided in the command-line arguments.

$ go run cmd.go userinfo -V 1.0.1 -v --force -d ./sub/dir
error => clapper.ErrorUnknownFlag{Name:"d", IsShort:true}

$ go run cmd.go userinfo -V 1.0.1 -v --force --d ./sub/dir
error => clapper.ErrorUnknownFlag{Name:"d", IsShort:false}

$ go run cmd.go userinfo -V 1.0.1 -v --force -di ./sub/dir
error => clapper.ErrorUnknownFlag{Name:"di", IsShort:false}

$ go run cmd.go userinfo -V 1.0.1 -v --force --directory ./sub/dir
error => clapper.ErrorUnknownFlag{Name:"directory", IsShort:false}

$ go run cmd.go userinfo -V 1.0.1 -v --force -directory=./sub/dir
error => clapper.ErrorUnknownFlag{Name:"directory", IsShort:false}
Example 5

When information was intended to be a sub-command but not registered.

$ go run cmd.go information --force

sub-command => ""
argument-value => &clapper.Arg{Name:"output", DefaultValue:"", Value:"information"}
flag-value => &clapper.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:"true"}
flag-value => &clapper.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:""}
flag-value => &clapper.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"", Value:""}
flag-value => &clapper.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:""}
Example 6

When a sub-command is executed.

$ go run cmd.go info thatisuday -V -v --output ./opt/dir

sub-command => "info"
argument-value => &clapper.Arg{Name:"username", DefaultValue:"", Value:"thatisuday"}
argument-value => &clapper.Arg{Name:"category", DefaultValue:"manager", Value:""}
flag-value => &clapper.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"1.0.1", Value:""}
flag-value => &clapper.Flag{Name:"output", ShortName:"o", IsBoolean:false, DefaultValue:"./", Value:"./opt/dir"}
flag-value => &clapper.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
Example 7

When the position of arguments' values are changed and extra argument values are provided.

$ go run cmd.go info -v thatisuday -V 2.0.0 teachers extra
$ go run cmd.go info thatisuday -v --version=2.0.0 teachers extra
$ go run cmd.go info thatisuday teachers extra -v -V=2.0.0

sub-command => "info"
argument-value => &clapper.Arg{Name:"username", DefaultValue:"", Value:"thatisuday"}
argument-value => &clapper.Arg{Name:"category", DefaultValue:"manager", Value:"teachers"}
flag-value => &clapper.Flag{Name:"output", ShortName:"o", IsBoolean:false, DefaultValue:"./", Value:""}
flag-value => &clapper.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
flag-value => &clapper.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"1.0.1", Value:"2.0.0"}
Example 8

When a sub-command is registered without any flags.

$ go run cmd.go ghost -v thatisuday -V 2.0.0 teachers extra

error => clapper.ErrorUnknownFlag{Name:"v", IsShort:true}
Example 9

When a sub-command is registered without any arguments.

$ go run cmd.go ghost
$ go run cmd.go ghost thatisuday extra

sub-command => "ghost
Example 10

When the root command is not registered or the root command is registered with no arguments.

$ NO_ROOT= go run cmd.go information
error => clapper.ErrorUnknownCommand{Name:"information"}

$ go run cmd.go ghost
sub-command => "ghost"
Example 11

When unsupported flag format is provided.

$ go run cmd.go ---version 
error => clapper.ErrorUnsupportedFlag{Name:"---version"}

$ go run cmd.go ---v=1.0.0 
error => clapper.ErrorUnsupportedFlag{Name:"---v"}

$ go run cmd.go -version 
error => clapper.ErrorUnsupportedFlag{Name:"-version"}

Contribution

A lot of improvements can be made to this library, one of which is the support for combined short flags, like -abc. If you are willing to contribute, create a pull request and mention your bug fixes or enhancements in the comment.

Documentation

Overview

Package clapper processes the command line arguments of getopt(3) syntax. This package provides the ability to process the root command, sub commands, command line arguments and command line flags.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Arg 

type Arg struct {
	// name of the argument
	Name string

	// default value of the argument
	DefaultValue string

	// value of the argument (provided by the user)
	Value string
}

Arg type holds the structured information about the command line argument

type Carg 

type Carg struct {

	// name of the command executed
	Cmd string

	// command line flags
	Flags map[string]*Flag

	// registered command argument values
	Args map[string]*Arg
	// contains filtered or unexported fields
}

Carg type holds the structured information about the command line arguments

func (*Carg) AddArg 

func (carg *Carg) AddArg(name string, defaultValue string) *Carg

AddArg registers a "Arg" value

func (*Carg) AddFlag 

func (carg *Carg) AddFlag(name string, shortName string, isBool bool, defaultValue string) *Carg

AddFlag method registeres a "Flag" value

type ErrorUnknownCommand 

type ErrorUnknownCommand struct {
	Name string
}

ErrorUnknownCommand represents an error when command line arguments contain an unregistered command.

func (ErrorUnknownCommand) Error 

func (e ErrorUnknownCommand) Error() string

type ErrorUnknownFlag 

type ErrorUnknownFlag struct {
	Name    string
	IsShort bool
}

ErrorUnknownFlag represents an error when command line arguments contain an unregistered flag.

func (ErrorUnknownFlag) Error 

func (e ErrorUnknownFlag) Error() string

type ErrorUnsupportedFlag added in v1.0.3 

type ErrorUnsupportedFlag struct {
	Name string
}

ErrorUnsupportedFlag represents an error when command line arguments contain an unsupported flag.

func (ErrorUnsupportedFlag) Error added in v1.0.3 

func (e ErrorUnsupportedFlag) Error() string

type Flag 

type Flag struct {

	// long name of the flag
	Name string

	// short name of the flag
	ShortName string

	// if flag holds boolean value
	IsBoolean bool

	// default value of the flag
	DefaultValue string

	// value of the flag (provided by the user)
	Value string
}

Flag type holds the structured information about the command line flag

type Registry 

type Registry map[string]*Carg

Registry holds the configuration of the registered commands.

func NewRegistry 

func NewRegistry() Registry

NewRegistry returns new instance of the "Registry"

func (Registry) Parse 

func (registry Registry) Parse(values []string) (*Carg, error)

Parse method parses command line arguments and returns an appropriate "Carg" object registered in the registry. If command is not registered, return `ErrorUnknownCommand` error If flag is not registered, return `ErrorUnknownFlag` error

func (Registry) Register 

func (registry Registry) Register(name string) *Carg

Register method registers a command. The "name" argument should be a simple string. If "name" is empty, it is considered as a root command. If a command is already registered, the registered command is returned.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.