Skip to content

Refactor help API#19

Draft
mfridman wants to merge 3 commits intomainfrom
mf/usage-api
Draft

Refactor help API#19
mfridman wants to merge 3 commits intomainfrom
mf/usage-api

Conversation

@mfridman
Copy link
Copy Markdown
Collaborator

@mfridman mfridman commented Apr 26, 2026

This PR reshapes help customization and usage-error handling against the API on main.

On main, custom help is Command.UsageFunc func(*Command) string, default help lives behind DefaultUsage, and flag metadata uses FlagOption / Command.FlagOptions. This branch keeps the core help surface string-based while making customization clearer:

  • Command.Help func(*Command) string replaces UsageFunc.
  • cli.Help(*Command) string renders help for the resolved command.
  • usage is optional for structured composition via Document, New, Help, Text, Lines, List, Flags, and Commands.
  • State.Cmd exposes the resolved command inside Exec.
  • cli.UsageErrorf marks invalid command-line usage from Exec; Run prints help before returning the underlying error.
  • FlagConfig / Command.FlagConfigs replace FlagOption / Command.FlagOptions.

Why: the default path stays small and automatic, while callers that want richer help can opt into usage without making structured documents part of the core API.

Examples:

// main
cmd.UsageFunc = func(c *cli.Command) string {
    return "custom help"
}

// this PR
cmd.Help = func(c *cli.Command) string {
    return "custom help"
}
// keep the default help and add examples
cmd.Help = func(c *cli.Command) string {
    doc := usage.New(c)
    doc = append(doc, usage.Lines("Examples:", "greet margo"))
    return doc.String()
}
// print command help for invalid args discovered in Exec
Exec: func(ctx context.Context, s *cli.State) error {
    if len(s.Args) == 0 {
        return cli.UsageErrorf("must supply a name")
    }
    return nil
},

Breaking changes:

  • Remove Command.UsageFunc; use Command.Help.
  • Remove DefaultUsage and Usage; use cli.Help(cmd).
  • Rename FlagOption to FlagConfig and Command.FlagOptions to Command.FlagConfigs.

Closes #4, #14, #15.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add ability to get command information from *State

1 participant