A Tool to Manipulate BibTEX Files

C Programmers Manual

Gerd Neugebauer

Abstract

BibTool provides a library of useful C functions to manipulate BibTEX files. This library has been used to implement the BibTool program. This document describes This library and allows you to write C programs dealing with BibTEX files.

— This documentation is still in a rudimentary form and needs additional efforts. —

\underline{2}

This file is part of BibTool Version 2.47

Copyright \begin{matrix}c \\ ◯ \end{matrix}2003 Gerd Neugebauer

BibTool is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.

BibTool is distributed in the hope that it will be useful, but WITHOUT ANY WAR-RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; see the file COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

Gerd Neugebauer Mainzer Str. 8 56321 Rhens (Germany)

WWW: http://www.uni-koblenz.de/~gerd
Net: gerd@informatik.uni-koblenz.de

Contents

1 Introduction 7 1.1 The Module main.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 The BibTool C Library 9 2.1 The Header File bibtool/bibtool.h . . . . . . . . . . . . . . . . . . . . . . 9 2.2 The Header File bibtool/database.h . . . . . . . . . . . . . . . . . . . . . 9 2.3 The Module database.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.4 The Header File bibtool/entry.h . . . . . . . . . . . . . . . . . . . . . . . 14 2.5 The Module entry.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.6 The Header File bibtool/error.h . . . . . . . . . . . . . . . . . . . . . . . 17 2.7 The Module error.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8 The Header File bibtool/expand.h . . . . . . . . . . . . . . . . . . . . . . 22 2.9 The Module expand.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.10 The Header File bibtool/init.h . . . . . . . . . . . . . . . . . . . . . . . . 23 2.11 The Module init.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.12 The Header File bibtool/keynode.h . . . . . . . . . . . . . . . . . . . . . . 23 2.13 The Header File bibtool/key.h . . . . . . . . . . . . . . . . . . . . . . . . 24 2.14 The Module key.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.15 The Header File bibtool/macros.h . . . . . . . . . . . . . . . . . . . . . . 29 2.16 The Module macros.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2.17 The Header File bibtool/names.h . . . . . . . . . . . . . . . . . . . . . . . 32 2.18 The Module names.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 2.19 The Header File bibtool/parse.h . . . . . . . . . . . . . . . . . . . . . . . 34 2.20 The Module parse.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 2.21 The Header File bibtool/print.h . . . . . . . . . . . . . . . . . . . . . . . 35 2.22 The Module print.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 2.23 The Header File bibtool/pxfile.h . . . . . . . . . . . . . . . . . . . . . . 37 2.24 The Module pxfile.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.25 The Header File bibtool/record.h . . . . . . . . . . . . . . . . . . . . . . 38 2.26 The Module record.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 2.27 The Header File bibtool/rewrite.h . . . . . . . . . . . . . . . . . . . . . . 44 2.28 The Module rewrite.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 2.29 The Header File bibtool/resource.h . . . . . . . . . . . . . . . . . . . . . 46 2.30 The Header File bibtool/rsc.h . . . . . . . . . . . . . . . . . . . . . . . . 46 2.31 The Module rsc.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 2.32 The Header File bibtool/s parse.h . . . . . . . . . . . . . . . . . . . . . . 48 2.33 The Module s parse.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.34 The Header File bibtool/stack.h . . . . . . . . . . . . . . . . . . . . . . . 49 2.35 The Module stack.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.36 The Header File bibtool/sbuffer.h . . . . . . . . . . . . . . . . . . . . . . 50 2.37 The Module sbuffer.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 2.38 The Header File bibtool/symbols.h . . . . . . . . . . . . . . . . . . . . . . 52 2.39 The Module symbols.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.40 The Header File bibtool/tex aux.h . . . . . . . . . . . . . . . . . . . . . . 55 2.41 The Module tex aux.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 2.42 The Header File bibtool/tex read.h . . . . . . . . . . . . . . . . . . . . . 56 2.43 The Module tex read.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2.44 The Header File bibtool/type.h . . . . . . . . . . . . . . . . . . . . . . . . 58 2.45 The Module type.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 2.46 The Header File bibtool/version.h . . . . . . . . . . . . . . . . . . . . . . 61 2.47 The Module version.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 2.48 The Header File bibtool/wordlist.h . . . . . . . . . . . . . . . . . . . . . 61 2.49 The Module wordlist.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

3 Creating and Using the BibTool C Library 65 3.1 Creating the BibTool C Library . . . . . . . . . . . . . . . . . . . . . . . . 65 3.2 Using the BibTool C Library . . . . . . . . . . . . . . . . . . . . . . . . . . 66

CONTENTS 5

4 Coding Standards 67 4.1 K&R-C vs. ANSI-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

6 CONTENTS

Introduction

The BibTool C library provides functions to deal with BibTEX files. These functions are described in this document. Thus it should be fairly easy to write new C program which handle BibTEX files. The reader is assumed to be familiar with BibTEX files. this documentation will not repeat an introduction into BibTEX.

This documentation can not only be used to write new C programs dealing with BibTEX files but also to understand BibTool—The Program which serves as one example for using the BibToolC library. In any case it is essential to understand some of the underlying concepts. Thus it is vital to read some sections very carefully. Especially the section

The BibTool program uses the BibTool C library. Well, in fact it is the other way round. Historically the BibTool program was first and then the library has been extracted from it. Nevertheless the BibTool program can serve as an example how the BibTool C libary can be used.

1.1 The Module main.c

This is the BibTool main module. It contains the main() function which evaluates the command line arguments and proceeds accordingly. This means that usually resource files and BibTEX files are read and one or more BibTEX files are written.

This file makes use of the BibTool C library but is not part of it. For this purpose it has to provide certain functions which are expected by the library. These functions are:

     save input file()
     save macro file()
     save output file()

The arguments and the expected behaviour of these functions is described below.

If you are trying to understand the implementation of BibTool the file resource.h plays a central rôle. Consult the description of this file for further details.

If you are trying to write your own program to manipulate BibTEX files then this file can serve as a starting point. But you should keep in mind that this file has grown over several years and it contains the full complexity of the BibTool program logic. Thus you can reduce this file drastically if you start playing around with the BibTool C library.

int main()  Function

int   argc;  Number of arguments
char *argv[];  Array of arguments

This is the main function which is automatically called when the program is started. This function contains the overall program logic. It has to perform the appropriate initializations, evaluate command line arguments, and run the main loop.

Returns: 0 upon success. Usually a failure raises an exception which leads to an exit(). Thus this function does not need to signal an error to the calling environment.

void save input file()  Function

char *file;  File name to save.

The input file pipe is a dynamic array of strings. This fifo stack is used to store the input BibTEX files to be processed by BibTool.

This function is called to push an string into the pipe. If neccesary the array has to be allocated or enlarged. This is done in larger junks to avoid lots of calls to realloc().

Returns: nothing

void save macro file()  Function

char *file;  File name to save

Simply feed the macro file name into the static variable. This function is useful since it can be called from rsc.c

Returns: nothing

void save output file()  Function

char * file;  File name to save

Simply feed the output file name into the static variable. This function is useful since it can be called from rsc.c

The BibTool C Library

2.1 The Header File bibtool/bibtool.h

This header file contains includes for all other header files belonging to the BibTool C library. It is here for the convenience of the C programmer who doen not have to include two dozen header files but can use this single file. Thus any C program which utilizes the BibTool C library can start as follows:

#include <bibtool/bibtool.h>

Note that this include file also contains includes to system specific header files.

2.2 The Header File bibtool/database.h

This header file contains functions which deal with databases.

This header file provides also access to the functions and variables defined in database.c. Consult the documentation of this file for details.

This header file automatically includes <stdio.h> and record.h aswell.

DB Type

This is a pointer type referencing a BibTEX database. It contains all information which characterizes a database.

The members of this record should not be used explicitly. Instead the macros should be used which are provided to accss this data type.

     typedef struct  {

10 2. The BibTool C Library

Record db normal;  List of normal records.
Record db string;  List of local macros.
Record db preamble;  List of additional TEX code.

Record db comment; List of trailing comments which are not attached to

records.

Record db modify;  List of modification rules.
Record db include;  List of included files.

  Record db alias;  List of aliases.

} sDB, *DB;

DB NoDB  Macro

This is an invalid database. In fact it is NULL of the type DB.

Record DBnormal()  Macro

DB  The database to consider.

This is the functional representation of the normal component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBstring()  Macro

DB  The database to consider.

This is the functional representation of the string component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBpreamble()  Macro

DB  The database to consider.

This is the functional representation of the preamble component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBcomment()  Macro

DB  The database to consider.

This is the functional representation of the comment component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBalias()  Macro

DB  The database to consider.

This is the functional representation of the alias component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBmodify()  Macro

DB  The database to consider.

This is the functional representation of the modify component of a database. It can be used to extract this information. It can also be used as a lvalue.

Record DBinclude()  Macro

DB  The database to consider.

This is the functional representation of the include component of a database. It can be used to extract this information. It can also be used as a lvalue.

2.3 The Module database.c

This module contains functions which deal with databases. Databases are stored in an abstract datatype DB which is defined in database.h. Methods are provided to query and modify a database.

void db add record()  Function

DB     db;  Database to insert the record into.
Record rec;  Record to add to the database.

Add a record to a database. The record can be any kind of record. It is added to the appropriate category.

Returns: nothing

int *db count()  Function

DB   db;  Database to count.
int *lp;  pointer to an integer for the length.

Count all entries in a database. This includes normal aswell as special records. The result is stored in a static array which is reused by db_count(). A pointer to this array is returned. The indices correspond to the entry types defined with add_entry_type() or declared as symbolic constants in entry.h.

The end of the array is marked by an element containing a negative number. In addition the argument lp can point to an integer where the number of valid elements is stored. If lp is NULL this step is omitted.

Returns: Static array containing the statistics.

Record db find()  Function

DB    db;  Database to search in.

char *key;

Search the database for a record with a given key. If RecordOldKey is set for the record then use this value. Otherwise use *Heap. *Heap contains the reference key of normal records.

Deleted records are ignored. An arbitrary matching record is returned. Thus if more than one record have the same key then the behaviour is nondeterministic.

void db forall()  Function

DB    db;  Database containing rec.

int (*fct)(DB,Record); Boolean valued function determining the end of the processing. It takes two arguments a DB and a Record.

