This is libIDL.info, produced by Makeinfo version 3.12a from
libIDL.texi.

INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* libIDL: (libIDL).     Interface Definition Language parsing library.
END-INFO-DIR-ENTRY

   Copyright 1998 Andrew T. Veliath


File: libIDL.info,  Node: Top,  Up: (dir)

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

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

* Menu:

* Overview::                  General overview.
* Example::                   Simple example.
* Reference::                 Data structure and function reference.

* Function Index::            Index of available functions.


File: libIDL.info,  Node: Overview,  Next: Example,  Prev: Top,  Up: Top

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.


File: libIDL.info,  Node: Example,  Next: Reference,  Prev: Overview,  Up: Top

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 <libIDL/IDL.h>
     
     gboolean
     print_repo_id (IDL_tree_func_data *tfd, gpointer user_data)
     {
     	char *repo_id = NULL;
     
     	if (IDL_NODE_TYPE (tfd->tree) == IDLN_INTERFACE)
     		repo_id = IDL_IDENT_REPO_ID (IDL_INTERFACE (tfd->tree).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;
     }


File: libIDL.info,  Node: Reference,  Next: Function Index,  Prev: Example,  Up: Top

Reference
*********

* Menu:

* Data Types::                Constructed data types used.
* Functions::                 Functions provided.
* Extensions::                Extensions provided to standard IDL.
* Tree Structure::            The C IDL tree representation.


File: libIDL.info,  Node: Data Types,  Next: Functions,  Up: Reference

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

   * IDL_tree

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

   * IDL_ns

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

   * IDL_msg_callback

     Defined as typedef int (*IDL_msg_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_func_data
     *TREE_FUNC_DATA, gpointer DATA).  A function of this type is
     passed to IDL_tree_walk_in_order to traverse the tree.
     TREE_FUNC_DATA contains an up traversal hierarchy of the current
     traversal, as well as some state information.  The current node
     being processed is given by TREE_FUNC_DATA->tree.


File: libIDL.info,  Node: Functions,  Next: Extensions,  Prev: Data Types,  Up: Reference

Functions
*********

   * Function: int IDL_parse_filename (const char *NAME, const char
     *CPP_ARGS, IDL_msg_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 (*note 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 (*note 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.


File: libIDL.info,  Node: Extensions,  Next: Tree Structure,  Prev: Functions,  Up: Reference

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.


File: libIDL.info,  Node: Tree Structure,  Prev: Extensions,  Up: Reference

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


File: libIDL.info,  Node: Function Index,  Prev: Reference,  Up: Top

Function Index
**************

* Menu:

* IDL_ns_free:                           Functions.
* IDL_parse_filename:                    Functions.
* IDL_tree_free:                         Functions.
* IDL_tree_walk_in_order:                Functions.



Tag Table:
Node: Top251
Node: Overview696
Node: Example1838
Node: Reference3094
Node: Data Types3450
Node: Functions4519
Node: Extensions7944
Node: Tree Structure8812
Node: Function Index8922

End Tag Table