Autodoc Module

The autodoc module contains functions for reading from and writing to autodoc type files, with named sections and key-value pairs within sections. There is a Fortran wrapper for almost every function listed here, with the same calling conventions. The only difference is that indices are numbered from 1 instead of 0, including returned indices. However, error codes returned to Fortran are not shifted up and are as listed below. There are no wrappers yet for AdocAppendSection, AdocDeleteSection, AdocGetNumberOfKeys, AdocGetKeyByIndex, and AdocGetValTypeAndSize. There are also no wrappers for a set of functions that write directly to a file without going through an autodoc structure; these are to support rapid writing from SerialEM.

The basic unit of organization in the autodoc file is the section, which starts with a line of the form:
[SectionType = name]
There can be many sections of the same type, i.e., having the same key name for the section, named typeName in the functions below. Each of these would typically have a different value for the name entry, although this is not strictly necessary as no uniqueness is enforced and sections are not ordinarily looked up by name. All of the sections of the same type are held in an array, referred to as a collection, and they are accessed by their array index. Thus, functions for setting or getting values from a section all refer to the section by its typeName and its index sectInd.

Inside of a section, the autodoc contains a set lines with key-value pairs, of the form:
key = value
In general, the values are stored as strings, but functions below can be used for storing or retrieving the values from strings consisting of 1 to 3 floats or integers. Sections of the same type do not need to have the same set of key-value pairs defined.

Every autodoc structure is initialized with a section for global data stored at the start of the file, before any actual sections are defined. These data are accessed by calls with a typeName of "PreData" and a sectInd of 0. C programs should use ADOC_GLOBAL_NAME, which is defined as "PreData"; Fortran programs should call
integer*4 AdocGetStandardNames(globalName, zvalueName)
to fetch this string and also the important string ADOC_ZVALUE_NAME, which is defined as "ZValue". That function returns -1 if a string does not fit into the supplied character argument.

Comments on lines starting with # can occur anywhere in an autodoc. They will be preserved when it is read in and generally be written out again in front of the same item.

Some simple Python functions for accessing data in an autodoc are available in the autodoc.py module. There is a function to take a set of autodoc lines and produce a top-level dictionary of the different types of sections, keyed by 'sectionType', with each entry containing an array of dictionaries, one for each section. Other functions will return a list of integer or floating point values from the value in a key-value pair.

An autodoc can be written as an XML file, and simple enough XML files can be read in and stored in the autodoc structure. When reading from an XML file, the root element can be anything, although the calling program may insist on a particular element name. When writing, the root element will be <autodoc> unless the autodoc was read from an XML file or the name was set with AdocSetXmlRootElement. Each section is written as a top-level child of the root element in this form: <typeName name="value">, although the global section is written as <PreData> without a name. Key-value pairs within a section are all written as children of the top-level child with the form <key>value</key>. Empty values are allowed and written as <key />. Any XML file that conforms to this structure can be read in; namely, each top-level child must have a name attribute except "PreData", and children of those nodes must be simple key-value pairs with no attributes or children. The latter will simply be lost; see AdocXmlReadStatus.

Header to include: autodoc.h


