funview(7)

📦 version 1.4.8, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, welcome to Funview — that's Database View Support for Tables, and yes it's from the SAORD Documentation crowd. it's a section 7 page, iykyk. 🎀

✨ SYNOPSIS ✨

this doc is literally just a big summary of all the options you've got for using database-inspired Views on tables. that's it. that's the whole vibe. 💅

🦋 DESCRIPTION 🦋

Database Views

so in database-speak, a View defines a "virtual table" — like, it's a description of row and/or column selection filters, but with no permanent storage space allocated. when you use it in place of a real table, a View picks out the specified rows and/or columns from one or more actual tables. Views let you see complicated data tables in a way more convenient format. they're also a whole security mechanism, because you can restrict 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 a glow-up version of Views for all tabular data — FITS tables, raw binary tables, and ASCII column files. Funtools Views let you pre-set values for the filter specification, the columns to activate, and the display format (though that last one is for fundisp only, bestie, don't get it twisted). setting the filter and column activation values gives you functionality equivalent to a classical database View, while the ability to set the format is basically classical report writing capabilities. iconic. 👑

Funtools View Attributes

a Funtools View is a text file containing one or more of these columns:

column         description
------         -----------------------------
view           name of view
file           data file name or template
filter         filter specification
columns        columns to activate
format         fundisp format specification

okay so — all of the attribute columns are optional, including the view name itself. which means a View can be named or unnamed. unnamed Views can refer to a specific file or a template of files (and obviously, if neither the view nor the file column is specified, that input View spec will literally never get used, so...). you can specify any combination of filter, column, and format parameters. (it's also possible to apply a file-specific View to other files — peep the discussion on View Lists below for that tea. 🍓) and heads up: each column has a size limit of 1024 characters.

for example, consider this View file:

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, meaning it uses tab delimiters and permits null values. any valid ASCII table format is acceptable, but if you use a format that does not permit null values, you're gonna have to quote the null strings. sorry, that's just the rules. 🙈

the first five entries (x3, x2, x1, x1a, x0) are named entries defining default values specifically for the snr.ev data file. typically you'd use these Views by specifying the View name, and then the corresponding file, filter, column, and format values would be used. also note that the x0 View is essentially just an alias for the pathname of this file. slay.

the next three entries define defaults that can be applied to any file. you typically would use these View names together with a specific file name (see View Lists below) so that the associated parameter(s) get applied to that file.

the last three entry in the database define unnamed Views that pertain 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. periodt. 💅

Invoking a Funtools View (in Place of an Input File)

to use a Funtools View, you simply pre-pend the "v:" prefix to a View name or a file name, right where an input file name usually goes. like:

fundisp v:x3

that says the View named x3 (with its file name and associated parameters) gets 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"

so like — 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. cute. 🎀

similarly, running a command like:

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"

and 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)
bestie. the second one is an ERROR. do not come crying to me. 😭

Basic View Matching Rules

when a "v:" prefix gets recognized, Funtools searches for a View database file in this exact 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 the one used to construct a new filename, plus an activation column specification and a format specification. here are the rules it follows:

  1. an attempt is made to match the input name (i.e., the part of the input View after the "v:" prefix) against the 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 — meaning the order of the database rows matters. 👀
  2. if no view match is made, an attempt is made to match the input name against the 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 the root specification:
fundisp v:snr.ev

will match a row in the database that has a full pathname in the file, letting you use a 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. 💅

  1. if neither a view or a view match has been found, then a simple template match is attempted against the view values. template matching supports a simplified version of file globbing (not a regular expression, bestie, don't @ me), with support for a single "*" (all characters), "?" (single character), or "[...]" (range) specification.
  2. if no template match was found on the view column, then a simple template match is attempted against the file columns.
  3. if no match is found, then the filename (minus the "v:" prefix) is returned.

More on View Matching Rules - Single vs. Multiple Matches

so 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 view or file match doesn't provide all three values, it's possible a template match might do so. looking at 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 for providing "global" values to several Views. ✨

obviously, multiple matching might not be wanted in every case. so 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, the 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.

so 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. no cap. 🔥

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 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. so the syntax for applying a viewlist to a file is:

v::view1,view2,...viewn:filename

and note that the name after the last ":" is assumed to be a file — it is not permissible (or sensible, honestly) to use a View name there. 💀

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 (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

so 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. and in this case, the explicitly specified Views of the viewlist trump the matched view values. 👑

But okay, plot twist 🎀 — if a file template match can hand over a View value that the viewlist itself just... didn't bother to supply, then bestie, that value gets taken from the file template match. Like:

fundisp v::x2:foo.fits

Notice how nobody typed a format value? And yet the file match on *.fits absolutely can supply one, and does. She's resourceful like that 💅.

Now if you want to ✨block✨ that energy and stop missing values from being filled in by file template matching, just swap the very first ":" for a "-" in your viewlist spec:

fundisp v:-x2:foo.fits

The :+ form is also supported for explicitly allowing file template matching — but it's literally the same as the default case, so, no drama there. Just so you know: the nuances of viewlist support are subject to change as our experience and understanding grow. iykyk 🦋

🌸 Overriding Values Associated with a View 🌸

Want to override stuff tied to a View? Easy — just drop the override values in the correct place on the command line. So, given that example database we were yapping about above, this:

fundisp v:x3

says "process the View named x3, along with its file name and associated parameters, as the input file to fundisp", like this:

fundisp  -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]'  "x y pi pha"

To override one or more of those 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]'

That one uses the columns and format of the x3 View but not the x3 filter. More examples, bestie:

fundisp v:x3 "x y dx dy"    # activate a different set of columns
fundisp -f "I=%3d" v:x3     # use a different format statement
Heads up 🫶 — extension names, extension index values, and other non-filter specifications do not override the View filter.

So this:

fundisp v:foo.fit[3]

will still use the filter associated with the .fit template (peep above 👀), because that "3" is an extension index, not a filter.

✨ Environment Variables ✨

Funtools Views is fed by these little icons:

  • FUN_VIEWNAME — specifies the name and location of the View database file. If she's not present, then ./.funtools.vu and $HOME/.funtools.vu are searched for, in that order. 🦋
  • FUN_VIEWMATCH — 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. 💅

💀 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. Not me exposing our own lore 🙈.

Go to Funtools Help Index

Last updated: August 3, 2007

and that's the whole page, bestie!! 🌈 This lil masterpiece is funview(7), living its best life at version 1.4.5, dated April 14, 2011. Take her home, read her often, and go make some Views slay 👑💖✨

📦 where this page comes from