\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