md.h

Go to the documentation of this file.

/*****************************************************************************\
 *  Copyright  1995  The Board of Trustees of the University of Illinois.
 *  All rights reserved.
 *
 *  md.h, part of the interface to the internal representation of the 
 *  IMPACT Meta-Description Language
 *  John C. Gyllenhaal, Wen-mei Hwu, and The IMPACT Research Group
 *  Coordinated Science Laboratory
 *  University of Illinois at Urbana-Champaign
 *
 *  The IMPACT Research Group may be contacted at impact@crhc.uiuc.edu.
 *
 *  md.h (part of the interface to the internal representation of the
 *  IMPACT Meta-Description Language software), including both binary 
 *  and source (hereafter, Software) is copyrighted by The Board of Trustees
 *  of the University of Illinois (UI), and ownership remains with the UI.
 *
 *  The UI grants you (hereafter, Licensee) a license to use the Software for
 *  academic, research and internal business purposes only, without a fee.
 *  Licensee may distribute the Software to third parties provided that the
 *  copyright notice and this statement appears on all copies and that no
 *  charge is associated with such copies.
 *
 *  Licensee may make derivative works.  However, if Licensee distributes
 *  any derivative work based on or derived from the Software, then Licensee
 *  will clearly notify users that such derivative work is a modified
 *  version and not the original Software distributed by the UI.
 *
 *  Any Licensee wishing to make commercial use of the Software should contact
 *  the UI, c/o the Research and Technology Management Office [rtmo@uiuc.edu],
 *  to negotiate an appropriate license for such commercial use.  Commercial
 *  use includes (1) integration of all or part of the source code into a
 *  product for sale or license by or on behalf of Licensee to third parties,
 *  or (2) distribution of the Software to third parties that need it to
 *  utilize a commercial product sold or licensed by or on behalf of Licensee.
 *
 *  UI MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE FOR
 *  ANY PURPOSE.  IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
 *  THE UI SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USERS OF THIS
 *  SOFTWARE.
 *
 *  By using or copying this Software, Licensee agrees to abide by the
 *  copyright law and all other applicable laws of the U.S. including, but
 *  not limited to, export control laws, and the terms of this license.
 *  UI shall have the right to terminate this license immediately by written
 *  notice upon Licensee's breach of, or non-compliance with, any of its terms.
 *  Licensee may be held legally responsible for any copyright infringement
 *  that is caused or encouraged by Licensee's failure to abide by the terms
 *  of this license.
 *
 *  Form approved by University Counsel, M.A.R., 05/10/93
\*****************************************************************************/
/*****************************************************************************\
 *      File:   md.h
 *
 *      Description: Header file for the interface to the internal 
 *                   representation of the IMPACT Meta-Description Language
 *
 *      Creation Date:  March 1995
 *
 *      Authors: John C. Gyllenhaal and Wen-mei Hwu
 *
 *      Revisions:
 *           Shail Aditya (HP Labs) February 1996
 *           Changed MD_get_xxx() arguments to be consistent with MD_set_xxx()
 *           Added MD_num_xxx() which returns number of sections, entries, etc.
 *
 *           John C. Gyllenhaal  May 1996
 *           Folded Shail's changes back into IMPACT's version
 *           Changed low-level representation to use hex for integers
 *           Added MD_rename_entry(), MD_delete_element(), MD_max_field_index()
 *                 MD_max_element_index(), and MD_print_md_declarations()
 *           Changed all error messages to uniformly use MD_punt()
 * 
 *           John C. Gyllenhaal July 1996
 *           Implemented Shail Aditya's suggestion of adding void pointers to
 *           MD_Section and MD_Entry for the user's use.  Added functions
 *           MD_set_section_ext(), MD_get_section_ext(), MD_set_entry_ext(), 
 *           and MD_get_entry_ext().
 * *
\*****************************************************************************/

#ifndef MD2_H
#define MD2_H

/* Stdio.h needed for prototypes */
#include <stdio.h>

/*
 * MD data types supported. 
 * (Use defines instead of enum to allow fitting into short int
 *  in MD_Element)
 */
