Request 2348 (accepted)

erlang-getopt.spec Changed

debian.changelog Changed

erlang-getopt.dsc Changed

getopt-0.8.2.tar.gz/rebar Deleted

getopt-0.8.2.tar.gz/Makefile -> getopt-1.0.1.tar.gz/Makefile Changed

getopt-0.8.2.tar.gz/README.md -> getopt-1.0.1.tar.gz/README.md Changed

@@ -8,40 +8,37 @@
 ------------
 
 You should only need a somewhat recent version of Erlang/OTP. The module has
-been tested with Erlang R13B, R14B, R15B and R16B.
-
-You also need a recent version of [rebar](http://github.com/basho/rebar) in
-the system path. If you're going to run the unit tests you need the latest
-version of rebar to make sure that the latest version of *getopt* is being
-used. rebar already includes a compiled copy of the ``getopt`` module in its
-own binary file and will give precedence to its own modules over the ones in
-the project.
+been tested with all versions of Erlang starting with R13B and ending with 20.
 
+You also need a recent version of [rebar3](http://www.rebar3.org/) in
+the system path.
 
 Installation
 ------------
 
-To compile the module you simply run ``make``.
-
-To run the unit tests run ``make test``.
-
-To run the example module run ``make example``.
+To compile the module you simply run `rebar3 compile`.
 
-To build the (very) limited documentation run ``make doc``.
+To run the unit tests run `rebar3 eunit`.
 
-After the module is compiled with ``make``, insert getopt into the Erlang lib directory (e.g. by soft link or copying).
+To build the (very) limited documentation run `rebar edoc`.
 
+To use getopt in your project you can just add it as a dependency in your
+`rebar.config` file in the following way:
 ```sh
-ln -s . /usr/local/lib/erlang/lib/getopt-0.8.2
+{deps,
+ [
+  {getopt, "1.0.1"}
+ ]
+}
 ```
 
 
 Usage
 -----
 
-The *getopt* module provides four functions:
+The `getopt` module provides four functions:
 
-``` erlang
+```erlang
 parse([{Name, Short, Long, ArgSpec, Help}], Args :: string() | [string()]) ->
     {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}
 
@@ -56,10 +53,10 @@
       CmdLineTail :: string(), OptionsTail :: [{string(), string}]) -> ok
 ```
 
-The ``parse/2`` function receives a list of tuples with the command line option
+The `parse/2` function receives a list of tuples with the command line option
 specifications. The type specification for the tuple is:
 
-``` erlang
+```erlang
 -type arg_type() :: 'atom' | 'binary' | 'boolean' | 'float' | 'integer' | 'string'.
 
 -type arg_value() :: atom() | binary() | boolean() | float() | integer() | string().
@@ -77,33 +74,33 @@
 
 The elements of the tuple are:
 
-  - ``Name``: name of the option.
-  - ``Short``: character for the short option (e.g. $i for -i).
-  - ``Long``: string for the long option (e.g. "info" for --info).
-  - ``ArgSpec``: data type and optional default value the argument will be converted to.
-  - ``Help``: help message that is shown for the option when ``usage/2`` is called.
+  - `Name`: name of the option.
+  - `Short`: character for the short option (e.g. $i for -i).
+  - `Long`: string for the long option (e.g. "info" for --info).
+  - `ArgSpec`: data type and optional default value the argument will be converted to.
+  - `Help`: help message that is shown for the option when `usage/2` is called.
 
 e.g.
 
-``` erlang
+```erlang
 {port, $p, "port", {integer, 5432}, "Database server port"}
 ```
 
-The second parameter receives the list of arguments as passed to the ``main/1``
+The second parameter receives the list of arguments as passed to the `main/1`
 function in escripts or the unparsed command line as a string.
 
 If the function is successful parsing the command line arguments it will return
 a tuple containing the parsed options and the non-option arguments. The options
-will be represented by a list of key-value pairs with the ``Name`` of the
+will be represented by a list of key-value pairs with the `Name` of the
 option as *key* and the argument from the command line as *value*. If the option
-doesn't have an argument, only the atom corresponding to its ``Name`` will be
+doesn't have an argument, only the atom corresponding to its `Name` will be
 added to the list of options. For the example given above we could get something
-like ``{port, 5432}``. The non-option arguments are just a list of strings with
+like `{port, 5432}`. The non-option arguments are just a list of strings with
 all the arguments that did not have corresponding options.
 
 e.g. Given the following option specifications:
 
-``` erlang
+```erlang
 OptSpecList =
     [
      {host,    $h,        "host",    {string, "localhost"}, "Database server host"},
@@ -117,25 +114,25 @@
 
 And this command line:
 
-``` erlang
+```erlang
 Args = "-h myhost --port=1000 -x myfile.txt -vvv dummy1 dummy2"
 ```
 
-Which could also be passed in the format the ``main/1`` function receives the arguments in escripts:
+Which could also be passed in the format the `main/1` function receives the arguments in escripts:
 
-``` erlang
+```erlang
 Args = ["-h", "myhost", "--port=1000", "-x", "file.txt", "-vvv", "dummy1", "dummy2"].
 ```
 
-The call to ``getopt:parse/2``:
+The call to `getopt:parse/2`:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, Args).
 ```
 
 Will return:
 
-``` erlang
+```erlang
 {ok,{[{host,"myhost"},
       {port,1000},
       xml,
@@ -145,27 +142,27 @@
      ["dummy1","dummy2"]}}
 ```
 
-The ``tokenize/1`` function will separate a command line string into
+The `tokenize/1` function will separate a command line string into
 tokens, taking into account whether an argument is single or double
 quoted, a character is escaped or if there are environment variables to
 be expanded. e.g.:
 
-``` erlang
+```erlang
 getopt:tokenize("  --name John\\ Smith --path \"John's Files\" -u ${USER}").
 ```
 
 Will return something like:
 
-``` erlang
+```erlang
 ["--name","John Smith","--path","John's Files","-u","jsmith"]
 ```
 
-The other functions exported by the ``getopt`` module (``usage/2``, ``usage/3``
-and ``usage/4``) are used to show the command line syntax for the program.
+The other functions exported by the `getopt` module (`usage/2`, `usage/3`
+and `usage/4`) are used to show the command line syntax for the program.
 For example, given the above-mentioned option specifications, the call to
-``getopt:usage/2``:
+`getopt:usage/2`:
 
-``` erlang
+```erlang
 getopt:usage(OptSpecList, "ex1").
 ```
 
@@ -180,10 +177,10 @@
       -v                            Verbosity level
       <file>                        Output file
 
-This call to ``getopt:usage/3`` will add a string after the usage command line:
+This call to `getopt:usage/3` will add a string after the usage command line:
 
-``` erlang
-    getopt:usage(OptSpecList, "ex1", "[var=value ...] [command ...]").
+```erlang
+getopt:usage(OptSpecList, "ex1", "[var=value ...] [command ...]").
 ```
 
 Will show (on *standard_error*):
@@ -197,10 +194,10 @@
       -v, --verbose         Verbosity level
       <file>                Output file
 
-Whereas this call to ``getopt:usage/3`` will also add some lines to the options
+Whereas this call to `getopt:usage/3` will also add some lines to the options
 help text:
 
-``` erlang
+```erlang
 getopt:usage(OptSpecList, "ex1", "[var=value ...] [command ...]",
              [{"var=value", "Variables that will affect the execution (e.g. debug=1)"},
               {"command",   "Commands that will be executed (e.g. count)"}]).
@@ -223,7 +220,7 @@
 Command-line Syntax
 -------------------
 
-The syntax supported by the ``getopt`` module is very similar to that followed
+The syntax supported by the `getopt` module is very similar to that followed
 by GNU programs, which is described [here](http://www.gnu.org/s/libc/manual/html_node/Argument-Syntax.html).
 
 Options can have both short (single character) and long (string) option names.
@@ -248,16 +245,16 @@
 --------------
 
 The arguments allowed for options are: *atom*; *binary*; *boolean*; *float*; *integer*; *string*.
-The ``getopt`` module checks every argument to see if it can be converted to its
+The `getopt` module checks every argument to see if it can be converted to its
 correct type.
 
 In the case of boolean arguments, the following values (in lower or
-upper case) are considered ``true``: *true*; *t*; *yes*; *y*; *on*; *enabled*; *1*.
-These ones are considered ``false``: *false*; *f*; *no*; *n*; *off*; *disabled*; *0*.
+upper case) are considered `true`: *true*; *t*; *yes*; *y*; *on*; *enabled*; *1*.
+These ones are considered `false`: *false*; *f*; *no*; *n*; *off*; *disabled*; *0*.
 
 Numeric arguments can only be negative when passed as part of an assignment expression.
 
-e.g. ``--increment=-100`` is a valid expression; whereas ``--increment -100`` is invalid
+e.g. `--increment=-100` is a valid expression; whereas `--increment -100` is invalid
 
 
 Implicit Arguments
@@ -279,7 +276,7 @@
 
 e.g. Given an option specification list with the following format:
 
-``` erlang
+```erlang
 OptSpecList =
     [
      {define,  $D, "define",  string,  "Define a variable"},
@@ -289,13 +286,13 @@
 
 The following invocation:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "-DFOO -DVAR1=VAL1 -DBAR --verbose --verbose=3 -v -vvvv dummy").
 ```
 
 would return:
 
-``` erlang
+```erlang
 {ok,{[{define,"FOO"}, {define,"VAR1=VAL1"}, {define,"BAR"},
       {verbose,1}, {verbose,3}, {verbose,1}, {verbose,4}],
      ["dummy"]}}
@@ -307,11 +304,11 @@
 
 We can also have options with neither short nor long option names. In this case,
 the options will be taken according to their position in the option specification
-list passed to ``getopt:/parse2``.
+list passed to `getopt:/parse2`.
 
 For example, with the following option specifications:
 
-``` erlang
+```erlang
 OptSpecList =
     [
      {xml,         $x,        "xml",     undefined, "Output data as XML"},
@@ -320,15 +317,15 @@
     ].
 ```
 
-This call to ``getopt:parse/2``:
+This call to `getopt:parse/2`:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "-x mydb file.out dummy dummy").
 ```
 
 Will return:
 
-``` erlang
+```erlang
 {ok,{[xml,{dbname,"mydb"},{output_file,"file.out"}],
      ["dummy","dummy"]}}
 ```