Visit all normal records in the data base and apply the given function fct to each. if this function returns TRUE then no more records need to be visited. No special order can be assumed in which the records are seen.

Returns: nothing

void db mac sort()  Function

DB db;  Database to sort.

Sort the macros of a database. The sorting uses increasing lexicographic order according to the character codes of the macro names. Note that this might lead to different results on machines with different character encodings, e.g. ASCII vs. EBCDIC.

Returns: nothing

char * db new key()  Function

DB    db;  Database to search in.

char *key;  Key to find.

Search the database for a record with a given old key and return the new one.

Returns: nothing

void db rewind()  Function

DB db;  Database to rewind.

Rewind the normal records of a database to point to the first record if at least one records exists. Otherwise nothing is done.

Returns: nothing

void db sort()  Function

DB    db;  Database to sort.

int (*less)(Record,Record); Comparison function to use. This boolean function takes two records and returns TRUE iff the first one is less than the second one.

Sort the normal records of a database. As a side effect the records are kept in sorted order in the database. The sorting order can be determined by the argument less which is called to compare two records.

char * db string()  Function

DB    db;  Database
char *s;  Name of the BibTEX macro to expand.

int localp; Boolean determining whether the search is only local to

the db.

Try to find the definition of a macro. First, the local values in the database db are considered. If this fails and localp is FALSE then the global list is searched aswell. If all fails NULL is returned.

Returns: The macro expansion or NULL upon failure.

void delete record()  Function

DB     db;  Database containing rec.
Record rec;  Record to delete.

Delete a record from a database. It is not checked, that the record really is part of the database. The record is just unlinked from its list. Just in case the record should be the first one the database record is modified.

Returns: nothing

void free db()  Function

DB db;  Database to release.

Deallocate the memory occupied by a database. Note that any references to this database becomes invalid.

Returns: nothing

DB new db()  Function

Create a new database and initialize it to contain no information. If no memory is left then an error is raised and the program is terminated.

Returns: The new database.

void print db()  Function

FILE *file;  The file handle for printing.
DB    db;  The database to print
char *spec;  String containing the specification of the parts to print.

Print a database to a file in a way which is readable by BibTEX. The spec determines which parts should be printed and the order of this parts. The spec is processed from left to right. Each unknown character is silently ignored. The following characters correspond to parts of the database:

p The preamble. $ All strings (macros) contained in the database.

S The strings (macros) which are used in the database. s The strings (macros) contained in the database where the resource print.all.strings

determines whether all strings should be printed or the used strings only. n The normal records. c The comments. i The includes. a The aliases. m The modifies.

Uppercase letters which are not mentioned are silently folded to their lowercase counterparts.

Returns: nothing

int read db()  Function

DB    db;  Database to augment.
char *file;  File name to read from.
int (*fct)(DB,Record);  Function to determine whether to store a given record.

int verbose; Boolean to determine whether progress should be re-

ported.

Read records from a file and add them to a database. A function has to be given as one argument. This function is called for each record. If this function returns TRUE then the record is added to the database. Otherwise the record is discarted.

The progress of reading is reported to stderr if the boolean argument verbose is

TRUE.

Returns: 1 if the file can not be opened. 0 otherwise.

2.4 The Header File bibtool/entry.h

This module provides also access to the functions and variables defined in entry.c. Consult also the documentation of this file for details.

This header file automatically includes symbols.h.

char ** entry type  Variable

This is an array of strings which represent entry types. They are either built-in or user defined. Use the function def_entry_type() to allocate a new entry type and the function get_entry_type() to find a certain entry type.

char * EntryName()  Macro

Entry  Index of the entry.

This is the functional representation of the name component for an entry type. The argument is the index of an entry type. This macro can also be used as lvalue. No range checks are performed.

int BIB EOF  Macro

This symbolic constant is returned when a record has to be read and the end of file has been encountered. It is some negative value for which no entry type is defined.

int BIB NOOP  Macro

This symbolic constant is returned when a record has to be read and something has been encountered which should be ignored. It is some negative value for which no entry type is defined.

int BIB STRING  Macro

This symbolic constant representing a record type of a BibTEX macro (@String). This is a special record type which is provided automatically.

int BIB PREAMBLE  Macro

This symbolic constant representing a record type of a BibTEX preamble (@Preamble). This is a special record type which is provided automatically.

int BIB COMMENT  Macro

This symbolic constant representing a record type of a BibTEX comment (@Comment). This is a special record type which is provided automatically.

int BIB ALIAS  Macro

This symbolic constant representing a record type of a BibTEX alias (@Alias) which is proposed for BibTEX 1.0. This is a special record type which is provided automatically.

int BIB MODIFY  Macro

This symbolic constant representing a record type of a BibTEX modification rule (@Modify) which is proposed for BibTEX 1.0. This is a special record type which is provided automatically.

int BIB INCLUDE  Macro

This symbolic constant representing a record type of a BibTEX inclusion instruction (@Include) which is proposed for BibTEX 1.0. This is a special record type which is provided automatically

IsSpecialRecord()  Macro

Type  Record type which should be checked.

Test whether a given record type denotes a special record. Special records are those defined above. They are provided automatically since BibTEX is supposed to do so as well.

Returns: TRUE iff the rcord type denoted a special record.

IsNormalRecord()  Macro

Type  Record type which should be checked.

Test whether a given record is a normal record. A normal record is one defined by a user. Normal records have indices larger than those of special records.

Returns: TRUE iff the rcord type denoted a normal record.

2.5 The Module entry.c

This module contains functions which deal with entry types. Right from the beginning only the special record types are known. Those special record types are @Comment, @Preamble,

@String, @Include, @Modify, and @Alias.

In addition to those special records the user can define additional record types which are denoted as “normal”. E.g. usually @Article and @Book are defined which are “normal” record types.

The record types are are managed in this module. In the other modules only numerical representations are used. This module provides means to map those numerical ids to the string representation and back. It is also possible to define additional record types.

Part of this module is likely to be integrated into databases.

void def entry type()  Function

char *s;  String containing the name of the entry.

Dynamically define an entry type. If the entry type already exists then a new printing representation is stored.

If no memory is left then an error is raised and the program is termined

Returns: nothing

int find entry type()  Function

char *s;  String of the potential entry name.

Look up an entry type in the array of defined entries.

Returns: The index in the array or NOOP.

char * get entry type()  Function

int idx;  Index of entry type.

Get the printable string representation corresponding to the numerical entry type given as argument. If no entry type is defined for the given index then NULL is returned.

Returns: Print representation of the entry type or NULL.

void init entries()  Function

Predefine some entry types which are stored at startup time in an array. The following entry types are predefined because they are considered special by BibTEX:

BIB STRING denotes a BibTEX macro definition. BIB PREAMBLE denotes a preamble item which goes before the bibligraphy en-

vironment. BIB COMMENT denotes a comment entry which is passed to the output file. BIB ALIAS denotes an alias entry which renames an existing entry. BIB MODIFY denotes a modification request which alters an existing entry. BIB INCLUDE denotes an include request which reads in another BibTEX file.

Note that this function is for internal purposes only. The normal user should call

init_bibtool() instead.

Returns: nothing

2.6 The Header File bibtool/error.h

This header file provides means for issuing error messages. Most of the macros provided in this header file are based on the function error() described in error.c. Nevertheless this function covers the general cases the macros in this header file are more convenient since they hide the unneccesary arguments of the error() function providing appropriate values.

This header file makes availlable the function error() as defined in error.c.

int ERR ERROR  Macro

Error type: Indicate that the error can not be suppressed and the messaged is marked as error.

int ERR WARNING  Macro

Error type: Indicate that the error is in fact a warning which can be suppressed. The messaged is marked as warning. This flag is only in effect if the ERR_ERROR flag is not set.

int ERR POINT  Macro

Error type: Indicate that the line and the error pointer should be displayed (if not suppressed via other flags).

int ERR FILE  Macro

Error type: Indicate that the file name and line number should be displayed (if not suppressed via other flags).

18 2. The BibTool C Library

int ERR EXIT  Macro

Error type: Indicate that the error() function should be terminated by exit() instead of returning.

void ERROR EXIT()  Macro

X  Error message.

Raise an error, print the single string argument as error message and terminate the program with exit(). Returns: nothing

void OUT OF MEMORY()  Macro

X  String denoting the type of unallocatable memory.

Raise an error because malloc() or realloc() failed. The argument denoted the type of memory for which the allocation failed. The program is terminated. Returns: nothing

void ERROR()  Macro

X  Error message.

Raise an error. Print the argument as error message and continue. Returns: nothing

void ERROR2()  Macro

X  First error message.
Y  Continuation of the error message.

Raise an error. Print the two arguments as error message and continue. Returns: nothing

void ERROR3()  Macro

X  First error message.
Y  Continuation of the error message.
Z  Second continuation of the error message.

Raise an error. Print the three arguments as error message and continue. Returns: nothing

void WARNING()  Macro

X  Warning message.

Raise a warning. Print the argument as warning message and continue. Returns: nothing

void WARNING2()  Macro

X  First warning message.
Y  Continuation of warning message.

Raise a warning. Print the two arguments as warning message and continue. Returns: nothing

void WARNING3()  Macro

X  First warning message.
Y  Continuation of warning message.
Z  Second continuation of warning message.

Raise a warning. Print the thre arguments as warning message and continue. Returns: nothing

void Err()  Macro

S  String to print.

Print a string to the error stream. This message is preceded with an indicator. The message is not automatically terminated by a newline. Returns: nothing

void ErrC()  Macro

CHAR  Character to send to output.

Print a single character to the error stream. Returns: nothing

void ErrPrint()  Macro

F  String to print.

Print a string to the error stream. The string is not preceded by any indicator not is it automatically terminated by a newline. Returns: nothing

void ErrPrintF()  Macro

F  Format.
A  Argument.

Apply a formatting instruction (with printf()). This macro takes a format string and a second argument which is determined by the formatting string. Returns: nothing

20 2. The BibTool C Library

void ErrPrintF2()  Macro

F  Format
A  First argument.
B  Second argument.

Apply a formatting instruction (with printf()). This macro takes a format string and two additional arguments which are determined by the formatting string. Returns: nothing

void FlushErr  Macro

Flush the error stream. This can be useful when single characters are written to an error stream which does buffering.

void VerbosePrint1()  Macro

A  Verbose message.

Print an informative message to the error stream. Returns: nothing

