Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3652) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3653) @@ -1,3 +1,3 @@ -%%% $Id: ChangeLogSDRS.tex,v 1.80 2005-04-01 04:20:31 jhoblitt Exp $ +%%% $Id: ChangeLogSDRS.tex,v 1.81 2005-04-04 23:19:51 jhoblitt Exp $ \subsection{Changes from version 00 to version 01} @@ -521,5 +521,12 @@ \end{itemize} -\item Restrictions on the use of \code{malloc}, \code{calloc}, \code{realloc}, and \code{free} should not be unintentional imposed on 3rd party code. -\item Added database support for ``auto-incrementing'' -\end{itemize} +\item Restrictions on the use of \code{malloc}, \code{calloc}, \code{realloc}, and \code{free} should not be unintentionaly imposed on 3rd party code. +\item Add database support for ``auto-incrementing'' +\item Changes to Configuration Files: +\begin{itemize} +\item Add \code{UTC,UT1,TAI,TT} types +\item Change ``multiple symbol'' declaration format to \code{[keyword] MULTI} +\item Add Scoping Rules +\end{itemize} +\item Add \code{PS_META_TIME} to \code{psMetadataType} +\end{itemize} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 3652) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 3653) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.194 2005-04-01 04:20:31 jhoblitt Exp $ +%%% $Id: psLibSDRS.tex,v 1.195 2005-04-04 23:19:51 jhoblitt Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -3690,4 +3690,5 @@ PS_META_PNG, ///< PNG (item.data) PS_META_ASTROM, ///< astrometric coefficients (item.data) + PS_META_TIME, ///< psTime (item.data.V) PS_META_UNKNOWN, ///< other (item.data) PS_META_NTYPE ///< Number of types; must be last @@ -3937,4 +3938,6 @@ On error, the function shall return \code{NULL}. +\subsubsection{Comments} + The configuration file shall consist of plain text with key/type/value/comment quads on separate lines. Blank lines, @@ -3948,16 +3951,20 @@ 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}. +\subsubsection{Types} +\paragraph{Scalar \& Vector} + +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}; valid time type are \code{UTC,UT1,TAI,TT}. \tbd{May, in the future, require more types, including U8,S16,C64, which will also necessitate updating the definition of 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}. +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}. Time type values will be in the ISO8601 +compatible format of "YYYY-MM-DDTHH:MM:SS,sZ". When parsed, time types shall +be represented as a \code{psTime} object. Following the value may be an optional comment, preceded by a comment @@ -3984,15 +3991,26 @@ 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{*}. No other data may be provided on -this line, though a comment, preceeded by the comment marker, is -valid. 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. +\tbd{May add null, Not-a-Number (NaN), denormalized, underflow, overflow, +and/or +/-infinity values for selected types.} + +\paragraph{MULTI} + +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 with a \code{MULTI} declaration. In +the form \code{[keyword] MULTI}. No other data may be provided on this line, +though a comment, preceeded by the comment marker, is valid. 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. It should be noted that non-unique +keys may be of mixed type (even the \code{TYPE} and \code{METADATA} complex +types). For example: +\begin{verbatim} +comment MULTI # a comment +comment STR some string +comment F32 1.23456 +comment BOOL T +\end{verbatim} If a line does not conform to the rules laid out here, a warning shall @@ -4029,13 +4047,15 @@ files. -We extend \code{psMetadataParseConfig} to allow a modest tree -structure by defining a reserved keyword \code{TYPE}. Any line in the -config file which starts with the word \code{TYPE} shall be -interpretted as defining a new valid type. The defined type name -follows the word \code{TYPE}, and is in turn followed by an arbitrary -number of words. These words are to be interpreted as the names of an -embedded \code{psMetadata} entry, where the values are given on any -line which (following the \code{TYPE} definition) employs the new type -name. For example, a new type may be defined as: +\subsubsection{Complex Types} +\paragraph{TYPE} + +We support a modest tree structure by defining a reserved keyword \code{TYPE}. +Any line in the config file which starts with the word \code{TYPE} shall be +interpretted as defining a new valid type. The defined type name follows the +word \code{TYPE}, and is in turn followed by an arbitrary number of words. +These words are to be interpreted as the names of an embedded \code{psMetadata} +entry, where the values are given on any line which (following the \code{TYPE} +definition) employs the new type name. For example, a new type may be defined +as: \begin{verbatim} TYPE CELL EXTNAME BIASSEC CHIP @@ -4055,11 +4075,13 @@ Figure~\ref{fig:metadata}. -We further extend \code{psMetadataParseConfig} to allow the definition -of a \code{psMetadata} entry using a sequence of successive lines to -define the values of the \code{psMetadataItem} entries. The initial -line defines the new \code{psMetadata} entry and its name. The -following lines have the same format as the other metadata config file -entries. The sequence is terminated with a line with a single word -\code{END}. For example, a metadata entry may be defined as: +\paragraph{METADATA} + +Another way to form a tree-like structure is to directly define a +\code{psMetadata} entry using a sequence of successive lines to define the +values of the \code{psMetadataItem} entries. The initial line defines the new +\code{psMetadata} entry and its name. The following lines have the same format +as the other metadata config file entries. The sequence is terminated with a +line with a single word \code{END}. For example, a metadata entry may be +defined as: \begin{verbatim} CELL METADATA @@ -4070,4 +4092,29 @@ END \end{verbatim} + +\subsubsection{Scoping Rules} + +A simple set of ``Scoping Rules'' are required to properly parse a +configuration file. ``Scope'' refers to the current ``level'' of +\code{METADATA} that a statement appears in. Statements that are not contained +in a nested \code{METADATA} are said to be in the ``Top level scope''. Each +level of nested \code{METADATA} statements create a new ``lower level scope''. + +\begin{itemize} +\item +Variable names are unique only to the current level of scope. + +\item +non-unique keywords (\code{MULTI}) apply only to the current scope. i.e. They +are invalid in ``higher'' or ``lower'' level scopes. + +\item +\code{TYPE} declarations apply only to the current scope. + +\item +\code{METADATA} declarations must begin and end in the same scope. i.e. They +may not be declared and end in two different nested METADATA and the same +depth. +\end{itemize} A series of test inputs is contained in