Changeset 4712 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Aug 4, 2005, 7:17:50 PM (21 years ago)

Author:

Paul Price

Message:

Adding psArgumentParse (may need another iteration for format) and psArgumentHelp.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (2 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.322 2005-08-05 03:51:16 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.323 2005-08-05 05:17:50 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1659 +1659 @@
 are processed.  The function shall return the resultant logging level.
 
+\begin{prototype}
+bool psArgumentParse(psMetadata *arguments, int *argc, char **argv);
+\end{prototype}
+
+\code{psArgumentParse} shall parse the command line arguments
+(supplied via \code{argc, argv}) into a metadata container of
+\code{arguments}.  The input \code{arguments} shall contain the list
+of possible arguments (lacking a leading dash) as the keywords
+providing the default values (of the appropriate type).  As matching
+arguments are found on the command line, the values shall be read into
+the \code{arguments} metadata, with the appropriate type.  Multiple
+values (i.e., when an argument takes two or more values) are specified
+using a \code{PS_DATA_METADATA_MULTI} list (i.e., by specifying a type
+with the \code{PS_META_DUPLICATE_OK} flag).  A boolean argument shall
+be set to \code{true} by the presence of the argument itself (no value
+is specified).  The arguments and their values shall be removed from
+the list of command line arguments as they are processed.  The
+function shall return \code{false} without modifying the
+\code{arguments} if any argument (i.e., a string beginning with a
+dash; but not a string that does not start with a dash, which is
+likely a mandatory argument for the program) was encountered that is
+not present in the \code{arguments}.
+
+\begin{prototype}
+void psArgumentHelp(psMetadata *arguments);
+\end{prototype}
+
+\code{psArgumentHelp} shall print to \code{stdout} a guide to the
+command-line \code{arguments} (containing the same information as for
+\code{psArgumentParse}) of the form:
+\begin{verbatim}
+Optional arguments:
+    -names      FRED    This is the comment from the first value
+                JIM     This is the comment from the second value
+                BOB     This is the comment from the third value
+    -answer     42      This is a comment
+    -truth      FALSE   This is another comment
+\end{verbatim}
+Here the \code{arguments} contains three keywords, \code{names, magic,
+truth}.  \code{names} has three values, \code{FRED, JIM, BOB}, stored
+as a \code{PS_DATA_METADATA_MULTI}, each with the comment as shown.
+
+It will be the responsibility of the user to supply information for
+the mandatory arguments.  An example follows:
+\begin{verbatim}
+void help(psMetadata *arguments,        // Command-line arguments
+          const char *programName       // Name of the program = argv[0]
+    )
+{
+    printf("Pan-STARRS Phase 2 processing\n\n");
+    printf("Usage: %s INPUT.fits OUTPUT.fits\n\n", programName);
+    psArgumentHelp(arguments);
+}
+
+int main(int argc, char *argv[])
+{
+    // Parse optional command-line arguments
+    psMetadata *arguments = psMetadataAlloc(); // The arguments, with default values
+    psMetadataAddStr(arguments, PS_LIST_TAIL, "bias", "Name of the bias image", NULL);
+    psMetadataAddStr(arguments, PS_LIST_TAIL, "dark", "Name of the dark image", NULL);
+    psMetadataAddStr(arguments, PS_LIST_TAIL, "flat", "Name of the flat-field image", NULL);
+    psMetadataAddS32(arguments, PS_LIST_TAIL, "chip", "Chip number to process (if positive)", -1);
+    psMetadataAddS32(arguments, PS_LIST_TAIL | PS_META_DUPLICATE_OK, "timerange", "The lower time value", 0);
+    psMetadataAddS32(arguments, PS_LIST_TAIL, "timerange", "The upper time value", 10);
+    psMetadataAddBool(arguments, PS_LIST_TAIL, "ok", "Is this OK?", FALSE);
+    if (! psArgumentParse(arguments, &argc, argv) || argc != 2) {
+        help(arguments, argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\end{verbatim}
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%