Skip to content

Commit 5d3c18f

Browse files
committed
Merge pull request #50 from amireh/3.0
3.0
2 parents e1c538f + 57ae114 commit 5d3c18f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+3655
-1819
lines changed

.busted

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
return {
2+
_all = {
3+
coverage = false
4+
},
5+
default = {
6+
coverage = false,
7+
verbose = true,
8+
ROOT = {"spec"},
9+
lpath = "src/?.lua;src/cliargs/?.lua;spec/?.lua;"
10+
}
11+
}

.env

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
GITHUB_USER="amireh"
22
GITHUB_REPO="lua_cliargs"
3-
GITHUB_TOKEN=
3+
GITHUB_TOKEN=
4+
LUAROCKS_API_KEY=

.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,7 @@
22
/luacov.stats.out
33
/.env.local
44
/*.rock
5-
**/.*.swp
5+
.swp
6+
/.luacheckcache
7+
/doc/compiled
8+
/doc/node_modules

.luacheckrc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
std = "min"
2+
cache = false
3+
4+
files["spec"] = {
5+
std = "+busted"
6+
}

.travis.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,8 @@ install:
1414
- sudo apt-get install luajit
1515
- sudo apt-get install luarocks
1616
- sudo luarocks install busted 2.0rc10-1
17+
- sudo luarocks install dkjson
18+
- sudo luarocks install yaml
19+
- sudo luarocks install inifile
1720

1821
script: "busted spec"

LICENSE

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2012 Ahmad Amireh
1+
Copyright (c) 2012-2015 Ahmad Amireh
22

33
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
44

README.md

Lines changed: 54 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,32 @@
1-
# cliargs
1+
# lua_cliargs
22