#define MD_INT          1
#define MD_DOUBLE       2
#define MD_STRING       3
#define MD_LINK         4

/* Field types supported */
typedef enum MD_FIELD_TYPE
{
    MD_REQUIRED_FIELD   = 1,
    MD_OPTIONAL_FIELD   = 2
} MD_FIELD_TYPE;

/* Used as index to declare optional element types */
#define MD_OPTIONAL_ELEMENTS    -1


/* Symbol table used for database section, entry, and field names.
 * Internal use only!  Not designed to be used by non-MD functions!
 */
typedef struct MD_Symbol
{
    char                        *name;          /* Not a copy! */
    unsigned int                hash_val;       /* Hashed value of name */
    void                        *data;          /* a MD_xxx structure */
    struct MD_Symbol_Table      *table;         /* For deletion of symbol */
    struct MD_Symbol            *next_hash;     /* For table's hash table */
    struct MD_Symbol            *prev_hash;
    struct MD_Symbol            *next_symbol;   /* For table's contents list */
    struct MD_Symbol            *prev_symbol;
    int                         symbol_id;      /* Used by MD_write_md */

} MD_Symbol;

typedef struct MD_Symbol_Table
{
    struct MD           *md;            /* For error messages */
    char                *name;          /* For error messages */
    MD_Symbol           **hash;         /* Array of size hash_size */
    int                 hash_size;      /* Must be power of 2 */
    int                 hash_mask;      /* AND mask, (hash_size - 1) */
    int                 resize_size;    /* When reached, resize hash table */
    MD_Symbol           *head_symbol;   /* Contents list */
    MD_Symbol           *tail_symbol;
    int                 symbol_count;
} MD_Symbol_Table;

/* Types to fill out later */

typedef struct MD
{
    char                *name;          /* Name of MD */
    MD_Symbol_Table     *section_table; /* Sections in the MD */
} MD;

typedef struct MD_Section
{
    MD                  *md;              /* MD that section is in */
    char                *name;            /* Name of section */
    MD_Symbol_Table     *field_decl_table;/* Field declared in the section */
    MD_Symbol_Table     *entry_table;     /* Entries in the section */
    int                 max_field_index;  /* Index of the max declared field */
    struct MD_Field_Decl **field_decl;    /* Array of field decl pointers */
    int                 field_array_size; /* Size of above field_decl array */
                                          /* and Entry's field array */
    MD_Symbol           *symbol;          /* In MD's section_table */
    void                *user_ext;        /* For user's use, NULL initially */
}
 MD_Section;

typedef struct MD_Element_Req
{
    struct MD_Field_Decl *field_decl;   /* Field decl that element_req is in */
    int                 require_index;  /* Index in field_decl->require array*/
    short               type;           /* Type of element required */
    char                *desc;          /* Description (for error messages) */
    int                 kleene_starred; /* 1 if kleene_starred */
    MD_Section          **link;         /* Array of section pointers */
    int                 link_array_size;/* Size/links in above link array */
} MD_Element_Req;

typedef struct MD_Field_Decl
{
    MD_Section          *section;           /* Section that field decl is in */
    int                 field_index;        /* Index in entry->field array*/
    char                *name;              /* Name of field being declared */
    MD_FIELD_TYPE       type;               /* Type of field being declared */
    int                 max_require_index;  /* Index of last requirement */
    MD_Element_Req      **require;          /* Decls of element requirements */
    int                 require_array_size; /* Size of above require array */
    MD_Element_Req      *kleene_starred_req;/* NULL if no req starred */
    MD_Symbol           *symbol;            /* In section->field_decl_table */
} MD_Field_Decl;

/* 
 * Each entry has an array of pointers to fields (of size field_size).
 * The pointers in the field array will be NULL for unspecified fields.
 */
typedef struct MD_Entry
{
    MD_Section          *section;       /* Section that entry is in */
    char                *name;          /* Name of entry */
    struct MD_Field     **field;        /* Array of field pointers, */
                                        /* of size section->field_array_size */
    MD_Symbol           *symbol;        /* In MD_Section's entry_table */
    void                *user_ext;      /* For user's use, NULL initially */
} MD_Entry;


