Changeset 1691

Timestamp:

Sep 3, 2004, 6:23:50 PM (22 years ago)

Author:

Paul Price

Message:

Specification of configuration files, psMetadataParseConfig.

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (3 diffs)
• psLibSDRS.tex (modified) (2 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-
+\
 \subsection{Changes from version 00 to version 01}
 
@@ -256 +256 @@
   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 +291 @@
   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}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +3518 @@
 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}