@@ -337,24 +334,24 @@
 Option Terminators
 ------------------
 
-The string ``--`` is considered an option terminator. This means that all the
+The string `--` is considered an option terminator. This means that all the
 command-line arguments after it are considered non-option arguments and will be
 returned without being evaluated even if they follow the *getopt* syntax.
 
 e.g. This invocation using the first option specification list in the document:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "-h myhost -p 1000 -- --dbname mydb dummy").
 ```
 
 will return:
 
-``` erlang
+```erlang
 {ok,{[{host,"myhost"}, {port,1000},{dbname,"users"}],
      ["--dbname","mydb","dummy"]}}
 ```
 
-Notice that the *dbname* option was assigned the value ``users`` instead of ``mydb``.
+Notice that the *dbname* option was assigned the value `users` instead of `mydb`.
 This happens because the option terminator prevented *getopt* from evaluating it
 and the default value was assigned to it.
 
@@ -362,17 +359,17 @@
 Non-option Arguments
 --------------------
 
-The single ``-`` character is always considered as a non-option argument.
+The single `-` character is always considered as a non-option argument.
 
 e.g. This invocation using the specification list from the previous example:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "-h myhost -p 1000 - --dbname mydb dummy").
 ```
 
 will return:
 
-``` erlang
+```erlang
 {ok,{[{host,"myhost"}, {port,1000}, {dbname,"mydb"}],
      ["-","dummy"]}}
 ```
