cargs

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Mar 28, 2020 License: MIT Imports: 2 Imported by: 0

README

cargs

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

Installation

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

Usage

// cmd.go
package main

import "github.com/thatisuday/cargs"

func main() {
    
    // create new registry
	registry := cargs.NewRegistry()

	// register the root command
	registry.
		Register("").
		AddArg("output").
		AddFlag("force", "f", true, "").
		AddFlag("verbose", "v", true, "").
		AddFlag("version", "V", false, "").
		AddFlag("dir", "", false, "/var/users")

	// register the `info` command
	registry.
		Register("info").
		AddArg("username").
		AddArg("category").
		AddFlag("verbose", "v", true, "").
		AddFlag("version", "V", false, "1.0.1").
        AddFlag("output", "o", false, "./")
    
    // register the `ghost` 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 command name
	fmt.Printf("Command Name => %#v\n", carg.Cmd)

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

	// get flag values
	for _, v := range carg.Flags {
		fmt.Printf("Flag => %#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
$ go run cmd.go

Command Name => ""
Arg => &cargs.Arg{Name:"output", Value:""}
Flag => &cargs.Flag{Name:"version", ShortName:"V", IsBoolean:true, DefaultValue:"false", Value:""}
Flag => &cargs.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:""}
Flag => &cargs.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:""}
Flag => &cargs.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:""}
Example 2
$ go run cmd.go userinfo -V 1.0.1 -v --force --dir ./sub/dir
$ go run cmd.go -V 1.0.1 -v --force userinfo --dir ./sub/dir
$ go run cmd.go -V 1.0.1 -v --force --dir ./sub/dir userinfo
$ go run cmd.go -V 1.0.1 -v --force -dir ./sub/dir userinfo

Command Name => ""
Arg => &cargs.Arg{Name:"output", Value:"userinfo"}
Flag => &cargs.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
Flag => &cargs.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"", Value:"1.0.1"}
Flag => &cargs.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:"./sub/dir"}
Flag => &cargs.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:"true"}
Example 3
$ go run cmd.go userinfo -V 1.0.1 -v --force -d ./sub/dir
Error => cargs.ErrorUnknownFlag{Name:"d", IsShort:true}

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

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

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

$ go run cmd.go userinfo -V 1.0.1 -v --force -directory ./sub/dir
Error => cargs.ErrorUnknownFlag{Name:"directory", IsShort:false}
Example 4
$ go run cmd.go information --force

Command Name => ""
Arg => &cargs.Arg{Name:"output", Value:"information"}
Flag => &cargs.Flag{Name:"force", ShortName:"f", IsBoolean:true, DefaultValue:"false", Value:"true"}
Flag => &cargs.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:""}
Flag => &cargs.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"", Value:""}
Flag => &cargs.Flag{Name:"dir", ShortName:"", IsBoolean:false, DefaultValue:"/var/users", Value:""}
Example 5
$ go run cmd.go info thatisuday teachers -V -v --output ./opt/dir extra

Command Name => "info"
Arg => &cargs.Arg{Name:"username", Value:"thatisuday"}
Arg => &cargs.Arg{Name:"category", Value:"teachers"}
Flag => &cargs.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
Flag => &cargs.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"1.0.1", Value:""}
Flag => &cargs.Flag{Name:"output", ShortName:"o", IsBoolean:false, DefaultValue:"./", Value:"./opt/dir"}
Example 6
$ go run cmd.go info -v thatisuday -V 2.0.0  teachers extra
$ go run cmd.go info thatisuday -v -V 2.0.0  teachers extra
$ go run cmd.go info thatisuday teachers extra -v -V 2.0.0

Command Name => "info"
Arg => &cargs.Arg{Name:"username", Value:"thatisuday"}
Arg => &cargs.Arg{Name:"category", Value:"teachers"}
Flag => &cargs.Flag{Name:"verbose", ShortName:"v", IsBoolean:true, DefaultValue:"false", Value:"true"}
Flag => &cargs.Flag{Name:"version", ShortName:"V", IsBoolean:false, DefaultValue:"1.0.1", Value:"2.0.0"}
Flag => &cargs.Flag{Name:"output", ShortName:"o", IsBoolean:false, DefaultValue:"./", Value:""}
Example 7
$ go run cmd.go ghost -v thatisuday -V 2.0.0 teachers extra

Error => cargs.ErrorUnknownFlag{Name:"v", IsShort:true}
Example 8
$ go run cmd.go ghost
$ go run cmd.go ghost thatisuday extra

Command Name => "ghost

Contribution

I am looking for some contributors for writing better test cases and documentation.

Documentation

Overview

Package cargs 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  string
	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) *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 contains 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 contains an unregistered flag.

func (ErrorUnknownFlag) Error 

func (e ErrorUnknownFlag) 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
	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.