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

Timestamp:

Aug 16, 2005, 1:18:38 PM (21 years ago)

Author:

Paul Price

Message:

Expanding discussion of psArguments.

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.324 2005-08-05 20:24:03 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.325 2005-08-16 23:18:38 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1666 +1666 @@
 (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}.
+of possible arguments 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; the purpose of this requirement is so that the
+default values are preserved) was encountered that is not present in
+the \code{arguments}.
 
 \begin{prototype}
@@ -1690 +1691 @@
 \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
+Optional arguments, with default values:
+    -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,
@@ -1704 +1705 @@
 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]);
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-string", PS_META_STR, "Test string", "SomeString");
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-bool", PS_META_BOOL, "Test bool", false);
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-int", PS_META_S32 | PS_META_DUPLICATE_OK, "Test integer 1", 1);
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-int", PS_META_S32 | PS_META_DUPLICATE_OK, "Test integer 2", 2);
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-int", PS_META_S32 | PS_META_DUPLICATE_OK, "Test integer 3", 3);
+    psMetadataAdd(arguments, PS_LIST_TAIL, "-float", PS_META_F32, "Test float", 1.234567);
+    if (! psArgumentParse(arguments, &argc, argv) || argc != 3) {
+        printf("\nName of the program here\n\n");
+        printf("Usage: %s INPUT OUTPUT\n\n", argv[0]);
+        psArgumentHelp(arguments);
+        psFree(arguments);
         exit(EXIT_FAILURE);
     }
+    const char *inputName = argv[1];    // Name of input
+    const char *outputName = argv[2];   // Name of output
+    printf("Success: %s %s\n", inputName, outputName);
+
+    psString string = psMetadataLookupString(NULL, arguments, "-string");
+    float floating = psMetadataLookupF32(NULL, arguments, "-float");
+    bool boolean = psMetadataLookupBool(NULL, arguments, "-truth");
+    printf("String: %s\n", string);
+    printf("Float: %f\n", floating);
+    printf("Boolean: %d\n", boolean);
+
+    psMetadataItem *intItem = psMetadataLookup(arguments, "-int");
+    if (intItem->type == PS_META_MULTI) {
+        psList *intMulti = intItem->data.V;
+        psListIterator *intIter = psListIteratorAlloc(intMulti, PS_LIST_HEAD, false);
+        psMetadataItem *intMultiItem = NULL;
+        while (intMultiItem = psListGetAndIncrement(intIter)) {
+            printf("Integer: %d\n", intMultiItem->data.S32);
+        }
+        psFree(intIter);
+    }
+}
+\end{verbatim}
+
+The above program should produce, on being given no arguments:
+\begin{verbatim}
+
+Name of the program here
+
+Usage: ./program INPUT OUTPUT
+
+Optional arguments, with default values:
+    -string    (SomeString)      Test string
+    -bool      (FALSE)           Test bool
+    -int       (1)               Test integer 1
+               (2)               Test integer 2
+               (3)               Test integer 3
+    -float     (1.234567e+00)    Test float
+\end{verbatim}
+
+and called with: \code{./program -string whatevers -float 9.876543
+-int 4 5 6 -bool input output}, then it should produce:
+
+\begin{verbatim}
+Success: input output
+String: SomeString
+Float: 1.234567
+Boolean: 0
+Integer: 1
+Integer: 2
+Integer: 3
 \end{verbatim}