@@ -388,7 +385,7 @@
 
 e.g. Given an option specification list with the following format:
 
-``` erlang
+```erlang
 OptSpecList =
     [
      {define,  $D, "define",  string,  "Define a variable"},
@@ -398,14 +395,14 @@
 
 The following invocation:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList,
              "-D'FOO=VAR 123' --define \"VAR WITH SPACES\" -u\"my user name\"").
 ```
 
 would return:
 
-``` erlang
+```erlang
 {ok,{[{define,"FOO=VAR 123"},
       {define,"VAR WITH SPACES"},
       {user,"my user name"}],
@@ -418,13 +415,13 @@
 
 e.g. The following invocation:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "--user ' my user ' \"argument with unclosed quotes").
 ```
 
 would return:
 
-``` erlang
+```erlang
 {ok,{[{user," my user "}],
      ["argument with unclosed quotes"]}}
 ```
@@ -448,7 +445,7 @@
 
 e.g. Given the following option specification list:
 
-``` erlang
+```erlang
 OptSpecList =
     [
      {path,    $p, "path",    string,  "File path"}
@@ -457,13 +454,13 @@
 
 The following invocation:
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "--path ${PATH} $NONEXISTENT_DUMMY_VAR").
 ```
 
 would return (depending on the value of your PATH variable) something like:
 