33
[![travis-ci status](https://secure.travis-ci.org/amireh/lua_cliargs.png)](http://travis-ci.org/#!/amireh/lua_cliargs/builds)
44

55
cliargs is a command-line argument parser for Lua. It supports several types of arguments:
66

77
1. required arguments
8-
1. optional arguments with different notations: `-short-key VALUE` and/or `--expanded-key=VALUE`
9-
2. optional arguments with multiple-values that get appended to a list
10-
1. optional "flag" arguments (on/off options) with notations: `-short-key` and/or `--expanded-key`
11-
1. a single optional "splat" argument which can be repeated (must be the last argument)
8+
2. optional arguments with different notations: `-short-key VALUE` and/or `--expanded-key=VALUE`
9+
3. optional arguments with multiple-values that get appended to a list
10+
4. optional "flag" arguments (on/off options) with notations: `-short-key` and/or `--expanded-key`
11+
5. a single optional "splat" argument which can be repeated (must be the last argument)
1212

1313
Optional arguments can have default values (strings), flags always default to 'true'.
1414

15-
## Usage Example
16-
See `example.lua` for an example on how to use the parser.
17-
Try it with the following sample command lines;
15+
## Usage Examples
1816

19-
```
20-
example.lua --help
21-
example.lua -o myfile -d --compress=gzip inputfile
22-
example.lua --__DUMP__ -o myfile -d --compress=gzip inputfile
23-
```
24-
25-
**Accessing arguments**
17+
See the examples under the `examples/` directory.
2618

27-
All types of arguments must specify a *key*. In the case of required arguments, the keys are only used in the help listings. However, for optional arguments, they are mandatory (either *--key* or *--extended-key* must be specified, the other is optional).
19+
## API
2820

29-
The `parse()` method will parse the command line and return a table with results. Accessing argument or option values in this table can be done using the key with the leading dashes omitted (`-` or `--`). When defining an option (or a flag) , you can access it using either key or expanded-key; they'll both be defined.
21+
See http://lua-cliargs.netlify.com/ for the API docs.
3022

3123
## Help listings `--help`
3224

33-
A help listing will be automatically generated and accessed using the `--help` argument. You can also force its display in the code using `cli:print_help()`.
25+
A help listing will be automatically generated and accessed using the `--help` argument. When such an option is encountered, `cli:parse()` will abort and return `nil, string` with the help message; you are free to print it to the screen using `print()` if you want.
3426

35-
This is the result for our example (see examples/00_general.lua):
27+
You can also force its display in the code using `cli:print_help()`.
28+
29+
This is the result for our example (see `examples/00_general.lua`):
3630

3731
```
3832
Usage: cli_example.lua [OPTIONS] INPUT [OUTPUT-1 [OUTPUT-2 [...]]]
@@ -110,35 +104,67 @@ Many thanks to everyone who reported bugs, provided fixes, and added entirely ne
110104

111105
*If I missed you, don't hesitate to update this file or just email me.*
112106

113-
## Reference
107+
## Changelog
108+
109+
### Changes from 2.5.x 3.0
114110

115-
A function reference was generated using [LunaDoc](http://jgm.github.com/lunamark/lunadoc.1.html) which can be found [here](http://lua-cliargs.docs.mxvt.net).
111+
This major version release contains BREAKING API CHANGES. See the UPGRADE guide for help in updating your code to make use of it.
116112

117-
## Changelog
113+
**More flexible parsing**
114+
115+
- options can occur anywhere now even after arguments (unless the `--` indicator is specified, then no options are parsed afterwards.) Previously, options were accepted only before arguments.
116+
- options using the short-key notation can be specified using `=` as a value delimiter as well as a space (e.g. `-c=lzma` and `-c lzma`)
117+
- the library is now more flexible with option definitions (notations like `-key VALUE`, `--key=VALUE`, `-k=VALUE` are all treated equally)
118+
- `--help` or `-h` will now cause the help listing to be displayed no matter where they are. Previously, this only happened if they were supplied as the first option.
119+
120+
**Basic command support**
121+
122+
You may now define commands with custom handlers. A command may be invoked by supplying its name as the first argument (options can still come before or afterwards). lua_cliargs will forward the rest of the options to that command to handle, which can be in a separate file.
123+
124+
See `examples/04_commands--git.lua` for an example.
125+
126+
**Re-defining defaults**
127+
128+
It is now possible to pass a table containing default values (and override any
129+
existing defaults).
130+
131+
The function for doing this is called `cli:load_defaults().`.
132+
133+
This makes it possible to load run-time defaults from a configuration file, for example.
134+
135+
**Reading configuration files**
136+
137+
`cliargs` now exposes some convenience helpers for loading configuration from files (and a separate hook, `cli:load_defaults()` to inject this config if you want) found in `cli:read_defaults()`. This method takes a file-path and an optional file format and it will parse it for you, provided you have the necessary libraries installed.
138+
139+
See the API docs for using this hook.
140+
141+
**Other changes**
142+
143+
- internal code changes and more comprehensive test-coverage
118144

119-
Changes from 2.5.1 to 2.5.2
145+
### Changes from 2.5.1 to 2.5.2
120146

121147
- No longer tracking the (legacy) tarballs in git or the luarocks package. Instead, we use the GitHub release tarballs for each version.
122148

123-
Changes in 2.4.0 from 2.3-4
149+
### Changes in 2.4.0 from 2.3-4
124150

125151
1. All arguments now accept a callback that will be invoked when parsing of those arguments was successful
126152
2. (**POSSIBLY BREAKING**) Default value for flags is now `nil` instead of `false`. This will only affect existing behavior if you were explicitly testing unset flags to equal `false` (i.e. `if flag == false then`) as opposed to `if flag then` (or `if not flag then`).
127153
3. Minor bugfixes
128154

129-
Changes in 2.3.0
155+
### Changes in 2.3.0
130156

131157
1. the parser will now understand `--` to denote the end of optional arguments and will map whatever comes after it to required/splat args
132158
2. `-short VALUE` is now properly supported, so is `-short=VALUE`
133159
3. short-key options can now officially be composed of more than 1 character
134160
4. the parser now accepts callbacks that will be invoked as soon as options are parsed so that you can bail out of parsing preemptively (like for `--version` or `--help` options)
135161
5. options can now accept multiple values via multiple invocations if a table was provided as a default value (passed-in values will be appended to that list)
136162

137-
Changes in 2.2-0 from 2.1-2
163+
### Changes in 2.2-0 from 2.1-2
138164

139165
1. the `=` that separates keys from values in the `--expanded-key` notation is no longer mandatory; using either a space or a `=` will map the value to the key (e.g., `--compress lzma` is equal to `--compress=lzma`)
140166

141-
Changes in 2.0.0 from 1.x.x
167+
### Changes in 2.0.0 from 1.x.x
142168

143169
1. added the 'splat' argument, an optional repetitive argument for which a maximum number of occurrences can be set
144170
1. removed the reference, arguments are now solely returned by their key/expanded-key (BREAKING!)
@@ -152,7 +178,7 @@ Changes in 2.0.0 from 1.x.x
152178

153179
The code is released under the MIT terms. Feel free to use it in both open and closed software as you please.
154180

155-
Copyright (c) 2011-2012 Ahmad Amireh
181+
Copyright (c) 2011-2015 Ahmad Amireh
156182

157183
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
158184

UPGRADE.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## Upgrading from 2.x to 3.0
2+
3+
- `cli._VERSION` has been renamed to `cli.VERSION`
4+
5+
**Function renames**
6+
7+
The functions for defining arguments of all types have been renamed to drop the
8+
`_add` prefix from their names. This affects the following functions:
9+
10+
- `cli:add_argument` has been renamed to `cli:argument`
11+
- `cli:add_option` has been renamed to `cli:option`
12+
- `cli:add_flag` has been renamed to `cli:flag`
13+
- `cli:optarg` has been renamed to `cli:splat`
14+
15+
**Function alias removals**
16+
17+
- `cli:add_opt` has been removed. Use `cli:option` instead
18+
- `cli:add_arg` has been removed. Use `cli:argument` instead
19+
- `cli:parse_args` has been removed. Use `cli:parse` instead
20+
21+
**`cli:parse()` invocation changes**
22+
23+
`cli:parse()` no longer accepts the auxiliary arguments `noprint` and `dump` as the second and third arguments; only one argument is now accepted and that is a custom arguments table. If left unspecified, we use the global `_G['arg']` program argument table as usual.
24+
25+
So, the new signature is:
26+
27+
`cli:parse(args: table) -> table`
28+
29+
- to make the parser silent, use `cli:set_silent(true)` before invoking the parser
30+
- to generate the internal state dump, a runtime argument `--__DUMP__` must be passed as the first argument
31+
32+
**Private function are now hidden**
33+
34+
Hopefully you weren't relying on any of these because they are no longer exposed, and they weren't documented. The affected previous exports are:
35+
36+
- `cli:__lookup()`
37+
- `cli:__add_opt()`

bin/coverage

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,23 @@
88
# $ ./bin/coverage
99
# $ cat luacov.report.out
1010

11+
which luacov &> /dev/null
12+
13+
if [ $? -ne 0 ]; then
14+
echo "You must have luacov installed."
15+
echo "Run 'luarocks install luacov' then try again".
16+
exit 1
17+
fi
18+
19+
which busted &> /dev/null
20+
21+
if [ $? -ne 0 ]; then
22+
echo "You must have luacov installed."
23+
echo "Run 'luarocks install busted' then try again".
24+
exit 1
25+
fi
26+
1127
busted -c
12-
luacov src/cliargs.lua
28+
luacov src/
1329
rm luacov.stats.out
1430
grep -zPo "(?s)={10,}\nSummary\n={10,}.+" luacov.report.out

bin/docs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#!/usr/bin/env bash
2+
3+
if [ ! -d "doc" ]; then
4+
echo "Must be run from lua_cliargs root"
5+
exit 1
6+
fi
7+
8+
which npm &> /dev/null
9+
10+
if [ $? -ne 0 ]; then
11+
echo "You must have npm (node.js) installed."
12+
exit 1
13+
fi
14+
15+
cd doc
16+
17+
npm install
18+
19+
./node_modules/tinydoc/cli/tinydoc run
20+
21+
echo "Docs compiled successfully. Open doc/compiled/index.html in a browser."

bin/lint

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env bash
2+
3+
which luacheck &> /dev/null
4+
5+
if [ $? -ne 0 ]; then
6+
echo "You must have luacheck installed."
7+
echo "Run 'luarocks install luacheck' then try again".
8+
exit 1
9+
fi
10+
11+
if [ ! -d src ]; then
12+
echo "You must run $0 from lua_cliargs root."
13+
exit 1
14+
fi
15+
16+
luacheck .

bin/release

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,7 @@ function confirm {
2424

2525
VERSION=$1
2626
SRC_FILE="src/cliargs.lua"
27-
# VERSION=$(grep "version" lua_cliargs-*.rockspec | cut -d' ' -f3 | sed 's/"//g')
28-
SRC_VERSION=$(grep "_VERSION" src/cliargs.lua | sed -e 's/.*=//' -e 's/.* //' -e 's/"//g')
27+
SRC_VERSION=$(grep "VERSION" src/cliargs.lua | sed -e 's/.*=//' -e 's/.* //' -e 's/"//g')
2928

3029
NEW_ROCKSPEC="lua_cliargs-${VERSION}.rockspec"
3130
OLD_ROCKSPEC="lua_cliargs-${SRC_VERSION}.rockspec"

bin/watch-tests.sh

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/usr/bin/env bash
2+
#
3+
# Watches spec files and re-runs the busted suite when a spec or source file
4+
# changes.
5+
#
6+
# Usage:
7+
#
8+
# $0 [--focus]
9+
#
10+
# If --focus is passed, only the last spec file that has changed will be run
11+
# when a _source_ file changes. Otherwise, all specs will run on source changes.
12+
#
13+
# Requires inotify-tools[1].
14+
#
15+
# [1] http://linux.die.net/man/1/inotifywait
16+
17+
if [ ! -d spec ]; then
18+
echo "Must be run from lua_cliargs root."
19+
exit 1
20+
fi
21+
22+
LAST_FILE="spec/"
23+
24+
inotifywait -rm --format '%w %f' -e close_write -e create src/ spec/ | while read dir file; do
25+
FILEPATH="${dir}${file}"
26+
27+
if [[ $FILEPATH =~ src\/ ]]; then
28+
busted $@ "${LAST_FILE}"
29+
else
30+
if [[ $1 =~ "focus" ]]; then
31+
LAST_FILE=$FILEPATH
32+
fi
33+
34+
busted $@ "${FILEPATH}"
35+
fi
36+
done

0 commit comments

Comments
 (0)