go-clap

KO | EN

gitlite — search

#hacktoberfest #react #ai #llm #machine-learning #deep-learning #docker #kubernetes #vue #awesome-list #pytorch #security #openai #open-source

(★ 76)

Lightweight, non intrusive Command Line Argument Parser

File Explorer

Download Latest Version (.zip)

- - unittests.yml
- dependabot.yml
- args.go
- clap.go
- clap_test.go
- fielddescription.go
- results.go
- tag.go
- tag_test.go
.gitignore
go.mod
LICENSE
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Release](https://img.shields.io/github/v/release/fred1268/go-clap.svg?style=flat-square)](https://github.com/fred1268/go-clap)
[![Go Report](https://goreportcard.com/badge/github.com/fred1268/go-clap)](https://goreportcard.com/report/github.com/fred1268/go-clap)
[![Codecov](https://codecov.io/github/fred1268/go-clap/graph/badge.svg?token=Z4KUF67S8W)](https://codecov.io/github/fred1268/go-clap)
[![Go Reference](https://pkg.go.dev/badge/github.com/fred1268/go-clap)](https://pkg.go.dev/github.com/fred1268/go-clap)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

# clap :clap:

The lightweight, non-intrusive **Command Line Argument Parser**

---

## Why?

The most famous command line parser is undoubtly Cobra. Cobra is very nice and has tons of features,
however, I was not quite happy with it. First, it does way too many things for my liking, and also,
it is pretty intrusive, i.e. you need to build your code around Cobra, rather than having Cobra
silently collaborating with your code.

---

### Enters clap :clap:

clap is a **non intrusive** Command Line Argument Parser, that will use struct tags to understand
what you want to parse. You don't have to implement interface or use a CLI to scaffold your project:
you just call `clap.Parse(args, &YourConfig)` and you are done. You are nonetheless responsible for
handling potential commands and subcommands, but clap will fill up your CLI configuration struct
with the values passed on the command line for those commands / subcommands.

---

### Benefits of clap :clap:

- lightweight
- non intrusive
- obvious defaults
- no dependencies
- easy to configure
- no CLI nor scaffolding

> As a bonus, clap is about 350 LoC (excluding comments and tests)

---

## Installation

```go
go get github.com/fred1268/go-clap
```

---

## Quick start

Very easy to start with:

1. declare a struct containing your configuration
2. add struct tags as hints for clap
3. call `clap.Parse(args, &config)`

```go
    type config struct {
    	Cookie      string   `clap:"--cookie"`
    	HTTPOnly    bool     `clap:"--httpOnly"`
    	Secure      bool     `clap:"--secure"`
    	Origins     [4]string `clap:"--origins,-O,mandatory"`
    	Port        int      `clap:",-P,mandatory"`
    	ConfigFiles []string `clap:"trailing"`
    }
```

> Please note that this automatically generates a `--no-secure` and `--no-httpOnly`
> flags that you can use on the command line to set the corresponding booleans
> to the `false` value. This is useful when you want to give a boolean a `true`
> default value.

A clap struct tag has the following structure:

```go
    Name        Type    `clap:"longName[,shortName][,mandatory]"`
```

longName is a... well... long name, like `--recursive` or `--credentials`

shortName is a single letter name, like `-R` or `-c`

mandatory can be added to make the non-optional parameters

In your main, just make a call to `clap.Parse()`:

```go
    func main() {
        var err error
        var results *clap.Results
        // define your defaults
    	cfg := &config{Secure: true}
        // note you may want to skip the first few
        // parameters (like command and subcommand)
        // by passing args[2:] instead of args
        if results, err = clap.Parse(args, cfg); err != nil {
            // results contains a list of arguments in error
            // can be used for user friendly error handling
            return err
        }
        // results contains the list of arguments being ignored
        // can be used for user friendly error handling
    }
```

Assuming the command line looks like:

```shell
    -P 8080 --cookie clapcookie --httpOnly --origins http://localhost:5137 \
    https://localhost:5173 http://localhost:3000 https://localhost:3000 \
    config-db.json config-log.json
```

You will get the following struct:

```go
    config{
    	Cookie:   "clapcookie",
    	HTTPOnly: true,
    	Secure:   true, // comes from your default (not in the command line)
    	Origins: []string{
    		"http://localhost:5137", "https://localhost:5173",
    		"http://localhost:3000", "https://localhost:3000",
    	},
    	Port:        8080,
    	// trailing parameters
    	ConfigFiles: []string{"config-db.json", "config-log.json"},
    }
```

> Note that it is important to use arrays rather than slices when you can,
> since arrays will consume, at maximum the requested number of
> parameters, whereas slices will consume all possible parameters.
> Thus, a slice parameter should not be used just before the trailing
> otherwise it will consume the trailing parameters.

---

## Supported parameter types

The following parameter types are supported by clap:

- bool: `--param` or `--no-param`
- string: `--param test`
- int: `--param 10`
- float: `--param 12.3`
- string array of any size (here 3): `--param a b c`
- int array of any size (here 2): `--param 80 443`
- string slice: `--param a b c`
- int slice: `--param 80 443`

---

## Handling commands and subcommands

clap doesn't have explicit support for commands and subcommands because
it doesn't really need it. The way to have commands is simple:

- create a parameter struct per command
- switch on `os.Args[1]` (the command)
- call `clap.Parse(os.Args[2:])`

Here is an example:

```go
type RunParams struct {
	ForceRebuild bool `clap:",-a"`
	PrintOnly    bool `clap:",-n"`
    // ...
}

type TestParams struct {
	Binary      string `clap:",-o"`
	CompileOnly bool   `clap:",-c"`
    // ...
}

func main() {
	if len(os.Args) < 2 {
		os.Exit(1)
	}
	var runParams RunParams
	var testParams TestParams
	switch os.Args[1] {
	case "run":
		clap.Parse(os.Args[2:], &runParams)
	case "test":
		clap.Parse(os.Args[2:], &testParams)
	}
	fmt.Printf("%v\n%v\n", runParams, testParams)
}
```

> Working with subcommands involves exactly the same steps, except
> that you will consume the first two args and give `os.Args[3:]`
> to `clap.Parse()`.

---

## License & contribution

clap is licensed under the MIT license (see [LICENSE](LICENSE)).

Issues or PR are welcome.

go-clap

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

go-clap

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README