spec

Software for Diffraction

2.4.2.5. - Text Output



print a [, b ... ]
Prints the string value of each argument, adding a space between each string. If the argument is an associative array, each element of the array is printed in a list, as in:
1.FOURC> print mA
mA["0"] = 2 mA["1"] = 0 mA["2"] = 1 mA["3"] = 3 2.FOURC>

If the argument is a data array, the contents of the array are printed in a compressed format, as in:
1.FOURC> array data[64][64]; data[0] = 1; data[1] = 2
2.FOURC> print data
{{1 <64 repeats>}, {2 <64 repeats>}, {0 <64 repeats>} <62 repeats>} 3.FOURC>



eprint a [, b ... ]
As above, except that if an error-log file is open, the generated string will also be written to that file prefixed by the #E characters.

printf(format [, a ... ])
Does formatted printing on the turned-on output devices. format contains the format specifications for any following arguments. See the description of printf() in any C-language manual. Returns true .

eprintf(format [, a ... ])
As above, except that if an error-log file is open, the generated string will also be written to that file prefixed by the #E characters.

fprintf(file_name, format [, a ... ])
Does formatted printing on file_name. All other devices (except log files) are turned off while the string is printed. The specified file is opened, if necessary, and remains open until closed with the close() function.

tty_cntl(cmd)
Sends terminal-specific escape sequences to the display. The sequences are only written to the "tty" device and only if it is turned on for output. The sequences are obtained from the system terminal-capability data base using the value of the environmental variable TERM. The following values for cmd are recognized:


"ho"
Move the cursor to the home position (upper left corner).

"cl"
Clear the screen.

"ce"
Clear to the end of the line.

"cd"
Clear from current position to the end of the screen.

"so"
Start text stand-out mode.

"se"
End text stand-out mode.

"md"
Start bold (intensified) mode.

"me"
End bold mode.

"us"
Start underline mode.

"ue"
End underline mode.