/* The data in the database.  
 * Use macro interface routines for accessing data.
 */
typedef struct MD_Element
{
    struct MD_Field     *field;         /* Field element is in */
    unsigned short      element_index;  /* index in field->element */
    short               type;           /* The type of data accessed */
    union                               
    {
        int             i;              /* INT value */
        double          d;              /* DOUBLE value */
        char            *s;             /* STRING value */
        MD_Entry        *l;             /* LINK value */
    } value;
} MD_Element;

/*
 * Each field has an array of pointers to elements (of size array_size).
 * max_index is the index of the last element set to a value, -1 if
 * no elements have been set.
 * The pointers in element array will be NULL for unspecified elements.
 */
typedef struct MD_Field
{
    MD_Entry            *entry;            /* Entry that field is in */
    MD_Field_Decl       *decl;             /* Declaration of field contents */
    int                 max_element_index; /* max_index of last set element */
    MD_Element          **element;         /* Pointers to elements in field */
    int                 element_array_size;/* Size of above element array */
} MD_Field;


/*
 * MD prototypes/macros declarations
 */

#ifdef __cplusplus
extern "C" {
#endif

/* Start prototypes of MD interface functions */
extern MD *MD_new_md (char *name, int num_sections);
extern int MD_check_md (FILE *out, MD *md);
extern void MD_delete_md (MD *md);

extern MD_Section *MD_new_section (MD *md, char *name, int num_entries, 
                            int num_fields);

extern MD_Section *MD_first_section (MD *md);
extern MD_Section *MD_last_section (MD *md);
extern MD_Section *MD_next_section (MD_Section *section);
extern MD_Section *MD_prev_section (MD_Section *section);

extern MD_Field_Decl *MD_new_field_decl (MD_Section *section, char *name, 
                                         MD_FIELD_TYPE field_type);

extern MD_Field_Decl *MD_first_field_decl (MD_Section *section);
extern MD_Field_Decl *MD_last_field_decl (MD_Section *section);
extern MD_Field_Decl *MD_next_field_decl (MD_Field_Decl *field_decl);
extern MD_Field_Decl *MD_prev_field_decl (MD_Field_Decl *field_decl);

extern void MD_require_int (MD_Field_Decl *field_decl, int element_index);
extern void MD_require_double (MD_Field_Decl *field_decl, int element_index);
extern void MD_require_string (MD_Field_Decl *field_decl, int element_index);
extern void MD_require_link (MD_Field_Decl *field_decl, int element_index, 
                      MD_Section *section);
extern void MD_require_multi_target_link (MD_Field_Decl *field_decl, 
                                   int element_index, int section_array_size,
                                   MD_Section **section_array);
extern void MD_kleene_star_requirement (MD_Field_Decl *field_decl, 
                                        int element_index);

extern MD_Entry *MD_new_entry (MD_Section *section, char *name);
extern void MD_rename_entry (MD_Entry *entry, char *new_name);

extern MD_Entry *MD_first_entry (MD_Section *section);
extern MD_Entry *MD_last_entry (MD_Section *section);
extern MD_Entry *MD_next_entry (MD_Entry *entry);
extern MD_Entry *MD_prev_entry (MD_Entry *entry);

extern MD_Field *MD_new_field (MD_Entry *entry, MD_Field_Decl *decl, 
                               int num_elements);
extern void MD_delete_field (MD_Field *field);
extern void MD_delete_field_decl (MD_Field_Decl *field_decl);
extern void MD_delete_element (MD_Field *field, int index);

extern MD *MD_read_md (FILE *in, char *name);
extern void MD_write_md (FILE *out, MD *md);
extern void MD_print_md (FILE *out, MD *md, int page_width);
extern void MD_print_md_declarations (FILE *out, MD *md, int page_width);
extern void MD_print_md_template (FILE *out, MD *md);

extern void MD_print_section (FILE *out, MD_Section *section, int page_width);
extern void MD_print_section_template (FILE *out, MD_Section *section);
extern void MD_print_field_decl (FILE *out, MD_Field_Decl *field_decl,
                                 int page_width);
extern void MD_print_entry (FILE *out, MD_Entry *entry, int page_width);
extern void MD_print_entry_template (FILE *out, MD_Entry *entry);

#ifdef __cplusplus
}
#endif

