boot

README

micro-boot

English | 简体中文

Framework insensitive microservices booter for Golang.

Documentation

Overview

This file is modified according to https://github.com/peterbourgon/ff/ffcli and https://github.com/ALiuGuanyan/ff/ffcli

Index

• func DotEnvParser(r io.Reader, set func(name, value string) error) error
• func Parse(fs *pflag.FlagSet, args []string, options ...Option) error
• func PlainParser(r io.Reader, set func(name, value string) error) error
• func SetDefaultConfigFileDirectory(val string)
• func SetDefaultConfigFileFlagName(val string)
• func SetDefaultConfigFileFlagShortHand(val string)
• func SetDefaultConfigFileFlagUsage(val string)
• func SetDefaultConfigFileName(val string)
• func SetDefaultConfigFileType(val string)
• func SetDefaultLogFileDirectory(val string)
• func SetDefaultLogFileFlagName(val string)
• func SetDefaultLogFileFlagShortHand(val string)
• func SetDefaultLogFileFlagUsage(val string)
• type Boot
  • func New(name string, server Booter, config Root) (bt Boot, err error)
• type Booter
• type Command
  • func (c *Command) Parse(args []string) error
  • func (c *Command) ParseAndRun(ctx context.Context, args []string) error
  • func (c *Command) Run(ctx context.Context) (err error)
• type Config
• type ConfigFileParser
• type Configurator
• type Option
  • func WithAllowMissingConfigFile(allow bool) Option
  • func WithConfigFile(filename string) Option
  • func WithConfigFileFlag(flagname string) Option
  • func WithConfigFileParser(p ConfigFileParser) Option
  • func WithConfigFileVia(filename *string) Option
  • func WithEnvVarNoPrefix() Option
  • func WithEnvVarPrefix(prefix string) Option
  • func WithEnvVarSplit(delimiter string) Option
  • func WithIgnoreUndefined(ignore bool) Option
• type ParseError
  • func (e ParseError) Error() string
  • func (e ParseError) Unwrap() error
• type Root

Functions

func DotEnvParser

func DotEnvParser(r io.Reader, set func(name, value string) error) error

func Parse

func Parse(fs *pflag.FlagSet, args []string, options ...Option) error

Parse the flags in the flag set from the provided (presumably commandline) args. Additional options may be provided to parse from a config file and/or environment variables in that priority order.

func PlainParser

func PlainParser(r io.Reader, set func(name, value string) error) error

PlainParser is a parser for config files in an extremely simple format. Each line is tokenized as a single key/value pair. The first whitespace-delimited token in the line is interpreted as the flag name, and all remaining tokens are interpreted as the value. Any leading hyphens on the flag name are ignored.

func SetDefaultConfigFileDirectory

func SetDefaultConfigFileDirectory(val string)

func SetDefaultConfigFileFlagName

func SetDefaultConfigFileFlagName(val string)

func SetDefaultConfigFileFlagShortHand

func SetDefaultConfigFileFlagShortHand(val string)

func SetDefaultConfigFileFlagUsage

func SetDefaultConfigFileFlagUsage(val string)

SetDefaultConfigFileFlagUsage will set the default config flag usage.

eg. SetDefaultConfigFileFlagUsage("specify the config file")

The output:

-c, --config specify the config file

func SetDefaultConfigFileName

func SetDefaultConfigFileName(val string)

func SetDefaultConfigFileType

func SetDefaultConfigFileType(val string)

func SetDefaultLogFileDirectory

func SetDefaultLogFileDirectory(val string)

SetDefaultLogFileDirectory will set the default directory to store the log file.

eg. SetDefaultLogFileDirectory("/var/log")

func SetDefaultLogFileFlagName

func SetDefaultLogFileFlagName(val string)

func SetDefaultLogFileFlagShortHand

func SetDefaultLogFileFlagShortHand(val string)

func SetDefaultLogFileFlagUsage

func SetDefaultLogFileFlagUsage(val string)

SetDefaultLogFileFlagUsage will set the default log flag usage.

