Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Exception Compiler
[Tools]


Detailed Description

The exception/message compiler is a pre-compiler for creating message and exception object factory functions.

The sobjxc tool is a program for generating message logging functions and exception object factory functions. For every message ID and for every exception ID, a separate function is created. Messages and exceptions are specified through a definition file (see below).

Invocation

The sobjxc accepts the following command line arguments:

Definition Files

A definition file is a plain text file containing comment text and special directives recognized by the sobjxc tool. Anything that is not a directive is ignored.

A directive is a keyword preceeded by a star character ('*'). The star must be the first character on a line (without any preceeding whitespace). No whitespace characters are allowed between the star and the keyword.

The following directives are recognized:

The *option Directive

The option directive specifies zero or more option values that affect all directives following the option directive. The directive has the following syntax:

	*option SPEC
 
SPEC is parsed as a simple object in array context. The resulting object is appended to the current options object.

The option directive must be specified on a single input line.

The *include Directive

The include directive recursively processes a definition file. All option settings performed by the included file are local to that file and have no effect in the including file. The directive has the following syntax:

	*include FILE
 
FILE is parsed as a simple object in string context. If the specified file name does not start with a slash, then the include path is scaned for the file, followed by the local directory.

The include directive must be specified on a single input line.

The *message Directive

The message directive defines a message. The directive has the following syntax:

	*message OPTIONS TYPE ID PARAMS:
	COMMENT
	/message
 
or (the short form):
	*message OPTIONS TYPE ID PARAMS:/
 

The message directive may span multiple input lines.

The *exception Directive

The exception directive defines an exception ID. The directive has the following syntax:

	*exception OPTIONS CLASS-LIST ID PARAMS:
	COMMENT
	/exception
 
or (the short form):
	*exception OPTIONS CLASS ID PARAMS:/
 

The exception directive may span multiple input lines.

The *code Directive

The code directive specifies target language code to be included in the output file. If multiple code directives are specified for the same language, then the specified code blocks are concatenated. The directive has the following syntax:

	*code LANGUAGE:
	CODE
	/code
 
The following language values are recognized for LANGUAGE: Code directives for unrecognized languages are ignored.

The *type Directive

The type directive declares a custom type to be supported by a specific output backend. The directive has the following syntax:

	*type LANGUAGE DEFINITION
 
The LANGUAGE parameter is an output language identifier. The DEFINITION parameter is an array object. The argument for the DEFINITION parameter may span multiple input lines.

For the C backend, the DEFINITION has the following format:

	*type c [
	  type: TYPE
	  ctype: CTYPE
	  cvt: CVT
	]
 

The *eof Directive

The EOF directive indicates the end of the input file. Everything following an EOF directive is ignored. The directive has the following syntax:

	*eof
 

Formal Parameter Lists

Formal parameter lists may be omitted. An omitted parameter list is equivalent to an empty parameter list. A formal parameter list is a comma separated list of formal parameters, enclosed in parentheses. A formal parameter is a parameter type and a parameter name, separated by whitespace. Both the parameter name and the parameter type must be valid C identifiers. The set of parameter types supported for an output file depends on the output backend.

The C backend supports the following parameter types.

The C backend supports the declaration of custom types using the type directive.

Output Options

The option directive and the OPTIONS parameter of the message and exception directives may be used to customize the output. The option directive modifies the global options. The OPTIONS parameter specifies options local for a single message or exception.

Options may be specified in the standard KEY=VALUE syntax. For boolean options, a shorthand syntax is provided: OPTION is a shorthand for OPTION=true and no-OPTION is a shorthand for OPTION=false. E.g. you can simply write no-i18n instead of i18n=false.

The following options are recognized:

Message Handling Code

The C backend invokes the user supplied code for message handling through a macro with the name DO_MESSAGE(). The macro has the following signature:

        void DO_MESSAGE(
            void *target,
            const char *module,
            int type,
            int level,
            const char *id,
            struct sobj *message
            )

If a message is flagged for syslog() output, then the macro DO_SYSLOG() is expanded. The user code may supply its own version of the DO_SYSLOG() macro, which is required if the messages written to syslog() are to be internationalized. The default implementation of DO_SYSLOG() will use a canonical representation of the message. The macro has the following signature:

        void DO_SYSLOG(
            void *target,
            const char *module,
            int type,
            int level,
            const char *id,
            struct sobj *message
            )
