NAME

       lopsub - Long option parser for subcommands

About

       Lopsub  is  an  open  source library written in C which aims to ease the task of creating,
       documenting and parsing the options of Unix command line utilities.  It  is  suitable  for
       simple commands as well as complex command line utilities with many subcommands where each
       subcommand has its own set of options. Options and documentation are kept  together  in  a
       single file which can be translated to C code (to be included in the application), or to a
       manual page.  The library supports  single-character  short  options  and  GNU-style  long
       options. The public API is well documented and stable.

       To make use of the library, the programmer provides a so-called suite file which describes
       the options of the application in an intuitive syntax. At build time  the  suite  file  is
       translated  into C code by the lopsubgen utility which also ships with the lopsub package.
       The generated code defines an instance of an opaque C structure and exposes a reference to
       this  structure  which  can  be passed to the option parser at run time, together with the
       usual argument vector. The option parser is part of the lopsub  library,  so  applications
       need  to  link  with  -llopsub.  In addition to the option parser, the library offers many
       more features. For example, there is a function for merging two different parse results to
       generate  an  effective  configuration.  This  is  useful  for  applications  which can be
       configured through command line options and via a config file.

       The suite file can also be processed into roff format to create a manual page.  Conversion
       into html can easily be performed with tools like grohtml (part of GNU roff) or man2html.

       Lopsub  does not rely on the system's getopt() or getopt_long() functions of the C library
       and is thus portable across different flavors of Unix. It  is  known  to  work  on  Linux,
       NetBSD and FreeBSD.

License

       The  lopsub  library  is licensed under the LGPLv3 while the lopsubgen utility is licensed
       under the GPLv3.  The examples and all  code  generated  by  the  utilities,  however,  is
       licensed  under the public domain. You are free to do anything you like with the generated
       code, including incorporating it into or linking it with proprietary software.

Quick Start

       Compile and run the minimal example included at  the  end  of  lopsub-suite(5)  ⟨./lopsub-
       suite.5.html⟩.   Examine  lopsubex.c  and  lopsubex.suite  in  the source tree and run the
       lopsubex command.

API documentation

       See ⟨./lopsub-api.html⟩.  Alternatively, examine lopsub.h or lopsub.h.m4.

Resources

       • git clone URL: ⟨https://git.tuebingen.mpg.de/lopsub.git⟩

       • gitweb: ⟨https://git.tuebingen.mpg.de/lopsub.git⟩

       • The author's homepage: ⟨https://people.tuebingen.mpg.de/maan/⟩

       • Send feedback to Andre Noll ⟨maan@tuebingen.mpg.de⟩