climan

README

climan

😄 CLI manager library, heavily inspired by ffcli.

This package is originally based on peterbourgon's ff package (Apache2 License).

It implements small changes that don't fit with the original's author Goals and Non-goals.

---

Changes include:

• Adding an optional Command.FlagSetBuilder callback to configure commands and subcommands dynamically and support sharing the same flag targets.
• Using flag.ContinueOnError by default instead of flag.ExitOnError.
• Printing usage instead of an returning an error if a command does not implements an Exec func.
• Use a different DefaultUsageFunc.

Example

import (
    "context"
    "flag"
    "fmt"
    "log"
    "os"

    "moul.io/climan"
)

func Example() {
    var opts struct {
        Debug bool
    }

    root := &climan.Command{
        Name:       "example",
        ShortUsage: "example [global flags] <subcommand> [flags] [args...]",
        ShortHelp:  "example's short help",
        LongHelp:   "example's longer help.\nwith more details.",
        FlagsBuilder: func(fs *flag.FlagSet) {
            fs.BoolVar(&opts.Debug, "debug", opts.Debug, "debug mode")
        },
        Exec: func(ctx context.Context, args []string) error {
            fmt.Println("args", args)
            return nil
        },
        Subcommands: []*climan.Command{
            &climan.Command{
                Name: "sub",
            },
        },
        // Options: []climan.Option{climan.WithEnvVarPrefix("EXAMPLE")},
    }
    if err := root.Parse(os.Args[1:]); err != nil {
        log.Fatal(fmt.Errorf("parse error: %w", err))
    }

    if err := root.Run(context.Background()); err != nil {
        log.Fatal(fmt.Errorf("run error: %w", err))
    }
}

Usage

TYPES

type Command struct {
    Name         string
    Exec         func(context.Context, []string) error
    FlagsBuilder func(fs *flag.FlagSet)
    Subcommands  []*Command
    ShortUsage   string
    ShortHelp    string
    LongHelp     string

    // Has unexported fields.
}

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

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

Install

Using go

go get moul.io/climan

Releases

See https://github.com/moul/climan/releases

Contribute

I really welcome contributions. Your input is the most precious material. I'm well aware of that and I thank you in advance. Everyone is encouraged to look at what they can do on their own scale; no effort is too small.

Everything on contribution is sum up here: CONTRIBUTING.md

Dev helpers

Pre-commit script for install: https://pre-commit.com

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Manfred Touron 🚧 📖 ⚠️ 💻

moul-bot 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

Stargazers over time

License

© 2021 Manfred Touron

Licensed under the Apache License, Version 2.0 (LICENSE-APACHE) or the MIT license (LICENSE-MIT), at your option. See the COPYRIGHT file for more details.

SPDX-License-Identifier: (Apache-2.0 OR MIT)

Documentation

Overview

message from the author:

+--------------------------------------------------------------+
| * * * ░░░░░░░░░░░░░░░░░░░░  Hello  ░░░░░░░░░░░░░░░░░░░░░░░░░░|
+--------------------------------------------------------------+
|                                                              |
|     ++              ______________________________________   |
|     ++++           /                                      \  |
|      ++++          |                                      |  |
|    ++++++++++      |   Feel free to contribute to this    |  |
|   +++       |      |       project or contact me on       |  |
|   ++         |     |    manfred.life if you like this     |  |
|   +  -==   ==|     |               project!               |  |
|  (   <*>   <*>     |                                      |  |
|   |          |    /|                  :)                  |  |
|   |         _)   / |                                      |  |
|   |      +++    /  \______________________________________/  |
|    \      =+   /                                             |
|     \      +                                                 |
|     |\++++++                                                 |
|     |  ++++      ||//                                        |
|  ___|   |___    _||/__                                     __|
| /    ---    \   \|  |||                   __ _  ___  __ __/ /|
|/  |       |  \    \ /                    /  ' \/ _ \/ // / / |
||  |       |  |    | |                   /_/_/_/\___/\_,_/_/  |
+--------------------------------------------------------------+

Example

package main

import (
	"context"
	"flag"
	"fmt"
	"log"
	"os"

	"moul.io/climan"
)

func main() {
	var opts struct {
		Debug bool
	}

	root := &climan.Command{
		Name:       "example",
		ShortUsage: "example [global flags] <subcommand> [flags] [args...]",
		ShortHelp:  "example's short help",
		LongHelp:   "example's longer help.\nwith more details.",
		FlagSetBuilder: func(fs *flag.FlagSet) {
			fs.BoolVar(&opts.Debug, "debug", opts.Debug, "debug mode")
		},
		Exec: func(ctx context.Context, args []string) error {
			fmt.Println("args", args)
			return nil
		},
		Subcommands: []*climan.Command{
			&climan.Command{
				Name: "sub",
			},
		},
		// Options: []climan.Option{climan.WithEnvVarPrefix("EXAMPLE")},
	}
	if err := root.Parse(os.Args[1:]); err != nil {
		log.Fatal(fmt.Errorf("parse error: %w", err))
	}

	if err := root.Run(context.Background()); err != nil {
		log.Fatal(fmt.Errorf("run error: %w", err))
	}
}

Index

• func DefaultUsageFunc(c *Command) string
• type Command
  • func (c *Command) Parse(args []string) error
  • func (c *Command) Run(ctx context.Context) error

Examples

• Package

Functions

func DefaultUsageFunc

func DefaultUsageFunc(c *Command) string

Types

type Command

type Command struct {
	Name           string
	Exec           func(context.Context, []string) error
	FlagSetBuilder func(fs *flag.FlagSet)
	Subcommands    []*Command
	ShortUsage     string
	ShortHelp      string
	LongHelp       string
	FFOptions      []ff.Option
	FlagSet        *flag.FlagSet
	UsageFunc      func(c *Command) string
	// contains filtered or unexported fields
}

func (*Command) Parse

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

func (*Command) Run

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