Dropped record syntax for the option specifications to simplify use f…

…rom escripts.

ChangeLog

@@ -0,0 +1,9 @@
+2009-11-16  Juan Jose Comellas <juanjo@comellas.org>
+
+	* *: Released v0.1
+
+	* src/getopt.erl:
+	* src/test/getopt_test.erl:
+	* src/examples/ex1.erl:
+
+	Dropped record syntax for the option specifications to simplify	use from escripts.

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2009, Novamens SA
+Copyright (c) 2009 Juan Jose Comellas
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -11,8 +11,8 @@ are permitted provided that the following conditions are met:
     this list of conditions and the following disclaimer in the documentation
     and/or other materials provided with the distribution.
 
-  - Neither the name of Novamens SA nor the names of its contributors may be
-    used to endorse or promote products derived from this software without
+  - Neither the name of Juan Jose Comellas nor the names of its contributors may
+    be used to endorse or promote products derived from this software without
     specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND

README.markdown

@@ -28,81 +28,59 @@ Usage
 
 The *getopt* module provides two functions:
 
-    parse([#option{}], Args :: string() | [string()]) ->
+    parse([{Name, Short, Long, ArgSpec, Help}], Args :: string() | [string()]) ->
         {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}
 
-    usage([#option{}], ProgramName :: string()) -> ok
+    usage([{Name, Short, Long, ArgSpec, Help}], ProgramName :: string()) -> ok
 
-The ``parse/2`` function receives a list of ``#option{}`` records (defined in
-``getopt.hrl``) with the command line option specifications. The ``#option{}``
-record has the following elements:
+The ``parse/2`` function receives a list of tuples with the command line option
+specifications. The type specification for the tuple is:
 
-    -record(option, {
-              name              :: atom(),
-              short             :: char() | undefined,
-              long              :: string() | undefined,
-              arg               :: getopt_arg_type() | {getopt_arg_type(), getopt_arg()} | undefined.
-              help              :: string() | undefined
-             }).
+    -type arg_type() :: 'atom' | 'binary' | 'boolean' | 'float' | 'integer' | 'string'.
+
+    -type arg_value() :: atom() | binary() | boolean() | float() | integer() | string().
+
+    -type arg_spec() :: arg_type() | {arg_type(), arg_value()} | undefined.
+
+    -type option_spec() :: {
+                       Name    :: atom(),
+                       Short   :: char() | undefined,
+                       Long    :: string() | undefined,
+                       ArgSpec :: arg_spec(),
+                       Help    :: string() | undefined
+                      }.
 
 The fields of the record 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).
-  - ``arg``: data type the argument will be converted to with an optional default value. It can either be an atom() (one of: 'atom', 'binary', 'boolean', 'float', 'integer', 'string') or a tuple with an atom() and the default value for that argument.
-  - ``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.
 
 The second parameter holds the list of arguments as passed to the ``main/1``
-function in escripts.
-
-e.g.
+function in escripts. e.g.
 
-     #option{name     = port,
-             short    = $p,
-             long     = "port",
-             arg      = {integer, 5432},
-             help     = "Database server port"
-            }
+     {port, $p, "port", {integer, 5432}, "Database server port"}
 
 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
 all the arguments that did not have corresponding options.
 
-e.g. For a program named ``ex1.escript`` with the following option specifications:
+e.g. For a program named ``ex.escript`` with the following option specifications:
 
     OptSpec =
         [
-         #option{name     = host,
-                 short    = $h,
-                 long     = "host",
-                 arg      = {string, "localhost"},
-                 help     = "Database server host"
-                },
-         #option{name     = port,
-                 short    = $p,
-                 long     = "port",
-                 arg      = integer,
-                 help     = "Database server port"
-                },
-         #option{name     = dbname,
-                 long     = "dbname",
-                 arg      = {string, "users"},
-                 help     = "Database name"
-                },
-         #option{name     = xml,
-                 short    = $x,
-                 help     = "Output data in XML"
-                },
-         #option{name     = file,
-                 arg      = string,
-                 help     = "Output file"
-                }
+         {host,   $h,        "host",    {string, "localhost"}, "Database server host"},
+         {port,   $p,        "port",    integer,               "Database server port"},
+         {dbname, undefined, "dbname",  {string, "users"},     "Database name"},
+         {xml,    $x,        undefined, undefined,             "Output data in XML"},
+         {file,   undefined, undefined, string,                "Output file"}
         ].
 
 And this command line:
@@ -132,7 +110,7 @@ Also, the call to ``getopt:usage/2``:
 
 Will show (on *stdout*):
 
-    Usage: ex1 [-h <host>] [-p <port>] [--dbname <dbname>] [-x] <file>
+    Usage: ex.escript [-h <host>] [-p <port>] [--dbname <dbname>] [-x] <file>
 
       -h, --host                    Database server host
       -p, --port                    Database server port
@@ -146,13 +124,3 @@ Known limitations
 
   - The syntax for non-option arguments that start with '-' (e.g. -a -- -b)
     is not supported yet.
-
-
-Known problems
---------------
-
-Currently, with Erlang R13B (and older versions), escripts cannot use the
-``-include()`` preprocessor directive so you're forced to install the *getopt*
-package in Erlang's library path for your escripts to be able to include the
-``getopt.hrl`` header file that defines the ``#option{}`` record used by the
-functions in the *getopt* module.

examples/ex1.escript