void VerbosePrint2()  Macro

A  Verbose message.
B  Continuation of verbose message.

Print an informative message consisting of two substrings to the error stream. Returns: nothing

void VerbosePrint3()  Macro

A  Verbose message.
B  Continuation of verbose message.
C  Second continuation of verbose message.

Print an informative message consisting of three substrings to the error stream. Returns: nothing

void VerbosePrint4()  Macro

A  Verbose message.
B  Continuation of verbose message.
C  Second continuation of verbose message.
D  Third continuation of verbose message.

Print an informative message consisting of four substrings to the error stream. Returns: nothing

void DebugPrint1()  Macro

A  Debug message.

This Macro is for debugging purposes. The compilation determines whether this macro prints its argument or simply ignores it. This is achieved by defining or undefining the macro DEBUG when compiling.

Returns: nothing

void DebugPrint2()  Macro

A  Debug message.
B  Conitnuation of the debug message.

This Macro is for debugging purposes. The compilation determines whether this macro prints its arguments or simply ignores them. This is achieved by defining or undefining the macro DEBUG when compiling.

Returns: nothing

void DebugPrint3()  Macro

A  Debug message.
B  Conitnuation of the debug message.
C  Second conitnuation of the debug message.

This Macro is for debugging purposes. The compilation determines whether this macro prints its arguments or simply ignores them. This is achieved by defining or undefining the macro DEBUG when compiling.

Returns: nothing

2.7 The Module error.c

To ensure a consistent appearence of error messages BibTool provides one generic error reporting routine. This routine is controlled by several arguments to allow maximum flexibility.

Usually it is awkward to fill out all those arguments. To avoid this trouble the header file error.h provides some macros which cover the most common situation and hide unneccesary details.

void error()  Function

int type; Error type: boolean combination of the error bits as

defined in error.h.

Uchar *s1;  1^{st} error message or NULL.
Uchar *s2;  2^{nd} error message or NULL.
Uchar *s3;  3^{rd} error message or NULL.
Uchar *line;  Current line when error occured (for reading errors).
Uchar *err pos;  Error position in line line.
int    line no;  The line number where the error occurred.
char * fname;  The file name where the error occurred.

This is the generic error printing routine. It prints an error message together with an optional filename, the line number, the errorous line and a pointer to the problematic position.

All parts of an error message are optional and can be suppressed under certain conditions. The error type determines which parts are actually shown. It is a boolean combination of the following flags which are defined in error.h:

ERR ERROR If this bit is set then the error message is marked as “error”. The flag ERR_WARNING is ignored in this case. This kind of messages can not be suppresed.

ERR WARNING If this bit is set and ERR_ERROR is not set then the error message is marked as “warning”. ERR_WARNING is ignored in this case.

ERR POINT If this bit is set then the line line is shown together with a pointer to the byte pointed to by err_pos. Otherwise the line is not shown.

ERR FILE If this bit is set then the name of the file file_name and the line number lineno are shown. Otherwise the file name and the line number are suppressed.

ERR EXIT If this bit is set then the error routine calles exit(-1) at the end. This implicitly sets the ERR_ERROR bit as well.

The error message itself can be split in up to three strings s1, s2, and s3. Those strings are concatenated. They can also be NULL in which case they are ignored.

The error message is written to the stream determined by the variable err_file. This variable refers to the stderr stream initially but can be redirected to any other destination.

Returns: nothing

2.8 The Header File bibtool/expand.h

This header file makes available the function defined in expand.c. This file includes the

header file database.h.

2.9 The Module expand.c

This module contains functions to expand macros as they are appearing in right hand sides of equations. This can be used to get rid of additional macro definitions.

char * expand rhs()  Function

char *s;  String to expand

char *pre; This is the opening brace character to be used. For BibTEX the valid values are { or ". This value has to match to post. char *post; This is the closing brace character to be used. For

BibTEX the valid values are } or ". This value has to match to pre.

DB    db;  Database containing the macros.

Expand the right hand side of an item. Each macro which is defined in this database is replaced by its value. The result is kept in a static variable until the next invocation of this function overwrites it.

Returns: A pointer to the expanded string. This value is kept in a static variable of this function and will be overwritten with the next invocation.

2.10 The Header File bibtool/init.h

This header file provides the prototype for the global initialization function which is required to be called before any action can be performed.

2.11 The Module init.c

This module contains the global initialization function which has to be called before any modules in BibTool are activated. This is for convenience, thus nobody has to call the various initialization functions for the different modules by hand.

void init bibtool()  Function

     char * progname;  Name of the program for KPATHSEA.

Perform any initializations necessary for BibTool.

Returns: nothing

2.12 The Header File bibtool/keynode.h

This header file provides the datatype of a keynode. This is an internal structure which is used to built parse trees from format specifications. Usually this is done in key.c and should not be visible outside.

KeyNode Type

typedef struct kEYnODE {

  short int       kn type;
  short int       kn pre;
  short int       kn post;
  char *          kn string;
  char *          kn from;
  char *          kn to;
  struct kEYnODE *kn next;
  struct kEYnODE *kn then;
  struct kEYnODE *kn else;

} *KeyNode, SKeyNode;

2.13 The Header File bibtool/key.h

This header file provides functions to deal with keys as they are defined in keys.h.

This header file automaticall includes the header files database.h and sbuffer.h since datatypes defined there are required.

2.14 The Module key.c

void add format()  Function

char *s;  Specification string

Add a key format specification to the current specification. This specification is used for generating new reference keys. Thus the resource rsc_make_key is turned on aswell.

Several strings are treated special. If a special format is encountered then the effect is that the old key specification is cleared first before the new format is added:

empty The empty format is activated. This means that the format is cleared and

without further action the default key will be used. long The long format is activated. This means that authors names with initials and

the first word of the title are used. short The short format is activated. This means that authors last names and the

first word of the title are used. new.long This means that the long format will be used but only if the record does

not have a key already. new.short This means that the short format will be used but only if the record does

not have a key already.

Returns: nothing

void add ignored word()  Function

char *s;  Word to add.

Add a new word to the list of ignored words for title key generation. The argument has to be saved by the caller! This means that it is assumed that the argument is a symbol.

Returns: nothing

void add sort format()  Function

char *s;  Specification string

Add a sort key format specification to the current specification. This specification is used for generating new sort keys.

Several strings are treated special. If a special format is encountered then the effect is that the old key specification is cleared first before the new format is added:

empty The empty format is activated. This means that the format is cleared and without further action the default key will be used.

long The long format is activated. This means that authors names with initials and the first word of the title are used.

short The short format is activated. This means that authors last names and the first word of the title are used.

new.long This means that the long format will be used but only if the record does not have a key already.

new.short This means that the short format will be used but only if the record does not have a key already.

Returns: nothing

int apply fmt()  Function

StringBuffer *sb;  Destination string buffer.
char *        fmt;  Format specification,
Record        rec;  Record to consider.
DB            db;  Datrabase containing rec.

Expands an arbitrary format specification for a given record. The format specification is given as a string. The result is stored in a string buffer.

Returns: 1 iff the format is invalid or the evaluation fails. 0 otherwise.

void clear ignored words()  Function

Delete the list of ignored words. Afterwards no words are recognized as ignored words.

Returns: nothing

void def format type()  Function

char *s;

Returns: nothing

char* fmt expand()  Function

StringBuffer *sb;  destination string buffer

char *        cp;  format

DB            db;  Datrabase containing rec.
Record        rec;  Record to consider.

Expands a format specification of the string buffer.

Returns: The first character after the

int foreach ignored word()  Function

int (*fct)(char*);  Function to apply.

Iterator a given function fct is applied to each ignored word in turn. If the function returns 0 then the loop is terminated. The different words are visited in a fixed order which does not necessarily coincide with the natural order of words. Thus don’t assume this.

Returns: The return status of the last fct call.

void free key node()  Function

KeyNode kn;  KeyNode to be freed.

A tree rooted at a given KeyNode will be freed.

Returns: nothing

char *get field()  Function

DB     db;  Datrabase containing rec.
Record rec;  Record to analyze.

char * name; Field name to search for. This has to be a symbol if a normal field is sought. For pseudo fields it can be an arbitrary string.

Evaluate the record rec. If name starts with @ then check the record name. If name starts with $ then return the special info. Else search in Record rec for the field name and return its value. NULL is returned to indicate failure.

Returns: The address of the value or NULL.

void make key()  Function

DB     db;  Database containing the record.
Record rec;  Record to consider.

Generate a key for a given record.

Returns: nothing

void make sort key()  Function

DB     db;  Database containing the record.
Record rec;  Record to consider.

Returns: nothing

int mark key()  Function

DB     db;  Database containing the record.
Record rec;  Record to consider

Set the key mark for the key symbol of a record.

Returns: nothing

void set base()  Function

char *value;  String representation of the new value.

Define the key base. This value determines the format of the disambiguation string added to a key if required. The following values are considered:

• If the value is upper or starts with an upper case letter then the disambiguation is done with uppercase letters.

• If the value is lower or starts with a lower case letter then the disambiguation is done with lowercase letters.

• If the value is digit or starts with an digit then the disambiguation is done with arabic numbers.

The comparison of the keywords is done case insensitive. The special values take precedence before the first character rules.

If an invalid value is given to this function then an error is raised and the program is terminated.

int set field()  Function

DB     db;  Datrabase containing rec.
Record rec;  Record to receive the value.
char * name;  Field name to add.
char * value;  String representation of the new value.

Store the given field or pseudo-field in a record. If the field is present then the old value is overwritten. Otherwise a new field is added. Fields starting with a $ or @ are treated special. They denote pseudo fields. If such a pseudo field is undefined then the assignment simply fails.

In contrast to the function push_to_record() this function does not assume that the arguments are symbols. In addition to push_to_record() it also handles pseudofields.

Returns: 0 if the asignment has succeeded.

void set separator()  Function

int   n;  Array index to modify.

char *s; New value for the given separator. The new value is stored as a symbol. Thus the memory of s need not to be preserved after this function is completed. The characters which are not allowed are silently sypressed.

Modify the key seps array. This array contains the different separators used during key formatting. The elements of the array have the following meaning:

0 The default key which is used when the formatting instruction fails completely.

1 The separator which is inserted between different names of a multi-authored publication.

2 The separator inserted between the first name and the last name when a name is formatted.

3 The separator inserted between the last names when more then one last name is present