eg. SetDefaultLogFileFlagUsage("specify the log file")

The output:

-l, --log specify the log file

Types

type Boot

type Boot interface {
	Execute() (err error)
}

func New

func New(name string, server Booter, config Root) (bt Boot, err error)

type Booter

type Booter interface {
	Serve() (err error)
	Close() (err error)
}

type Command

type Command struct {
	// Name of the command. Used for sub-command matching, and as a replacement
	// for Usage, if no Usage string is provided. Required for sub-commands,
	// optional for the root command.
	Name string

	// ShortUsage string for this command. Consumed by the DefaultusageFunc and
	// printed at the top of the help output. Recommended but not required.
	// Should be one line of the form
	//
	//     cmd [flags] subcmd [flags] <required> [<optional> ...]
	//
	// If it's not provided, the DefaultusageFunc will use Name instead.
	// Optional, but recommended.
	ShortUsage string

	// ShortHelp is printed next to the command name when it appears as a
	// sub-command, in the help output of its parent command. Optional, but
	// recommended.
	ShortHelp string

	// LongHelp is consumed by the DefaultusageFunc and printed in the help
	// output, after ShortUsage and before flags. Typically a paragraph or more
	// of prose-like text, providing more explicit context and guidance than
	// what is implied by flags and arguments. Optional.
	LongHelp string

	// FlagSet associated with this command. Optional, but if none is provided,
	// an empty FlagSet will be defined and attached during the parse phase, so
	// that the -h flag works as expected.
	FlagSet *bootflag.FlagSet

	// Options provided to ff.Parse when parsing arguments for this command.
	// Optional.
	Options []Option

	// Subcommands accessible underneath (i.e. after) this command. Optional.
	Subcommands []*Command

	// Hidden is used to make command invisible.
	Hidden bool

	// Exec is invoked if this command has been determined to be the terminal
	// command selected by the arguments provided to Parse or ParseAndRun. The
	// args passed to Exec are the args left over after flags parsing. Optional.
	//
	// If Exec returns flag.ErrHelp, then Run (or ParseAndRun) will behave as if
	// -h were passed and emit the complete usage output.
	//
	// If Exec is nil, and this command is identified as the terminal command,
	// then Parse, Run, and ParseAndRun will all return noExecError. Callers may
	// check for this error and print e.g. help or usage text to the user, in
	// effect treating some commands as just collections of subcommands, rather
	// than being invocable themselves.
	Exec func(ctx context.Context, args []string) error
	// contains filtered or unexported fields
}

Command combines a main function with a flag.FlagSet, and zero or more sub-commands. A commandline program can be represented as a declarative tree of commands.

func (*Command) Parse

func (c *Command) Parse(args []string) error

Parse the commandline arguments for this command and all sub-commands recursively, defining flags along the way. If Parse returns without an error, the terminal command has been successfully identified, and may be invoked by calling Run.

If the terminal command identified by Parse doesn't define an Exec function, then Parse will return noExecError.

func (*Command) ParseAndRun

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

ParseAndRun is a helper function that calls Parse and then Run in a single invocation. It's useful for simple command trees that don't need two-phase setup.

func (*Command) Run

func (c *Command) Run(ctx context.Context) (err error)

Run selects the terminal command in a command tree previously identified by a successful call to Parse, and calls that command's Exec function with the appropriate subset of commandline args.

If the terminal command previously identified by Parse doesn't define an Exec function, then Run will return noExecError.

type Config

type Config struct {
	// ShortUsage string for this command. Consumed by the DefaultusageFunc and
	// printed at the top of the help output. Recommended but not required.
	// Should be one line of the form
	//
	//     cmd [flags] subcmd [flags] <required> [<optional> ...]
	//
	// If it's not provided, the DefaultusageFunc will use Name instead.
	// Optional, but recommended.
	ShortUsage string

	// ShortHelp is printed next to the command name when it appears as a
	// sub-command, in the help output of its parent command. Optional, but
	// recommended.
	ShortHelp string

	// LongHelp is consumed by the DefaultusageFunc and printed in the help
	// output, after ShortUsage and before flags. Typically a paragraph or more
	// of prose-like text, providing more explicit context and guidance than
	// what is implied by flags and arguments. Optional.
	LongHelp string

	Configurator Configurator

	Options []Option
}

