7 Group Expressions

 7.1 Indirection
 7.2 Modification
 7.3 Groups of Data Files
 7.4 Examples

Several of the POLPACK applications have parameters which are described in appendix A as being associated with groups (or lists) of objects. For instance, the POLKA parameter “IN” specifies a group of input data files, and the POLPLOT parameter “STYLE” specifies a group of plotting attributes. A group expression is the string typed in by the user in response to a prompt for such a parameter. It should identify the members of the required group in any of the following ways:

If the supplied group expression is terminated with a minus sign, the user is re-prompted for another group expression. The objects specified by this second group expression are added to those specified by the first. This re-prompting continues until a group expression is supplied which does not end with a minus sign.

Certain classes of objects have additional features, for instance if the objects are the names of data files, then wild-card characters are allowed in the supplied values (see section 7.3)

7.1 Indirection

It is sometimes convenient to store the strings specifying the objects to be used within a text file. The name of the text file can then be given in response to a prompt for a group expression, rather than giving a long list of explicit values. This is done by preceding the name of the text file with an up-arrow (“^”) character. For instance, the group expression “^style.dat” would result in the file style.dat being opened and the strings read from the file. Each line within the file is considered to be a group expression, and is processed in the same way as a group expression supplied directly. In particular, a text file may contain references to other text files. If the file style.dat contained the following two lines:

  grid=1,colour(grid)=red,border=1
  colour(border)=red,^labels.dat

then the strings grid=1, colour(grid)=red, border=1 and colour(border)=red would be returned to the application, and in addition the file labels.dat would be searched for further strings. This nesting of text files can go down to seven levels. Text files may also contain comments. Anything occurring after a “#” character is ignored. To ignore an entire line the # character must be in column 1 (any blanks in front of the # character are considered to be significant).

7.2 Modification

A group of objects can be given by specifying some editing to apply to another already existing group of objects. For instance, if the string new_*b|_ds|_im| was given in response to a request for a group expression, then the following steps occur:

Thus if the existing group contained the strings file1_ds and file2_ds, the resulting group would be new_file1_imb and new_file2_imb. Note, this facility is only available if the parameter description identifies an existing group which will be used as the basis for the modified strings.

7.3 Groups of Data Files

If a group expression is used to specify a list of input data files, then file names may be specified which contain wild card characters (“*” and “?”). These will be expanded into a list of explicit file names before returning the group to the application. Note, group expressions containing wild-cards must be enclosed in quotes if they are supplied on the command line (this prevents the shell from expanding the wild-cards itself).

If the final character in a group expression is a colon (:), then a list of the data files represented by the group expression (minus the colon) is displayed, but no data files are actually added to the group of files to be processed. The user is then re-prompted for another group expression. Note, this facility only applies to group expressions representing existing data files, not data files which are to be created by the application.

If an HDS container file9 is supplied which contains two or more NDF structures, then each NDF within the container file is processed as a separate image. NDFs which are contained within an extension of another NDF are not included.

If a group of output NDFs are created by modification of a group of input NDFs (i.e. if the supplied string includes an asterisk), then the structure of each output container file will be copied from the corresponding input container file. For instance, if the container file o66_int.sdf contains 16 NDFs in components I1 to I16, then specifying “o66_int” when asked for a group of input images will result in all 16 NDFs being used. If the corresponding output images are specified using the string “*_A” then a single output file named o66_int_A.sdf will be created. The structure of this file will be copied from the input file, and will therefore contain the 16 output NDFs in components I1 to I16.

7.4 Examples

Group expressions can be used to specify objects other than data files. For instance, if an application asks for a group of pixels to be specified by their X and Y pixel indices, then the pixels (10,11), (21,-10) and (0,0) could be specified in any of the following ways:

(1)
  10,11,21,-10,0,0

This gives the indices as a comma separated list.

(2)
  10,11-
  21,-10-
  0,0

Ending each line with a minus sign causes the user to be re-prompted for more values.

(3)
  ^pixels.dat

The file pixels.dat is read. The file could contain the following four lines:

(4)
  #  Approximate star centres.
  10,11
  21,-10
  0,0

9HDS container files can usually be identified by the fact they have a file type of .sdf. They can be used to store one or more standard Starlink NDF structures.