@@ -0,0 +1,51 @@
+#!/usr/bin/env escript
+%% -*- erlang -*-
+%%! -sname ex1 -pz ebin
+
+%%%-------------------------------------------------------------------
+%%% @author Juan Jose Comellas <juanjo@comellas.org>
+%%% @copyright (C) 2009 Juan Jose Comellas
+%%% @doc Example file for the getopt module.
+%%% @end
+%%%
+%%% This source file is subject to the New BSD License. You should have received
+%%% a copy of the New BSD license with this software. If not, it can be
+%%% retrieved from: http://www.opensource.org/licenses/bsd-license.php
+%%%-------------------------------------------------------------------
+-module(ex1).
+-author('juanjo@comellas.org').
+
+main([]) ->
+    getopt:usage(option_spec_list(), "ex1.escript");
+main(Args) ->
+    OptSpecList = option_spec_list(),
+
+    io:format("For command line: ~p~n"
+              "getopt:parse/2 returns:~n~n", [Args]),
+    case getopt:parse(OptSpecList, Args) of
+        {ok, {Options, NonOptArgs}} ->
+            io:format("Options:~n  ~p~n~nNon-option arguments:~n  ~p~n", [Options, NonOptArgs]);
+        {error, {Reason, Data}} ->
+            io:format("Error: ~s ~p~n~n", [Reason, Data]),
+            getopt:usage(OptSpecList, "ex1.escript")
+    end.
+
+
+option_spec_list() ->
+    CurrentUser = case os:getenv("USER") of
+                      false ->
+                          "user";
+                      User ->
+                          User
+                  end,
+    [
+     %% {Name,     ShortOpt,  LongOpt,       ArgSpec,               HelpMsg}
+     {help,        $?,        "help",        undefined,             "Show the program options"},
+     {username,    $U,        "username",    string,                "Username to connect to the database"},
+     {password,    $P,        "password",    {string, CurrentUser}, "Password to connect to the database"},
+     {host,        $h,        "host",        {string, "localhost"}, "Database server host name or IP address"},
+     {port,        $p,        "port",        {integer, 1000},       "Database server port"},
+     {output_file, $o,        "output-file", string,                "File where the data will be saved to"},
+     {xml,         $x,        "xml",         undefined,             "Output data as XML"},
+     {dbname,      undefined, undefined,     string,                "Database name"}
+    ].

src/examples/ex1.erl

@@ -1,6 +1,6 @@
 %%%-------------------------------------------------------------------
-%%% @author Juan Jose Comellas <jcomellas@novamens.com>
-%%% @copyright (C) 2009, Novamens SA (http://www.novamens.com)
+%%% @author Juan Jose Comellas <juanjo@comellas.org>
+%%% @copyright (C) 2009 Juan Jose Comellas
 %%% @doc Example file for the getopt module.
 %%% @end
 %%%
@@ -9,9 +9,7 @@
 %%% retrieved from: http://www.opensource.org/licenses/bsd-license.php
 %%%-------------------------------------------------------------------
 -module(ex1).
--author('Juan Jose Comellas <jcomellas@novamens.com>').
-
--include("include/getopt.hrl").
+-author('juanjo@comellas.org').
 
 -export([test/0, test/1]).
 
@@ -26,7 +24,7 @@ test(CmdLine) ->
               "getopt:parse/2 returns:~n~n", [CmdLine]),
     case getopt:parse(OptSpecList, CmdLine) of
         {ok, {Options, NonOptArgs}} ->
-            io:format("Options:~n  ~p~nNon-option arguments:~n  ~p~n", [Options, NonOptArgs]);
+            io:format("Options:~n  ~p~n~nNon-option arguments:~n  ~p~n", [Options, NonOptArgs]);
         {error, {Reason, Data}} ->
             io:format("Error: ~s ~p~n~n", [Reason, Data]),
             getopt:usage(OptSpecList, "ex1")
@@ -36,48 +34,13 @@ test(CmdLine) ->
 option_spec() ->
     CurrentUser = os:getenv("USER"),
     [
-     #option{name     = help,
-             short    = $?,
-             long     = "help",
-             help     = "Show the program options"
-            },
-     #option{name     = username,
-             short    = $U,
-             long     = "username",
-             arg      = string,
-             help     = "Username to connect to the database"
-            },
-     #option{name     = password,
-             short    = $P,
-             long     = "password",
-             arg      = {string, CurrentUser},
-             help     = "Password to connect to the database"
-            },
-     #option{name     = host,
-             short    = $h,
-             long     = "host",
-             arg      = {string, "localhost"},
-             help     = "Database server host name or IP address"
-            },
-     #option{name     = port,
-             short    = $p,
-             long     = "port",
-             arg      = {integer, 1000},
-             help     = "Database server port"
-            },
-     #option{name     = output_file,
-             short    = $o,
-             long     = "output-file",
-             arg      = string,
-             help     = "File where the data will be saved to"
-            },
-     #option{name     = xml,
-             short    = $x,
-             long     = "xml",
-             help     = "Output data as XML"
-            },
-     #option{name     = dbname,
-             arg      = string,
-             help     = "Database name"
-            }
+     %% {Name,     ShortOpt,  LongOpt,       ArgSpec,               HelpMsg}
+     {help,        $?,        "help",        undefined,             "Show the program options"},
+     {username,    $U,        "username",    string,                "Username to connect to the database"},
+     {password,    $P,        "password",    {string, CurrentUser}, "Password to connect to the database"},
+     {host,        $h,        "host",        {string, "localhost"}, "Database server host name or IP address"},
+     {port,        $p,        "port",        {integer, 1000},       "Database server port"},
+     {output_file, $o,        "output-file", string,                "File where the data will be saved to"},
+     {xml,         $x,        "xml",         undefined,             "Output data as XML"},
+     {dbname,      undefined, undefined,     string,                "Database name"}
     ].