src/lib/clopts.mlua

   1 --------------------------------------------------------------------------------
   2 -- Command Line OPTionS handler
   3 -- ============================
   4 --
   5 -- This lib generates parsers for command-line options. It encourages
   6 -- the following of some common idioms: I'm pissed off by Unix tools
   7 -- which sometimes will let you concatenate single letters options,
   8 -- sometimes won't, will prefix long name options with simple dashes
   9 -- instead of doubles, etc.
  10 --
  11 --------------------------------------------------------------------------------
  12
  13 -- TODO:
  14 -- * add a generic way to unparse options ('grab everything')
  15 -- * doc
  16 -- * when a short options that takes a param isn't the last element of a series
  17 --   of shorts, take the remaining of the sequence as that param, e.g. -Ifoo
  18 -- * let unset strings/numbers with +
  19 -- * add a ++ long counterpart to +
  20 --
  21
  22 -{ extension 'match' }
  23
  24 function clopts(cfg)
  25    local short, long, param_func = { }, { }
  26    local legal_types = table.transpose{
  27       'boolean','string','number','string*','number*','nil', '*' }
  28
  29    -----------------------------------------------------------------------------
  30    -- Fill short and long name indexes, and check its validity
  31    -----------------------------------------------------------------------------
  32    for x in ivalues(cfg) do
  33       local xtype = type(x)
  34       if xtype=='table' then
  35          if not x.type then x.type='nil' end
  36          if not legal_types[x.type] then error ("Invalid type name "..x.type) end
  37          if x.short then
  38             if short[x.short] then error ("multiple definitions for option "..x.short)
  39             else short[x.short] = x end
  40          end
  41          if x.long then
  42             if long[x.long] then error ("multiple definitions for option "..x.long)
  43             else long[x.long] = x end
  44          end
  45       elseif xtype=='function' then
  46          if param_func then error "multiple parameters handler in clopts"
  47          else param_func=x end
  48       end
  49    end
  50
  51    -----------------------------------------------------------------------------
  52    -- Print a help message, summarizing how to use the command line
  53    -----------------------------------------------------------------------------
  54    local function print_usage(msg)
  55       if msg then print(msg,'\n') end
  56       print(cfg.usage or "Options:\n")
  57       for x in values(cfg) do
  58          if type(x) == 'table' then
  59             local opts = { }
  60             if x.type=='boolean' then
  61                if x.short then opts = { '-'..x.short, '+'..x.short } end
  62                if x.long  then table.insert (opts, '--'..x.long) end
  63             else
  64                if x.short then opts = { '-'..x.short..' <'..x.type..'>' } end
  65                if x.long  then table.insert (opts,  '--'..x.long..' <'..x.type..'>' ) end
  66             end
  67             printf("  %s: %s", table.concat(opts,', '), x.usage or '<undocumented>')
  68          end
  69       end
  70       print''
  71    end
  72
  73    -- Unless overridden, -h and --help display the help msg
  74    if not short.h   then short.h   = {action=print_usage;type='nil'} end
  75    if not long.help then long.help = {action=print_usage;type='nil'} end
  76
  77    -----------------------------------------------------------------------------
  78    -- Helper function for options parsing. Execute the attached action and/or
  79    -- register the config in cfg.
  80    --
  81    -- * cfg  is the table which registers the options
  82    -- * dict the name->config entry hash table that describes options
  83    -- * flag is the prefix '-', '--' or '+'
  84    -- * opt  is the option name
  85    -- * i    the current index in the arguments list
  86    -- * args is the arguments list
  87    -----------------------------------------------------------------------------
  88    local function actionate(cfg, dict, flag, opt, i, args)
  89       local entry = dict[opt]
  90       if not entry then print_usage ("invalid option "..flag..opt); return false; end
  91       local etype, name = entry.type, entry.name or entry.long or entry.short
  92       match etype with
  93       | 'string' | 'number' | 'string*' | 'number*' ->
  94          if flag=='+' then
  95             print_usage ("flag "..flag.." is reserved for boolean options, not for "..opt)
  96             return false
  97          end
  98          local arg = args[i+1]
  99          if not arg then
 100             print_usage ("missing parameter for option "..flag..opt)
 101             return false
 102          end
 103          if etype:strmatch '^number' then
 104             arg = tonumber(arg)
 105             if not arg then
 106                print_usage ("option "..flag..opt.." expects a number argument")
 107             end
 108          end
 109          if etype:strmatch '%*$' then
 110             if not cfg[name] then cfg[name]={ } end
 111             table.insert(cfg[name], arg)
 112          else cfg[name] = arg end
 113          if entry.action then entry.action(arg) end
 114          return i+2
 115       | 'boolean' ->
 116          local arg = flag~='+'
 117          cfg[name] = arg
 118          if entry.action then entry.action(arg) end
 119          return i+1
 120       | 'nil' ->
 121          cfg[name] = true;
 122          if entry.action then entry.action() end
 123          return i+1
 124       | '*' ->
 125          local arg = table.isub(args, i+1, #args)
 126          cfg[name] = arg
 127          if entry.action then entry.action(arg) end
 128          return #args+1
 129       |  _ -> assert( false, 'undetected bad type for clopts action')
 130       end
 131    end
 132
 133    -----------------------------------------------------------------------------
 134    -- Parse a list of commands: the resulting function
 135    -----------------------------------------------------------------------------
 136    local function parse(...)
 137       local cfg = { }
 138       if not ... then return cfg end
 139       local args = type(...)=='table' and ... or {...}
 140       local i, i_max = 1, #args
 141       while i <= i_max do
 142          local arg, flags, opts, opt = args[i]
 143          --printf('beginning of loop: i=%i/%i, arg=%q', i, i_max, arg)
 144          if arg=='-' then
 145             i=actionate (cfg, short, '-', '', i, args)
 146             -{ `Goto 'continue' }
 147          end
 148
 149          -----------------------------------------------------------------------
 150          -- double dash option
 151          -----------------------------------------------------------------------
 152          flag, opt = arg:strmatch "^(%-%-)(.*)"
 153          if opt then
 154             i=actionate (cfg, long, flag, opt, i, args)
 155             -{ `Goto 'continue' }
 156          end
 157
 158          -----------------------------------------------------------------------
 159          -- single plus or single dash series of short options
 160          -----------------------------------------------------------------------
 161          flag, opts = arg:strmatch "^([+-])(.+)"
 162          if opts then
 163             local j_max, i2 = opts:len()
 164             for j = 1, j_max do
 165                opt = opts:sub(j,j)
 166                --printf ('parsing short opt %q', opt)
 167                i2 = actionate (cfg, short, flag, opt, i, args)
 168                if i2 ~= i+1 and j < j_max then
 169                   error ('short option '..opt..' needs a param of type '..short[opt])
 170                end
 171             end
 172             i=i2
 173             -{ `Goto 'continue' }
 174          end
 175
 176          -----------------------------------------------------------------------
 177          -- handler for non-option parameter
 178          -----------------------------------------------------------------------
 179          if param_func then param_func(args[i]) end
 180          if cfg.params then table.insert(cfg.params, args[i])
 181          else cfg.params = { args[i] } end
 182          i=i+1
 183
 184          -{ `Label 'continue' }
 185          if not i then return false end
 186       end -- </while>
 187       return cfg
 188    end
 189
 190    return parse
 191 end
 192
 193