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]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]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
'
