This file documents the GNOME Interface Definition Language parsing library, libIDL.

Copyright 1998 Andrew T. Veliath

This file documents the Interface Definition Language (IDL) parsing library, libIDL.

This document applies to version 0.5 of libIDL.  It is still incomplete.

Overview
********

libIDL is a small library for creating parse trees of CORBA v2.2 compliant Interface Definition Language (IDL) files, which is a specification for defining interfaces which can be used between different CORBA implementations.  Although the primary use of libIDL will be for a tool such as an IDL compiler, future uses may include use in an interface repository or interface browsing tool.  Since libIDL uses the Unix yacc and lex tools, the resulting library is not reentrant and is not thread-safe.  However, the yacc and lex functions are hidden so that it does not conflict with other yacc parsers or lex scanners.

By calling IDL_parse_filename, libIDL performs compilation phases from lexical analysis to nearly full semantic analysis and some optimization, and will attempt to generate meaningful errors and warnings for invalid or deprecated features, which can be redirected using callbacks.  libIDL supports some extensions to standard IDL, including declarations spec tags which can assign attributions to certain IDL constructs.

Usage
*****

The following C program using libIDL will parse an IDL file and print the Repository IDs of the interfaces in the IDL module.

     #include <assert.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <glib.h>
     #include <libIDL/IDL.h>

     gboolean
     print_repo_id (IDL_tree p, gpointer user_data)
     {
     	char *repo_id = NULL;

     	assert (p != NULL);

     	if (IDL_NODE_TYPE (p) == IDLN_INTERFACE)
     		repo_id = IDL_IDENT_REPO_ID (IDL_INTERFACE (p).ident);

     	if (repo_id)
     		printf ("%s\n", repo_id);

     	return TRUE;
     }

     int
     main (int argc, char *argv[])
     {
     	IDL_tree tree;
     	IDL_ns ns;
     	char *fn;
     	int rv;

     	if (argc < 2) {
     		fprintf (stderr, "usage: %s <file>\n", argv[0]);
     		exit (1);
     	}
     	fn = argv[1];

     	rv = IDL_parse_filename (fn, NULL, NULL, &tree, &ns, 0, IDL_WARNING1);

     	if (rv == IDL_ERROR || rv < 0) {
     		if (rv < 0)
     			perror (fn);
     		exit (1);
     	}
     	IDL_tree_walk_in_order (tree, print_repo_id, NULL);
     	IDL_ns_free (ns);
     	IDL_tree_free (tree);

     	return 0;
     }

Reference
*********

Data Types
**********

  * IDL_tree

     A semi-opaque tree which encapsulates an IDL tree node.  Must be freed with IDL_tree_free (see Functions).

  * IDL_ns

     A semi-opaque structure which encapsulates the IDL module namespace. Must be freed with IDL_ns_free (see Functions).

  * IDL_callback

     Defined as typedef int (*IDL_callback)(int LEVEL, int NUM, int LINE, const char *NAME, const char *ERR).  A function of this type can be optionally passed to IDL_parse_filename to be called when a parse warning or error occurs.

  * IDL_tree_func

     Defined as typedef gboolean (*IDL_tree_func)(IDL_tree TREE, gpointer DATA).  A function of this type is passed to IDL_tree_walk_in_order to traverse the tree.

Functions
*********

  * Function: int IDL_parse_filename (const char *NAME, const char *CPP_ARGS, IDL_callback CALLBACK, IDL_tree *TREE, IDL_ns *NS, unsigned long FLAGS, int MAX_MESSAGE_LEVEL)

     Parse an file containing an IDL definition into a parse tree.  Returns IDL_SUCCESS if successful, or IDL_ERROR if there was a parse error.  If -1 is returned, errno will be set accordingly.

       - NAME: required, specifies the filename to be parsed.

       - CPP_ARGS: optional, if non-NULL, specifies extra arguments to pass to the C preprocessor.  The most common type of string would be in the form of -I<dir> to include additional directories for file inclusion search, or defines in the form of -D<define>=<value>.

       - CALLBACK: optional, if non-NULL, this function will be called when a warning or error is generated (see Data Types).  If not given, warnings and errors will be sent to stderr.  All errors and warning, including callbacks, are subject to MAX_MESSAGE_LEVEL as described below.

       - TREE: optional, if non-NULL, points to an IDL_tree * to return the generated tree which must be freed with IDL_tree_free.  If NULL, the tree is freed and not returned.

       - NS: optional, if non-NULL, points to an IDL_ns * to return the namespace tree which must be freed with IDL_ns_free.  If NULL, the tree is freed and not returned.  If TREE is NULL, then NS must also be NULL, since the namespace is created as the AST is generated.

       - FLAGS: optional, specifies extra flags for parsing or 0.  Here are the possible flags:

            - IDLF_NO_EVAL_CONST: instructs the parser not to evaluate constant expressions.

            - IDLF_COMBINE_REOPENED_MODULES: instructs the parser to combine modules defined later in the IDL code in the first module node in the tree.

            - IDLF_PREFIX_FILENAME: instructs the parser to prefix the filename to the namespace.

       - MAX_MESSAGE_LEVEL:

          This specifies the maximum message level to display.  Possible values are -1 for no messages, IDL_ERROR for errors only, or IDL_WARNING1, IDL_WARNING2 and IDL_WARNING3.  A typical value is IDL_WARNING1, which will limit verbosity.  IDL_WARNINGMAX is defined as the value in which all messages will be displayed.

  * Function: void IDL_tree_walk_in_order (IDL_tree ROOT, IDL_tree_func FUNC, gpointer DATA)

     Walks an IDL_tree, calling FUNC for every node.  If the FUNC returns TRUE for a particular node, that particular node will also be traversed, if FALSE is returned, that particular node will be skipped, in the assumption that the function has taken care of it.

       - ROOT: required, specifies the IDL_tree to traverse.

       - FUNC: required, specifies the callback function (see Data Types).

       - DATA: optional, specifies the callback data.

  * Function: void IDL_tree_free (IDL_tree TREE)

     Frees the memory associated with TREE.

  * Function: void IDL_ns_free (IDL_ns NS)

     Frees the memory associated with NS.

Extensions
**********

This page documents extensions to standard IDL which libIDL will understand.  To maintain portability, it is recommended that these extensions are only used with some sort of C preprocessor define so they can be conditionally omitted.

  * __declspec (<spec>)

     This token assigns special attributions to particular IDL constructs.

       - inhibit

          If __declspec (inhibit) is placed before a module or interface keyword, that module or interface definition will be removed from the tree.  The tree is only deleted when the IDL_ns component is freed, so it can be traversed from the namespace component for extended information, but will be omitted from the primary tree.

Tree Structure
**************