Skip to content

Commit af229d4

Browse files
hedzrhedzr
committed
cmdr: bump to v2.0.0
1 parent d771720 commit af229d4

File tree

3 files changed

+226
-8
lines changed

3 files changed

+226
-8
lines changed

‎CHANGELOG

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
1-
initial commit
1+
# CHANGELOG
22

3-
- integrated with store.Store
4-
- preProcess, parse, and exec
5-
- help screen, external editor, try parse value, atoa subpackage
6-
- mutual exclusive, just once, prerequisites, circuit break
7-
- sbom, --config, debug info screen
83

9-
a (string) to any (type) - To convert a string to an exact value according to the given meme.
4+
- v2.0.0
5+
6+
initial commit
7+
8+
- integrated with store.Store
9+
- preProcess, parse, and exec
10+
- help screen, external editor, try parse value, atoa subpackage
11+
- mutual exclusive, just once, prerequisites, circuit break
12+
- sbom, --config, debug info screen
13+
14+
a (string) to any (type) - To convert a string to an exact value according to the given meme.

‎README.md

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# cmdr
2+
3+
![Go](https://github.com/hedzr/cmdr/workflows/Go/badge.svg)
4+
[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/hedzr/cmdr.svg?label=release)](https://github.com/hedzr/cmdr/releases)
5+
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/hedzr/cmdr) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhedzr%2Fcmdr.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhedzr%2Fcmdr?ref=badge_shield)
6+
[![go.dev](https://img.shields.io/badge/go.dev-reference-green)](https://pkg.go.dev/github.com/hedzr/cmdr)
7+
[![Go Report Card](https://goreportcard.com/badge/github.com/hedzr/cmdr)](https://goreportcard.com/report/github.com/hedzr/cmdr)
8+
[![codecov](https://codecov.io/gh/hedzr/cmdr/branch/master/graph/badge.svg)](https://codecov.io/gh/hedzr/cmdr)<!--
9+
[![Coverage Status](https://coveralls.io/repos/github/hedzr/cmdr/badge.svg?branch=master)](https://coveralls.io/github/hedzr/cmdr?branch=master)-->
10+
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#command-line)
11+
12+
`cmdr` is a POSIX-compliant, command-line argument parser library with Golang. Since v2, our license moved to Apache 2.0.
13+
14+
![ee99d078e2f7](https://user-images.githubusercontent.com/12786150/72876202-f49ee500-3d30-11ea-9de0-434bf8decf90.gif)<!-- built by https://ezgif.com/ -->
15+
16+
> ~~See the image frames at [#1](https://github.com/hedzr/cmdr/issues/1#issuecomment-567779978).~~
17+
18+
## Motivations
19+
20+
There are many dirty codes in the cmdr.v1 which cannot be refactored as well. It prompted we reimplment a new one as v2.
21+
22+
The passing winter, we did rewrite the cmdr.v2 to keep it clean and absorbed in parsing and dispatching.
23+
Some abilities were removed and relayouted to new modules.
24+
That's why the `Option Store` has been split as a standalone module [hedzr/store](https://github.com/hedzr/store)[^1].
25+
A faster and colorful slog-like logger has been implemented freshly as [hedzr/logg](https://github.com/hedzr/logg).
26+
[hedzr/evendeep](https://github.com/hedzr/evendeep) provides a deep fully-functional object copy tool. It helps to deep copy some internal objects easily. It is also ready for you.
27+
[hedzr/is](https://github.com/hedzr/is) is an environment detecting framework with many out-of-the-box detectors, such as `is.InTesting` and `is.InDebugging`.
28+
29+
Anyway, the whole supply chain painted:
30+
31+
```mermaid
32+
graph BT
33+
hzis(hedzr/is)-->hzlogg(hedzr/logg/slog)
34+
hzis-->hzdiff(hedzr/evendeep)
35+
hzlogg-->hzdiff
36+
hzerrors(gopkg.in/hedzr/errors.v3)-->hzdiff
37+
hzerrors-->hzstore(hedzr/store)
38+
hzis-->hzstore(hedzr/store)
39+
hzlogg-->hzstore(hedzr/store)
40+
hzdiff-->hzstore(hedzr/store)
41+
hzlogg-->cmdr(hedzr/cmdr/v2)
42+
hzis-->cmdr
43+
hzlogg-->cmdr
44+
hzdiff-->cmdr
45+
hzstore-->cmdr
46+
47+
```
48+
49+
> The .netCore version [Cmdr.Core](https://github.com/hedzr/Cmdr.Core) is available now. A cxx version [`cmdr-cxx`](https://github.com/hedzr/cmdr-cxx) was released (Happy Spring Festival 2021).
50+
51+
## Features
52+
53+
v2 is in earlier state but the baseline is stable:
54+
55+
- Basic command-line arguments parser like POSIX getopt and go stdlib flag.
56+
- Short flag, single character or a string here to support golang CLI style
57+
- Compact flags if possible. Also the sticking value will be parsed. For example: `-c1b23zv` = `-c 1 -b 23 -z -v`
58+
- Hit info: `-v -v -v` = `-v` (hitCount == 3, hitTitle == 'v')
59+
- Optimized for slice: `-a 1,2,3 -a 4 -a 5,6` => []int{1,2,3,4,5,6}
60+
- Value can be sticked or not. Valid forms: `-c1`, `-c 1`, `-c=1` and quoted: `-c"1"`, `-c'1'`, `-c="1"`, `-c='1'`, etc.
61+
- ...
62+
63+
- Long flags and aliases
64+
- Eventual subcommands: an `OnAction` handler can be attached.
65+
- Eventual subcommands and flags: PreActions, PostAction, OnMatching, OnMatched, ...,
66+
- Auto bind to environment variables, For instance: command line `HELP=1 app` = `app --help`.
67+
- Builtin commands and flags:
68+
- `--help`, `-h`
69+
- `--version`, `-V`
70+
- `--verbose`. `-v`
71+
- ...
72+
73+
- Help Screen: auto generate and print
74+
- Smart suggestions when wrong cmd or flag parsed. Jaro-winkler distance is used.
75+
76+
- Loosely parse subcmds and flags:
77+
- Subcommands and flags can be input in any order
78+
- Lookup a flag along with subcommands tree for resolving the duplicated flags
79+
80+
- Can integrate with [hedzr/store](https://github.com/hedzr/store)[^1]
81+
- High-performance in-memory KV store for hierarchical data.
82+
- Extract data to user-spec type with auto-converting
83+
- Loadable external sources: environ, config files, consul, etcd, etc..
84+
- extensible codecs and providers for loading from data sources
85+
86+
- Three kinds of config files are searched and loaded via `loaders.NewConfigFileLoader()`:
87+
- Primary: main config, shipped with installable package.
88+
- Secondary: 2ndry config. Wrapped by reseller(s).
89+
- Alternative: user's local config, writeable. The runtime changeset will be written back to this file while app stopping.
90+
91+
- TODO
92+
- Shell autocompletion
93+
- ...
94+
95+
96+
[^1]: `hedzr/store` is a high-performance configure management library
97+
98+
More minor details need to be evaluated and reimplemented if it's still meaningful in v2.
99+
100+
## History
101+
102+
v2 is staying in earlier state:
103+
104+
- Full list: [CHANGELOG](https://github.com/hedzr/cmdr/blob/master/CHANGELOG)
105+
106+
## Guide
107+
108+
A simple cli-app can be:
109+
110+
```go
111+
package main
112+
113+
import (
114+
logz "github.com/hedzr/logg/slog"
115+
116+
"github.com/hedzr/cmdr/v2"
117+
"github.com/hedzr/cmdr/v2/cli"
118+
"github.com/hedzr/cmdr/v2/loaders"
119+
"github.com/hedzr/cmdr/v2/pkg/dir"
120+
"github.com/hedzr/store"
121+
)
122+
123+
func main() {
124+
app := prepareApp()
125+
126+
// // simple run the parser of app and trigger the matched command's action
127+
// _ = app.Run(
128+
// cmdr.WithForceDefaultAction(false), // true for debug in developing time
129+
// )
130+
131+
if err := app.Run(
132+
cmdr.WithStore(store.New()),
133+
cmdr.WithExternalLoaders(
134+
loaders.NewConfigFileLoader(),
135+
loaders.NewEnvVarLoader(),
136+
),
137+
cmdr.WithForceDefaultAction(true), // true for debug in developing time
138+
); err != nil {
139+
logz.Error("Application Error:", "err", err)
140+
}
141+
}
142+
143+
func prepareApp() (app cli.App) {
144+
app = cmdr.New().
145+
Info("demo-app", "0.3.1").
146+
Author("hedzr")
147+
app.AddFlg(func(b cli.FlagBuilder) {
148+
b.Titles("no-default").
149+
Description("disable force default action").
150+
OnMatched(func(f *cli.Flag, position int, hitState *cli.MatchState) (err error) {
151+
app.Store().Set("app.force-default-action", false)
152+
return
153+
})
154+
})
155+
app.AddCmd(func(b cli.CommandBuilder) {
156+
b.Titles("jump").
157+
Description("jump command").
158+
Examples(`jump example`).
159+
Deprecated(`jump is a demo command`).
160+
Hidden(false)
161+
162+
b.AddCmd(func(b cli.CommandBuilder) {
163+
b.Titles("to").
164+
Description("to command").
165+
Examples(``).
166+
Deprecated(`v0.1.1`).
167+
Hidden(false).
168+
OnAction(func(cmd *cli.Command, args []string) (err error) {
169+
app.Store().Set("app.demo.working", dir.GetCurrentDir())
170+
println()
171+
println(dir.GetCurrentDir())
172+
println()
173+
println(app.Store().Dump())
174+
return // handling command action here
175+
})
176+
b.AddFlg(func(b cli.FlagBuilder) {
177+
b.Default(false).
178+
Titles("full", "f").
179+
Description("full command").
180+
Build()
181+
})
182+
})
183+
})
184+
185+
app.AddFlg(func(b cli.FlagBuilder) {
186+
b.Titles("dry-run", "n").
187+
Default(false).
188+
Description("run all but without committing")
189+
})
190+
191+
app.Flg("wet-run", "w").
192+
Default(false).
193+
Description("run all but with committing").
194+
Build() // no matter even if you're adding the duplicated one.
195+
return
196+
}
197+
```
198+
199+
200+
201+
## Thanks to JODL
202+
203+
Thanks to [JetBrains](https://www.jetbrains.com/?from=cmdr) for donating product licenses to help develop **cmdr**
204+
[![jetbrains](https://gist.githubusercontent.com/hedzr/447849cb44138885e75fe46f1e35b4a0/raw/bedfe6923510405ade4c034c5c5085487532dee4/jetbrains-variant-4.svg)](https://www.jetbrains.com/?from=hedzr/cmdr)
205+
[![goland](https://gist.githubusercontent.com/hedzr/447849cb44138885e75fe46f1e35b4a0/raw/ca8ac2694906f5650d585263dbabfda52072f707/logo-goland.svg)](https://www.jetbrains.com/?from=hedzr/cmdr)
206+
207+
## License
208+
209+
Since v2, our license moved to Apache 2.0.
210+
211+
The v1 keeps under MIT itself.
212+
213+
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhedzr%2Fcmdr.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhedzr%2Fcmdr?ref=badge_large)

‎doc.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
package cmdr
44

5-
const Version = "v2.0.0"
5+
const Version = "v2.0.0" // Version fir hedzr/cmdr/v2

0 commit comments

Comments
 (0)