4 The separator between the name and the title of a publication.

5 The separator inserted between words of the title.

6 The separator inserted before the number which might be added to disambiguate reference keys.

7 The string which is added when a list of names is truncated. (.ea)

2.15 The Header File bibtool/macros.h

This header file contains definitions for the Macro structure. Macro is the pointer type corresponding to the structure SMacro. All C macros and functions provided through this header file deal with the pointer type. The structure itself is used in the allocation function only.

Macro Type

This is a pointer type to represent a mapping from a string to another string. This mapping is accompanied by a counter which can be used as a reference count.

typedef struct mACRO {

char *        mc name;  Name of the macro.
char *        mc value;  Value of the macro.
int           mc used;  Reference count.
struct mACRO *mc next;  Pointer the next macro.

} SMacro, *Macro;

Macro MacroNULL  Macro

This is the NULL pointer for the Macro type. It can be used as a special or illlegal macro.

char * MacroName()  Macro

M                           Macro to consider

This is the functional representation of the name component of a Macro. It can be used to extract this information. It can also be used as a lvalue.

char * MacroValue()  Macro

M                           Macro to consider

This is the functional representation of the value component of a Macro. It can be used to extract this information. It can also be used as a lvalue.

int MacroCount()  Macro

M                           Macro to consider

This is the functional representation of the counter component of a Macro. It can be used to extract this information. It can also be used as a lvalue.

Macro NextMacro()  Macro

M                           Macro to consider

This is the functional representation of the next Macro. It can be used to extract this information. It can also be used as a lvalue.

2.16 The Module macros.c

void def field type()  Function

char * s;  String containing an equation.

This function adds a printing representation for a field name to the used list. The argument is an equation of the following form

type = value

type is translated to lower case and compared against the internal representation. value is printed at the appropriate places instead.

Returns: nothing

int def macro()  Function

char *name;  name of the macro.
char *val;  NULL or the value of the new macro
int   count;  initial count for the macro.

Define or undefine a macro.

Returns: nothing

void dump mac()  Function

char *fname;  File name of the target file.
int   allp;  if == 0 only the used macros are written.

Write macros to a file.

Returns: nothing

void foreach macro()  Function
int (*fct) (char *,char *);

Apply a function to each macro in turn. The function is called with the name and the value of the macro. If it returns FALSE then the processing of further macros is suppressed.

The function given as argument is called with two string arguments. The first is the name of the macro and the second is its value. Both are symbols and must not be modified in any way.

The order of the enumeration of the macros is determined by the implementation. No specific assumptions should be made about this order.

Returns: nothing

void free macro()  Function

Macro mac;  First Macro to release.

Free a list of macros. The memory allocated for the Macro given as argument and all struictures reachable via the NextMacro pointer are released.

Returns: nothing

char * get item()  Function

char * name;  Symbol to get the print representation for.

int    type;  One of the values SYMBOL\_TYPE\_UPPER,
                               SYMBOL\_TYPE\_LOWER, or SYMBOL\_TYPE\_CASED

as they are defined in type.h.

Return the print representation of a BibTEX string. The appearance is determined by the items mapping. If no approriate entry is found then type is used to decide whether the item should be returned as uppercase, lowercase or first upper only.

Returns: A pointer to a static string. This location is reused upon the next invocation of this function.

char * get key name()  Function

char *s;

Returns:

void init macros()  Function

Initialize some macros from a table defined in the configuration file or given as define to the C compiler. This function has to be caled to initialize the global macros.

Note that this function is for internal purposes only. The normal user should call

init_bibtool() instead.

Returns: nothing

char * look macro()  Function

char *name; The name of the macros to find. This needs not to be

a symbol.

int add; Initial reference count or indicator that no new macro is required.

Return the value of a macro if it is defined. This value is a symbol. If the macro is undefined then NULL is returned. In this case the value of add determines whether or not the macro shpould be defined. If it is less than 0 then no new macros is defined. Otherwise a new macro is defined. The value is the empty string and the initial reference count is add.

Returns: The value or NULL.

Macro new macro()  Function

char *name;  Name of the macro. This must be a symbol.
char *val;  The value of the macro. This must be a symbol.
int   count;  The initial reference count.
Macro next;  The next pointer of the Macro structure.

Allocate a new macro structure and fill it with initial values. Upon failure an error is raised and exit() is called.

Returns: The new Macro.

void save key()  Function

char * s;
char * key;

Returns: nothing

2.17 The Header File bibtool/names.h

SNameNode Type

The name format is translated internally into a list of nodes which are easier to evaluate since they avoid the reparsing of the format. This structure contains such a node.

typedef struct nameNODE {

  int              nn type;
  int              nn strip;
  char *           nn pre;
  char *           nn mid;
  char *           nn post;

struct nameNODE *nn next; Pointer to the next name node

} SNameNode, *NameNode;

NameNode NameNULL  Macro

The NULL pointer to a NameNode which can be used as a special value to indicate the end of a NameNode list.

int NameType()  Macro
NN

Returns:

int NameStrip()  Macro
NN

2.18. The Module names.c 33

Returns:

char* NamePre()  Macro
NN

Returns:

char* NameMid()  Macro
NN

Returns:

char* NamePost()  Macro
NN

Returns:

NameNode NextName()  Macro

NN                          NameNode to consider.

Functional representation of the pointer to the next NameNode. Returns: The next Namenode.

2.18 The Module names.c

NameNode name format()  Function

char *s;

Returns:

char * pp list of names()  Function

char **  wa;  Word array of name constituents

NameNode format;

char *   trans;  Translation table
int      max;  maximum or 0

char *   comma;  ”,”

char *   and;  name separator

char *   namesep;
char *   etal;

Returns: Pointer to static string which is reused upon the next invocation of this function.

void set name format()  Function

NameNode *nodep;
char *    s;

Returns: nothing

2.19 The Header File bibtool/parse.h

This header file contains functions which deal with the parsing of BibTEX files. They are defined in parse.c and declared in this file.

2.20 The Module parse.c

void init read()  Function

Initialize the reading apparatus. Primarily try to figure out the file search path.

Note that this function is for internal purposes mainly. The normal user should call init_bibtool() instead. Just in case the search paths are changed afterwards this function has to be called again to propagate the information.

Returns: nothing

int parse bib()  Function

Record rec;  Record to store the result in.

Read one entry and fill the internal record structure. Return the type of the entry read.

BIB_EOF is returned if nothing could be read and the end of the file has been encountered.

BIB_NOOP is returned when an error has occured. This is an indicator that no record has been read but the error recovery is ready to try it again.

This function is for internal purposes mainly. See read_db() for a higher level function to read a database.

Returns: The type of the entry read, BIB_EOF, or BIB_NOOP.

int read rsc()  Function

char *name;  Name of the file to read from.

Read a resource file and evaluate all instructions contained.

The characters #, %, and ; start an endline comment but only between resource instructions. They are not recogniized between a resource instructiuon and its value or inside the value braces.

This function is contained in this module because it shares several functions with the BibTEX parsing routines.

Returns:

int see bib()  Function

char * fname;  Name of the file or NULL.

Open a BibTEX file to read from. If the argument is NULL then stdin is used as input stream.

This function has to be called before parse() can be called. It initializes the parser routine and takes care that the next reading is done from the given file.

The file opened with this function has to be closed with seen().

This function is for internal purposes mainly. See read_db() for a higher level function to read a database.

Returns: TRUE iff the file couls be opened for reading.

int seen()  Function

Close input file for the BibTEX reading apparatus. After this function has been called parse() might not return sensible results.

This function is for internal purposes mainly. See read_db() for a higher level function to read a database.

Returns: FALSE if an attempt was made to close an already closed file.

void set rsc path()  Function

char * val;  The string representation of the file search path.

Initialize the resource file reading apparatus. Primarily try to figure out the file search path.

Returns: nothing

2.21 The Header File bibtool/print.h

This header file provides access to the functions and variables defined in print.c. Consult also the documentation of this file for details.

This header file automatically includes record.h and database.h.

2.22 The Module print.c

This module provides also access to the functions and variables defined in entry.c. Consult also the documentation of this file for details.

void fput record()  Function

FILE * file;  Stream to print onto.
DB     db;  Database containing the record.
Record rec;  Record to print.

char * start; Initial string used before the type. Should be ”@” nor-

mally.

Format and print a complete record onto a given stream. for further details see

put_record().

Returns: nothing

void put record()  Function

int (* fct)(int);  function to use for writing a character.
Record rec;  Record to print.
DB     db;  Database containing the record.

char * start; Initial string used before the type. Should be ”@” nor-

mally.

Format and print a complete record. The record type and several resources are taken into account. The following external variables (from rsc.c) are taken into account:

rsc parentheses If this boolean variable is TRUE then ( and ) are used to delimit the record. Otherwise { and } are used.

rsc col p This integer variable controlls the indentation of preamble records.

rsc col s This integer variable controlls the indentation of string records.

rsc expand macros If this boolean variable is set then macros are expanded before the record is printed. This does not effect the internal representation.

rsc col This integer variable controlls the indentation of normal records.

rsc col key This integer variable controlls the indentation of the key in a normal record.

rsc newlines This integer variable controlls the number of newlines printed after a normal record.

rsc linelen This integer variable controlls the length of the line. The line breaking algorithm is applied if this column is about to be violated.

rsc indent This integer variable controlls the indentation of equations.

rsc eq right This boolean variable controlls the alignment of the = in equations. It it is set then the equality sign is flused right. Otherwise it is flushed left.

The field in the record are sorted with sort_record() before they are printed.

In normal records all fields not starting with an allowed character are ignored. Thus it is possible to store private and invisible information in a field. Simply start the field name with an not allowed character like %.

Returns: nothing

void set symbol type()  Function

char * s;  String description of the value.

Function to set the symbol type which is used by the printing routine. The argument is a string describing the value to use. Possible values are "upper", "lower", and "cased". The comparison of the values is performed case insensitive.

If no appropriate value is found then an error message is issued as the only action.

This function is called from rsc.c.

Returns: nothing

char * sput record()  Function

DB     db;  Database containing the record.
Record rec;  Record to print.

char * start; Initial string used before the type. Should be ”@” nor-

mally.

Format and print a complete record into a string and return it. The string returned points to static memory which is reused upon the next invocation of this function.

Returns: The string containing the printed representation.

2.23 The Header File bibtool/pxfile.h

