fang

README

Fang

The CLI starter kit. A small, experimental library for batteries-included Cobra applications.

Features

• Fancy output: fully styled help and usage pages
• Fancy errors: fully styled errors
• Automatic --version: set it to the build info, or a version of your choice
• Manpages: Adds a hidden man command to generate manpages using mango[^1]
• Completions: Adds a completion command to generate shell completions
• Themeable: use the built-in theme, or make your own
• UX: Silent usage output (help is not shown after a user error)

[^1]: Default cobra man pages generates one man page for each command. This is generally fine for programs with a lot of sub commands, like git, but its an overkill for smaller programs. Mango also uses roff directly instead of converting from markdown, so it should render better looking man pages.

Usage

To use it, invoke fang.Execute passing your root *cobra.Command:

package main

import (
	"context"
	"os"

	"github.com/charmbracelet/fang"
	"github.com/spf13/cobra"
)

func main() {
	cmd := &cobra.Command{
		Use:   "example",
		Short: "A simple example program!",
	}
	if err := fang.Execute(context.Background(), cmd); err != nil {
		os.Exit(1)
	}
}

That's all there is to it!

Contributing

See contributing.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• Discord
• The Fediverse

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source

Documentation

Overview

Package fang provides styling for cobra commands.

Index

• func DefaultErrorHandler(w io.Writer, styles Styles, err error)
• func Execute(ctx context.Context, root *cobra.Command, options ...Option) error
• func StyleExamples(c *cobra.Command, styles Styles) []string
• func StyleUsage(c *cobra.Command, styles Program, complete bool) string
• type Codeblock
• type ColorScheme
  • func AnsiColorScheme(c lipgloss.LightDarkFunc) ColorScheme
  • func DefaultColorScheme(c lipgloss.LightDarkFunc) ColorScheme
  • func DefaultTheme(isDark bool) ColorScheme
• type ColorSchemeFunc
• type ErrorHandler
• type HelpContext
• type HelpRenderer
• type Option
  • func WithColorSchemeFunc(cs ColorSchemeFunc) Option
  • func WithCommit(commit string) Option
  • func WithErrorHandler(handler ErrorHandler) Option
  • func WithHelpRenderer(renderer HelpRenderer) Option
  • func WithNotifySignal(signals ...os.Signal) Option
  • func WithTheme(theme ColorScheme) Option
  • func WithVersion(version string) Option
  • func WithoutCompletions() Option
  • func WithoutManpage() Option
  • func WithoutVersion() Option
• type Program
• type Styles

Functions

func DefaultErrorHandler

func DefaultErrorHandler(w io.Writer, styles Styles, err error)

DefaultErrorHandler is the default ErrorHandler implementation.

func Execute

func Execute(ctx context.Context, root *cobra.Command, options ...Option) error

Execute applies fang to the command and executes it.

func StyleExamples

func StyleExamples(c *cobra.Command, styles Styles) []string

StyleExamples stylizes example lines for a given command.

func StyleUsage

func StyleUsage(c *cobra.Command, styles Program, complete bool) string

StyleUsage stylizes a usage line for a given command.

Types

type Codeblock

type Codeblock struct {
	Base    lipgloss.Style
	Program Program
	Text    lipgloss.Style
	Comment lipgloss.Style
}

Codeblock styles.

type ColorScheme

type ColorScheme struct {
	Base           color.Color
	Title          color.Color
	Description    color.Color
	Codeblock      color.Color
	Program        color.Color
	DimmedArgument color.Color
	Comment        color.Color
	Flag           color.Color
	FlagDefault    color.Color
	Command        color.Color
	QuotedString   color.Color
	Argument       color.Color
	Help           color.Color
	Dash           color.Color
	ErrorHeader    [2]color.Color // 0=fg 1=bg
	ErrorDetails   color.Color
}

ColorScheme describes a colorscheme.

func AnsiColorScheme

func AnsiColorScheme(c lipgloss.LightDarkFunc) ColorScheme

AnsiColorScheme is a ANSI colorscheme.

func DefaultColorScheme

func DefaultColorScheme(c lipgloss.LightDarkFunc) ColorScheme

DefaultColorScheme is the default colorscheme.

func DefaultTheme

func DefaultTheme(isDark bool) ColorScheme

DefaultTheme is the default colorscheme.

Deprecated: use DefaultColorScheme instead.

type ColorSchemeFunc

type ColorSchemeFunc = func(lipgloss.LightDarkFunc) ColorScheme

ColorSchemeFunc gets a lipgloss.LightDarkFunc and returns a ColorScheme.

type ErrorHandler

type ErrorHandler = func(w io.Writer, styles Styles, err error)

ErrorHandler handles an error, printing them to the given io.Writer.

type HelpContext

type HelpContext struct {
	Writer *colorprofile.Writer
	Styles Styles
	Width  int
}

HelpContext contains styling and writer helpers for custom help rendering.

type HelpRenderer

type HelpRenderer func(cmd *cobra.Command, ctx HelpContext)

HelpRenderer renders command help using Fang styling primitives.

type Option

type Option func(*settings)

Option changes fang settings.

func WithColorSchemeFunc

func WithColorSchemeFunc(cs ColorSchemeFunc) Option

WithColorSchemeFunc sets a function that return colorscheme.

func WithCommit

func WithCommit(commit string) Option

WithCommit sets the commit SHA.

func WithErrorHandler

func WithErrorHandler(handler ErrorHandler) Option

WithErrorHandler sets the error handler.

func WithHelpRenderer

func WithHelpRenderer(renderer HelpRenderer) Option

WithHelpRenderer sets a custom help renderer.

func WithNotifySignal

func WithNotifySignal(signals ...os.Signal) Option

WithNotifySignal sets the signals that should interrupt the execution of the program.

func WithTheme

func WithTheme(theme ColorScheme) Option

WithTheme sets the colorscheme.

Deprecated: use WithColorSchemeFunc instead.

func WithVersion

func WithVersion(version string) Option

WithVersion sets the version.

func WithoutCompletions

func WithoutCompletions() Option

WithoutCompletions disables completions.

func WithoutManpage

func WithoutManpage() Option

WithoutManpage disables man pages.

func WithoutVersion

func WithoutVersion() Option

WithoutVersion skips the `-v`/`--version` functionality.

type Program

type Program struct {
	Name           lipgloss.Style
	Command        lipgloss.Style
	Flag           lipgloss.Style
	Argument       lipgloss.Style
	DimmedArgument lipgloss.Style
	QuotedString   lipgloss.Style
}

Program name, args, flags, styling.

type Styles

type Styles struct {
	Text            lipgloss.Style
	Title           lipgloss.Style
	Span            lipgloss.Style
	ErrorHeader     lipgloss.Style
	ErrorText       lipgloss.Style
	FlagDescription lipgloss.Style
	FlagDefault     lipgloss.Style
	Codeblock       Codeblock
	Program         Program
}

Styles represents all the styles used.