int AdocRead(const char *filename)
int AdocXmlReadStatus(int *sectNotElem, int *sectNoName, int *childNotElem, int *childAttribs, int *valueNotText, int *multipleChilds)
int AdocOpenImageMetadata(const char *filename, int addMdoc, int *montage, int *numSect, int *sectType)
int AdocGetImageMetaInfo(int *montage, int *numSect, int *sectType)
int AdocNew()
int AdocGetCurrentIndex()
int AdocSetCurrent(int index)
void AdocClear(int index)
void AdocDone()
int AdocWrite(const char *filename)
void AdocRetryWriteOpens(int num)
void AdocSetWriteAsXML(int asXML)
int AdocGetWriteAsXML()
int AdocGetXmlRootElement(char **string)
int AdocSetXmlRootElement(const char *element)
int AdocAppendSection(const char *filename)
int AdocPrintToString(char *string, int stringSize, int writeAll)
int AdocOrderWriteByValue(const char *typeName)
int AdocAddSection(const char *typeName, const char *name)
int AdocInsertSection(const char *typeName, int sectInd, const char *name)
int AdocDeleteSection(const char *typeName, int sectInd)
int AdocChangeSectionName(const char *typeName, int sectInd, const char *newName)
int AdocLookupSection(const char *typeName, const char *name)
int AdocLookupByNameValue(const char *typeName, int nameValue)
int AdocFindInsertIndex(const char *typeName, int nameValue)
int AdocTransferSection(const char *typeName, int sectInd, int toAdocInd, const char *newName, int byValue)
int AdocTransferToNewType(const char *typeName, int sectInd, int toAdocInd, const char *newType, const char *newName, int byValue)
int AdocSetKeyValue(const char *typeName, int sectInd, const char *key, const char *value)
int AdocSetInteger(const char *typeName, int sectInd, const char *key, int ival)
int AdocSetTwoIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2)
int AdocSetThreeIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2, int ival3)
int AdocSetIntegerArray(const char *typeName, int sectInd, const char *key, int *ivals, int numVals)
int AdocSetFloat(const char *typeName, int sectInd, const char *key, float val)
int AdocSetTwoFloats(const char *typeName, int sectInd, const char *key, float val1, float val2)
int AdocSetThreeFloats(const char *typeName, int sectInd, const char *key, float val1, float val2, float val3)
int AdocSetFloatArray(const char *typeName, int sectInd, const char *key, float *vals, int numVals)
int AdocSetDouble(const char *typeName, int sectInd, const char *key, double val)
int AdocDeleteKeyValue(const char *typeName, int sectInd, const char *key)
int AdocGetNumCollections()
int AdocGetCollectionName(int collInd, char **string)
int AdocGetSectionName(const char *typeName, int sectInd, char **string)
int AdocGetNumberOfSections(const char *typeName)
int AdocGetNumberOfKeys(const char *typeName, int sectInd)
int AdocGetKeyByIndex(const char *typeName, int sectInd, int keyInd, char **key)
int AdocGetValTypeAndSize(const char *typeName, int sectInd, const char *key, int *valType, int *numTokens)
int AdocGetString(const char *typeName, int sectInd, const char *key, char **string)
int AdocGetInteger(const char *typeName, int sectInd, const char *key, int *val1)
int AdocGetFloat(const char *typeName, int sectInd, const char *key, float *val1)
int AdocGetDouble(const char *typeName, int sectInd, const char *key, double *val1)
int AdocGetTwoIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2)
int AdocGetTwoFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2)
int AdocGetThreeIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2, int *val3)
int AdocGetThreeFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2, float *val3)
int AdocGetIntegerArray(const char *typeName, int sectInd, const char *key, int *array, int *numToGet, int arraySize)
int AdocGetFloatArray(const char *typeName, int sectInd, const char *key, float *array, int *numToGet, int arraySize)
int AdocWriteInteger(FILE *fp, const char *key, int ival)
int AdocWriteTwoIntegers(FILE *fp, const char *key, int ival1, int ival2)
int AdocWriteThreeIntegers(FILE *fp, const char *key, int ival1, int ival2, int ival3)
int AdocWriteIntegerArray(FILE *fp, const char *key, int *ivals, int numVals)
int AdocWriteFloat(FILE *fp, const char *key, float val)
int AdocWriteTwoFloats(FILE *fp, const char *key, float val1, float val2)
int AdocWriteThreeFloats(FILE *fp, const char *key, float val1, float val2, float val3)
int AdocWriteFloatArray(FILE *fp, const char *key, float *vals, int numVals)
int AdocWriteKeyValue(FILE *fp, const char *key, const char *value)
int AdocWriteSectionStart(FILE *fp, const char *key, const char *value)

int AdocRead(const char *filename)

Reads an autodoc or autodoc-compatible XML file from the file specified by filename, and returns the index of the new autodoc (numbered from zero) or -1 for an error.

int AdocXmlReadStatus(int *sectNotElem, int *sectNoName, int *childNotElem, int *childAttribs, int *valueNotText, int *multipleChilds)

Returns whether the last file read in was an XML file, and information about aspects that could not be encoded as an autodoc if the last file was an XML file.  Each value is the number of occurrences of the problem:
sectNotElem if a top-level child is not an element,
sectNoName if a top-level child does not have a name attribute,
childNotElem if a child of a top-level child is not an element,
childAttribs if a child has attributes,
valueNotText if a child's value is not text,
multipleChilds if a child of a top-level child has multiple children.
If a top-level child has attributes other than "name", these will become key-value pairs indistinguishable from the ones coming from child nodes, and there is no indicator that this occurred.  The return value is 0 if file was not XML, 1 if it was and had no problems, or -1 if it was XML and had some of these problems.

