Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 1690) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 1691) @@ -1,3 +1,3 @@ - +\ \subsection{Changes from version 00 to version 01} @@ -256,6 +256,5 @@ dimension. \item Added \code{psLibVersion} (bug 156). -\item Added specification of iterator (\code{which}) to - \code{psMetadataSetIterator}. +\item Added specification of iterator to \code{psMetadataSetIterator}. \item Replaced \code{which} and \code{where} in \code{psMetadata} and \code{psList} functions with \code{iterator} and \code{location}, @@ -292,3 +291,5 @@ specify a protocol for \code{stderr,stdout,none}). \item Leading dot in facility name for \code{psTrace} is optional. +\item Specification of configuration file format and parse function, + \code{psMetadataParseConfig}. \end{itemize} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 1690) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 1691) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.106 2004-09-03 21:22:20 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.107 2004-09-04 04:23:21 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -3518,4 +3518,113 @@ Read header data from a FITS image file descriptor into a \code{psMetadata} structure. + + +\subsubsection{Configuration files} + +It will be necessary for the \PS{} system, in order to load +pre-defined settings, to parse a configuration file into a +\code{psMetadata} structure. This shall be performed by the +function \code{psMetadataParseConfig}, as described below. + +\begin{verbatim} +int psMetadataParseConfig(psMetadata *md, const char *filename, bool overwrite); +\end{verbatim} + +Given a previously allocated metadata container, \code{md}, and the +name of a configuration file, \code{filename}, +\code{psMetadataParseConfig} shall parse the configuration file, +placing the contained key/type/value/comment quads into the metadata, +and returning the number of lines that failed to parse. Multiple +specifications of a key that haven't been declared (see below) are +overwritten if and only if \code{overwrite} is \code{true}. + +The configuration file shall consist of plain text with +key/type/value/comment quads on separate lines. Blank lines, +including those consisting solely of whitespace (both spaces and +tabs), shall be ignored, as shall lines that commence with the comment +character (a hash mark, \code{#}), either immediately at the start of +the line, or preceded by whitespace. The key/type/value/comment quads +shall all lie on a single line, separated by whitespace. + +The key shall be first, possibly preceded on the line by whitespace +which should not form part of the key. + +Next, to assist the casting of the value, shall be a string +identifying the type of the value, which shall correspond to one of +the simple types supported in \code{psMetadata}: +\code{STRING,BOOL,S32,F32,F64}; \code{STR} may be used to abbreviate +\code{STRING}. + +\tbd{May, in the future, require more types, including +\code{U8,S16,C64}, which will necessitate updating the definition of +\code{psMetadata}.} + +The value shall follow the type: strings may consist of multiple +words, and shall have all leading and trailing whitespace removed; +booleans shall simply be either \code{T} or \code{F}. + +Following the value may be an optional comment, preceded by a comment +character (a hash mark, \code{#}), which in the case of a string +value, serves to mark the end of the value, and for other types serves +to identify the comment to the reader. Only one comment character may +be present on any single line (i.e., neither strings nor comments are +permitted to contain the comment character). The comment may consist +of multiple words, and shall have leading and trailing whitespace +removed. + +One wrinkle is the specification of vectors. Keys for which the value +is to be parsed as a vector shall be preceded immediately by a +``vector symbol'', which we choose to be the ``at'' sign, \code{@}. +In this case, the type shall be interpreted as the type for the +vector, which may be any of the signed or unsigned integer or floating +point types (\code{U8,U16,U32,U64,S8,S16,S32,S32,S64,F32,F64}) but not +the complex floating point types; and the value shall consist of +multiple numbers, separated either by a comma or whitespace. These +values shall populate a \code{psVector} of the appropriate type in the +order in which they appear in the configuration file. + +\tbd{May add complex types, likely to be specified with values such as +\code{1.23+4.56i} in the future.} + +An additional hurdle is the specification of keys that may be +non-unique (such as the \code{COMMENT} keyword in a FITS header). +These keys shall be specified in the configuration file as non-unique +by specifying the key at the start of the line (possibly preceded by +whitespace) and specifying the type as a ``multiple symbol'', which we +choose to be an asterisk, \code{*}. Everything else on the line shall +be ignored. A warning shall be produced when a key which has not been +specified to be non-unique is repeated; in this case, the former value +shall be overwritten if \code{overwrite} is \code{true}, otherwise the +line shall be ignored and counted as one that could not be parsed. + +If a line does not conform to the rules laid out here, a warning shall +be generated, it shall be ignored and counted as a line that could not +be parsed. The total number of lines that were not able to be parsed +(including those that were ignored because \code{overwrite} is +\code{false}, and any other parsing problems, but not including blank +lines and comment lines) shall be returned by the function. + +Here are some examples of lines of a valid configuration file: +\begin{verbatim} + Double F64 1.23456789 # This is a comment +Float F32 0.98765#This is a comment too + String STR This is the string that forms the value #comment + #This is a comment line and is to be ignored +boolean BOOL T # The value of `boolean' is `true' + +@primes U8 2,3 5 7,11,13 17 # These are prime numbers +comment * The rest of this line is ignored, but `comment' is set to be non-unique +comment STR This +comment STR is +comment STR a +comment STR non-unique +comment STR key +Float F64 1.23456 # This generates a warning, and, if `overwrite' is `false', is ignored +\end{verbatim} + +Of course, a real configuration file should look much nicer to humans +than the above example, but PSLib must be able to parse such ugly +files. + \subsection{Detector and sky positions}