CTutorial

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

• [Generating C parser & usage code](#Generating C parser & usage code)
  • [Step 1. Defining the options](#Step 1. Defining the options)
  • [Step 2. Generate parser header & sources](#Step 2. Generate parser header & sources)
  • [Step 3. Write your program](#Step 3. Write your program)
  • [Step 4. Build the program](#Step 4. Build the program)
  • [Step 5. Run!](#Step 5. Run!)
  • [Step 6. Beyond the C program](#Step 6. Beyond the C program)
    • [Auto complete](#Auto complete)
  • [See also](#See also)

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
<?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

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

This command line will generate two files [cmdline.h](https://github.com/noresources/ns-xml/wiki/cmdline.h) and [cmdline.c](https://github.com/noresources/ns-xml/wiki/cmdline.c) which will contains

• the base functions of the C parser (nsxml_* functions and structs)
• A struct miniapp_info which is a C representation of the XML file.
• A struct miniapp_result to receive the result of the command line parsing
• Functions to initialize and destroy miniapp_info miniapp_result
• miniapp_usage to display miniapp usage
• miniapp_parse to process command line arguments

Step 3. Write your program

Let's write a little and useless C program [miniapp.c](https://github.com/noresources/ns-xml/wiki/miniapp.c)

#!cpp
#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

#!bash
gcc -o miniapp miniapp.c cmdline.c

Step 5. Run!

#!bash
./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

#!bash
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

#!bash
. miniapp-autocomplete.inc.sh

And try typing

#!bash
./miniapp -<TAB>

The shell will propose...

#!bash
$ ./miniapp -
-a		   -h		   --help	   --some-arg   

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

See also

• The C parser API details
• build-c command line tool usage

---

The program interface definition framework