The parameters have the same values as the parameters passed to the DO_MESSAGE() macro.

Generated C Code

The C code generated by the C backend provides the following definitions:

  1. An enumeration of message IDs and a conversion function mapping the message IDs to their string representations. The name of the enumeration type is enum module_msgid. The names of the enumeration constants are MODULE_MSGID_ID. The enumeration contains a fixed null-value named MODULE_MSGID_NONE. The name of the conversion function is module_msgid_to_string().
  2. For every message ID a preprocessor constant is defined. The name of the constants are MODULE_MSG_ID. The constants expand to plain string literals containing the message IDs.
  3. An enumeration of exception IDs and a conversion function mapping the exception IDs to their string representations. The name of the enumeration type is enum module_excid. The names of the enumeration constants are MODULE_EXCID_ID. The enumeration contains a fixed null-value named MODULE_EXCID_NONE. The named of the conversion function is module_excid_to_string().
  4. For every exception ID a preprocessor constant is defined. The named of the constants are MODULE_EXC_ID. The constants expand to plain string literals containing the message IDs.
  5. For every message ID, a message function is created (see below). If configured, then a convenience macro is defined for calling the message function.
  6. For every exception ID, an exception factory function is created (see below). If configured, then a convenience macro is defined for calling the exception factory function.

The symbol MODULE represents the module name in all uppercase characters. The symbol module represents the module name as it is defined (per convention this should be all lowercase characters). The symbol ID represents the respective message/exception ID.

Message Functions

The names of the message functions are prefixID(). The symbol prefix represents the message function prefix as defined through the option message-prefix. If the target option is set for the message, then the first parameter of the message function is a void-pointer to the message target (it is up to the user-supplied DO_MESSAGE() and/or DO_SYSLOG() macros to handle the target argument). The following three parameters are the name of the source file (as obtainable through the __FILE__ macro), the source line number (as obtainable through the __LINE__ macro), and the name of the calling function (as obtainable through the __func__ constant). The remaining parameters are the message parameters as declared in the message declaration. The return type of the message functions is void. Here's the signature of a message function:

        void {prefix}{id}(
            void *target, // Only if the target-option is set.
            const char *source_file,
            int source_line,
            const char *source_function,
            {...}
            )
The symbol {prefix} represents the prefix as defined in the message-prefix option, the symbol {id} represents the message ID, the symbol {...} represents the message parameters. If no information about the source file name is available or relevant, then the source_file parameter should be null; if no information about the source line number is available or relevant, then the source_line parameter should be zero; if no information about the calling function is available or relevant, then the source_function parameter should be null.

If the message-macro-prefix option is defined, then a convenience macro is defined for every message ID. The macro has the same signature as the functions, except that the source file name, source line, and calling function parameters are omitted. The expanded macro obtains these parameters through the __FILE__, __LINE__, and __func__ constants.

Exception Factory Functions

The names of the exception factory functions are prefixID. The symbol prefix represents the exception factory function prefix as defined through the option exception-prefix. The first three parameters if the exception factory function are the name of the source file (as obtainable through the __FILE__ macro), the source line number (as obtainable through the __LINE__ macro), and the name of the calling function (as obtainable through the __func__ constant). The remaining parameters are the exception parameters as declared in the exception declaration. The return type of the exception factory functions is struct sobj *. Here's the signature of an exception factory function:

        struct sobj *{prefix}{id}(
            const char *source_file,
            int source_line,
            const char *source_function,
            {...}
            )
The symbol {prefix} represents the prefix as defined in the exception-prefix option, the symbol {id} represents the exception ID, the symbol {...} represents the exception parameters. If no information about the source file name is available or relevant, then the source_file parameter should be null; if no information about the source line number is available or relevant, then the source_line parameter should be zero; if no information about the calling function is available or relevant, then the source_function parameter should be null.

An exception factory function never returns a null-pointer. The object returned is an array object with the class as specified through the cn option. If the cn option is not set, then the default class name "exc" is used. The exception object has the following fields:

If the exception-macro-prefix option is defined, then a convenience macro is defined for every message ID. The macro has the same signature as the functions, except that the source file name, source line, and calling function parameters are omitted. The expanded macro obtains these parameters through the __FILE__, __LINE__, and __func__ constants.


Modules

group  Implementation
 Documentation for the sobjxc tool implementation.


Generated on Sat Jul 23 16:07:34 2005 for sobject by  doxygen 1.3.9.1