/* End prototypes of MD interface functions */

/* 
 * MD macros.
 * Two versions available:
 *  1) macro replaced with code optimized for speed.
 *  2) macro replaced with function call version.
 *
 *  Version 2 is provided to aid debugging macro arguments.
 */
#ifndef MD_DEBUG_MACROS

#define MD_num_sections(md)             ((md)->section_table->symbol_count)
#define MD_find_section(md, name) \
            ((MD_Section *)_MD_find_symbol_data((md)->section_table, name))


#define MD_delete_section(section) \
            (MD_delete_symbol(((MD_Section *)(section))->symbol, \
                              (void (*)(void *))_MD_free_section))

#define MD_num_entries(section)         ((section)->entry_table->symbol_count)

#define MD_find_entry(section, name) \
            ((MD_Entry *)_MD_find_symbol_data((section)->entry_table, name))

#define MD_delete_entry(entry) \
            (MD_delete_symbol(((MD_Entry *)(entry))->symbol, \
                              (void (*)(void *))_MD_free_entry))

#define MD_num_field_decls(section) \
            ((section)->field_decl_table->symbol_count)

#define MD_max_field_index(section)     ((section)->max_field_index)

#define MD_find_field_decl(section, name) \
          ((MD_Field_Decl *)_MD_find_symbol_data((section)->field_decl_table, \
                                                 name))

#define MD_find_field(entry, field_decl) \
            ((entry)->field[(field_decl)->field_index])

#define MD_num_elements(field)          ((field)->max_element_index + 1)
#define MD_max_element_index(field)     ((field)->max_element_index)

#define MD_set_int(field, index, value) _MD_set_int(field, index, value)
#define MD_get_int(field, index)        ((field)->element[index]->value.i)

#define MD_set_double(field, index, value) _MD_set_double(field, index, value)
#define MD_get_double(field, index)     ((field)->element[index]->value.d)

#define MD_set_string(field, index, value) _MD_set_string(field, index, value)
#define MD_get_string(field, index)     ((field)->element[index]->value.s)

#define MD_set_link(field, index, value) _MD_set_link(field, index, value)
#define MD_get_link(field, index)       ((field)->element[index]->value.l)

#define MD_set_section_ext(section, ext) ((section)->user_ext = (void *)(ext))
#define MD_get_section_ext(section)     ((section)->user_ext)

#define MD_set_entry_ext(entry, ext)    ((entry)->user_ext = (void *)(ext))
#define MD_get_entry_ext(entry)         ((entry)->user_ext)

#else

#define MD_num_sections(md)             _MD_num_sections(md)
#define MD_find_section(md, name)       _MD_find_section(md, name)
#define MD_delete_section(section)      _MD_delete_section(section)

#define MD_num_entries(section)         _MD_num_entries(section)
#define MD_find_entry(section, name)    _MD_find_entry(section, name)
#define MD_delete_entry(entry)          _MD_delete_entry(entry)


#define MD_num_field_decls(section)     _MD_num_field_decls(section)
#define MD_max_field_index(section)     _MD_max_field_index(section)
#define MD_find_field_decl(section, name) _MD_find_field_decl(section, name)

#define MD_find_field(entry, field_decl) _MD_find_field(entry, field_decl)

#define MD_num_elements(field)          _MD_num_elements(field)
#define MD_max_element_index(field)     _MD_max_element_index(field)

#define MD_set_int(field, index, value) \
            _MD_set_int_type_checking(field, index, value)
#define MD_get_int(field, index)        _MD_get_int(field, index)

#define MD_set_double(field, index, value) \
            _MD_set_double_type_checking(field, index, value)
