source: trunk/third/libIDL/libIDL2.texi @ 18251

\input texinfo @c -*- mode: texinfo -*-
@setfilename libIDL2.info
@settitle libIDL2
@setchapternewpage odd

@ifinfo
@dircategory Libraries
@direntry
* libIDL2: (libIDL2).     Interface Definition Language parsing library.
@end direntry

Copyright 1998 Andrew T. Veliath
@end ifinfo

@titlepage
@title libIDL2
@author Andrew T. Veliath

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998, 1999 Andrew T. Veliath
@end titlepage

@node Top, , , (dir)
@ifinfo
This file documents the Interface Definition Language (IDL) parsing
library, libIDL.

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

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

* Function Index::            Index of available functions.
@end menu

@node Overview, Example, top, top
@chapter Overview
libIDL is a library licensed under the GNU LGPL for creating trees of
CORBA Interface Definition Language (IDL) files, which is a
specification for defining portable interfaces.  libIDL was initially
written for ORBit (the ORB from the GNOME project, and the primary
means of libIDL distribution).  However, the functionality was
designed to be as reusable and portable as possible.

It is written in C, and the aim is to retain the ability to compile it
on a system with a standard C compiler.  Preprocessed parser files are
included so you are not forced to rebuild the parser, however an
effort is made to keep the parser and lexer compatible with standard
Unix yacc and lex (although bison and flex are more efficient, and are
used for the preprocessed parsers in the distribution).

With libIDL, you can parse an IDL file which will be automatically run
through the C preprocessor (on systems with one available), and have
detailed error and warning messages displayed.  On a compilation
without errors, the tree is returned to the custom application.
libIDL performs compilation phases from lexical analysis to nearly
full semantic analysis with some optimizations, and will attempt to
generate meaningful errors and warnings for invalid or deprecated IDL.

libIDL exports functionality used to generate detailed conforming
error and warning messages in gcc-like format, and also comes with a
default backend to generate IDL into a file or string (useful for
customized messages or comments in the output).  The IDL backend is
complete enough that most generated IDL can be reparsed by libIDL
without errors. libIDL returns separate syntax and namespace trees,
and includes functionality to hide syntactical information from the
primary tree, while keeping it accessible through the namespace for
type information and name lookup.

Optional extensions to standard IDL can be enabled using parse flags.
These include node properties, embedded code fragments, and XPIDL.
Nodes can also have declarations tags which assign particular
attributions to certain IDL constructs to further facilitate custom
applications.

@node Example, Reference, Overview, top
@chapter Usage
The following C program using libIDL will parse an IDL file and print
the Repository IDs of the interfaces in the IDL module.

@example
#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;
@}
@end example

@node Reference, Function Index, Example, top
@chapter Reference

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

@node Data Types, Functions, , Reference
@chapter Data Types

@itemize @bullet
@item
IDL_tree

A semi-opaque tree which encapsulates an IDL tree node.  Must be freed
with IDL_tree_free (@pxref{Functions}).

@item
IDL_ns

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

@item
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.

@item
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.

@end itemize

@node Functions, Extensions, Data Types, Reference
@chapter Functions

@itemize @bullet
@item
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)
@findex IDL_parse_filename

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.  Usually, if IDL_ERROR is
returned, all one needs to do is exit with a non-zero status, since
libIDL will probably have made the reason for failure explictly known.

@itemize @minus
@item
NAME: required, specifies the filename to be parsed.

@item
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>.

@item
CALLBACK: optional, if non-NULL, this function will be called when a
warning or error is generated (@pxref{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.

@item
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.

@item
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.

@item
FLAGS: optional, specifies extra flags for parsing or 0.  The various
flags are described here.

@item
General Parse Flags

@itemize @minus
@item
IDLF_NO_EVAL_CONST: instructs the parser not to evaluate constant expressions.

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

@item
IDLF_PREFIX_FILENAME: instructs the parser to prefix the filename to the
namespace.

@item
IDLF_IGNORE_FORWARDS: instructs the parser to not try to resolve and
print messages for unresovled forward declarations.

@item
IDLF_PEDANTIC: instructs the parser to display stricter errors and
warnings.

@item
IDLF_INHIBIT_TAG_ONLY: only tag inhibited nodes, do not remove them.
Use IDL_tree_remove_inhibits to remove them at a later time.

@item
IDLF_INHIBIT_INCLUDES: causes libIDL to automatically inhibit IDL trees
in included files.
@end itemize

@item
Syntax Extension Flags

@itemize @minus
@item
IDLF_TYPECODES: understand the `TypeCode' keyword extension.

@item
IDLF_XPIDL: enable XPIDL syntax.

@item
IDLF_PROPERTIES: enable support for node properties.

@item
IDLF_CODEFRAGS: enable support for embedded code fragments.
@end itemize

@item
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.

@end itemize

@item
Function: void IDL_tree_walk_in_order (IDL_tree ROOT, IDL_tree_func
FUNC, gpointer DATA)
@findex IDL_tree_walk_in_order

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.

@itemize @minus
@item
ROOT: required, specifies the IDL_tree to traverse.

@item
FUNC: required, specifies the callback function (@pxref{Data Types}).

@item
DATA: optional, specifies the callback data.

@end itemize

@item
Function: void IDL_tree_free (IDL_tree TREE)
@findex IDL_tree_free

Frees the memory associated with TREE.

@item
Function: void IDL_ns_free (IDL_ns NS)
@findex IDL_ns_free

Frees the memory associated with NS.

@end itemize

@node Extensions, Tree Structure, Functions, Reference
@chapter 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.

@itemize @bullet
@item
__declspec (<spec>)

This token assigns special attributions to particular IDL constructs.

@itemize @minus
@item
inhibit

If __declspec (inhibit) is placed before a definition or export, 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.

@end itemize

@end itemize

@node Tree Structure, , Extensions, Reference
@chapter Tree Structure

@node Function Index, , Reference, top
@chapter Function Index
@printindex fn

@contents
@bye