int AdocOpenImageMetadata(const char *filename, int addMdoc, int *montage, int *numSect, int *sectType)

Try to read an image metadata file and determine its properties.  It will look for and try to read the file with name filename if addMdoc is less than or equal to 0, otherwise it will append '.mdoc' to filename.  Returns a non-zero in montage if the file indicates a montage; the number of sections in numSect, and 1 for a metadata autodoc, or 2 for an image series autodoc in sectType.  An autodoc with one section named FrameSet is allowed if addMdoc is less than 0 or greater than 1, in which case sectType will be returned with 4 and the autodoc will be retained.  If addMdoc is 0 or 1, or if there is more than one FrameSet section, the autodoc will be cleared and the return value will be -3.  The return value is the index of the autodoc, or -1 for an error opening or reading the file, -2 if the file does not exist, or -3 if it is not a valid autodoc.

int AdocGetImageMetaInfo(int *montage, int *numSect, int *sectType)

Determines whether the current autodoc is a valid image metadata autodoc and returns a non-zero in montage if the file indicates a montage; the number of sections in numSect; and 1 for a metadata autodoc, 2 for an image series autodoc, 3 for any other autodoc with sections named ZValue (including the autodoc holding attributes for an HDF file), or 4 for an autodoc with one section named FrameSet. The return value is -3 if it is not one of these types of autodocs, 1 if it is a FrameSet autodoc, or 0 for a valid image file autodoc.

int AdocNew()

Finds an unused autodoc in the internal array if one exists or creates a new one if not, makes it the current one, and returns its index or -1 for an error.

int AdocGetCurrentIndex()

Returns the current autodoc index, or -1 if there is none

int AdocSetCurrent(int index)

Makes the autodoc at index be the current autodoc.  The index is numbered from zero.  Returns -1 for an index out of bounds.

void AdocClear(int index)

Deletes all data from the autodoc at index and marks it as unused.

void AdocDone()

Deletes all autodocs and returns the module to its initial state.

int AdocWrite(const char *filename)

Writes the current autodoc to the file specified by filename.  Returns 1 for failure to back up a previous file, and -1 for other errors

void AdocRetryWriteOpens(int num)

Sets the number of times to retry opening the autodoc file for writing to num. Retries occur every 250 msec.

void AdocSetWriteAsXML(int asXML)

Sets the current autodoc to be written as XML if asXML is non-zero.

int AdocGetWriteAsXML()

Returns 1 if current autodoc is to be written as XML, 0 if not, -1 for invalid current autodoc

int AdocGetXmlRootElement(char **string)

Returns a copy of the root element name into string if a file was loaded from XML; it should be freed with free if it is non-NULL.  Returns -1 for no current autodoc or 1 for memory error.

int AdocSetXmlRootElement(const char *element)

Sets the root element name to element when writing as an XML file; returns -1 for no current autodoc or 1 for memory error.

int AdocAppendSection(const char *filename)

Appends the last section in the current autodoc to the file specified by filename; or writes the autodoc completely if it is being written as XML. Returns -1 for errors.

int AdocPrintToString(char *string, int stringSize, int writeAll)

Writes either the entire current autodoc, if writeAll is non-zero, or just the last section otherwise, into string, whose size must be specified by stringSize. Returns -1 for all errors, including not fitting into the string.

int AdocOrderWriteByValue(const char *typeName)

Sets the next write so that all sections in the collection with name typeName are output after the global section and in order by the value of their names. Returns 1 for memory error.

int AdocAddSection(const char *typeName, const char *name)

Adds a section of type specified by typeName and name given by name. Returns the index of the new section in the collection of sections of that type, or -1 for error.

int AdocInsertSection(const char *typeName, int sectInd, const char *name)

Inserts a section with name given by name into the collection of sections of type typeName, at the index sectInd.  The collection must exist unless sectInd is 0, and sectInd must be less than or equal to the number of sections in that collection. Returns -1 for error.

int AdocDeleteSection(const char *typeName, int sectInd)

Deletes the section at index sectInd from the collection of sections of type typeName.  Returns -1 for error.

int AdocChangeSectionName(const char *typeName, int sectInd, const char *newName)

Changes the name of the section at index sectInd from the collection of sections of type typeName to newName.  Returns -1 for error.

int AdocLookupSection(const char *typeName, const char *name)

