You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: LICENSE
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
Copyright (c) 2012 Ahmad Amireh
1
+
Copyright (c) 2012-2015 Ahmad Amireh
2
2
3
3
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:
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
28
20
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.
30
22
31
23
## Help listings `--help`
32
24
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.
34
26
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`):
@@ -110,35 +104,67 @@ Many thanks to everyone who reported bugs, provided fixes, and added entirely ne
110
104
111
105
*If I missed you, don't hesitate to update this file or just email me.*
112
106
113
-
## Reference
107
+
## Changelog
108
+
109
+
### Changes from 2.5.x 3.0
114
110
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.
116
112
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
118
144
119
-
Changes from 2.5.1 to 2.5.2
145
+
### Changes from 2.5.1 to 2.5.2
120
146
121
147
- No longer tracking the (legacy) tarballs in git or the luarocks package. Instead, we use the GitHub release tarballs for each version.
122
148
123
-
Changes in 2.4.0 from 2.3-4
149
+
### Changes in 2.4.0 from 2.3-4
124
150
125
151
1. All arguments now accept a callback that will be invoked when parsing of those arguments was successful
126
152
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`).
127
153
3. Minor bugfixes
128
154
129
-
Changes in 2.3.0
155
+
### Changes in 2.3.0
130
156
131
157
1. the parser will now understand `--` to denote the end of optional arguments and will map whatever comes after it to required/splat args
132
158
2.`-short VALUE` is now properly supported, so is `-short=VALUE`
133
159
3. short-key options can now officially be composed of more than 1 character
134
160
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)
135
161
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)
136
162
137
-
Changes in 2.2-0 from 2.1-2
163
+
### Changes in 2.2-0 from 2.1-2
138
164
139
165
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`)
140
166
141
-
Changes in 2.0.0 from 1.x.x
167
+
### Changes in 2.0.0 from 1.x.x
142
168
143
169
1. added the 'splat' argument, an optional repetitive argument for which a maximum number of occurrences can be set
144
170
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
152
178
153
179
The code is released under the MIT terms. Feel free to use it in both open and closed software as you please.
154
180
155
-
Copyright (c) 2011-2012 Ahmad Amireh
181
+
Copyright (c) 2011-2015 Ahmad Amireh
156
182
157
183
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:
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:
0 commit comments