README
¶
About
yacli is an open source command line tool written in GoLang that allows developers to easily create powerful and customizable command line interfaces (CLIs) for their applications.
With yacli, you can quickly build interactive CLI applications that are easy to use and provide a rich user experience.
yacli comes with a simple and intuitive API that makes it easy to define commands, flags, and arguments for your CLI.
You can create subcommands, and define flags with short and long names.
yacli also supports various types of flags, such as boolean, string, integer, float and provides built-in support for input validation and error handling.
Features
Aesthetics and Simplicity
Commands do not require the use of global variables or init() function.
Just declaratively describe your command and let yacli do the rest.
Explicit Work With Flags and Arguments
Validation comes by default - you can take a break from arguments and flags validation.
Help Template
Verbose help message is already shipped.
How To Start
1. Install yacli
The first step is to install yacli on your system. You can do this by running the following command:
$ go get github.com/dkharms/yacli
2. Define your CLI commands
var root = yacli.NewRootCommand(
yacli.WithCommandDescription("Just prints <message> in format you specified"),
yacli.WithMutualExclusiveFlags(
yacli.NewFlag("uppercase", "u", "Print <message> in uppercase", yacli.Bool),
yacli.NewFlag("lowercase", "l", "Print <message> in lowercase", yacli.Bool),
),
yacli.WithArguments(
yacli.NewArgument("message", "Message to print", yacli.String),
yacli.NewArgument("amount", "Print <message> `n` times", yacli.Integer),
),
yacli.WithAction(echo),
)
func echo(ctx yacli.Context) error { … }
3. Build and run your CLI application
Once you have defined your CLI commands, you can build and run your application using the following commands:
$ go build
$ ./echo --uppercase true "I love Computer Science" 2
$ I LOVE COMPUTER SCIENCE
$ I LOVE COMPUTER SCIENCE
What's Next
Documentation
¶
Index ¶
- Constants
- func NewArgument(name, description string, ttype ytype, opts ...argumentOption) *argument
- func NewCommand(name string, opts ...commandOption) *command
- func NewFlag(name, short, description string, ttype ytype, opts ...flagOption) *flag
- func NewRootCommand(opts ...commandOption) *command
- func WithAction(f func(Context) error) commandOption
- func WithAlwaysTogetherFlags(flags ...*flag) commandOption
- func WithArgumentOptional(optional bool) argumentOption
- func WithArgumentValidator(v func(Argument) error) argumentOption
- func WithArguments(args ...*argument) commandOption
- func WithCommandDeprecated(d bool) commandOption
- func WithCommandDescription(desc string) commandOption
- func WithFlagDeprecated(d bool) flagOption
- func WithFlagValidator(v func(Flag) error) flagOption
- func WithFlags(flags ...*flag) commandOption
- func WithMutualExclusiveFlags(flags ...*flag) commandOption
- func WithSubcommand(subc *command) commandOption
- type Argument
- type Command
- type Context
- type Flag
Constants ¶
const ( Integer ytype = iota Integer8 Integer16 Integer32 Integer64 Float32 Float64 String Bool )
Variables ¶
This section is empty.
Functions ¶
func NewArgument ¶
func NewArgument( name, description string, ttype ytype, opts ...argumentOption, ) *argument
NewArgument creates a new argument with the given name, description, and type, and applies the specified options to it.
func NewCommand ¶
func NewCommand(name string, opts ...commandOption) *command
NewCommand creates a new command with the specified name and options.
The command is initialized with an empty flagset and commandset. It then applies the given options to the command. Returns a pointer to the created command.
func NewFlag ¶
func NewFlag(name, short, description string, ttype ytype, opts ...flagOption) *flag
NewFlag creates and returns a new Flag instance with the provided name, short name, description, and type.
func NewRootCommand ¶
func NewRootCommand(opts ...commandOption) *command
NewRootCommand returns a new instance of a `command` struct with the name of the command set to the base name of the program. It accepts an optional argument `opts`, which is a variadic parameter of `commandOption` type, representing functional options for customizing the command.
func WithAction ¶
WithAction is a commandOption that sets the action function for a command object.
This function takes a single argument, a function that accepts a Context and returns an error.
func WithAlwaysTogetherFlags ¶
func WithAlwaysTogetherFlags(flags ...*flag) commandOption
WithAlwaysTogetherFlags is a commandOption that creates a group of flags that must always be set together.
This function takes a variable number of flags as its arguments. The flags passed to this function will be added to the group, and an error will not be thrown even if one of the flags is not set.
func WithArgumentOptional ¶
func WithArgumentOptional(optional bool) argumentOption
func WithArgumentValidator ¶
WithArgumentValidator is an argumentOption function that allows adding custom validators to an argument. It takes a function with an Argument parameter that returns an error, and appends it to the argument's list of custom validators.
func WithArguments ¶
func WithArguments(args ...*argument) commandOption
WithArguments is a commandOption that adds one or more arguments to a command object.
This function takes a variable number of argument pointers as its arguments. Each argument passed to this function will be added to the command object's argument slice. If an argument with the same name has already been defined, an error will be thrown.
func WithCommandDeprecated ¶
func WithCommandDeprecated(d bool) commandOption
func WithCommandDescription ¶
func WithCommandDescription(desc string) commandOption
WithCommandDescription sets the description for a command.
The description is typically used for displaying help or usage information. It should be a brief summary of what the command does.
func WithFlagDeprecated ¶
func WithFlagDeprecated(d bool) flagOption
func WithFlagValidator ¶
func WithFlags ¶
func WithFlags(flags ...*flag) commandOption
WithFlags sets the provided flags as options for the command.
This commandOption takes a variable number of flag pointers as input and adds each flag to the command's flagset. If a flag with the same name already exists in the flagset, it will be replaced.
func WithMutualExclusiveFlags ¶
func WithMutualExclusiveFlags(flags ...*flag) commandOption
This function takes a variable number of flags as its arguments. The flags passed to this function will be added to the group, and an error will be thrown if more than one flag in the group is set.
func WithSubcommand ¶
func WithSubcommand(subc *command) commandOption
WithSubcommand returns a commandOption that adds a subcommand to a command.
The subcommand is added to the parent command's commandset using the subcommand's name as the key. The subcommand can be invoked by calling the parent command with the subcommand's name as an argument.
Types ¶
type Argument ¶
type Argument interface {
// Name returns the name of the argument.
Name() string
// Value returns the value of the argument.
Value() any
// Type returns the type of the argument.
Type() ytype
Description() string
Optional() bool
}
Argument represents a command argument.
type Command ¶
type Command interface {
// Name returns the name of the command.
Name() string
// Description returns a brief description of the command.
Description() string
// Deprecated returns a boolean indicating whether or not the command is deprecated.
Deprecated() bool
// Subcommands returns a list of subcommands that are associated with this command.
Subcommands() []Command
// Flags returns a list of flags of command.
Flags() []Flag
// Arguments returns a list of arguments that were passed to command.
Arguments() []Argument
// Usage returns a string describing how the command should be used in POSIX format.
Usage() string
// Help returns a string containing a more detailed explanation of how to use the command.
Help() string
}
Command represents a command definition which has a name, a description, flags, arguments, and an action.
type Context ¶
type Context interface {
// Flags returns a flagset object that contains
// all the flag values that were parsed.
Flags() flagset
// Arguments returns an argset object that contains
// all the positional arguments that were parsed.
Arguments() argset
}
Context is an interface that defines the methods for accessing command-line arguments and flags that were parsed by a command-line parser.
Source Files
Directories