NAME

cparse - parse a character string into fields given an arbitrary field delimiter

USAGE

cparse cline [delim] [nselect] [lignore] [mignore] [verbose]

PARAMETERS

cline = ""

Character string to parse into fields.

delim = " "

Arbitrary field delimiting character or multi-character string. 'delim' defaults to a single space character.

nselect = 1

Return the value of the 'nselect'th field in 'cline'.

(cfield) [string]

Parameter returning the value of field number 'nselect' in string 'cline'.

(nfields) [int]

Parameter returning the total number of fields found in 'cline'.

lignore = yes

Ignore leading delimiters (if any)?

mignore = yes

Treat multiple successive embedded delimiters as one (if any)?

verbose = no

Return the value of the selected field to the standard output?

DESCRIPTION

Task to parse a character string 'cline' into separate fields, given an arbitrary field delimiting character (e.g., " ", ":", ",", "/") or multi-character string (e.g., "//", ".fits", "-->"). By default, leading and multiple successive delimiters are ignored, but this behavior may be changed by setting either or both 'lignore' and 'mignore' to "no". A user-specified field (parameter 'nselect') is returned in task parameter 'cfield' and optionally to the standard output as well (if 'verbose=yes'). The total number of fields found in 'cline' is returned in task parameter 'nfields'. If the specified field number is larger than the number of fields in string 'cline', the last field in the string is returned.

Usually, a string contains at least one field, which equals the entire input string if the specified delimiter does not occur in 'cline'. Regardless of the number of fields, 'cfield' will be returned empty ("") upon exit when 'nselect = 0' or 'nselect = INDEF', or when 'cline' equals 'delim'. In the latter case, 'nfields = 1' when 'lignore = no', and '0' otherwise (default). Although these trivial cases are rather silly when using cparse interactively, its behavior is useful when cparse is embedded in routines where no a priori knowledge regarding the sensibility of the input to this task is available.

EXAMPLES

Parse a line from an electronic observing log and rename a FITS image read back from tape (and in the header of which no IRAFNAME keyword is present):

    rj> cparse ("a0061.fits: NGC4594      B  300s -01:32:15 1.324",
          delim=":", nsel=1, verbose+) | scan(s1)
    rj> cparse ("a0061.fits: NGC4594      B  300s -01:32:15 1.324",
          delim=" ", nsel=2, verbose+) | scan(s2)
    rj> cparse ("a0061.fits: NGC4594      B  300s -01:32:15 1.324",
          delim=" ", nsel=3, verbose+)
    B
    rj> imcopy (s1, s2//cparse.cfield//".fits", verbose+)
    a0061.fits -> NGC4594B.fits

Note, that the multiple space characters are collapsed in the second and third commands below because 'mignore = yes'. In the third command we might have turned off the 'verbose' switch to suppress printing "B" to the standard output. Although the input string to parse in this example is given explicitly, normally it would be a string-valued variable obtained through some other means (e.g., 'fscan' or 'rjtools.rdlist') that is passed to 'cparse'.

REVISIONS

CPARSE v2.10, Apr 23 1996 [R.A. Jansen]

Original fixed 15-field version of this task; IRAF 2.10.4

CPARSE v2.11, Jun 28 2000 [RAJ]

Added option to select a specific field by giving its field number; IRAF 2.11.3

CPARSE v2.12, Jul 29 2003 [RAJ]

Complete revision of this task: did away with the fixed fields and increased flexibility. There no longer is any limitation on the number of fields, and ignoring of leading and embedded multiple delimiters can be switched on and off separately. For backward compatibility with some user tasks, the original 15-field version is still available as 'ocparse'; IRAF 2.12.1

BUGS

Strings containing parentheses, "(" or ")", may result in an error:

    "ambiguous parameter `' within `<searchpath>'"

Escaping the parenthesis with a back-slash ("\") tends to solve this problem.

[RAJ 24-Apr-2004] In the case that delim="[" and in the input text string the "[" is preceded by a space " ", the fields are not properly terminated, giving a result string containing concatenated fields. Still need to resolve this bug...

SEE ALSO

fields