This module provides access to the functions and variables defined in pxfile.c. Consult also the documentation of this file for details.

This header file automatically includes bibtool.h and <stdio.h>.

2.24 The Module pxfile.c

This file provides routines for extended file opening. Files are sought in a list of directories and optionally with a set of extensions appended to them.

Patterns may be given which are used to determine the full file name. The patterns are stored in a special data structure. A function is provided to allocate a pattern structure and fill it from a string specification.

px filename  Variable

This variable contains the file name actually used by the last px_fopen() call. The memory is automatically managed and will be reused by the next call to px_fopen(). Thus if you need to use it make a private copy immediately after the call to the

function px_fopen().

FILE * px fopen()  Function

char * name;  (base) name of the file to open.
char * mode;  Mode for opening the file like used with fopen().
char **pattern;  A NULL terminated array of patterns.
char **path;  The NULL terminated array of directories.

int (* show)(char*);  A function pointer or NULL.

Open a file using path and pattern.

Returns: A file pointer refering to the file or NULL.

char **px s2p()  Function

char * s;
int    sep;

Translate a path string specification into an array of the components. The memory of the array is malloced and should be freed when not used any longer.

Returns: The array of the components

2.25 The Header File bibtool/record.h

This module contains functions which deal with records in databases.

Record Type

This data type represents a record in a BibTEX database. Since the record can contain an arbitrary number of fields the central rôle is taken by the dynamic array rc_heap. This array contains at even positions the name of the field and the following odd position the associated value. In normal records the position 0 contains the reference key of the record.

If a field is deleted then the name is replaced by a NULL. The structure member rc_free contains the size of the heap.

The type of the record is determined by the integer rc_type.

typedef struct rECORD {

  char *          rc key;  The sort key.
  char *          rc old key; The old sort key.

int             rc type; The type of the record.
int             rc flags; Some bits; e.g. used during selecting aux records.

int rc free; The size of the heap. This is purely internal and must

not be modified.

  char **         rc heap; The heap.

char *          rc comment;The comment following the given record.

char * rc source; The source of the record. I.e. the file name it has been

read from.

struct rECORD * rc next; Pointer to the next record.
struct rECORD * rc prev; Pointer to the previous record.

} SRecord, *Record;

Record RecordNULL  Macro

Symbolic constant for the NULL pointer of type Record. This is used as special (invalid) record.

int RecordType()  Macro

R  Record to consider.

Functional representation of the record token. This can be used to access the token component of a record. It can also be used as lvalue.

Returns: The pure token.

int RecordFlags()  Macro

R  Record to consider.

Functional representation of the record type. This can be used to access the token component of a record. It can also be used as lvalue.

Returns: The flags as integer.

int RecordFlagMARKED  Macro

Bit mask for the MARKED flag of a record. The mark is used temporarily to determine certain records; e.g. during gc.

This macro is usually not used directly but implicitly with other macros from this header file.

int RecordFlagXREF  Macro

Bit mask for the XREF flag of a record. This flag is maintained to indicate that the record contains an crossref field. This is done for efficiency reasons only.

This macro is usually not used directly but implicitly with other macros from this header file.

int RecordFlagDELETED  Macro

Bit mask for the DELETED flag of a record. This flag indicates that the record has been deleted. To avoid dangling pointers the deleted records are not removed from the database immediately but a call to record_gc() performs this cleanup. In the meantime the deleted records are just left in the chain. Many operations automatically ignore deleted records.

This macro is usually not used directly but implicitly with other macros from this header file.

int SetRecordXREF()  Macro

R  The record to consider.

Mark the record with the XREF flag. If it is marked already nothing is done.

The XREF flag is used to mark those records which contain a crossref field. This is done for efficiency only.

Returns: The new value of the record flags.

int ClearRecordXREF()  Macro

R  The record to consider.

Remove the XREF mark.

Returns: The new value of the record flags.

int RecordIsXREF()  Macro

R  Record to consider.

Check whether the XREF flag of a record is set.

Returns: FALSE iff the XREF flag is not set.

int SetRecordDELETED()  Macro

R  Record to consider.

Mark the record with the DELETED flag. If it is marked already nothing is done.

The DELETED flag is used to mark those records which should be treated as non existent. Deleted records are ignored for most operations.

Returns: The new value of the record flags.

int ClearRecordDELETED()  Macro

R  Record to consider.

Remove the deleted flag. Thus you can effictively undelete a record as long as its memory has not been released.

2.25. The Header File bibtool/record.h 41

Returns: The new value of the record flags.

int RecordIsDELETED()  Macro

R  Record to consider.

Check whether the record is marked as deleted. Returns: FALSE iff the DELETED flag is not set.

int SetRecordMARK()  Macro

R  Record to consider.

Mark the record. The mark is used temporarily. Do not assume that the mark is preserved in each function. Returns: The new value of the record flags.

int ClearRecordMARK()  Macro

R  Record to consider.

Remove the deleted flag. Thus you can effictively undelete a record as long as its memory has not been released. Returns: The new value of the record flags.

int RecordIsMARKED()  Macro

R  Record to consider.

Check whether the record is marked as deleted. Returns: FALSE iff the DELETED flag is not set.

char * RecordOldKey()  Macro

R  Record to consider

char * RecordSortkey()  Macro

R  Record to consider.

This is the functional representation of the sort key of a record. This can be used to access the key component of a record. It can also be used as lvalue. Note that the reference key of a normal record is stored in the heap at position 0.

char ** RecordHeap()  Macro

R  Record to consider.

The heap of a record is a array of strings. The even positions contain the names of fields and the following array cell contains its value. If the name or value is NULL then this slot is not used. Thus it is easy to delete a field. Simply write a NULL into the appropriate place.

Record NextRecord()  Macro

R  Record to consider

This is the functional representation of the next record of a record. It can be used to get this value as well as an lvalue to set it.

Record PrevRecord()  Macro

R  Record to consider

This is the functional representation of the previous record of a record. It can be used to get this value as well as an lvalue to set it.

char * RecordComment()  Macro

R  Record to consider

This is the functional representation of the comment component of a record. It can be used to get this value as well as an lvalue to set it.

char * RecordSource()  Macro

R  Record to consider

This is the functional representation of the source indicator of a record. It is a string containing the file name from which this record has been read. The empty string is used to denote unknown sources.

Returns:

int RecordFlags()  Macro

R  Record to consider

This is the functional representation of the record flags. They are extra bits used for arbitrary purposes. Right now only the bit with the mask 1 is used for selecting the records found in an aux file.

Returns:

2.26 The Module record.c

void add sort order()  Function

char *val;  string resource of the order.

Insert the sort order into the order list.

Record copy record()  Function

Record rec;  The record to copy.

Copy a record and return a new instance. If no memory is left then an error is raised and the program is terminated.

Returns: The new copy of rec.

void free 1 record()  Function

Record rec;  record to free

Free the memory occupied by a single record. This does not ensure that there is no dangling pointer to the record. Thus beware!

Returns: nothing

void free record()  Function

Record rec;  Arbitrary Record in the chain.

Release a list of records. All records reachable through a previous/next chain are deallocated.

Returns: nothing

Record new record()  Function

int token;  The token type of the record.
int size;  The initial heap size.

Create a new record and return it. If no memory is left then an eror is raised and the program is terminated.

Returns: The new record.

WordList new wordlist()  Function

char * s;  Initial string to fill in the WordList structure

Allocate a WordList and fill its slots.

Returns:

void push to record()  Function

Record rec;  Pointer to any entry in the chain.
char * s;  Left hand side of the equation.
char * t;  Right hand side of the equation.

Put an equation s=t onto the heap of a record. If a field s is already there then the value is overwritten. The arguments are expected to be synbols. Thus it is not necessary to make private copies and it is possible to avoid expensive string comparisons.

Record record gc()  Function

Record rec;  Pointer to any entry in the chain.

Garbage collecting a record list. The entries marked as deleted are unlinked and the memory is freed. Any pointers to such a deleted entry become invalid.

Be careful when using this function!

Returns: Pointer to some entry in the cleared chain or RecordNULL if none is left.

void sort record()  Function

Record rec;  Record to sort

The heap is reordered according to the sorting order determined by the record type. For this purpose a copy of the original record is made and the original record is overwritten. The copy is released at the end. Memory management is easy since all strings are in fact symbols, i.e. they must not be freed and comparison is done by pointer comparison.

Returns: nothing

Record unlink record()  Function

Record rec;  Record to free.

Remove a record from a chain and free its memory. The chain is modified such that the freed Record is not referenced any more. A neighbor in the chain of the given record is returned or NULL if there is none.

Returns: nothing

2.27 The Header File bibtool/rewrite.h

2.28 The Module rewrite.c

void add check rule()  Function

char *s;  Rule to save.

Save a check rule for later use.

Returns: nothing

void add extract()  Function

char *s;  Rule to save.

Save an extraction rule for later use. The argument is interpreted as regular expression to be matched against the field value.

The value of rsc_case_select at the invocation of this function determines whether the matching is performed case sensitive or not.

2.28. The Module rewrite.c 45

Returns: nothing

void add field()  Function

char *spec;  A string of the form token=value

Save a token and value for addition. Returns: nothing

void add rewrite rule()  Function

char *s;  Rule to save.

Save a rewrite rule for later use. The main task is performed by add_rule(). Returns: nothing

void add s extract()  Function

char *s;  Rule to save.

Save an extraction rule for later use. The argument is interpreted as string to be found in the field value. The value of rsc_case_select at the search time determines whether the matching is performed case sensitive or not. Returns: nothing

void clear addlist()  Function

Reset the addlist to the empty list. Returns: nothing

int is selected()  Function

DB     db;  Database containing the record.
Record rec;  Record to look at.

Boolean function to decide whether a record should be considered. These selections are described by a set of regular expressions which are applied. If none are given then the match simply succeeds. Returns: TRUE iff the record is seleced by a regexp or none is given.

void remove field()  Function

char * field; This is a symbol containing the name of the field to

remove.

Record rec;  Record in which the field should be removed.

Remove the given field from record. Returns: nothing

void rewrite record()  Function

DB     db;  The database record is belonging to.
Record rec;  Actual record to apply things to.

Apply deletions, checks, additions, and rewriting steps in this order.

Returns: nothing

void save regex()  Function

char *s;  Regular expression to search for.