Looks up a section of type specified by typeName and name given by name. Returns the index of that section in the collection of sections of that type, -1 if there is none, or -2 for error.

int AdocLookupByNameValue(const char *typeName, int nameValue)

Looks up a section of type specified by typeName whose name converts to the integer value nameValue. Returns the index of that section in the collection of sections of that type, -1 if there is none, or -2 for error.  When calling from Fortran, be sure to pass the actual value in the file, as this routine will not adjust the passed value down by 1.

int AdocFindInsertIndex(const char *typeName, int nameValue)

Looks in the collection of sections of type typeName, converts their name strings to integers, and returns the index of the first section whose name is greater than nameValue, the number of sections if there is no such section, or -1 for error (including if a section exists whose name converts to nameValue).  This returned index can thus be used in a call to AdocInsertSection to maintain the sections in numeric order by name value.

int AdocTransferSection(const char *typeName, int sectInd, int toAdocInd, const char *newName, int byValue)

Transfers all key/value pairs from the section of index sectInd in the collection of type typeName of the current autodoc to a section of the same type in the autodoc with index toAdocInd, with a name newName.  If byValue is non-zero, the new name is converted to an integer and the section is inserted so as to maintain sections in order.  The collection in the receiving autodoc is created if necessary; the new section may already exist or will be created if necessary; existing values with the same key are overwritten.  To transfer the global data, set typeName to ADOC_GLOBAL_NAME, sectInd to 0, and byValue to 0; newName is ignored.  Returns -1 if the originating section does not exist, -2 for incorrect index for new autodoc or newName NULL (unless typeName is ADOC_GLOBAL_NAME), -3 for failure to add a new section, or -4 for failure to add a key-value.

int AdocTransferToNewType(const char *typeName, int sectInd, int toAdocInd, const char *newType, const char *newName, int byValue)

Like AdocTransferSection except that the section is transferred to a collection with the name newType.

int AdocSetKeyValue(const char *typeName, int sectInd, const char *key, const char *value)

Sets a key-value pair to key and value in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any.  value may be NULL.  Returns -1 for error.

int AdocSetInteger(const char *typeName, int sectInd, const char *key, int ival)

Sets the value of key to the integer ival in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any. Returns -1 for error.

int AdocSetTwoIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2)

Like AdocSetInteger, except that the value is set to the two integers ival1 ival2.

int AdocSetThreeIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2, int ival3)

Like AdocSetInteger, except that the value is set to the three integers ival1 ival2 ival3.

int AdocSetIntegerArray(const char *typeName, int sectInd, const char *key, int *ivals, int numVals)

Like AdocSetInteger, except that the value is set to the array of numVals integers in ivals.

int AdocSetFloat(const char *typeName, int sectInd, const char *key, float val)

Sets the value of key to the float val in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any. Returns -1 for error.

int AdocSetTwoFloats(const char *typeName, int sectInd, const char *key, float val1, float val2)

Like AdocSetFloat, except that the value is set to the two floats val1 val2.

int AdocSetThreeFloats(const char *typeName, int sectInd, const char *key, float val1, float val2, float val3)

Like AdocSetFloat, except that the value is set to the three floats val1 val2 val3.

int AdocSetFloatArray(const char *typeName, int sectInd, const char *key, float *vals, int numVals)

Like AdocSetFloat, except that the value is set to the array of numVals floats in vals.

int AdocSetDouble(const char *typeName, int sectInd, const char *key, double val)

Like AdocSetFloat, except that val is a double

int AdocDeleteKeyValue(const char *typeName, int sectInd, const char *key)

Deletes the key-value pair matching key in the section with index sectInd in the collection of sections of type typeName.  Clears out both the key and the value.  Returns -1 for error.

int AdocGetNumCollections()

Returns the number of collections of sections, excluding the global data collection, or -1 if there is no current autodoc.

int AdocGetCollectionName(int collInd, char **string)

Returns the name of the collection with index collInd into string, which is allocated and should be freed with free.  The index is numbered from 0 (1 in Fortran) and excludes the global data collection.  Returns -1 for errors.

int AdocGetSectionName(const char *typeName, int sectInd, char **string)

Gets the name of the section with index sectInd in the collection of sections of type typeName.  Returns the name in string, which is allocated and should be freed with free.  Returns -1 for errors.

int AdocGetNumberOfSections(const char *typeName)

Returns the number of sections of type typeName.  Returns -1 for errors, and 0 if there are no sections of the given type.

