Skip to content

Commit

Permalink
Adding more info to the README
Browse files Browse the repository at this point in the history
  • Loading branch information
Rican7 committed Aug 11, 2023
1 parent 91649be commit 980e0d5
Showing 1 changed file with 25 additions and 1 deletion.
26 changes: 25 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,41 @@
[![Go Reference](https://pkg.go.dev/badge/github.com/Rican7/lieut.svg)](https://pkg.go.dev/github.com/Rican7/lieut)
<!--[![Latest Stable Version](https://img.shields.io/github/release/Rican7/lieut.svg?style=flat)](https://github.com/Rican7/lieut/releases)-->

Lieut, short for lieutenant, or "second-in-command" to a commander.
_Lieut, short for lieutenant, or "second-in-command" to a commander._

An opinionated, feature-limited, no external dependency, "micro-framework" for building command line applications in Go.

#### But why though?

In general, I personally don't like using frameworks... especially macro frameworks, and especially in Go.

I prefer using Go's extensive standard library, and when that doesn't quite provide what I'm looking for, I look towards smaller libraries that carry few (if any) other external dependencies and that integrate well with the standard library and its interfaces.

That being said, [the `flag` package in the standard library](https://pkg.go.dev/flag) leaves a lot to be desired, and unfortunately acts far less like a library and much more like a framework (it's library code [that calls `os.Exit()`](https://github.com/golang/go/blob/go1.21.0/src/flag/flag.go#L1168-L1171)... 😕😖). It defines a lot of higher-level application behaviors than typically expected, and those can be a little surprising.

The goal of this project is to get some of those quirks out of the way (or at least work WITH them in ways that reduce the surprises in behavior) and reduce the typical "setup" code that a command line application needs, all while working with the standard library, to expand upon it's capabilities rather than locking your application into a tree of external/third-party dependencies.


## Project Status

This project is currently in "pre-release". The API may change.
Use a tagged version or vendor this dependency if you plan on using it.


## Features

- Relies solely on the standard library.
- Sub-command applications (`app command`, `app othercommand`).
- Automatic handling of typical error paths.
- Standardized output handling of application (and command) usage, description, help, and version..
- Help flag (`--help`) handling, with actual user-facing notice (it shows up as a flag in the options list), rather than just handling it silently..
- Version flag (`--version`) handling with a standardized output.
- Automatic flag handling (`--help` and `--version`) can be disabled by simply defining your own flags of the same name.
- Global and sub-command flags with automatic merging.
- Built-in signal handling (interrupt) with context cancellation.
- Smart defaults, so there's less to configure.


## Example

```go
Expand Down

0 comments on commit 980e0d5

Please sign in to comment.