Generating C parser & usage code

This tutorial will demonstrate how to use the The program interface definition framework to generate a C command line parser for your program

Step 1. Defining the options

The first step is to describe the program options in a XML file. The XML elements have to follow the program interface XML Schema.

samples/miniapp/miniapp.xml

<?xml version="1.0" encoding="utf-8"?>
<prg:program version="2.0" xmlns:prg="http://xsd.nore.fr/program">
  <prg:name>miniapp</prg:name>
  <prg:version>1.0</prg:version>
  <prg:options>
    <prg:switch>
      <prg:databinding>
        <prg:variable>displayHelp</prg:variable>
      </prg:databinding>
      <prg:names>
        <prg:long>help</prg:long>
        <prg:short>h</prg:short>
      </prg:names>
    </prg:switch>
    <prg:argument>
      <prg:databinding>
        <prg:variable>arg</prg:variable>
      </prg:databinding>
      <prg:names>
        <prg:long>some-arg</prg:long>
        <prg:short>a</prg:short>
      </prg:names>
    </prg:argument>
  </prg:options>
</prg:program>

You can use any editor to write this file but an XML editor with auto-completion and XML Schema support will greatly increase the writing speed.

Step 2. Generate parser header & sources

Using the build-c command line tool

${NS_XML_PATH}/ns/sh/build-c.sh --xml-description miniapp.xml --embed --output .

This command line will generate two files cmdline.h and cmdline.c which will contains

Step 3. Write your program

Let's write a little and useless C program miniapp.c

#include "cmdline.h"

#include <stdio.h>
#include <stdlib.h>

int main (int argc, const char **argv)
{
  miniapp_result *result = NULL;
  miniapp_info *info = miniapp_info_new();
  result = miniapp_parse(info, argc, argv, 1);

  {
    size_t err = miniapp_result_error_count(result);
    printf("Errors: %d\n", (int)err);
    if (err != 0)
    {
      printf("Errors\n");
      miniapp_result_display_errors(stderr, result, " - ");
      miniapp_usage(stderr, info, result, nsxml_usage_format_short, NULL);
      miniapp_result_free(result);
      miniapp_info_free(info);
      return EXIT_FAILURE;
    }
  }

  if (result->subcommand_name)
  {
    printf("Subcommand: %s\n", result->subcommand_name);
  }
 
  if (result->options.displayHelp.is_set)
  {
    miniapp_usage(stdout, info, result, nsxml_usage_format_abstract, NULL);
    miniapp_result_free(result);
    miniapp_info_free(info);
    return EXIT_SUCCESS;
  }
 
  if (result->options.arg.is_set)
  {
    printf("You give a value to arg: %s\n", result->options.arg.argument.string_value);
  }
}

Step 4. Build the program

gcc -o miniapp miniapp.c cmdline.c

Step 5. Run!

./miniapp --help --some-arg "Bleeeh Blaaah"

You should try to type invalid options or forget the --some-arg argument to see what's happen.

Step 6. Beyond the C program

Auto complete

To get a bash auto-completion command file, use the bashcompletion.xsl style sheet to transform the option specification file

xsltproc -o miniapp-autocomplete.inc.sh ${NS_XML_PATH}/ns/xsl/program/${SCHEMA_VERSION}/bashcompletion.xsl miniapp.xml

Then, include the generated file in your current environment

. miniapp-autocomplete.inc.sh

And try typing

./miniapp -<TAB>

The shell will propose...

$ ./miniapp -
-a       -h      --help    --some-arg  

See the Bash auto-complete file generation for more details.

XUL Frontend

You can automatically build a XUL application without more work. Follow the XUL Tutorial to learn how.

See also

The program interface definition framework