"mb"
Start blink mode. (Note, xterms don't blink.)

"mh"
Start half-bright mode.

"mr"
Start reverse video mode.

"up"
Move cursor up one line.

"do"
Move cursor down one line.

"le"
Move cursor left one space.

"nd"
Move cursor right one space (nondestructive).

"resized?"
A special option that updates the ROWS and COLS variables in the event the window size has changed and returns a nonzero value if the window size has changed since the last call to tty_cntl("resized?").


Returns true if cmd is recognized, otherwise returns false .

tty_move(x, y [, string ])
Moves the cursor to column x and row y of the display, where column 0, row 0 is the upper left corner of the screen. If the third argument string is present, it is written as a label at the given position. The sequences and string are only written to the "tty" device and only if it is turned on for output. Special tty control sequences of the form \[xx], where xx is one of the codes listed for the tty_cntl() function above, can be used with string. Negative x or y position the cursor relative to the right or bottom edges of the screen, respectively. Relative moves are possible by adding ±1000 to x or y position arguments. Both coordinates must specify either relative or absolute moves. If one coordinate specifies a relative move, the absolute move in the other coordinate will be ignored. Please note, not all terminal types support relative moves. Returns true .

tty_fmt(x, y, wid, string)
Writes the string string to the screen starting at column x and row y, where column 0, row 0 is the upper left corner of the screen. The string is only written to the "tty" device and only if it is turned on for output. If string is longer than the width given by wid, the string is split at space characters such that no line is longer then wid. Newlines in the string are retained, however. The function will truncate words that are wider than wid and drop lines that would go off the bottom of the screen. Special tty control sequences of the form \[xx], where xx is one of the codes listed for the tty_cntl() function above, can be used with string. Negative x or y position the cursor relative to the right or bottom edges of the screen, respectively. The function returns the number of lines written.

spec_menu(menu [, modes [, dumbterm]])
Creates an interactive menu from specifications in the associative array menu. The menu can be used for configuring macros and other spec options. The standard spec macros setplot, setshow, mstartup and plotselect all use the spec_menu() function. When the menu is active, the user can use arrow and control keys to navigate the options and edit strings. While waiting for input in spec_menu(), spec will continue to poll hardware and respond to client commands if in server mode, (just as spec does while waiting for input at the main command prompt).

The menu argument is a two-dimensional associative array that completely describes the menu as detailed below. The first index of the array is a number that identifies an item. The second index of the array is a string that matches one of a set of keys that identify an attribute for the item. The value of the array element depends on the key.

The optional modes argument is a single value where each bit can be associated with a menu item. Up to 52 items may have associated bits.

If the number of menu items plus the number of lines needed to display the hints and "info" strings is greater than the number of rows in the terminal window, the menu items will be scrollable. The number of additional lines above or below the visible window will be displayed in the left of the screen. Navigating past the top or bottom will automatically scroll the menu.

If the width of the menu is greater than the width of the window, the menu items will be compressed or scrolled horizontally, to fit the available space.

If dumbterm is nonzero, spec_menu() will not use cursor positioning. Instead, the menu options will be displayed one at a time in sequence and the user will be prompted for a value. In this mode, entering a single - for any response will jump back and prompt again for the previous item in the sequence.

The function will return a possibly modified value for modes, reflecting the user's choices. If the menu is exited with ^C or the x command, the values of the menu items on entry are restored to their starting values.

Each item selected by the first index into the menu[][] array can have various attributes configured via the following string keys placed in the second array index.

The "title", "head" and "subhead" items don't have any other modifiers. All other items require at least a "desc" key. An item with a "desc" key also needs at least one of "bit", "value", "svalue", "!" or "list". The other keys are optional.


"title"
The title for the menu. No further attributes apply to a "title" item. Only one title will be displayed, and it will be displayed at the top of the page.

"width"
The width of the menu. If not specified, the entire window will be used.

"head"
A section header for the menu. It will be preceded by a blank line.

"subhead"
A subsection header for the menu. It will not be preceded by a blank line.

"desc"
A required descriptive text string for each item. The string is displayed when prompting for the value. A null description creates a blank line.

"info"
Optional text that gives a description of the parameter. The "info" text is displayed only when the current item is active. The text will be formatted for width using the rules of the tty_fmt() function. Formatting will work best if there are no embedded newlines in the string.


The value of a menu item is modifiable if at least one of the following five keys is included in the item description.


"bit"
Associates a bit in the modes argument to this item. The element value should be a single bit and each item in the array that has a bit set should have a unique value. The associated bit will be set or cleared in the return value of spec_menu(). Also, a "bit" attribute can be associated with items that have a "value", "svalue", "toggle" or "list" attribute so that such items can be enabled or disabled for editing using the "bit_and", "bit_or" and "bit_not" attributes. Currently, bits 0 through 51 can be used.

"toggle"
Similar to the "bit" key in that the value can be toggled on or off, but there is no limit to the number of such items and no connection to the modes argument. The item's value contains the initial state on entry and the selected state when spec_menu() returns.

"choices"
For "bit" and "toggle" items, provides prompt strings to replace the default YES and NO. The choices are provided in one colon-delimited string, for example, "ENABLE:DISABLE" or "ON:OFF". The choices don't need to be capitalized and can include spaces. The first choice is associated with the value of one and the second with zero.

"value"
Indicates a number value is wanted. Also used to hold the "list" item selection. This item's value will be modified. Not used if the "!" indirection key is present. Note, the number value can be entered as an expression which will be evaluated with the result displayed.

"svalue"
Indicates a string value is wanted. Can also be used to select the current "list" item. This item's value will be modified. Not used if the "!" indirection key is present.

"list"
Presents a list of possible values, only one of which can be selected. The selection is set and returned in "value", "svalue" or indirectly via the "!" key. Use "value" to indicate selection based on position in the list, counting from one. Use "svalue" to indicate selection based on a matching strings. If "!" is used, spec will use a number or string as appropriate. By default, one or more space characters separate the list items. An alternate delimiter character or string can be specified using the "delim" attribute.

"!"
The value of this element contains the string name of a spec variable that is to be modified. If its current value is a number, then the rules for entering number values will be followed. If its current value is a string or the parameter is unset, the string rules will be followed. This key takes precedence over "value" or "svalue" attributes. Names of scalars and associative array elements are allowed, but data array elements are not. If the named variable doesn't exist, spec_menu() will display the variable name and "notfound" as the value.

"format"
Can be used to set an alternative printf() format for display of a number-valued item. For example, "0x%X" can be used to display a value in hexadecimal. In fact, the format can be used to specify the same number value in multiple formats, such as @hex=0x%xdec=%d@. The default format is "%.9g".

"delim"
Provides an alternative delimiter for "list"items. Can be one or more characters. The default delimiter is a space character. When the delimiter is a space character, multiple space and tab characters count as one delimiter. When the delimiter is any other character or string, each instance is a delimiter.

"default"
For "list" items, sets the default choice if the value passed via "value", "svalue" or "!" is invalid or out of range.

"min"
For "value" items, a minimum value to allow.

"max"
For "value" items, a maximum value to allow.


The item types "bit", "value", "svalue", "toggle" and "list" can have the following attributes set to enable or disable the item for editing based on the bit values of other items in the current value of modes.


"bit_and"
Editable if all the matching bits (or bit) are set in modes.

"bit_or"
Editable if any of the matching bits (or bit) are set in modes.

"bit_not"
Editable if the matching bits (or bit) are not set in modes.
Finally, this key applies to bit-toggle items:


"bit_flip"
Flip the YES/NO sense of this item. Normally, when a bit is set in modes, the value is presented as "YES". If "bit_flip" is present, the logic is reversed. This option can be used to avoid double negatives in the query/response, particularly when one doesn't have the freedom to define what a set bit means. For example, "Draw error bars (YES)?" is preferable to "Don't draw error bars (NO)".


On a normal return with the q or ^D keys, spec_menu() will return an updated value for modes that reflects the new values of all the "bit" items. In addition, new values for "value", "svalue" and variables passed indirectly using "!" will be assigned. Finally, for any items that have been modified an element will be added to the *menu* array with a second index named "updated" and a value set to one.

The menu is presented as a list with the cursor positioned at the current value for a modifiable item. The up- and down-arrow keys, the ^P (previous) and ^N (next) control keys and the return key accept the current choice and move up or down the list.

One exits the menu saving the modifications using the q (quit) key or ^D. One can abandon the menu without saving the modifications using the x (exit) key or ^C.

The display is refreshed with ^L, taking into account the current window size.

Bit-value and toggle items are toggled using the space bar or the left- or right-arrow keys. In addition, the y, Y and 1 keys select YES, while the n, N and 0 keys select NO.

List items are also navigated using the left- and right-arrow keys and the ^B (back) and ^F (forward) to move one position. The ^A and ^E keys move to the first item and last item, respectively. Also, typing the first character of a list item will move the cursor to the first item in the list that begins with that character. The space bar makes the currently highlighted item the list selection.

Text entry items (both string- and number-valued) allow insertion and deletion of text from any point in the string. The left- and right-arrow keys and the ^B (back) and ^F (forward) move one position. The ^A and ^E keys move the cursor to the start and end of the entry, respectively. The ^D key and the keyboard forward-delete key both delete forward. The backspace and delete key delete backward. The ^U and ^K keys delete from the current position to the beginning and end of line, respectively.

For number-valued items, the text entered will be evaluated. Thus, expressions are allowed. For example, PI/2, 2+2 or pow(2,12) are all valid entries. Only commands and functions that make sense in the context of generating an expression are allowed. Other commands will not be executed and will generate an error message that will be displayed near the bottom of the menu window. Among the commands not allowed are those that generate screen output or control hardware.

To enter a string that starts with one of the navigation command letters, namely q or x, use one of the text-editing keys, such as left- or right-arrow to switch to text-entry mode.

When items are disabled by way of the "bit_and", "bit_or" and "bit_not" logic, the values appear as ---, and the up/down navigation passes over those items.

The standard spec macros setplot, setshow, mstartup and plotselect use the spec_menu() function.

Here is another example:
def menu1 '{
    local i, menu[], modes
    local   group_size

    modes = 1
    group_size = 512
    menu[++i]["title"] = "Menu Example"
    menu[++i]["desc"] = "Enable List Examples"
    menu[  i]["bit"] = 0x0001

    menu[++i]["desc"] = "  List Example 1"
    menu[  i]["bit_and"] = 0x0001
    menu[  i]["list"] = "Now is the time for all good men"
    menu[  i]["svalue"] = "time"

    menu[++i]["desc"] = "  List Example 2"
    menu[  i]["bit_and"] = 0x0001
    menu[  i]["list"] = "The quick::brown fox::jumps over::the lazy dog"
    menu[  i]["delim"] = "::"
    menu[  i]["value"] = 3

    menu[++i]["desc"] = "  List Example 3"
    menu[  i]["bit_and"] = 0x0001
    menu[  i]["list"] = "128 256 512 1024 2048 4096 8192"
    menu[  i]["@"] = "group_size"

    menu[++i]["desc"] = ""
    menu[++i]["desc"] = "Use logarithmic y-axis"
    menu[  i]["bit"]     = PL_YLOG
    menu[++i]["desc"] = "Force y-axis minimum to zero"
    menu[  i]["bit"]     = PL_YZERO
    menu[  i]["bit_not"] = PL_YLOG

    modes = spec_menu(menu, modes)

    print modes, group_size
'