AfterStep unifyed parsing code Developer's Guide.

Copyright Sasha Vasko < sasha at aftercode.net >

Table of Contents.

  1. Overview.
  2. Data structures.
  3. Functions.
  4. Files and Directories.
  5. Creating Config definition.
  6. Defining custom config data structure.
  7. Writing exception handling function.
  8. Writing config reader.
  9. Memory cleanup notes.
  10. Linking application to the Config Reader Code.

  1. Overview.

    2. The parsing code parser.c is a part of main AfterStep library - libafterstep. It allows for convinient parsing of the plain text configuration files, or configuration information from plain text buffer.

    Configuration information consists of two kinds of options -

    1. Executable name specific option.
      This options must be prepended with '*' character, and specific executable name - like *PagerMyOption.
    2. Non executable name specific options. Must not begin with '*' character.

    Configuration options are defined as a syntax definition.
    Syntax definition includes:

    1. terminator - character terminating single option;
    2. config_terminator - character terminating entire configuration data;
    3. terms - an array of term definitions.
      Term definition includes :
      1. term's flags - defining specific ways of treating that option;
      2. keyword - identifying this option in configuration file;
      3. type - definig option's data postprocessing method
      4. unique ID - identifying this option to the application.
    Prior to performing parsing - simple hash table is built from term definition's, for faster processing.

    Parsing is done in two steps :

    1. Building FreeStorage for configuration data:
      This step is done by ParseConfig() function.
      It creates linked list of FreeStorage elements, representing single configuration option each.
      FreeStorage elements consist of:
      1. term - pointer to the Term definition identifying option;
      2. argc - number of space separated data elements ( TF_DONT_SPLIT term's flag can be used to prevent splitting of the option's data into elements - in this case argc will be equal 1)
      3. argv - array of pointers to space separated data elements, that will be terminated with '\0' each.
      In case option needs some special processing and possibly need not to be included into FreeStorage - custom exception function can be supplied. ( like for processing ballons options in the module configuration.)
    2. Processing of FreeStorage into the application usable format:
      In this step linked list is processed by custom made, application specific function, in order to convert it into the application readable data structure.
      This data structure can be used later on for communication between Centralized Configuration module and the rest of the AfterStep, and between ascp and the rest of the AfterStep. Just my thoughts, anyway :).

    The way it is implemented now - all app-specific config reading code for the step 2 gothered together in the src/Config dir. It is all organized in the lib, but modules should link to specific object files to reduce executable's size.
    Header file for that stuff is : confdefs.h

  2. Data structures.

  3. Functions.

  4. Files and Directories.

  5. Creating Config definition.

  6. Defining custom config data structure.

  7. Writing exception handling function.

  8. Writing config reader.

  9. Memory cleanup notes.

  10. Linking application to the Config Reader Code.