type ConfigFileParser

type ConfigFileParser func(r io.Reader, set func(name, value string) error) error

ConfigFileParser interprets the config file represented by the reader and calls the set function for each parsed flag pair.

type Configurator

type Configurator interface {
	Initialize(name string) (err error)
	flag.Flags
}

type Option

type Option func(*pContext)

Option controls some aspect of Parse behavior.

func WithAllowMissingConfigFile

func WithAllowMissingConfigFile(allow bool) Option

WithAllowMissingConfigFile tells Parse to permit the case where a config file is specified but doesn't exist. By default, missing config files result in an error.

func WithConfigFile

func WithConfigFile(filename string) Option

WithConfigFile tells Parse to read the provided filename as a config file. Requires WithConfigFileParser, and overrides WithConfigFileFlag. Because config files should generally be user-specifiable, this option should be rarely used. Prefer WithConfigFileFlag.

func WithConfigFileFlag

func WithConfigFileFlag(flagname string) Option

WithConfigFileFlag tells Parse to treat the flag with the given name as a config file. Requires WithConfigFileParser, and is overridden by WithConfigFile.

To specify a default config file, provide it as the default value of the corresponding flag -- and consider also using the WithAllowMissingConfigFile option.

func WithConfigFileParser

func WithConfigFileParser(p ConfigFileParser) Option

WithConfigFileParser tells Parse how to interpret the config file provided via WithConfigFile or WithConfigFileFlag.

func WithConfigFileVia

func WithConfigFileVia(filename *string) Option

WithConfigFileVia tells Parse to read the provided filename as a config file. Requires WithConfigFileParser, and overrides WithConfigFileFlag. This is useful for sharing a single root level flag for config files among multiple ffcli subcommands.

func WithEnvVarNoPrefix

func WithEnvVarNoPrefix() Option

WithEnvVarNoPrefix tells Parse to try to set flags from environment variables without any specific prefix. Flag names are matched to environment variables by capitalizing the flag name, and replacing separator characters like periods or hyphens with underscores. By default, flags are not set from environment variables at all.

func WithEnvVarPrefix

func WithEnvVarPrefix(prefix string) Option

WithEnvVarPrefix tells Parse to try to set flags from environment variables with the given prefix. Flag names are matched to environment variables with the given prefix, followed by an underscore, followed by the capitalized flag names, with separator characters like periods or hyphens replaced with underscores. By default, flags are not set from environment variables at all.

func WithEnvVarSplit

func WithEnvVarSplit(delimiter string) Option

WithEnvVarSplit tells Parse to split environment variables on the given delimiter, and to make a call to Set on the corresponding flag with each split token.

func WithIgnoreUndefined

func WithIgnoreUndefined(ignore bool) Option

WithIgnoreUndefined tells Parse to ignore undefined flags that it encounters in config files. By default, if Parse encounters an undefined flag in a config file, it will return an error. Note that this setting does not apply to undefined flags passed as arguments.

type ParseError

type ParseError struct {
	Inner error
}

ParseError wraps all errors originating from the YAML parser.

func (ParseError) Error

func (e ParseError) Error() string

Error implenents the error interface.

func (ParseError) Unwrap

func (e ParseError) Unwrap() error

Unwrap implements the errors.Wrapper interface, allowing errors.Is and errors.As to work with ParseErrors.

type Root

type Root struct {
	Exec                  func(ctx context.Context, args []string) error
	ShortUsage            string
	ShortHelp             string
	LongHelp              string
	ErrorHandling         flag.ErrorHandling
	Start                 *Config
	Stop                  *Config
	Options               []Option
	CustomCommands        []*Command
	LocalRPCServerOptions []grpc.ServerOption
	LocalRPCDialOptions   []grpc.DialOption
}