Lapp Framework

lua-users home

Making Simple Command-Line Scripts Easier

Original source is at; now in PenlightLibraries, see write up at [1].

Lapp is a small and focused Lua module which aims to make standard command-line parsing easier and intuitive. It implements the standard GNU style, i.e. short flags with one letter start with '-', and there may be an additional long flag which starts with '--'. Generally options which take an argument expect to find it as the next parameter (e.g. 'gcc test.c -o test') but single short options taking a numerical parameter can dispense with the space (e.g. 'head -n4 test.c')

As far as possible, Lapp will convert parameters into their equivalent Lua types, i.e. convert numbers and convert filenames into file objects. If any conversion fails, or a required parameter is missing, an error will be issued and the usage text will be written out. So there are two necessary tasks, supplying the flag and option names and associating them with a type.

For any non-trivial script, even for personal consumption, it's necessary to supply usage text. The novelty of Lapp is that it starts from that point and defines a loose format for usage strings which can specify the names and types of the parameters.

An example will make this clearer:

-- scale.lua
  require 'lapp'
  local args = lapp [[
  Does some calculations
    -o,--offset (default 0.0)  Offset to add to scaled number
    -s,--scale  (number)  Scaling factor
     <number> (number)  Number to be scaled

  print(args.offset + args.scale * args.number)

Here is a command-line session using this script:

  D:\dev\lua\lapp>lua scale.lua
  scale.lua:missing required parameter: scale

  Does some calculations
   -o,--offset (default 0.0)  Offset to add to scaled number
   -s,--scale  (number)  Scaling factor
    <number> (number )  Number to be scaled

  D:\dev\lua\lapp>lua scale.lua -s 2.2 10

  D:\dev\lua\lapp>lua scale.lua -s 2.2 x10
  scale.lua:unable to convert to number: x10

  ....(usage as before)

There are two kinds of lines in Lapp usage strings which are meaningful; option and parameter lines. An option line gives the short option, optionally followed by the corresponding long option. A type specifier in parentheses may follow. Similarly, a parameter line starts with '<' PARAMETER '>', followed by a type specifier. Type specifiers are either of the form '(default ' VALUE ')' or '(' TYPE ')'; the default specifier means that the parameter or option has a default value and is not required. TYPE is one of 'string','number','file-in' or 'file-out'; VALUE is a number, one of ('stdin','stdout','stderr') or a token. The rest of the line is not parsed and can be used for explanatory text.

This script shows the relation between the specified parameter names and the fields in the output table.

  -- simple.lua
  local args = require ('lapp') [[
  Various flags and option types
    -p          A simple optional flag, defaults to false
    -q,--quiet  A simple flag with long name
    -o  (string)  A required option with argument
    <input> (default stdin)  Optional input file parameter

  for k,v in pairs(args) do

I've just dumped out all values of the args table; note that args.quiet has become true, because it's specified; args.p defaults to false. If there is a long name for an option, that will be used in preference as a field name. A type or default specifier is not necessary for simple flags, since the default type is boolean.

The parameter input has been set to an open read-only file object - we know it must be a read-only file since that is the type of the default value. The field input_name is automatically generated, since it's often useful to have access to the original filename.

  D:\dev\lua\lapp>simple -o test -q simple.lua
  p       false
  input   file (781C1BD8)
  quiet   true
  o       test
  input_name      simple.lua
  D:\dev\lua\lapp>simple -o test simple.lua one two three
  1       one
  2       two
  3       three
  p       false
  quiet   false

  input   file (781C1BD8)
  o       test
  input_name      simple.lua

Notice that any extra parameters supplied will be put in the result table with integer indices, i.e. args[i] where i goes from 1 to #args.

Files don't really have to be closed explicitly for short scripts with a quick well-defined mission, since the result of garbage-collecting file objects is to close them.

Enforcing a Range for a Parameter

The type specifier can also be of the form '(' MIN '..' MAX ')'.

  require 'lapp'
  local args = lapp [[
  Setting ranges
    <x> (1..10)  A number from 1 to 10
    <y> (-5..1e6) Bigger range


Here the meaning is that the value is greater or equal to MIN and less or equal to MAX; there is no provision for forcing a parameter to be a whole number.

You may also define custom types that can be used in the type specifier:

    require ('lapp')

            lapp.assert(math.ceil(x) == x, 'not an integer!')

    local args =  lapp [[
        <ival> (integer) Process PID


lapp.add_type takes three parameters, a type name, a converter and a constraint function. The constraint function is expected to throw an assertion if some condition is not true; we use lapp.assert because it fails in the standard way for a command-line script. The converter argument can either be a type name known to Lapp, or a function which takes a string and generates a value.

'varargs' Parameter Arrays

    require 'lapp'
    local args = lapp [[
    Summing numbers
        <numbers...> (number) A list of numbers to be summed

    local sum = 0
    for i,x in ipairs(args.numbers) do
        sum = sum + x
    print ('sum is '..sum)

The parameter number has a trailing '...', which indicates that this parameter is a 'varargs' parameter. It must be the last parameter, and args.number will be an array.

Consider this implementation of the head utility from Unix-like OSs:

    -- implements a BSD-style head
    -- (see

    require ('lapp')

    local args = lapp [[
    Print the first few lines of specified files
       -n         (default 10)    Number of lines to print
       <files...> (default stdin) Files to print

    -- by default, lapp converts file arguments to an actual Lua file object.
    -- But the actual filename is always available as <file>_name.
    -- In this case, 'files' is a varargs array, so that 'files_name' is
    -- also an array.
    local nline = args.n
    local nfile = #args.files
    for i = 1,nfile do
        local file = args.files[i]
        if nfile > 1 then
            print('==> '..args.files_name[i]..' <==')
        local n = 0
        for line in file:lines() do
            n = n + 1
            if n == nline then break end

Note how we have access to all the filenames, because the auto-generated field files_name is also an array!

(This is probably not a very considerate script, since Lapp will open all the files provided, and only close them at the end of the script. See the xhead.lua example for another implementation.)

Flags and options may also be declared as vararg arrays, and can occur anywhere. Bare in mind that short options can be combined (like 'tar -xzf'), so it's perfectly legal to have '-vvv'. But normally the value of args.v is just a simple true.

    local args = require ('lapp') [[
       -v...  Verbosity level; can be -v, -vv or -vvv
    vlevel = not args.v[1] and 0 or #args.v

The vlevel assigment is a bit of Lua voodoo, so consider the cases:

Defining a Parameter Callback

If a script implements lapp.callback, then Lapp will call it after each argument is parsed. The callback is passed the parameter name, the raw unparsed value, and the result table. It is called immediately after assignment of the value, so the corresponding field is available.

    require ('lapp')

    function lapp.callback(parm,arg,args)

    local args = lapp [[
    Testing parameter handling
        -p               Plain flag (defaults to false)
        -q,--quiet       Plain flag with GNU-style optional long name
        -o  (string)     Required string option
        -n  (number)     Required number option
        -s (default 1.0) Option that takes a number, but will default
        <start> (number) Required number argument
        <input> (default stdin)  A parameter which is an input file
        <output> (default stdout) One that is an output file
    print 'args'
    for k,v in pairs(args) do

This produces the following output:

    D:\dev\lua\lapp>args -o name -n 2 10 args.lua
    +       o       name
    +       n       2
    +       start   10
    +       input   args.lua
    p       false
    s       1
    input_name      args.lua
    quiet   false
    output  file (781C1B98)
    start   10
    input   file (781C1BD8)
    o       name
    n       2

Why is a callback useful? There are cases where you would like to take action immediately on parsing an argument.


Very interesting idea! Perhaps this will lead to clones for other programming languages :) At any rate, thanks for this approach and writing the code.

One minor suggestion in lapp.lua -- something like 'local typespec' before line 178 of lapp.lua. This sort of change might make 'strict' happier.


Lapp is available under the same licence as Lua.

Copyright, SteveDonovan, 2009

See Also

RecentChanges · preferences
edit · history
Last edited May 16, 2015 8:12 pm GMT (diff)