Changeset 3653

Timestamp:

Apr 4, 2005, 1:19:51 PM (21 years ago)

Author:

jhoblitt

Message:

add UTC,UT1,TAI,TT types
change "multiple symbol" declaration format to [keyword] MULTI
add Scoping Rules
add PS_META_TIME to psMetadataType

Location:

trunk/doc/pslib

Files:

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

trunk/doc/pslib/ChangeLogSDRS.tex

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +3690 @@
     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 +3938 @@
 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 +3951 @@
 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 +3991 @@
   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 +4047 @@
 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 +4075 @@
 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 +4092 @@
 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