int AdocGetNumberOfKeys(const char *typeName, int sectInd)

Returns the number of key-value pairs in the section with index sectInd in the collection of sections of type typeName.  Returns -1 for errors.

int AdocGetKeyByIndex(const char *typeName, int sectInd, int keyInd, char **key)

Gets the key at index keyInd in the section with index sectInd in the collection of sections of type typeName.  Returns a copy of the key in key, which should be freed with free, or returns NULL if this key has been deleted. Returns -1 for errors.

int AdocGetValTypeAndSize(const char *typeName, int sectInd, const char *key, int *valType, int *numTokens)

Returns information about the value string matching key in the section with index sectInd in the collection of sections of type typeName: the value type (ADOC_ONE_INT, etc) in valType and the number of space-separated tokens in the string in numTokens.  Returns -1 if the key is null, the section does not exist, or for a memory error; returns 1 if the key does not occur in the given section or if the value is null.

int AdocGetString(const char *typeName, int sectInd, const char *key, char **string)

Gets the value string matching key in the section with index sectInd in the collection of sections of type typeName.  Returns a copy of the value in string; it should be freed with free.  Returns -1 if the key is null, the section does not exist, or for a memory error; returns 1 if the key does not occur in the given section or if the value is null.

int AdocGetInteger(const char *typeName, int sectInd, const char *key, int *val1)

Like AdocGetString, except that it extracts one integer from the value string and returns its value in val1.

int AdocGetFloat(const char *typeName, int sectInd, const char *key, float *val1)

Like AdocGetInteger except that it returns a float

int AdocGetDouble(const char *typeName, int sectInd, const char *key, double *val1)

Like AdocGetInteger except that it returns a double

int AdocGetTwoIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2)

Like AdocGetString, except that it extracts two integers from the value string and returns their values in val1 and val2.

int AdocGetTwoFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2)

Like AdocGetTwoIntegers except that it returns floats

int AdocGetThreeIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2, int *val3)

Like AdocGetString, except that it extracts three integers from the value string and returns their values in val1, val2, and val3.

int AdocGetThreeFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2, float *val3)

Like AdocGetThreeIntegers except that it returns floats

int AdocGetIntegerArray(const char *typeName, int sectInd, const char *key, int *array, int *numToGet, int arraySize)

Like AdocGetString, except that it extracts a set of integers from the value string and returns their values in array, whose size is given in arraySize.  Set numToGet to the number of values to get, or 0 to get all the values; in the latter case numToGet is returned with the number of values retrieved.  Returns -1 for errors in parsing, too few values on the line, or not enough space in the array, as well as for failures in getting the value string.

int AdocGetFloatArray(const char *typeName, int sectInd, const char *key, float *array, int *numToGet, int arraySize)

Like AdocGetIntegerArray except that it returns floats

int AdocWriteInteger(FILE *fp, const char *key, int ival)

DIRECT WRITING FUNCTIONS

int AdocWriteTwoIntegers(FILE *fp, const char *key, int ival1, int ival2)

Like AdocWriteInteger, except that the value is set to the two integers ival1 ival2.

int AdocWriteThreeIntegers(FILE *fp, const char *key, int ival1, int ival2, int ival3)

Like AdocWriteInteger, except that the value is set to the three integers ival1 ival2 ival3.

int AdocWriteIntegerArray(FILE *fp, const char *key, int *ivals, int numVals)

Like AdocWriteInteger, except that the value is set to the array of numVals integers in ivals.

int AdocWriteFloat(FILE *fp, const char *key, float val)

Like AdocWriteInteger, except that the value is set to the float val.

int AdocWriteTwoFloats(FILE *fp, const char *key, float val1, float val2)

Like AdocWriteInteger, except that the value is set to the two floats val1 val2.

int AdocWriteThreeFloats(FILE *fp, const char *key, float val1, float val2, float val3)

Like AdocWriteInteger, except that the value is set to the thre floats val1 val2 val3.

int AdocWriteFloatArray(FILE *fp, const char *key, float *vals, int numVals)

Like AdocWriteInteger, except that the value is set to the array of numVals floats in vals.

int AdocWriteKeyValue(FILE *fp, const char *key, const char *value)

Writes one key-value pair directly to the file in fp from the strings in key and value.  Returns 1 for write error.

int AdocWriteSectionStart(FILE *fp, const char *key, const char *value)

Writes a section header directly to the file in fp from the strings in key and value.  Returns 1 for write error.