Save an extraction rule for later use. Only the regular expression of the rule is given as argument. The fields are taken from the resource select.fields.

Returns: nothing

2.29 The Header File bibtool/resource.h

This file is the central component of the resource evaluator. To reduce redundancy everything in this file is encapsulated with macros. Thus it is possible to adapt the meaning according to the task to be performed.

This file is included several times from different places. One task is the definition of certain variables used in this file. Another task is the execution of the commands associated with a command name.

This is one place where the power and the beauty of the C preprocessor make live easy. It should also be fun to find the three ways in which this file is used. Read the sources and enjoy it!

For the normal user this file is consulted automatically when the header file rsc.h is used.

2.30 The Header File bibtool/rsc.h

This header file provides definitions for all resource variables, i.e. the variables defined in the header file resource.h.

In addition the functions defined in resource.c are made accessible to those modules including this header file.

2.31 The Module rsc.c

This module contains functions which deal with resources. Resources are commands to configure the behaviour of BibTool. They can be read either from a file or from a string.

The syntax of resources are modelled after the syntax rules for BibTEX files. See the user’s guide for details of the syntax.

int load rsc()  Function

char *name;  The name of the resource file to read.

This function tries to load a resource file. Details: Perform initialization if required. The main job is done by read_rsc(). This function is located in parse.c since it shares subroutines with the parser.

Returns: FALSE iff the reading failed.

void rsc print()  Function

char *s;  String to print.

Print a string to the error stream as defined in error.h. The string is automatically augmented by a trailing newline. This wrapper function is used for the resource print.

Returns: nothing

int search rsc()  Function

Try to open the resource file at different places:

• In the place indicated by the environment variable RSC_ENV_VAR. This step is skipped if the macro RSC_ENV_VAR is not defined (at compile time of the module).

• In the home directory. The home directory is determined by an environment variable. The macro HOME_ENV_VAR contains the name of this environment variable. If this macro is not defined (at compile time of the module) then this step is skipped.

• In the usual place for resource files.

For each step load_rsc() is called until it succeeds. The files sought is determined by the macro DefaultResourceFile at compile time of the module. (see bibtool.h)

Returns: TRUE iff the resource loading succeeds somewhere.

int set rsc()  Function

char * name;  Name of the resource to set.
char * val;  The new value of the resource.

Set the resource to a given value. Here the assignment is divided into two parts: the name and the value. Both arguments are assumed to be symbols.

Returns: FALSE iff everything went right.

int use rsc()  Function

char *s;  String containg a resource command.

This function can be used to evaluate a single resource instruction. The argument is a string which is parsed to extract the resource command. This is an entry point for command line options which set resources.

Returns: FALSE iff no error has occurred.

2.32 The Header File bibtool/s parse.h

2.33 The Module s parse.c

char * s parse()  Function

int type; is the type of construct to parse. it is defined in

s parse.h

char **sp; is a pointer to the string which is parsed. The value is

changed to hold the remaining characters at the end.

int errp; this boolean indicated whether or not a verbose error message should be created in case of an error.

Parse a string for a certain entity. Leading whitespace is ignored. type determines which kind of entity should be exepected. It can take the following values which are

defined in s_parse.h:

StringParseValue The string is analyzed and the proper type is determined automatically. This can be considered as the normal way of operation.

StringParseSymbol The string is analyzed and only a symbol is accepted, i.e. a sequence of allowed characters.

StringParseNumber The string is analyzed and only a number is accepted.

StringParseBraces The string is analyzed and only an expression in braces is accepted. The braced contained must come in matching pairs. The whole expression – including the braces – is returned.

StringParseUnquotedBraces The string is analyzed and only an expression in braces is accepted. The braced contained must come in matching pairs. The expression without the outer braces is returned.

StringParseString The string is analyzed and only a string enclosed in double quotes is accepted. The string must contain braces in matching pairs. Double quotes which are inside of braces are not considered as end of the string. The whole string – including the double quotes is returned.

StringParseUnquotedString The string is analyzed and only a string enclosed in double quotes is accepted. The string must contain braces in matching pairs. Double quotes which are inside of braces are not considered as end of the string. The string without the outer double quotes is returned.

StringParseSkip The string is analyzed and the first position not containing whitespace, =, or # is returned. In this case the returned value is not translated into a symbol.

StringParseEOS The string is analyzed and any remaining characters which are not whitespace are reported as error. A pointer to the terminating 0 byte is returned upon success

If an error occurs or the requested entity is not found then NULL is returned. As a side effect sp is advanced to point to the next unprocessed character.

The string analyzed should be opened at the beginning with sp_open() in order to get an appropriate error message.

This function is usually not called directly but the convenience macros defined in s_parse.h should be used instead.

Returns: A symbol containing the requested entity or NULL.

int sp open()  Function

char * s;  String to open for parsing.

Open a string for parsing. The argument string is used for the parsing process. Thus this string should not be modified during this time. Especially it should not be freed if it is a pointer to dynamically allocated memory.

Returns: TRUE

2.34 The Header File bibtool/stack.h

This module provides access to the functions defined in the module stack.c. The the documentation of this module for details.

2.35 The Module stack.c

This module provides a single stack of strings. There are two operations on this stack, namely to push a string onto the stack and a pop operation to get the topmost element from the stack and remove it or to get a signal that the stack is empty.

The stack is implemented as an array which grows on demand. Currently the memory of the stack is not returned to the operating system. This seems to be not problemeatic since this memory is not assumed to be really large. Normally just a few strings are pushed to the stack at any time.

char * pop string()  Function

Pop a string from the stack. It the stack is empty then NULL is returned. Thus the NULL value should not be pushed to the stack since this can be confused with the end of the stack.

Returns: The old top element or NULL if the stack is empty.

void push string()  Function

char * s;  String to push to the stack.

Push a string onto the stack. Only the memory for the stack is allocated. The string is stored as pointer to existing memory. No copy of the string is made.

If no memory is left then an error is raised and the program is terminated.

Returns: nothing

2.36 The Header File bibtool/sbuffer.h

This header file makes accessible the functions to treat strings like streams In addition to the functions defined in sbuffer.c one macro is defined here.

sbputchar()  Macro

C  Character to put.
SB  Destination string buffer.

Put the character C into the string buffer SB.

This macro is not sane. The arguments are expanded several times. Thus they must not contain side effects.

Returns: nothing

2.37 The Module sbuffer.c

This module contains functions for dealing with strings of aribtrary size. The allocation of memory is done automatically when more characters are added.

The functions are modeled after the stream functions of C. Currently a printf-like function is missing because one was not needed yet and it is not so easy to implement—portably.

