subcmd

README

koron-go/subcmd

koron-go/subcmd is very easy and very simple sub-commander library. It focuses solely on providing a hierarchical subcommand mechanism. It does not provide any flags nor options.

Getting Started

Install or update:

$ go install github.com/koron-go/subcmd@latest

The basic usage consists of just 3 steps.

1. Define commands with function.

   package item
   
   import "github.com/koron-go/subcmd"
   
   var List = subcmd.DefineCommand("list", "list items", func(ctx context.Context, args []string) error {
       // TODO: list your items (A)
       return nil
   })
   
   var Add = subcmd.DefineCommand("add", "add a new item", func(ctx context.Context, args []string) error {
       // TODO: add a your item (B)
       return nil
   })
   

2. Define command sets by bundling the defined commands.

   package item
   
   var CommandSet = subcmd.DefineSet("item", "operate items", List, Add)
   

   Similarly, assume that multiple commands (List/Add/Delete) have been defined for user package.

   package user
   
   var CommandSet = subcmd.DefineSet("user", "operate users", List, Add, Delete)
   

3. Call function subcmd.Run() with the defined set from main().

   package main
   
   import (
       "log"
       "os"
   
       "github.com/koron-go/subcmd"
   
       "{some/pacakge/path}/item"
       "{some/package/path}/user"
   )
   
   var rootSet = subcmd.DefineRootSet(
       item.CommandSet,
       user.CommandSet,
   )
   
   func main() {
       if err := subcmd.Run(rootSet, os.Args[1:]...); err != nil {
           log.Fatal(err)
       }
   }
   

This will enable you to use subcommands such as the following:

# This call (A)
$ myprog item list

# This call (B)
$ myprog item add

# List subcommands in "item" command set
$ myprog item --help

# Same about "user" command set.
$ myprog user list
$ myprog user add
$ myprog user delete
$ myprog user --help

Concept

• Want to write each command as a function.
• Want to associate command name and description with a function.
• Want to make commands and command sets reusable, and re-assemblable.
• Don't want to use types that are not in the standard library in the function signature.
• Don't want to declare a struct or define a type instead of a function.

Documentation

Overview

Package subcmd provides sub commander.

Index

• func FlagSet(ctx context.Context) *flag.FlagSet
• func Names(ctx context.Context) []string
• func Run(r Runner, args ...string) error
• type Command
  • func DefineCommand(name, desc string, fn CommandFunc) Command
  • func (c Command) Desc() string
  • func (c Command) Name() string
  • func (c Command) Run(ctx context.Context, args []string) error
• type CommandFunc
• type Runner
• type Set
  • func DefineRootSet(runners ...Runner) Set
  • func DefineSet(name, desc string, runners ...Runner) Set
  • func (s Set) Desc() string
  • func (s Set) Name() string
  • func (s Set) Run(ctx context.Context, args []string) error

Functions

func FlagSet

func FlagSet(ctx context.Context) *flag.FlagSet

FlagSet creates a new flag.FlagSet with name of subcommand.

func Names

func Names(ctx context.Context) []string

Names retrives names layer of current sub command.

func Run

func Run(r Runner, args ...string) error

Run runs a Runner with ctx and args.

Types

type Command

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

Command repreesents a sub-command, and implements Runner interface.

func DefineCommand

func DefineCommand(name, desc string, fn CommandFunc) Command

DefineCommand defines a Command with name, desc, and function.

func (Command) Desc

func (c Command) Desc() string

Desc returns description of the command.

func (Command) Name

func (c Command) Name() string

Name returns name of the command.

func (Command) Run

func (c Command) Run(ctx context.Context, args []string) error

Run executes sub-command. It will invoke CommandFunc which passed to DefineCommand.

type CommandFunc

type CommandFunc func(ctx context.Context, args []string) error

CommandFunc is handler of sub-command, and an entry point.

type Runner

type Runner interface {
	// Name returns name of runner.
	Name() string

	// Desc returns description of runner.
	Desc() string

	// Run runs runner with context and arguments.
	Run(ctx context.Context, args []string) error
}

Runner defines a base interface for Command and Set. Runner interface is defined for use only with DefineSet function.

type Set

type Set struct {
	Runners []Runner
	// contains filtered or unexported fields
}

Set provides set of Commands or nested Sets.

func DefineRootSet

func DefineRootSet(runners ...Runner) Set

DefineRootSet defines a set of Runners which used as root of Set (maybe passed to Run).

func DefineSet

func DefineSet(name, desc string, runners ...Runner) Set

DefineSet defines a set of Runners with name, and desc.

func (Set) Desc

func (s Set) Desc() string

Desc returns description of Set.

func (Set) Name

func (s Set) Name() string

Name returns name of Set.

func (Set) Run

func (s Set) Run(ctx context.Context, args []string) error