diff options
Diffstat (limited to 'funtools/doc/pod/funvu.pod')
| -rw-r--r-- | funtools/doc/pod/funvu.pod | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/funtools/doc/pod/funvu.pod b/funtools/doc/pod/funvu.pod new file mode 100644 index 0000000..528ea50 --- /dev/null +++ b/funtools/doc/pod/funvu.pod @@ -0,0 +1,404 @@ +=pod + +=head1 NAME + + + +B<Funvu: database View support for tables> + + + +=head1 SYNOPSIS + + + + + +This document contains a summary of the options for utilizing +database-inspired Views of tables. + + + +=head1 DESCRIPTION + + + + + +B<Database Views> + +In database parlance, a B<View> defines a "virtual table", i.e., +a description of row and/or column selection filters (but with no +permanent storage space allocated). When used in place of a table, a +View selects the specified rows and/or columns from one or more real +tables. Views enable users to see complicated data tables in a more +convenient format. They also can be used as a security mechanism, by +restricting user access to specific columns and/or rows. [See: +http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm +for a good discussion of SQL Views.] + + +Funtools supports an expanded notion of Views for all tabular data +(FITS tables, raw binary tables, and ASCII column files). Funtools +Views allow you to pre-set values for the filter specification, the +columns to activate and display format (though the latter is for +fundisp only). Setting the filter and column activation values +provides functionality equivalent to that of a classical database +View, while the ability to set the format is similar to classical +report writing capabilities. + +B<Funtools View Attributes> + +A Funtools View consists of one or more of the following attributes: + + column description + ------ ----------------------------- + view name of view + file data file name or template + filter filter specification + columns columns to activate + format fundisp format specification + +All of the attribute columns are optional, including +the B<view> name itself. This means that a View can be named or +unnamed. Unnamed Views can refer to a specific file or a template of +files (obviously if neither the view or the file column is specified, +the input View specification will never be used). You can specify any +combination of filter, column, and format parameters. (It also is +possible to apply file-specific View to other files; see the discussion +on B<View Lists> below). Each column has a size limit of 1024 characters. + + +For example, consider the following View database: + + view file format columns filter + ---- ---------------------- ------ ------------ ------- + x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 + x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1 + x1 ${HOME}/data/snr.ev cir 512 512 .1 + x1a ${HOME}/data/snr.ev x y pi pha + x0 ${HOME}/data/snr.ev + xf I=%4d + xc x y pi pha + xr cir 512 512 .1 + *.ev x y pi pha + *.fit x y dx dy cir 400 400 3 + *.fits I=%3d x y dx dy cir 400 400 3 + +This database example is in rdb format, i.e. using tab delimiters and +permitting null values. Any valid ASCII table format is acceptable, +but if you use a format that does not permit null values, it will be +necessary to quote the null strings. + + +The first five entries (x3, x2, x1, x1a, x0) are named entries defining +default values specifically for the snr.ev data file. Typically, you +would use these Views by specifying View name, and the corresponding +file, filter, column, and format values would be used. Note that the x0 +View is essentially an alias for the pathname of this file. + + +The next three entries define defaults that can be applied to any +file. Here, you typically would use these View names in conjunction with +a specific file name (see B<View Lists> below) so that the associated +parameter(s) were applied to that file. + + +The last three entry in the database define unnamed Views that +pertains to all files ending with the specified templates. In these +cases, any View that specifies a file name matching the file template +would be processed with the associated parameter attributes. + +B<Invoking a Funtools View (in Place of an Input File)> + +To specify a Funtools View, pre-pend the "v:" prefix to a View name or +a file name where an input file name usually is specified. For example: + + fundisp v:x3 + +specifies that the View named x3, its file name and associated +parameters, be processed as the input file to fundisp. Using the +example database, above, this is equivalent to: + + fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" + +That is, the format is used with fundisp's -f (format) switch, while the +filename and extension are composed of the x3 View's filename and +region filter. + + +Similarly, executing a command such as: + + fundisp v:foo.fit + +will match the unnamed View associated with the template "*.fit". +This is equivalent to executing: + + fundisp foo.fit'[cir 400 400 3]' "x y dx dy" + +Of course, if you omit the "v:" prefix, then no View processing takes place: + + fundisp foo.fit # process foo.fit without any View parameters + fundisp x3 # error (assuming there is no file named x3) + + +B<Basic View Matching Rules> + + +When a "v:" prefix is recognized, Funtools searches for a View database +file in the following order: + + location description + ------------ ------------------------------------ + FUN_VIEWFILE environment variable (any file name) + ./.funtools.vu hidden file, default name + $HOME/.funtools.vu hidden file, default name + +The first View database file located is used to construct a new +filename, as well as an activation column specification and a format +specification. The following rules are used: + + +1. An attempt is made to match the input name (i.e. the part of the +input View after the "v:" prefix) against the B<view> column value +(if present) of each row in the database. If a match is found, the +values of all non-blank columns are saved for later use. Also note +that the first match terminates the search: i.e. the order of the +database rows does matter. + + +2. If no B<view> match is made, an attempt is made to match the input +name against the B<file> column value (if present). Matching is +performed on the full pathname of both the input name and the +database file name, and on the non-directory (root) part of these +files. This means that the root specification: + + fundisp v:snr.ev + +will match a row in the database that has a full pathname in the file, +allowing you to use a B<file>-matched View without having to +specify the full pathname. In this example, the "v:snr.ev" View +specification will match the first row (v:x3) in the database: + + x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 + +even though the row contains a fully qualified pathname as the file +value. Once again, values of all non-blank columns are saved, and the +first match terminates the search. + + +3. If neither a B<view> or a B<view> match has been found, +then a simple template is attempted against the B<view> +values. The template matching supports a simplified version of file +globbing (not a regular expression), with support for a single "*" +(all characters), "?" (single character), or "[...]" (range) specification. + + +4. If no template match was found on the B<view> column, then a +simple template match is attempted against the B<file> columns. + + +5. If no match is found, then the filename (minus the "v:" prefix) is +returned. + +B<More on View Matching Rules: Single vs. Multiple Matches > + +The matching rules described above stop after the first match, +regardless of whether that match provides values for all three +parameters (filter, columns, and format). In cases where a B<view> +or B<file> match does not provide all three values, it is possible +that a template match might do so. With regard to the example View +database above, the x1 View provides only a filter, while omitting +both the format and columns values. But note that the final rows in +the database could provide the values via a template match on the +filename. This sort of multiple matching is especially valuable in +order to provide "global" values to several Views. + + +Obviously, multiple matching might not be wanted in every +case. Therefore, we support both multiple matching and single matching +according to the value of the FUN_VIEWMATCH environment variable. If +the FUN_VIEWMATCH environment variable exists and if its value begins +with "s", then a single match is used and missing parameters are not +filled in with subsequent template matches on the file name. That is, +matching rules above are followed exactly as explained above. If the +value of this environment variable begins with "m" (or does not exist), +then multiple matches are used to try to fill in missing parameters. +In this case, template matching always takes place and missing values are +taken from these template matches. + + +Thus, in the example above, the View specification: + + fundisp v:x1 + +will take the file name and filter value from the x1 View: + + x1 ${HOME}/data/snr.ev cir 512 512 .1 + +The column value then will be taken from the "*.ev" file template match +against the x1 file name: + + *.ev x y pi pha + +Note once again that order is important: missing values are taken in the +order in which the template matches are processed. + +B<View Lists: Applying a View to Any File> + + +It is possible to apply a named View, or even several Views, to any +data file by appending a B<viewlist> immediately after the standard "v:" +prefix. A viewlist takes the form: + + :v1,v2,...vn: + +where v1, v2, etc. are named Views. The two ":" colon characters surrounding +the list are required. Thus, the syntax for applying a viewlist to a file is: + + v::view1,view2,...viewn:filename + +Note that the name after the last ":" is assumed to be a file; it is +not permissible (or sensible) to use a View name. + + +For example, the View specification: + + fundisp v::x2:foo + +applies the x2 View to the file foo (even if there is a View named foo) +and (in using our example database) is equivalent to: + + ./fundisp foo'[cir 512 512 .1] "x y pi pha" + +The same command can be effected using a list of Views: + + fundisp v::x1,x1a:foo + + + +What happens if a viewlist is used and the file also matches a +template? Consider, for example, this View specification: + + fundisp v::x2:foo.fit + +Here, the x2 View will supply filter and column values, while the +template *.fit can also supply (different) filter and column +values. In this case, the explicitly specified Views of the viewlist +trump the matched view values. + + +On the other hand, if a file template match can supply a View value +that is not supplied by the viewlist, then that value will be taken +from the file template match. For example: + + fundisp v::x2:foo.fits + +does not explicitly supply a format value, but the file match on *.fits +can and does. You can avoid supplying missing values using file template +matching by replacing the first ":" with a "-" in a viewlist +specification: + + fundisp v:-x2:foo.fits + +The use of ":+" to explicitly allow file template matching is also +supported, but is the same as the default case. Note that the nuances +of viewlist support are subject to change as our experience and +understanding grows. + +B<Overriding Values Associated with a View> + + +To override values associated with a View, simply supply the override +values in the correct place on the command line. For example, given +the example database described above, the command: + + fundisp v:x3 + +specifies that the View named x3, along with its file name and +associated parameters, be processed as the input file to fundisp in +this way: + + fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" + +To override one or more of these values, simply specify a new value +for the format, filter, or columns. For example, if your input View file +contains a filter, then the View will use that filter as an override +of the View filter: + + fundisp v:x3'[cir 400 400 3]' + +will use the columns and format of the x3 View but not the x3 filter. Further +examples are: + + fundisp v:x3 "x y dx dy" # activate a different set of columns + fundisp -f "I=%3d" v:x3 # use a different format statement + + + +Note that extension names, extension index values, and other +non-filter specifications B<do not> override the View +filter. Thus: + + fundisp v:foo.fit[3] + +will still use the filter associated with the .fit template (see above), since +the "3" is an extension index, not a filter. + +B<Environment Variables> + +The following environment variables are used by Funtools Views: + + +=over 4 + + + + +=item * + +B<FUN_VIEWNAME> + + +The B<FUN_VIEWNAME> environment variable specifies the +name and location of the View database file. If not present, the +files ./.funtools.vu and $HOME/.funtools.vu are searched for, in +that order. + + + +=item * + +B<FUN_VIEWMATCH> + + +The B<FUN_VIEWMATCH> environment variable specifies whether a +single match or multiple match algorithm is used to locate parameter +values. If the value of this environment variable begins with "s", +then a single match is used and missing parameters are not filled in +with subsequent template matches on the file name. If the value begins +with "m", then multiple matches are used to try to fill in missing +parameters. The default is to use multiple matches. + + +=back + + + +B<Restrictions and Problems> + +Support for overriding a filter (while not overriding extension names, +extension indexes, etc.) requires that we can sense the presence of a +filter in a bracket specification. It is unclear yet whether our +algorithm is perfect. + + +Go to Funtools Help Index + +Last updated: January 3, 2006 + + + + + +=cut |