#define MD_get_double(field, index)     _MD_get_double(field, index)

#define MD_set_string(field, index, value) \
            _MD_set_string_type_checking(field, index, value)
#define MD_get_string(field, index)     _MD_get_string(field, index)

#define MD_set_link(field, index, value) \
            _MD_set_link_type_checking(field, index, value)
#define MD_get_link(field, index)       _MD_get_link(field, index)

#define MD_set_section_ext(section, ext) \
            _MD_set_section_ext(section, (void *)(ext))
#define MD_get_section_ext(section)     _MD_get_section_ext(section)

#define MD_set_entry_ext(entry, ext)    _MD_set_entry_ext(entry, (void *)(ext))
#define MD_get_entry_ext(entry)         _MD_get_entry_ext(entry)


#endif

/* MD checking macros (only one version available) */
#define MD_check_section(out, section) \
             _MD_check_section(out, section, "MD_check_section")
#define MD_check_entry(out, entry) \
             _MD_check_entry(out, entry, "MD_check_entry")
#define MD_check_field(out, field) \
             _MD_check_field(out, field, "MD_check_field")






/* Start prototypes of functions used by MD macros.  
 * DO NOT CALL THE FUNCTIONS BELOW DIRECTLY!
 */

#ifdef __cplusplus
extern "C" {
#endif

extern void *_MD_find_symbol_data (MD_Symbol_Table *table, char *name);

extern int _MD_num_sections (MD *md);
extern MD_Section *_MD_find_section (MD *md, char *name);
extern void *_MD_set_section_ext(MD_Section *section, void *ext);
extern void *_MD_get_section_ext(MD_Section *section);
extern void _MD_free_section (MD_Section *section);
extern void _MD_delete_section (MD_Section *section);
extern int _MD_check_section (FILE *out, MD_Section *section, 
                              char *caller_name);


extern int _MD_num_entries (MD_Section *section);
extern MD_Entry *_MD_find_entry (MD_Section *section, char *name);
extern void *_MD_set_entry_ext(MD_Entry *entry, void *ext);
extern void *_MD_get_entry_ext(MD_Entry *entry);
extern void _MD_free_entry (MD_Entry *entry);
extern void _MD_delete_entry (MD_Entry *entry);
extern int _MD_check_entry (FILE *out, MD_Entry *entry, char *caller_name);

extern MD_Field_Decl *_MD_find_field_decl (MD_Section *section, char *name);
extern void _MD_free_field_decl (MD_Field_Decl *field_decl);

extern int _MD_num_field_decls (MD_Section *section);
extern int _MD_max_field_index (MD_Section *section);

extern MD_Field *_MD_find_field (MD_Entry *entry, MD_Field_Decl *field_decl);
extern int _MD_check_field (FILE *out, MD_Field *field, char *caller_name);

extern int _MD_num_elements (MD_Field *field);
extern int _MD_max_element_index (MD_Field *field);

extern void _MD_set_int (MD_Field *field, int index, int value);
extern void _MD_set_int_type_checking (MD_Field *field, int index, int value);
extern int _MD_get_int (MD_Field *field, int index);

extern void _MD_set_double (MD_Field *field, int index, double value);
extern void _MD_set_double_type_checking (MD_Field *field, int index,
                                          double value);
extern double _MD_get_double (MD_Field *field, int index);

extern void _MD_set_string (MD_Field *field, int index, char *value);
extern void _MD_set_string_type_checking (MD_Field *field, int index,
                                          char *value);
extern char *_MD_get_string (MD_Field *field, int index);

extern void _MD_set_link (MD_Field *field, int index, MD_Entry *value);
extern void _MD_set_link_type_checking (MD_Field *field, int index,
                                        MD_Entry *value);
extern MD_Entry *_MD_get_link (MD_Field *field, int index);

#ifdef __cplusplus
}
#endif
/* End prototypes of functions used by MD macros.  
 * DO NOT CALL THE FUNCTIONS ABOVE DIRECTLY!
 */

#endif

---