-``` erlang
+```erlang
 {ok,{[{path, "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"}],
      ["$NONEXISTENT_DUMMY_VAR"]}}
 ```
@@ -479,12 +476,12 @@
 
 e.g.
 
-``` erlang
+```erlang
 getopt:parse(OptSpecList, "--path /john\\'s\\ files dummy").
 ```
 
 Will return:
 
-``` erlang
+```erlang
 {ok,{[{path,"/john's files"}],["dummy"]}}
 ```

getopt-0.8.2.tar.gz/rebar.config -> getopt-1.0.1.tar.gz/rebar.config Changed

getopt-1.0.1.tar.gz/rebar.lock Added

getopt-0.8.2.tar.gz/src/getopt.app.src -> getopt-1.0.1.tar.gz/src/getopt.app.src Changed

getopt-0.8.2.tar.gz/src/getopt.erl -> getopt-1.0.1.tar.gz/src/getopt.erl Changed

@@ -1,6 +1,6 @@
 %%%-------------------------------------------------------------------
 %%% @author Juan Jose Comellas <juanjo@comellas.org>
-%%% @copyright (C) 2009 Juan Jose Comellas
+%%% @copyright (C) 2009-2017 Juan Jose Comellas
 %%% @doc Parses command line options with a format similar to that of GNU getopt.
 %%% @end
 %%%
@@ -12,7 +12,7 @@
 -author('juanjo@comellas.org').
 
 -export([parse/2, check/2, parse_and_check/2, format_error/2,
-         usage/2, usage/3, usage/4, tokenize/1]).
+         usage/2, usage/3, usage/4, usage/6, tokenize/1]).
 -export([usage_cmd_line/2]).
 
 -define(LINE_LENGTH, 75).
@@ -149,8 +149,13 @@
 format_error(OptSpecList, {error, Reason}) ->
     format_error(OptSpecList, Reason);
 format_error(OptSpecList, {missing_required_option, Name}) ->
-    {_Name, Short, Long, _Type, _Help} = lists:keyfind(Name, 1, OptSpecList),
-    lists:flatten(["missing required option: -", [Short], " (", to_string(Long), ")"]);
+    OptStr = case lists:keyfind(Name, 1, OptSpecList) of
+                 {Name,  undefined, undefined, _Type, _Help} -> ["<", to_string(Name), ">"];
+                 {_Name, undefined,      Long, _Type, _Help} -> ["--", Long];
+                 {_Name,     Short, undefined, _Type, _Help} -> ["-", Short];
+                 {_Name,     Short,      Long, _Type, _Help} -> ["-", Short, " (", Long, ")"]
+             end,
+    lists:flatten(["missing required option: ", OptStr]);
 format_error(_OptSpecList, {invalid_option, OptStr}) ->
     lists:flatten(["invalid option: ", to_string(OptStr)]);
 format_error(_OptSpecList, {invalid_option_arg, {Name, Arg}}) ->
@@ -437,7 +442,7 @@
 to_type(float, Arg) ->
     list_to_float(Arg);
 to_type(boolean, Arg) ->
-    LowerArg = string:to_lower(Arg),
+    LowerArg = lowercase(Arg),
     case is_arg_true(LowerArg) of
         true ->
             true;
@@ -495,7 +500,7 @@
 
 -spec is_boolean_arg(string()) -> boolean().
 is_boolean_arg(Arg) ->
-    LowerArg = string:to_lower(Arg),
+    LowerArg = lowercase(Arg),
     is_arg_true(LowerArg) orelse is_arg_false(LowerArg).
 
 
@@ -535,8 +540,8 @@
 %%       arguments that are supported by the program.
 -spec usage([option_spec()], string(), output_stream() | string()) -> ok.
 usage(OptSpecList, ProgramName, OutputStream) when is_atom(OutputStream) ->
-    io:format(OutputStream, "~s~n~n~s~n",
-              [usage_cmd_line(ProgramName, OptSpecList), usage_options(OptSpecList)]);
+    io:format(OutputStream, "~ts~n~n~ts~n",
+              [unicode:characters_to_list(usage_cmd_line(ProgramName, OptSpecList)), unicode:characters_to_list(usage_options(OptSpecList))]);
 %% @doc  Show a message on standard_error indicating the command line options and
 %%       arguments that are supported by the program. The CmdLineTail argument
 %%       is a string that is added to the end of the usage command line.
@@ -549,8 +554,8 @@
 %%       is a string that is added to the end of the usage command line.
 -spec usage([option_spec()], ProgramName :: string(), CmdLineTail :: string(), output_stream() | [{string(), string()}]) -> ok.
 usage(OptSpecList, ProgramName, CmdLineTail, OutputStream) when is_atom(OutputStream) ->
-    io:format(OutputStream, "~s~n~n~s~n",
-              [usage_cmd_line(ProgramName, OptSpecList, CmdLineTail), usage_options(OptSpecList)]);
+    io:format(OutputStream, "~ts~n~n~ts~n",
+              [unicode:characters_to_list(usage_cmd_line(ProgramName, OptSpecList, CmdLineTail)), unicode:characters_to_list(usage_options(OptSpecList))]);
 %% @doc  Show a message on standard_error indicating the command line options and
 %%       arguments that are supported by the program. The CmdLineTail and OptionsTail
 %%       arguments are a string that is added to the end of the usage command line
@@ -566,8 +571,24 @@
 -spec usage([option_spec()], ProgramName :: string(), CmdLineTail :: string(),
             [{OptionName :: string(), Help :: string()}], output_stream()) -> ok.
 usage(OptSpecList, ProgramName, CmdLineTail, OptionsTail, OutputStream) ->
-    io:format(OutputStream, "~s~n~n~s~n",
-              [usage_cmd_line(ProgramName, OptSpecList, CmdLineTail), usage_options(OptSpecList, OptionsTail)]).
+    io:format(OutputStream, "~ts~n~n~ts~n",
+              [unicode:characters_to_list(usage_cmd_line(ProgramName, OptSpecList, CmdLineTail)), unicode:characters_to_list(usage_options(OptSpecList, OptionsTail))]).
+
+%% @doc Show a message on standard_error or standard_io indicating the
+%%      command line options and arguments that are supported by the
+%%      program. The Description allows for structured command line usage
+%%      that works in addition to the standard options, and appears between
+%%      the usage_cmd_line and usage_options sections.  The CmdLineTail and
+%%      OptionsTail arguments are a string that is added to the end of the
+%%      usage command line and a list of tuples that are added to the end of
+%%      the options' help lines.
+-spec usage([option_spec()], ProgramName :: string(), CmdLineTail :: string(),
+            Description :: string(),
+            [{OptionName :: string(), Help :: string()}],
+            output_stream()) -> ok.
+usage(OptSpecList, ProgramName, CmdLineTail, Description, OptionsTail, OutputStream) ->
+    io:format(OutputStream, "~ts~n~n~ts~n~n~ts~n",
+              [unicode:characters_to_list(usage_cmd_line(ProgramName, OptSpecList, CmdLineTail)), Description, unicode:characters_to_list(usage_options(OptSpecList, OptionsTail))]).
 
 
 -spec usage_cmd_line(ProgramName :: string(), [option_spec()]) -> iolist().
@@ -598,7 +619,7 @@
 %%      already wrapped according to the maximum MaxLineLength.
 -spec usage_cmd_line_options(MaxLineLength :: non_neg_integer(), [option_spec()], CmdLineTail :: string()) -> iolist().
 usage_cmd_line_options(MaxLineLength, OptSpecList, CmdLineTail) ->
-    usage_cmd_line_options(MaxLineLength, OptSpecList ++ string:tokens(CmdLineTail, " "), [], 0, []).
+    usage_cmd_line_options(MaxLineLength, OptSpecList ++ lexemes(CmdLineTail, " "), [], 0, []).
 
 usage_cmd_line_options(MaxLineLength, [OptSpec | Tail], LineAcc, LineAccLength, Acc) ->
     Option = [$\s | lists:flatten(usage_cmd_line_option(OptSpec))],
@@ -769,7 +790,7 @@
     %% Look for the first whitespace character in the current (reversed) line
     %% buffer to get a wrapped line. If there is no whitespace just cut the
     %% line at the position corresponding to the maximum length.
-    {NextLineAcc, WrappedLine} = case string:cspan(CurrentLineAcc, " \t") of
+    {NextLineAcc, WrappedLine} = case cspan(CurrentLineAcc, " \t") of
                                      WhitespacePos when WhitespacePos < Count ->
                                          lists:split(WhitespacePos, CurrentLineAcc);
                                      _ ->
@@ -912,3 +933,15 @@
     atom_to_list(Atom);
 to_string(Value) ->
     io_lib:format("~p", [Value]).
+
+%% OTP-20/21 conversion to unicode string module
+-ifdef(unicode_str).
+lowercase(Str) -> string:lowercase(Str).
+lexemes(Str, Separators) -> string:lexemes(Str, Separators).
+cspan(Str, Chars) -> length(element(1,string:take(Str, Chars, true))).
+-else.
+lowercase(Str) -> string:to_lower(Str).
+lexemes(Str, Separators) -> string:tokens(Str, Separators).
+cspan(Str, Chars) -> string:cspan(Str, Chars).
+-endif.
+

getopt-0.8.2.tar.gz/test/getopt_test.erl -> getopt-1.0.1.tar.gz/test/getopt_test.erl Changed

@@ -287,7 +287,10 @@
 check_test_() ->
     OptSpecList =
         [
-         {arg,        $a,        "arg",        string,   "Required arg"}
+         {  arg,        $a,     "arg",   string,   "Required arg"},
+         {short,        $s, undefined,   string,   "short option"},
+         { long, undefined,    "long",   string,   "long option"},
+         {other, undefined, undefined,   string,   "task"}
         ],
     {ok, {Opts, _}} = parse(OptSpecList, ""),
     [
@@ -301,6 +304,15 @@
      {"Format missing option error test 2",
       ?_assertEqual("missing required option: -a (arg)",
                     format_error(OptSpecList, {missing_required_option, arg}))},
+     {"Format missing option error test 3",
+      ?_assertEqual("missing required option: -s",
+                    format_error(OptSpecList, {missing_required_option, short}))},
+     {"Format missing option error test 4",
+      ?_assertEqual("missing required option: --long",
+                    format_error(OptSpecList, {missing_required_option, long}))},
+     {"Format missing option error test 5",
+      ?_assertEqual("missing required option: <other>",
+                    format_error(OptSpecList, {missing_required_option, other}))},
      {"Format invalid option error test 1",
       ?_assertEqual("invalid option: --verbose",
                     format_error(OptSpecList, {error, {invalid_option, "--verbose"}}))},

Overview

Request 2348 (accepted)

Request History