Commit 9ee1f043 authored by Peter W. Draper's avatar Peter W. Draper

Import the argparse library from https://github.com/cofyc/argparse

Provides GNU --long-name arguments, necessary as we are running out of characters. We could use the glibc library function getopt_long, but that is not POSIX
parent 54a5c390
# FAQs
## Why removing parsed command-line switches/options?
It destroys the original `argv` array, not compatible with other arguments parsing
library.
This is because this library is used for short-lived programs, e.g. cli tools
at beginning. It's very convenient to process remain arguments if we remove
parsed command-line arguments, e.g. `<comamnd> [-[s]|--switch]... arguments`.
If you want keep original `argc/argv`, you can make a copy, then pass them to
`argparse_parse`, e.g.
```c
int copy_argc = argc;
const char **copy_argv = argv;
copy_argv = malloc(copy_argc * sizeof(char *));
for (int i = 0; i < argc; i++) {
copy_argv[i] = (char *)argv[i];
}
argparse_parse(&argparse, copy_argc, copy_argv);
```
Issues:
- https://github.com/cofyc/argparse/issues/3
- https://github.com/cofyc/argparse/issues/9
## Why using `intptr_t` to hold associated data? Why not `void *`?
I choose `intptr_t` because it's a integer type which also can be used to hold
a pointer value. Most of the time, we only need a integer to hold
user-provided value, see `OPT_BIT` as example. If you want to provide a pointer
which points to a large amount of data, you can cast it to `intptr_t` and cast
it back to original pointer in callback function.
The MIT License (MIT)
Copyright (c) 2012-2013 Yecheng Fu <cofyc.jackson@gmail.com>
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 above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
approvers:
- cofyc
# argparse [![Build Status](https://travis-ci.org/cofyc/argparse.png)](https://travis-ci.org/cofyc/argparse)
argparse - A command line arguments parsing library in C (compatible with C++).
## Description
This module is inspired by parse-options.c (git) and python's argparse
module.
Arguments parsing is common task in cli program, but traditional `getopt`
libraries are not easy to use. This library provides high-level arguments
parsing solutions.
The program defines what arguments it requires, and `argparse` will figure
out how to parse those out of `argc` and `argv`, it also automatically
generates help and usage messages and issues errors when users give the
program invalid arguments.
## Features
- handles both optional and positional arguments
- produces highly informative usage messages
- issues errors when given invalid arguments
There are basically three types of options:
- boolean options
- options with mandatory argument
- options with optional argument
There are basically two forms of options:
- short option consist of one dash (`-`) and one alphanumeric character.
- long option begin with two dashes (`--`) and some alphanumeric characters.
Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
Options are case-sensitive.
Options and non-option arguments can clearly be separated using the `--` option.
## Examples
```c
#include "argparse.h"
static const char *const usage[] = {
"test_argparse [options] [[--] args]",
"test_argparse [options]",
NULL,
};
#define PERM_READ (1<<0)
#define PERM_WRITE (1<<1)
#define PERM_EXEC (1<<2)
int
main(int argc, const char **argv)
{
int force = 0;
int test = 0;
int num = 0;
const char *path = NULL;
int perms = 0;
struct argparse_option options[] = {
OPT_HELP(),
OPT_GROUP("Basic options"),
OPT_BOOLEAN('f', "force", &force, "force to do"),
OPT_BOOLEAN('t', "test", &test, "test only"),
OPT_STRING('p', "path", &path, "path to read"),
OPT_INTEGER('n', "num", &num, "selected num"),
OPT_GROUP("Bits options"),
OPT_BIT(0, "read", &perms, "read perm", NULL, PERM_READ, OPT_NONEG),
OPT_BIT(0, "write", &perms, "write perm", NULL, PERM_WRITE),
OPT_BIT(0, "exec", &perms, "exec perm", NULL, PERM_EXEC),
OPT_END(),
};
struct argparse argparse;
argparse_init(&argparse, options, usage, 0);
argparse_describe(&argparse, "\nA brief description of what the program does and how it works.", "\nAdditional description of the program after the description of the arguments.");
argc = argparse_parse(&argparse, argc, argv);
if (force != 0)
printf("force: %d\n", force);
if (test != 0)
printf("test: %d\n", test);
if (path != NULL)
printf("path: %s\n", path);
if (num != 0)
printf("num: %d\n", num);
if (argc != 0) {
printf("argc: %d\n", argc);
int i;
for (i = 0; i < argc; i++) {
printf("argv[%d]: %s\n", i, *(argv + i));
}
}
if (perms) {
printf("perms: %d\n", perms);
}
return 0;
}
```
This diff is collapsed.
/**
* Copyright (C) 2012-2015 Yecheng Fu <cofyc.jackson at gmail dot com>
* All rights reserved.
*
* Use of this source code is governed by a MIT-style license that can be found
* in the LICENSE file.
*/
#ifndef ARGPARSE_H
#define ARGPARSE_H
/* For c++ compatibility */
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
struct argparse;
struct argparse_option;
typedef int argparse_callback (struct argparse *self,
const struct argparse_option *option);
enum argparse_flag {
ARGPARSE_STOP_AT_NON_OPTION = 1,
};
enum argparse_option_type {
/* special */
ARGPARSE_OPT_END,
ARGPARSE_OPT_GROUP,
/* options with no arguments */
ARGPARSE_OPT_BOOLEAN,
ARGPARSE_OPT_BIT,
/* options with arguments (optional or required) */
ARGPARSE_OPT_INTEGER,
ARGPARSE_OPT_FLOAT,
ARGPARSE_OPT_STRING,
};
enum argparse_option_flags {
OPT_NONEG = 1, /* disable negation */
};
/**
* argparse option
*
* `type`:
* holds the type of the option, you must have an ARGPARSE_OPT_END last in your
* array.
*
* `short_name`:
* the character to use as a short option name, '\0' if none.
*
* `long_name`:
* the long option name, without the leading dash, NULL if none.
*
* `value`:
* stores pointer to the value to be filled.
*
* `help`:
* the short help message associated to what the option does.
* Must never be NULL (except for ARGPARSE_OPT_END).
*
* `callback`:
* function is called when corresponding argument is parsed.
*
* `data`:
* associated data. Callbacks can use it like they want.
*
* `flags`:
* option flags.
*/
struct argparse_option {
enum argparse_option_type type;
const char short_name;
const char *long_name;
void *value;
const char *help;
argparse_callback *callback;
intptr_t data;
int flags;
};
/**
* argpparse
*/
struct argparse {
// user supplied
const struct argparse_option *options;
const char *const *usages;
int flags;
const char *description; // a description after usage
const char *epilog; // a description at the end
// internal context
int argc;
const char **argv;
const char **out;
int cpidx;
const char *optvalue; // current option value
};
// built-in callbacks
int argparse_help_cb(struct argparse *self,
const struct argparse_option *option);
// built-in option macros
#define OPT_END() { ARGPARSE_OPT_END, 0, NULL, NULL, 0, NULL, 0, 0 }
#define OPT_BOOLEAN(...) { ARGPARSE_OPT_BOOLEAN, __VA_ARGS__ }
#define OPT_BIT(...) { ARGPARSE_OPT_BIT, __VA_ARGS__ }
#define OPT_INTEGER(...) { ARGPARSE_OPT_INTEGER, __VA_ARGS__ }
#define OPT_FLOAT(...) { ARGPARSE_OPT_FLOAT, __VA_ARGS__ }
#define OPT_STRING(...) { ARGPARSE_OPT_STRING, __VA_ARGS__ }
#define OPT_GROUP(h) { ARGPARSE_OPT_GROUP, 0, NULL, NULL, h, NULL, 0, 0 }
#define OPT_HELP() OPT_BOOLEAN('h', "help", NULL, \
"show this help message and exit", \
argparse_help_cb, 0, 0)
int argparse_init(struct argparse *self, struct argparse_option *options,
const char *const *usages, int flags);
void argparse_describe(struct argparse *self, const char *description,
const char *epilog);
int argparse_parse(struct argparse *self, int argc, const char **argv);
void argparse_usage(struct argparse *self);
#ifdef __cplusplus
}
#endif
#endif
#!/bin/bash
_version='1.02'
_plan_set=0
_no_plan=0
_skip_all=0
_test_died=0
_expected_tests=0
_executed_tests=0
_failed_tests=0
TODO=
usage(){
cat <<'USAGE'
tap-functions: A TAP-producing BASH library
PLAN:
plan_no_plan
plan_skip_all [REASON]
plan_tests NB_TESTS
TEST:
ok RESULT [NAME]
okx COMMAND
is RESULT EXPECTED [NAME]
isnt RESULT EXPECTED [NAME]
like RESULT PATTERN [NAME]
unlike RESULT PATTERN [NAME]
pass [NAME]
fail [NAME]
SKIP:
skip [CONDITION] [REASON] [NB_TESTS=1]
skip $feature_not_present "feature not present" 2 || {
is $a "a"
is $b "b"
}
TODO:
Specify TODO mode by setting $TODO:
TODO="not implemented yet"
ok $result "some not implemented test"
unset TODO
OTHER:
diag MSG
EXAMPLE:
#!/bin/bash
. tap-functions
plan_tests 7
me=$USER
is $USER $me "I am myself"
like $HOME $me "My home is mine"
like "`id`" $me "My id matches myself"
/bin/ls $HOME 1>&2
ok $? "/bin/ls $HOME"
# Same thing using okx shortcut
okx /bin/ls $HOME
[[ "`id -u`" != "0" ]]
i_am_not_root=$?
skip $i_am_not_root "Must be root" || {
okx ls /root
}
TODO="figure out how to become root..."
okx [ "$HOME" == "/root" ]
unset TODO
USAGE
exit
}
opt=
set_u=
while getopts ":sx" opt ; do
case $_opt in
u) set_u=1 ;;
*) usage ;;
esac
done
shift $(( OPTIND - 1 ))
# Don't allow uninitialized variables if requested
[[ -n "$set_u" ]] && set -u
unset opt set_u
# Used to call _cleanup on shell exit
trap _exit EXIT
plan_no_plan(){
(( _plan_set != 0 )) && "You tried to plan twice!"
_plan_set=1
_no_plan=1
return 0
}
plan_skip_all(){
local reason=${1:-''}
(( _plan_set != 0 )) && _die "You tried to plan twice!"
_print_plan 0 "Skip $reason"
_skip_all=1
_plan_set=1
_exit 0
return 0
}
plan_tests(){
local tests=${1:?}
(( _plan_set != 0 )) && _die "You tried to plan twice!"
(( tests == 0 )) && _die "You said to run 0 tests! You've got to run something."
_print_plan $tests
_expected_tests=$tests
_plan_set=1
return $tests
}
_print_plan(){
local tests=${1:?}
local directive=${2:-''}
echo -n "1..$tests"
[[ -n "$directive" ]] && echo -n " # $directive"
echo
}
pass(){
local name=$1
ok 0 "$name"
}
fail(){
local name=$1
ok 1 "$name"
}
# This is the workhorse method that actually
# prints the tests result.
ok(){
local result=${1:?}
local name=${2:-''}
(( _plan_set == 0 )) && _die "You tried to run a test without a plan! Gotta have a plan."
_executed_tests=$(( $_executed_tests + 1 ))
if [[ -n "$name" ]] ; then
if _matches "$name" "^[0-9]+$" ; then
diag " You named your test '$name'. You shouldn't use numbers for your test names."
diag " Very confusing."
fi
fi
if (( result != 0 )) ; then
echo -n "not "
_failed_tests=$(( _failed_tests + 1 ))
fi
echo -n "ok $_executed_tests"
if [[ -n "$name" ]] ; then
local ename=${name//\#/\\#}
echo -n " - $ename"
fi
if [[ -n "$TODO" ]] ; then
echo -n " # TODO $TODO" ;
if (( result != 0 )) ; then
_failed_tests=$(( _failed_tests - 1 ))
fi
fi
echo
if (( result != 0 )) ; then
local file='tap-functions'
local func=
local line=
local i=0
local bt=$(caller $i)
while _matches "$bt" "tap-functions$" ; do
i=$(( $i + 1 ))
bt=$(caller $i)
done
local backtrace=
eval $(caller $i | (read line func file ; echo "backtrace=\"$file:$func() at line $line.\""))
local t=
[[ -n "$TODO" ]] && t="(TODO) "
if [[ -n "$name" ]] ; then
diag " Failed ${t}test '$name'"
diag " in $backtrace"
else
diag " Failed ${t}test in $backtrace"
fi
fi
return $result
}
okx(){
local command="$@"
local line=
diag "Output of '$command':"
$command | while read line ; do
diag "$line"
done
ok ${PIPESTATUS[0]} "$command"
}
_equals(){
local result=${1:?}
local expected=${2:?}
if [[ "$result" == "$expected" ]] ; then
return 0
else
return 1
fi
}
# Thanks to Aaron Kangas for the patch to allow regexp matching
# under bash < 3.
_bash_major_version=${BASH_VERSION%%.*}
_matches(){
local result=${1:?}
local pattern=${2:?}
if [[ -z "$result" || -z "$pattern" ]] ; then
return 1
else
if (( _bash_major_version >= 3 )) ; then
eval '[[ "$result" =~ "$pattern" ]]'
else
echo "$result" | egrep -q "$pattern"
fi
fi
}
_is_diag(){
local result=${1:?}
local expected=${2:?}
diag " got: '$result'"
diag " expected: '$expected'"
}
is(){
local result=${1:?}
local expected=${2:?}
local name=${3:-''}
_equals "$result" "$expected"
(( $? == 0 ))
ok $? "$name"
local r=$?
(( r != 0 )) && _is_diag "$result" "$expected"
return $r
}
isnt(){
local result=${1:?}
local expected=${2:?}
local name=${3:-''}
_equals "$result" "$expected"
(( $? != 0 ))
ok $? "$name"
local r=$?
(( r != 0 )) && _is_diag "$result" "$expected"
return $r
}
like(){
local result=${1:?}
local pattern=${2:?}
local name=${3:-''}
_matches "$result" "$pattern"
(( $? == 0 ))
ok $? "$name"
local r=$?
(( r != 0 )) && diag " '$result' doesn't match '$pattern'"
return $r
}
unlike(){
local result=${1:?}
local pattern=${2:?}
local name=${3:-''}
_matches "$result" "$pattern"
(( $? != 0 ))
ok $? "$name"
local r=$?
(( r != 0 )) && diag " '$result' matches '$pattern'"
return $r
}
skip(){
local condition=${1:?}
local reason=${2:-''}
local n=${3:-1}
if (( condition == 0 )) ; then
local i=
for (( i=0 ; i<$n ; i++ )) ; do
_executed_tests=$(( _executed_tests + 1 ))
echo "ok $_executed_tests # skip: $reason"
done
return 0
else
return
fi
}
diag(){
local msg=${1:?}
if [[ -n "$msg" ]] ; then
echo "# $msg"
fi
return 1
}
_die(){
local reason=${1:-'<unspecified error>'}
echo "$reason" >&2
_test_died=1
_exit 255
}
BAIL_OUT(){
local reason=${1:-''}
echo "Bail out! $reason" >&2
_exit 255
}
_cleanup(){
local rc=0
if (( _plan_set == 0 )) ; then
diag "Looks like your test died before it could output anything."
return $rc
fi
if (( _test_died != 0 )) ; then
diag "Looks like your test died just after $_executed_tests."
return $rc
fi
if (( _skip_all == 0 && _no_plan != 0 )) ; then
_print_plan $_executed_tests
fi
local s=
if (( _no_plan == 0 && _expected_tests < _executed_tests )) ; then
s= ; (( _expected_tests > 1 )) && s=s
local extra=$(( _executed_tests - _expected_tests ))
diag "Looks like you planned $_expected_tests test$s but ran $extra extra."
rc=-1 ;
fi
if (( _no_plan == 0 && _expected_tests > _executed_tests )) ; then
s= ; (( _expected_tests > 1 )) && s=s
diag "Looks like you planned $_expected_tests test$s but only ran $_executed_tests."
fi
if (( _failed_tests > 0 )) ; then
s= ; (( _failed_tests > 1 )) && s=s
diag "Looks like you failed $_failed_tests test$s of $_executed_tests."
fi
return $rc
}
_exit_status(){
if (( _no_plan != 0 || _plan_set == 0 )) ; then
return $_failed_tests
fi
if (( _expected_tests < _executed_tests )) ; then
return $(( _executed_tests - _expected_tests ))
fi
return $(( _failed_tests + ( _expected_tests - _executed_tests )))
}
_exit(){
local rc=${1:-''}
if [[ -z "$rc" ]] ; then
_exit_status
rc=$?
fi
_cleanup
local alt_rc=$?
(( alt_rc != 0 )) && rc=$alt_rc
trap - EXIT
exit $rc
}
argparse/test.sh 0 → 100755