flagforge

README

flagforge

flagforge allows you to automatically generate Go flag code, as well as the associated Markdown and HTML documentation for those flags, all using a single configuration file. This means you only have to define your command-line options once in a TOML file, and flagforge will do the rest.

Running flagforge

Clone the repo and execute go build. Pass -h to flagforge to learn how to use it.

flagforge -f go|markdown|html <TOML file>

Example usage

rqlite uses flagforge to generate the code and documentation for its extensive set of command-line flags:

• rqlite TOML file
• Generated Go code for command-line flag parsing, and then calling the generated code from rqlite.
• Example of automatically generated HTML documentation for the flags deployed to production site. You can review the generated HTML here.

Documentation

Index

• type Argument
• type Flag
• type Format
  • func (f Format) String() string
• type Generator
  • func NewGenerator(cfg *ParsedConfig) (*Generator, error)
  • func (g *Generator) Execute(f Format, w io.Writer) error
• type GoConfig
• type ParsedConfig
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) ParsePath(path string) (*ParsedConfig, error)
  • func (p *Parser) ParseReader(r io.Reader) (*ParsedConfig, error)

Types

type Argument

type Argument struct {
	Name      string `mapstructure:"name"`
	Type      string `mapstructure:"type"`
	Required  bool   `mapstructure:"required"`
	ShortHelp string `mapstructure:"short_help"`
	LongHelp  string `mapstructure:"long_help"`
}

Argument represents a single argument configuration.

type Flag

type Flag struct {
	Name      string      `mapstructure:"name"`
	CLI       string      `mapstructure:"cli"`
	Type      string      `mapstructure:"type"`
	Delimiter string      `mapstructure:"delimiter"`
	Default   interface{} `mapstructure:"default"`
	ShortHelp string      `mapstructure:"short_help"`
	LongHelp  string      `mapstructure:"long_help"`
}

Flag represents a single flag configuration.

type Format

type Format int

Format represents the output format of the generator.

const (
	Go Format = iota
	Markdown
	HTML
)

func (Format) String

func (f Format) String() string

String returns the string representation of the format.

type Generator

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

Generator represents a flag, HTML, or Markdown generator.

func NewGenerator

func NewGenerator(cfg *ParsedConfig) (*Generator, error)

NewGenerator creates a new generator with the given package name, name, and path to the TOML configuration file.

func (*Generator) Execute

func (g *Generator) Execute(f Format, w io.Writer) error

Execute generates the output in the given format and writes it to the given writer.

type GoConfig

type GoConfig struct {
	Package           string `mapstructure:"package"`
	ConfigTypeName    string `mapstructure:"config_type_name"`
	FlagSetUsage      string `mapstructure:"flag_set_usage"`
	FlagSetName       string `mapstructure:"flag_set_name"`
	FlagErrorHandling string `mapstructure:"flag_error_handling"`
}

GoConfig represents the configuration for the generated Go code.

type ParsedConfig

type ParsedConfig struct {
	GoConfig  GoConfig
	Arguments []Argument
	Flags     []Flag
}

type Parser

type Parser struct {
}

func NewParser

func NewParser() *Parser

func (*Parser) ParsePath

func (p *Parser) ParsePath(path string) (*ParsedConfig, error)

func (*Parser) ParseReader

func (p *Parser) ParseReader(r io.Reader) (*ParsedConfig, error)