The functions in this module are very handy to deal with strings of arbitrary length where the length is not known in advance. E.g. consider the case that a line has to be read from a file file and the line length should not be restricted by some artificial boundry. This can be implemented as follows: { StringBuffer *sb = sb_open(); /* Declare and initialize a string buffer. */

int c; /* Variable to store a single character. */ char *s; /* Variable to hold the string at the end. */

while ( (c=fgetc(file) != EOF
     && c != '\n')

{ sbputchar(c,sb); } /* Store each character in the string buffer.*/ s = sbflush(sb); /* Get the string from the string buffer. */

puts(s);  /* Process the string; e.g. print it.  */

sb_close(sb);  /* Free the string buffer.  */

}

Note that the flushing of the string buffer returns a C string which is managed by the string buffer. This memory is freed or reused whenever the string buffer needs to. Thus you should make a private copy of this string if it should survive the next operation of the string buffer. Especially, after the call to sb_close() this memory has been returned to the operating system and is not available any more.

int sbclose()  Function

StringBuffer* sb;  Pointer to string buffer which should be closed

Free an old string buffer.

Returns: Return 0 upon failure.

char* sbflush()  Function

StringBuffer* sb;  String buffer to close.

Close a string buffer with a trailing \0 and reset the current pointer to the beginning. The next write operation starts right at the end. Thus additional write operations will overwirte the terminating byte.

Returns: The string contained in the string buffer as a proper C string.

StringBuffer* sbopen()  Function

Allocate a new string buffer. Return a pointer to the new string buffer or NULL if none was available.

Returns: pointer to new string buffer or NULL

int sbputc()  Function

int           c;  Character to put to the string buffer.
StringBuffer* sb;  Destination string buffer.

Push a single character onto a string buffer. In contrast to the macro this function handles the reallocation of the memory. For the user it should not make a difference since the macros uses this function when needed.

When no memory is left then the character is discarted and this action is signalled via the return value.

Returns: FALSE if no memory is left.

int sbputs()  Function

char *        s;  String to be pushed.
StringBuffer* sb;  Destination string buffer.

Push a whole string onto a string buffer.

Returns: FALSE if something went wrong.

void sbrewind()  Function

StringBuffer* sb;  String buffer to consider.

Reset the string buffer pointer to the beginning. The next write or read will operate there.

Returns: nothing

int sbseek()  Function

StringBuffer* sb;  String buffer to reposition.
int           pos;  New position of the string buffer.

Reset the current pointer to the position given. If the position is outside the valid region then TRUE is returned and the position is left unchanged.

Returns: FALSE if everything went right.

int sbtell()  Function

StringBuffer* sb;  String buffer to consider.

Return the current pointer to the string buffer position. This can be used with sbseek() to reset it.

Returns: The relative byte position of the current writing position. This is an integer offset from the beginning of the string buffer.

2.38 The Header File bibtool/symbols.h

This header file contains definitions dealing with symbols.

BibTool uses symbols as the basic representation for strings. Symbols are stored in a symbol table and shared amoung different instances. Thus the same string occurring at different places has to be stored only once.

Another advantage of symbols is that once you have got two symbols at hand it is rather easy to compare them for equality. A simple pointer comparison is enough. It is not neccesary to compare them character by character.

The disadvantage of a symbol is that you can not simply modify it temporarily since it is part of the symbol table. This symbol table would be in an insane state otherwise. Thus you always have to make a copy if you want to modify a symbol.

The functions defined in symbols.c are exported with this header file aswell.

char * symbol()  Macro

STR  String to translate into a symbol.

Translate a string into a symbol. The symbol returned is either created or an existing symbol is returned.

Returns: The symbol corresponding to the argument.

void ReleaseSymbol()  Macro

SYM  Symbol to release.

The symbol given as argument is released. In fact the memory is not really freed but one instance is marked as not used any more. At other places the symbol might be still required. The freeing of memory is performed by the garbage collector sym_gc().

Returns: nothing

char * sym empty  Variable

The empty symbol. This is a symbol pointing immediately to a \0 byte. This needs init_symbols() to be called first.

char * sym crossref  Variable

The symbol crossref. This variable needs init_symbols() to be called first.

2.39 The Module symbols.c

This module contains functions which deal with symbols and general memory management. This module implements a single symbol table.

This module required initialization before all functions can be used. Especially the symbol table does not exist before initialization.

void init symbols()  Function

Initialize the symbols module. The symbol table is cleared. This is not secure when the symbols have already been initialized because it would lead to a memory leak and a violation of the symbol comparison assumtion. Thus this case is caught and nothing is done when the initialization seems to be requested for the second time. If no more memory is available then an error is raised and the program is terminated. Note that this function is for internal purposes only. The normal user should call

init_bibtool() instead.

Returns: nothing

char * new string()  Function

char * s;  String to duplicate

Allocate a space for a string and copy the argument there. Note this is just a new copy of the memory not a symbol! If no more memory is available then an error is raised and the program is terminated.

Returns: Pointer to newly allocated memory containing a duplicate of the argument string.

char * sym add()  Function

char *s;  String which should be translated into a symbol.
int   count;  The use count which should be added t the symbol

Add a symbol to the global symbol table. If the string already has a symbol assigned to it then this symbol is returned. If the symbol is not static then the use count is incremented by count.

If the symbol does not exist already then a new symbol is added to the symbol table and the use count is initialized to count. A negative value for count indicates that a static symbol is requested. A static symbol will never bee deleted from the symbol table. Static can be used at places where one does not care about the memory occupied.

If no more memory is available then an error is raised and the program is terminated.

See also the macro symbol() in symbols.h for a convenient alternative to this function.

Returns: The new symbol.

void sym dump()  Function

Dump the symbol table to the error stream—see module error.c. The symbols are printed according to their hash value and the sequence they are occurring in the buckets. A summary of the memory used is also printed.

Returns: nothing

int sym flag()  Function

char * s;  Symbol

Get the flags of the symbol given as argument.

Returns: The flags of the recently touched StringTab.

void sym set flag()  Function

char *s;  Symbol to augment.
int   flags;  New flags to add.

Add the flags to the symbol corresponding to the argument s by oring them together with the given value.

void sym unlink()  Function

char *s;  Symbol to be released.

Free a symbol since it is no longer used. This does not mean that the memory is also freed. The symbol can be static or used at other places. The real free operation requires that the garbage collector sym_gc() to be called.

If the argument is NULL or an arbitrary string (no symbol) then this case is also dealt with.

Returns: nothing

2.40 The Header File bibtool/tex aux.h

2.41 The Module tex aux.c

int apply aux()  Function

DB db;  Database to clean.

This function deletes all entries which are not requested by the recently read aux file. This means that the entry to be kept is either mentioned directly, it is crossreferenced, or all entries are requested with the \nocite{*} feature.

Note that the entries are in fact not deleted but only marked as deleted. Thus they can be recovered if necessary.

Returns: FALSE iff all entries are kept because of an explicit or implicit star (*).

int aux used()  Function

char * s;  reference key to check

Check whether a reference key has been requested by the previously read aux file. The request can either be expicit or implicit if a * is used.

Returns:

void clear aux()  Function

Reset the aux table to the initial state.

Returns: nothing

int foreach aux()  Function

int (fct)(char*);  funtion to apply

Apply the function to all words in the citation list of the aux file.

Returns: cite_star

int read aux()  Function

char * fname;  The file name of the aux file.
void (*fct)(char*);  A function to be called for each BibTEX file requested.

int verbose; Boolean indicating whether messages should be produced

indicating the status of the operation.

Analyze an aux file. If additional files are requested, e.g. by \include instructions in the original source file then those are read as well. Each citation found is remembered and can be queried afterwards. If a \cite{*} has been used then only a flag is set and all citation keys are discarted.

The aux file contains also the information about the BibTEX files used. For each such file the function fct is called with the file name as argument. This function can arrange things that those BibTEX files are read into a database.

This function has only a very simple parser for the aux file. Thus it can be confused by legal contents. But a similar thing can happen to BibTEX aswell.

Returns: TRUE iff the file could not be opened.

2.42 The Header File bibtool/tex read.h

This header file provides definitions for the use of functions to immitate the reading apparatus of TEX which are defined in tex_read.c.

2.43 The Module tex read.c

This module contains functions which immitate the reading apparatus of TEX. Macro expansion can be performed.

void TeX active()  Function

int    c;  Character to make active.
int    arity;  Arity of the macro assigned to the active character.
char * s;  Body of the definition as string.

Assign a macro to an active character. If the character is not active then the catcode is changed.

Returns: nothing

void TeX close()  Function

Gracefully terminate the reading of TEX tokens. Any remaining pieces of text which have already been consumed are discarted.

void TeX def()  Function

char *s;

Define a macro. The argument is a string specification of the following form:

\name[arity]=replacement text
\name=replacement text

0 <= arity <= 9

Returns: nothing

void TeX define()  Function

char *name;
int   arity;
char *body;

Add a new TEX macro definition.

Returns: nothing

void TeX open file()  Function

FILE * file;  File pointer of the file to read from.

Prepare things to parse from a file.

Returns: nothing

void TeX open string()  Function

char * s;  String to read from.

Prepare things to parse from a string.

Returns: nothing

int TeX read()  Function

char * cp;  Pointer to position where the character is stored.
char **sp;  Pointer to position where the string is stored.

Read a single Token and return it as a pair consisting of an ASCII code and possibly a string in case of a macro token.

Returns: FALSE iff everything went right.

void TeX reset()  Function

Reset the TEX reading apparatus to its initial state. All macros and active characters are cleared and the memory is released. Thus this function can also be used for this purpose.

2.44 The Header File bibtool/type.h

This module is a replacement for the system header file ctype.h. in contrast to some implemetations of the isalpha and friends the macros in this header are stable. This means that the argument is evaluated exactely once and each macro consistes of execately one C statement. Thus these macros can be used even at those places where only a single statement is allowed (conditionals without braces) or with arguments containing side effects.

In addition this is a starting point to implement an xord array like TEX has one (some day…)

This header file requires the initializaation function init_type() to be called before all macros will work as described.

This header file also provides the functions and varaibles defined in type.c

char* trans lower  Variable

Translation table mapping upper case letters to lower case. Such a translation table can be used as argument to the regular expression functions.

char* trans upper  Variable

Translation table mapping lower case letters to upper case. Such a translation table can be used as argument to the regular expression functions.

char* trans id  Variable

Translation table performing no translation. Thus it implements the identity a translation table can be used as argument to the regular expression functions.

int is allowed()  Macro

C  Character to consider

Decide whether the character given as argument is an allowed character in the sense of BibTEX.

Returns: TRUE iff the argument is an allowed character.

int is upper()  Macro

C  Character to consider

Decide whether the character given as argument is a upper case letter. (Characters outside the ASCII range are not considered letters yet)

Returns: TRUE iff the character is an uppercase letter.

int is lower()  Macro

C  Character to consider

Decide whether the character given as argument is a lower case letter. (Characters outside the ASCII range are not considered letters yet)

2.44. The Header File bibtool/type.h 59

Returns: TRUE iff the character is a lowercase letter.

int is alpha()  Macro

C  Character to consider

Decide whether the character given as argument is a letter. (Characters outside the ASCII range are not considered letters yet) Returns: TRUE iff the character is a letter.

int is digit()  Macro

C  Character to consider

Decide whether the character given as argument is a digit. (Characters outside the ASCII range are not considered letters yet) Returns: TRUE iff the character is a digit.

int is space()  Macro

C  Character to consider

Decide whether the character given as argument is a space character. '\0' is not a space character. Returns: TRUE iff the character is a space character.

int is extended()  Macro

C  Character to consider

Decide whether the character given as argument is an extended character outside the ASCII range. Returns: TRUE iff the character is an extended character.

int is wordsep()  Macro

C  Character to consider

Decide whether the character given as argument is a word separator which denotes no word constituent. Returns: TRUE iff the character is a word separator.

char ToLower()  Macro

C  Character to translate

Translate a character to it’s lower case dual. If the character is no upper case letter then the character is returned unchanged. Returns: The lower case letter or the character itself.

char ToUpper()  Macro

C  Character to translate

Translate a character to it’s upper case dual. If the character is no lower case letter then the character is returned unchanged.

Returns: The upper case letter or the character itself.

2.45 The Module type.c

This file contains functions to support a separate treatment of character types. The normal functions and macros in ctype.h are replaced by those in type.h. This file contains an initialization function which is required for the macros in type.h to work properly.

See also the documentation of the header file type.h for further information.

int case cmp()  Function

char * s;  First string to consider.
char * t;  Second string to consider.

Compare two strings ignoring cases. If the strings are identical up to differences in case then this function returns TRUE.

Returns: FALSE iff the strings differ.

void init type()  Function

This is the initialization routine for this file. This has to be called before some of the macros in type.h will work as described. It does no harm to call this initialization more than once. It just takes some time.

Note that this function is for internal purposes only. The normal user should call

init_bibtool() instead.

Returns: nothing

char * lower()  Function

char * s;  string to convert

Function to translate all letters in a string to lower case.

Returns: The converted string

2.46 The Header File bibtool/version.h

2.47 The Module version.c

char * bibtool version  Variable

This string variable contains the version number of BibTool. Usually it is of the form major.minor where major and minor are the major and minor version numbers. In addition a postfix like alpha or a patchlevel like p1 can be present.

void show version()  Function

Print the version number and a short copyright notice onto the error stream.

Returns: nothing

2.48 The Header File bibtool/wordlist.h

WordList Type

This data type represents a node in a list of strings. This list only provides a next pointer. and is prety generic.

typedef struct wORDlIST {

char *           wl word; String value of this node.

  struct wORDlIST *wl next; Pointer to the next node.

} SWordList, *WordList;

WordList WordNULL  Macro

This is the NULL value for a WordList. It terminates the list and represents the empty node.

char * ThisWord()  Macro

WL                          WordList to consider which is not WordNULL.

This macro returns the string of a WordList node.

Returns: The word stored in this node.

WordList NextWord()  Macro

WL                          WordList to consider which is not WordNULL.

This macro returns the next WordList node of a given WordList if this is not WordNULL.

Returns: The next WordList.

2.49 The Module wordlist.c

This module contains functions which deal with lists of words. Those words are in fact simple strings. Thus this module provides a very general functionality, namely a list of strings and the associated methods.

void add word()  Function

char *    s;  String to add to the wordlist.
WordList *wlp;  Pointer to a wordlist.

Put a string into a word list. The string itself is not copied. Thus it is highly recommended to use symbols as words nevertheless this is not required as long as the string s persists as long as the word list exists.

The second argument is a pointer to a WordList. This destination is modified by adding a new node. The use of a pointer allows a uniform treatment of empty and not empty word lists.

If no memory is left then an error is raised and the program is terminated.

Returns: nothing

int delete word()  Function

char *    s;  Word to remove.
WordList *wlp;  Pointer to the wordlist to modify.

void (* fct)(char*); Function to call to free the memory occupied by the

word.

Remove a word from a WordList. Only the first appearance of such a word is removed. I a word is found which contains the same string as s then the associated node is removed from the list and the function fct is called to free the memory of the string in the WordList node if the function is not NULL. In this case the function returns 0. Otherwise 1 is returned.

Returns: 0 if the word was not found. 1 otherwise.

int find word()  Function

char *   s;  String to find.
WordList wl;  Word list to search in.

Look up a word in a word list. The comparison is done case insensitive.

Returns: FALSE iff the word does not occur in the wordlist.

int foreach word()  Function

WordList wl;  WordList to traverse.

int (*   fct)(char*);  function to apply.

Applies the given function fct to all elements in the WordList as long as the function does not return 0. Thus it can be used to search for a specified word – e.g. determined by matching against a template. Another application the the processing of all elements in the WordList. In this case fct must always return TRUE.

Returns: return value of last function or 1.

void free words()  Function

WordList *wlp;  Pointer to the WordList.

void (* fct)(char*); Function to be called to free the memory of the word

itself. If it is NULL then no function is called.

Release the memory allocated for a list of words. All nodes in the list are freed. The function fct is called to free the memory occupied by the string component if it is

not NULL.

64 2. The BibTool C Library

Creating and Using the BibTool C Library

3.1 Creating the BibTool C Library

Creating the BibTool library should not be too hard. Mainly make BibTool in the main directory according to the instructions given there. As a side effect various object files are created. These object files—except the one for main.c—have to be put into the library.

For UNIX this is prepared in the makefile. Usually an invocation of make should be enough:

  make libbib.a

This invocation of make is in fact the same as the following two commands:

  ar r libbib.a $OFILES
  ranlib libbib.a

Here $OFILES denotes the list of object files as described above. On some systems no ranlib program is present and needed. In this case the second command can be omitted.

For other operating systems I simply do not know how things work there. I would be grateful to receive descriptions what to do there.

3.2 Using the BibTool C Library

If you have written a program which uses the BibTool C Library you have to include the library into the linking list. In addition the directory where the library can be found has to be specified. On UNIX this can be done with the compiler switches -l and -L respectively. Thus consider you have a program named mybib.c and you have created the object file mybib.o for it. The linking step can be performed with the following command:

  cc mybib.o -L$DIR -lbib -o mybib

Here $DIR denotes the path containing the file libbib.a. This path can be omitted if the library has been installed in a “standard” place like /usr/lib.

Coding Standards

Several tools are used for the development of BibTool. Mostly they are home grown— maybe they will be replaced by some wider used tools some day. Among those tools are indentation routines for Emacs to format the comments contained in the source. There is also a Lisp function to generate the function prototypes contained in the header files and sometimes in the C files as well. And finally there is a Program to extract the documentation from the source files and generate a printable manual.

All those support programs rely on standards for coding. Some of those standards have been develped independantly but should be used for consistency. In the following sections these coding standards are described.

4.1 K&R-C vs. ANSI-C

BibTool tries hard to be portable to wide variety of C systems. Thus it can not be assumed that an ANSI C compiler is at hand. As a consequence the function heads are written in the old style which is also tolerated by ANSI compliant compilers. This means that the argument types are given after the argument list.

Here it is essential that the arguments type declarations are given in the same order as the arguments of the function. Each type variable must have a new type declaration in a line by it’s own. This feature is used by the program which extracts the function prototypes.

Those function heads are use to generate function prototypes which can be understood by ANSI-C compilers as well as by of K&R compilers. This is achieved by the od trick to introduce a macro which expands to nothing on the old compilers and to its aregument on ANSI compilers. This macro is defined appropriately according to the existence of the macro __STDC__which should indicate an ANSI compliant compiler.

Index

BIBALIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 BIBCOMMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BIBEOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 BIBINCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BIBMODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BIBNOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BIBPREAMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BIBSTRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

ClearRecordDELETED() . . . . . . . . . . . . . . . . . . . . . . . . . 40 ClearRecordMARK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 ClearRecordXREF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

DBalias() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DBcomment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DBinclude() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 DBmodify() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DBnormal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DBpreamble() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DBstring() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 DebugPrint1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 DebugPrint2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 DebugPrint3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

ERRERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ERREXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ERRFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ERROR() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ERROR2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ERROR3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ERROREXIT() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ERRPOINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ERRWARNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 EntryName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Err() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ErrC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ErrPrint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ErrPrintF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ErrPrintF2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

FlushErr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

IsNormalRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 IsSpecialRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 MacroCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 MacroNULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 MacroName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 MacroValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

NameMid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 NameNULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 NamePost() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 NamePre() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 NameStrip() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 NameType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 NextMacro() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 NextName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 NextRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 NextWord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 NoDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

OUTOFMEMORY() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

PrevRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

RecordComment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 RecordFlagDELETED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 RecordFlagMARKED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 RecordFlagXREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 RecordFlags() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39, 42 RecordHeap() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 RecordIsDELETED() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 RecordIsMARKED() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 RecordIsXREF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 RecordNULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 RecordOldKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 RecordSortkey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 RecordSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 RecordType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 ReleaseSymbol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

SetRecordDELETED() . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 SetRecordMARK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 SetRecordXREF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

TeX active() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

                                               TeX close() ...................................56
                                               TeX def() .....................................57
                                               TeX define() ..................................57

\underline{INDEX 69}

TeX open file() ...............................57
TeX open string() ............................57
TeX read() ....................................57
TeX reset() ...................................57
ThisWord() ....................................61

ToLower() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 ToUpper() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

VerbosePrint1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 VerbosePrint2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 VerbosePrint3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 VerbosePrint4() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

WARNING() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 WARNING2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 WARNING3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 WordNULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

add check rule() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

add db record() ...............................11
add extract() .................................44
add field() ...................................45
add format() ..................................24
add ignored word() ...........................25
add rewrite rule() ...........................45
add s extract() ...............................45
add sort format() ............................25
add sort order() ..............................42
add word() ....................................62
apply aux() ...................................55
apply fmt() ...................................25
aux used() ....................................55
bibtoolversion ...............................61
case cmp() ....................................60
clear addlist() ..............................45
clear aux() ...................................55
clear ignored words() ........................26
copy record() .................................43
db count() ....................................11
db find() .....................................11
db forall() ...................................12
db mac sort() .................................12
db new key() ..................................12
db rewind() ...................................12
db sort() .....................................12
db string() ...................................13
def entry type() ..............................16
def field type() ..............................30
def format type() ............................26
def macro() ...................................30
delete record() ..............................13

                                               delete word() .................................62
                                               dump mac() ....................................30
                                               entrytype .....................................14
                                               error() .......................................21
                                               expand rhs() ..................................23
                                               find entry type() ............................16
                                               find word() ...................................62
                                               fmt expand() ..................................26
                                               foreach aux() .................................55
                                               foreach ignored word() .......................26
                                               foreach macro() ..............................30
                                               foreach word() ...............................62
                                               fput record() .................................36
                                               free 1 record() ...............................43
                                               free db() .....................................13
                                               free key node() ...............................26
                                               free macro() ..................................30
                                               free record() .................................43
                                               free words() ..................................63
                                               get entry type() ..............................16
                                               get field() ...................................26
                                               get item() ....................................31
                                               get key name() ................................31
                                               init bibtool() ...............................23
                                               init entries() ...............................17
                                               init macros() .................................31
                                               init read() ...................................34
                                               init symbols() ...............................53
                                               init type() ...................................60
                                               is selected() .................................45
                                               isallowed() ...................................58

isalpha() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 isdigit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 isextended() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 islower() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 isspace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 isupper() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 iswordsep() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

load rsc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

                                               look macro() ..................................31
                                               lower() .......................................60
                                               main() .........................................8
                                               make key() ....................................27
                                               make sort key() ...............................27
                                               mark key() ....................................27
                                               name format() .................................33
                                               new db() ......................................13
                                               new macro() ...................................32

\underline{70 INDEX}

new record() ..................................43
new string() ..................................53
new wordlist() ...............................43
parse bib() ...................................34
pop string() ..................................49
pp list of names() ............................33
print db() ....................................13
push string() .................................50
push to record() ..............................43
put record() ..................................36
px fopen() ....................................38
px s2p() ......................................38
pxfilename ....................................38
read aux() ....................................56
read db() .....................................14
read rsc() ....................................34
record gc() ...................................44
remove field() ...............................45
rewrite record() .............................46
rsc print() ...................................47
s parse() .....................................48
save input file() ..............................8
save key() ....................................32
save macro file() ..............................8
save output file() ............................8
save regex() ..................................46
sbclose() .....................................51
sbflush() .....................................51
sbopen() ......................................51
sbputc() ......................................51
sbputchar() ...................................50

sbputs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

sbrewind() ....................................52
sbseek() ......................................52
sbtell() ......................................52
search rsc() ..................................47
see bib() .....................................35
seen() ........................................35
set base() ....................................27
set field() ...................................28
set name format() ............................34
set rsc() .....................................47
set rsc path() ................................35
set separator() ..............................28
set symbol type() ............................37
show version() ...............................61
sort record() .................................44
sp open() .....................................49
sput record() .................................37
sym add() .....................................54
sym dump() ....................................54

                                               sym flag() ....................................54
                                               sym set flag() ................................54
                                               sym unlink() ..................................55
                                               symbol() ......................................52

symcrossref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

                                               symempty ......................................53
                                               transid .......................................58
                                               translower ....................................58
                                               transupper ....................................58
                                               unlink record() ..............................44
                                               use rsc() .....................................47