mango

README

mango

mango is a man-page generator for the Go flag, pflag, cobra, coral, and kong packages. It extracts commands, flags, and arguments from your program and enables it to self-document.

Adapters

Currently the following adapters exist:

• flag: support for Go's standard flag package
• mango-cobra: an adapter for cobra
• mango-coral: an adapter for coral
• mango-kong: an adapter for kong
• mango-pflag: an adapter for the pflag package

Usage with flag:

import (
    "flag"
    "fmt"

    "github.com/muesli/mango"
    "github.com/muesli/mango/mflag"
    "github.com/muesli/roff"
)

var (
    one = flag.String("one", "", "first value")
    two = flag.String("two", "", "second value")
)

func main() {
    flag.Parse()

    manPage := mango.NewManPage(1, "mango", "a man-page generator").
        WithLongDescription("mango is a man-page generator for Go.\n"+
            "Features:\n"+
            "* User-friendly\n"+
            "* Plugable").
        WithSection("Copyright", "(C) 2022 Christian Muehlhaeuser.\n"+
            "Released under MIT license.")

    flag.VisitAll(mflag.FlagVisitor(manPage))
    fmt.Println(manPage.Build(roff.NewDocument()))
}

Mango will extract all the flags from your app and generate a man-page similar to this example:

Usage with pflag:

import (
    "fmt"

    "github.com/muesli/mango"
    mpflag "github.com/muesli/mango-pflag"
    "github.com/muesli/roff"
    flag "github.com/spf13/pflag"
)

func main() {
    flag.Parse()

    manPage := mango.NewManPage(1, "mango", "a man-page generator").
        WithLongDescription("mango is a man-page generator for Go.").
        WithSection("Copyright", "(C) 2022 Christian Muehlhaeuser.\n"+
            "Released under MIT license.")

    flag.VisitAll(mpflag.PFlagVisitor(manPage))
    fmt.Println(manPage.Build(roff.NewDocument()))
}

Usage with cobra:

import (
	"fmt"

	mcobra "github.com/muesli/mango-cobra"
	"github.com/muesli/roff"
	"github.com/spf13/cobra"
)

var (
    rootCmd = &cobra.Command{
        Use:   "mango",
        Short: "A man-page generator",
    }
)

func main() {
    manPage, err := mcobra.NewManPage(1, rootCmd)
    if err != nil {
        panic(err)
    }

    manPage = manPage.WithSection("Copyright", "(C) 2022 Christian Muehlhaeuser.\n"+
        "Released under MIT license.")

    fmt.Println(manPage.Build(roff.NewDocument()))
}

Usage with coral:

import (
	"fmt"

	mcoral "github.com/muesli/mango-coral"
	"github.com/muesli/roff"
	"github.com/muesli/coral"
)

var (
    rootCmd = &coral.Command{
        Use:   "mango",
        Short: "A man-page generator",
    }
)

func main() {
    manPage, err := mcoral.NewManPage(1, rootCmd)
    if err != nil {
        panic(err)
    }

    manPage = manPage.WithSection("Copyright", "(C) 2022 Christian Muehlhaeuser.\n"+
        "Released under MIT license.")

    fmt.Println(manPage.Build(roff.NewDocument()))
}

Feedback

Got some feedback or suggestions? Please open an issue or drop me a note!

• Twitter
• The Fediverse

Documentation

Index

• type Builder
• type Command
  • func NewCommand(name string, short string, usage string) *Command
  • func (m *Command) AddCommand(c *Command) error
  • func (m *Command) AddFlag(f Flag) error
• type Flag
• type ManPage
  • func NewManPage(section uint, title string, description string) *ManPage
  • func (m ManPage) Build(w Builder) string
  • func (m *ManPage) WithLongDescription(desc string) *ManPage
  • func (m *ManPage) WithSection(section string, text string) *ManPage
• type Section

Types

type Builder

type Builder interface {
	Heading(section uint, title, description string, ts time.Time)
	Paragraph()
	Indent(n int)
	IndentEnd()
	TaggedParagraph(indentation int)
	List(text string)
	Section(text string)
	EndSection()
	Text(text string)
	TextBold(text string)
	TextItalic(text string)
	String() string
}

Builder is the interface of a man page builder.

type Command

type Command struct {
	Name     string
	Short    string
	Usage    string
	Example  string
	Flags    map[string]Flag
	Commands map[string]*Command
}

Command represents a command.

func NewCommand

func NewCommand(name string, short string, usage string) *Command

NewCommand returns a new Command.

func (*Command) AddCommand

func (m *Command) AddCommand(c *Command) error

AddCommand adds a sub-command.

func (*Command) AddFlag

func (m *Command) AddFlag(f Flag) error

AddFlag adds a flag to the command.

type Flag

type Flag struct {
	Name  string
	Short string
	Usage string
	PFlag bool
}

Flag represents a flag.

type ManPage

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

ManPage represents a man page generator.

func NewManPage

func NewManPage(section uint, title string, description string) *ManPage

NewManPage returns a new ManPage generator instance.

func (ManPage) Build

func (m ManPage) Build(w Builder) string

Build generates the man page.

func (*ManPage) WithLongDescription

func (m *ManPage) WithLongDescription(desc string) *ManPage

WithLongDescription sets the long description.

func (*ManPage) WithSection

func (m *ManPage) WithSection(section string, text string) *ManPage

WithSection adds a section to the man page.

type Section

type Section struct {
	Name string
	Text string
}

Section represents a section.