bismarck

README

Bismarck

Bismarck is a framework for command-line interfaces. If you're building systems in Go, we believe it's a very useful option. By using Bismarck, you can easily create a subcommand-based CLI.

Bismarck has the following features:

• Simple: With limited functionality, it requires minimal learning effort.
• Fast: Processing is fast and does not slow down execution.
• Help: Automatically generates help sub command.

We hope you have a wonderful development experience with Bismarck.

Quick Start

You just add structures that implement the SubCommand interface to the Bismarck structure. You can automatically retrieve subcommand options by declaring them as tagged fields in the structure. In the following example, we are creating the build command as a subcommand. We have configured it so that the optimization level can be specified as an option for the subcommand.

package main

import (
	"fmt"

	"github.com/tsukinoha/bismarck"
)

type (
	Build struct {
		Optimize int `bismarck:"short=o,long=optimize,desc=optimize level,required"`
	}
)

func (b *Build) Init() {
	println("Initialize")
}

func (b *Build) Run(ctx *bismarck.Context) error {
	fmt.Printf("Optimize level: %d", b.Optimize)
	return nil
}

func main() {
	cmd := bismarck.New("sample")
	cmd.Add(&Build{}, "build", "build the binary from the source files.")
	cmd.Run()
}

When you run the code above, the following output is displayed.

$ go run main.go build -o 2
Initialize
Optimize level: 2

Usage

Sub Command

The requirements for a structure to be registered as a subcommand are simple: it must implement the bismarck.SubCommand interface. That’s all there is to it. The bismarck.SubCommand interface requires the implementation of the following two functions:

• Init()
• Run(*bismarck.Context) error

Options

Subcommands allow you to declaratively define options by using tags on fields of structures that implement the SubCommand interface. The types of fields that can be used as options are as follows:

• string
• bool
• int
• int8
• int16
• int32
• int64
• uint
• uint8
• uint16
• uint32
• uint64
• float32
• float64
• time.Time

The following items can be configured using tags.

Item	Description
short	Short option name. 1 character from numerics or alphabets(0-9 a-z A-Z). Either short or long is required.
long	Long option name. 2 to 15 characters from numerics, alphabets, hyphen or undersocre(0-9 a-z A-Z - _). Either short or long is required.
required	required option.
desc	Description. Displayed within the help command.
format	format for time.Time. time package format or custom layouts (e.g. 2006/01/02)

Build struct {
  Label string `bismarck:"short=l,long=label,desc=display name,required"`
  Today time.Time `bismarck:"short=t,desc=today,format=RFC3339"`
}

Documentation

Index

• func Debug(msg string, args ...any)
• type Command
  • func New(name string) *Command
  • func (cmd *Command) Add(subCmd SubCommand, name, desc string) error
  • func (cmd *Command) Run() error
  • func (cmd *Command) Use(middleware MiddlewareFunc)
• type Context
  • func (ctx *Context) Arg(i int) string
  • func (ctx *Context) Args() []string
  • func (ctx *Context) Database() (*sql.Conn, error)
  • func (ctx *Context) Get(key string) any
  • func (ctx *Context) Location() *time.Location
  • func (ctx *Context) NumArg() int
  • func (ctx *Context) NumRawArg() int
  • func (ctx *Context) RawArg(i int) string
  • func (ctx *Context) RawArgs() []string
  • func (ctx *Context) Set(key string, value any)
  • func (ctx *Context) SetDatabase(db *sql.DB)
  • func (ctx *Context) SetLocation(loc *time.Location)
  • func (ctx *Context) StartTime(command bool) time.Time
• type HandlerFunc
• type Kind
• type MiddlewareFunc
• type SubCommand
• type SubCommandBucket

Functions

func Debug

func Debug(msg string, args ...any)

Types

type Command

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

func New

func New(name string) *Command

func (*Command) Add

func (cmd *Command) Add(subCmd SubCommand, name, desc string) error

func (*Command) Run

func (cmd *Command) Run() error

func (*Command) Use

func (cmd *Command) Use(middleware MiddlewareFunc)

type Context

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

func (*Context) Arg

func (ctx *Context) Arg(i int) string

func (*Context) Args

func (ctx *Context) Args() []string

func (*Context) Database

func (ctx *Context) Database() (*sql.Conn, error)

func (*Context) Get

func (ctx *Context) Get(key string) any

func (*Context) Location

func (ctx *Context) Location() *time.Location

func (*Context) NumArg

func (ctx *Context) NumArg() int

func (*Context) NumRawArg

func (ctx *Context) NumRawArg() int

func (*Context) RawArg

func (ctx *Context) RawArg(i int) string

func (*Context) RawArgs

func (ctx *Context) RawArgs() []string

func (*Context) Set

func (ctx *Context) Set(key string, value any)

func (*Context) SetDatabase

func (ctx *Context) SetDatabase(db *sql.DB)

func (*Context) SetLocation

func (ctx *Context) SetLocation(loc *time.Location)

func (*Context) StartTime

func (ctx *Context) StartTime(command bool) time.Time

type HandlerFunc

type HandlerFunc func(ctx *Context) error

type Kind

type Kind int

const (
	Unknown Kind = iota
	String
	Bool
	Int
	Int8
	Int16
	Int32
	Int64
	Uint
	Uint8
	Uint16
	Uint32
	Uint64
	Float32
	Float64
	Time
)

type MiddlewareFunc

type MiddlewareFunc func(next HandlerFunc) HandlerFunc

type SubCommand

type SubCommand interface {
	Init()
	Run(*Context) error
}

type SubCommandBucket

type SubCommandBucket struct {
	Name string
	Desc string
	// contains filtered or unexported fields
}