YUME(1) User Manuals YUME(1)
NAME
yume - Easy menu system with mouse-over user commands, for X Window
System, based on xforms library
SYNOPSIS
yume [commands] [-bu] [-do] [-dl] [-ex] [-at geometry] [-in file] [-iv
value] [-la label] [-ti title] [-de valpair] [-bd buttondata] [-bw
widthcodes] [-Y[adeilnotuvwx]] [-Y<d>]
DESCRIPTION
yume creates and runs a menu based on the arguments it's given. The
items (commands and switches) shown in the synopsis may appear in any
desired order to create a particular menu. Description of yume is con-
tinued below, following a brief continuation of SYNOPSIS.
SYNOPSIS, continued
This section gives an overview of option sequences, in a form less
terse than above. For full details and examples, please see the
OPTIONS section below.
-at geometry
Specifies menu window geometry in widexhigh+xo+yo or similar
form
-bd buttondata
A future option
-bw widthcodes
Use letters of widthcodes to control button widths
-bu c1 c2 ...
Creates row of buttons labeled c1, c2, ... that do commands c1,
c2 ...
-bu -la l1 c1 -la l2 c2 ...
Creates row of buttons labeled l1, l2, ... that do commands c1,
c2 ...
-do c1 c2 ...
Creates do-groups (editable command boxes) in two-line form,
that do commands c1, c2 ...
-dl c1 c2 ...
Creates do-groups in one-line form, that do commands c1, c2 ...
-ex Creates an exit button in current row of buttons
-in file
Loads options from file
-iv ival
Set up a value-field (a button-plus-textbox unit) for a shell
variable, initialized with ival.
-la svar -la blab -iv ival
Set up a value-field for shell variable svar, initialized with
ival, and no-command button labeled blab.
-la cmd -la svar -la blab -iv ival
Set up a value-field for shell variable svar, initialized with
ival, and button labeled blab for command cmd.
-la label
Specifies a label. More precisely, pushes label onto a stack of
text values.
-ti title
Specifies window-name for the menu window
-de valpair
(where valpair is of form name:value) changes an attribute value
such as text size or color
-Y[adeilnotuvwx]
Aliases for all the other options
-Y<d> Set debug options. Eg, if S is a set of yume options, the com-
mand yume -Y7 S -Y8 will display options as yume processes them
and builds a menu form, and commands as they are executed.
DESCRIPTION, continued
yume creates and runs a menu based on the arguments it's given. The
items (commands and switches) shown in the synopsis may appear in any
desired order to create a particular menu.
For example,
yume -bu date ls -ex &
creates a menu window with three buttons, labeled date, ls, exit (left
to right); while
yume -bu ls -ex date &
creates a menu window with three buttons, labeled ls, exit, date (left
to right). For these examples, clicking a button labeled 'date' runs
the date command and displays the result in the terminal window where
yume started; clicking an ls button runs an ls command for the direc-
tory current when yume started; and clicking an exit button closes the
menu window.
Created menus may consist of a mix of buttons, "do-items", and "value-
fields", created via -bu, -ex, -do, -dl, and -iv options.
A do-item is a unit with two buttons (labeled "EE" and "do:") and a
command-editing box. If you click the do: button, the command list in
the editing box will be performed. If you change the text in the edit-
ing box, the new command will be performed the next time you do: it. A
value-field is a unit with a command, a shell-variable name, a label,
and a text-editing box. The text in the box can be used elsewhere in
the menu by shell-variable substitution, as described below for the -iv
option.
For example,
yume -do 'ls -al' 'cal -3' &
creates a yume menu window with two do: items. Clicking the do: button
of the top item runs the command "ls -al". Clicking the other do: but-
ton runs the command "cal -3". Clicking the EE button of a do: item
will cause its EE button and do: button to turn red to indicate that
"entry execution" has been turned on. When you move the mouse onto
such a do: button, its command list will be run right then, no click
needed. (If you move the mouse cursor onto an EE-enabled do: button
and click it, the command list will get executed twice -- once for the
entry, once for the click.)
Note, red is the color used to signal EE-enabled if you haven't changed
default settings. In the following example, the EE-action do: button
color is cyan:
yume -de ddRolCol:CYAN 'ls -al' 'cal -3' -ex
(This menu has the same two do: items as before, plus a button labeled
"exit". yume starts out in -do, not -bu, mode; and -ex automatically
turns on -bu mode.)
The command-editing box may contain several commands, separated by
semicolons or other shell conventions. For further explanation, see
"[commands]" in the next section.
Throughout this document, the term "parameter-required switch" refers
to any option-switch that requires a parameter value-string. Parame-
ter-required switches include -at, -bd, -bw, -de, -in, -iv, -la, and
-ti. If you leave out a parameter value-string after such a switch,
yume will treat another option or a command as a parameter value-string
or will quit with an error. Example: "yume -la D -bu date" will (cor-
rectly) make a button labeled D, with command date, while "yume -la -bu
date" will make a do-group with command date. Example: "yume -la" will
display a missing-argument error.
OPTIONS
-at geometry
Specify menu-window location and size, with a geometry string of
one of the following forms:
widexhigh+xo+yo
widexhigh+xo-yo
widexhigh-xo-yo
widexhigh-xo+yo
where wide, high, xo, and yo are integers that specify numbers
of pixels, in the usual X Window System -geometry manner. The
user can move and resize the menu-window, after it appears,
using ordinary window-manager controls. (See 'COMMENTS: -at'
section.)
For example, either of these:
yume -at 99x99-44-33 -ex
yume -ex -at 99x99-44-33
produces a 1-button box, labeled exit, near the lower right cor-
ner of display.
If the parameters to yume do not include an -at option, the
menu-window size will depend on sizes of labels and commands,
and it will be placed by window-manager rules.
-bd buttondata
Specify button options to apply to subsequent buttons until
other options are set. When a -bd parameter is encountered, all
of the -bd-controlled settings are cleared, and new values are
set based on specified buttondata. [TBA]
-bu Select button mode and start a new row.
The general idea is that the commands and switches following a
-bu, up until another -bu or a -do appears, will form one row of
the menu. For each command after a -bu, yume will store the
command while processing parameters; will compute button sizes
while preparing the menu; and will perform the command when the
menu is used. In more detail ---
While parameters are being processed: If the label stack is
empty, push the command onto it for use as a button label. Get
a label from the label stack. Make an items-list entry with the
label and command and data from earlier -de and -bd parameters.
If -Y<d> has turned on ShoParProc, print out the command and
some related data.
While menu is being prepared: Compute size of button, based on
natural size of label text, or on a specified width code, and on
scaled size of row. If -Y<d> has turned on ShoAddObj, print out
size of button for command.
While menu is being used: If -Y<d> has turned on ShoAssert,
print button data whenever it's clicked. If -Y<d> has turned on
ShoWExp and the button action uses wordexp, report results of
each use. Execute the command as described in "[commands]".
-bw widthcodes
Set specific button widths, or width ratios. The i'th letter of
widthcodes specifies a size for i'th buttons in a row, left to
right. If a row has more buttons than widthcodes has letters,
widths are calculated (as below) for excess buttons. Natural
row width for a menu is the maximum sum of button widths in one
row. If a -at parameter sets overall menu size, buttons are
scaled proportionately to their natural widths, within each row.
A -bw setting is effective forward from where it appears, until
end of parameters or another -bw occurs.
Width codes are letters, a, b, c,...z, that stand for widths of
3, 6, 9,...78 "M" letters in the button-label font. For exam-
ple: "-bw dc" says that in a row of two buttons, the left button
size will accomodate 12 M's, and the right, 9 M's. If some fol-
lowing rows have more than two buttons, the widths of buttons
after the first two will be calculated as described in the next
paragraph.
If no -bw setting occurs among yume parameters, yume will com-
pute button widths based on the sizes of the text strings that
label the buttons, plus a margin, plus quantization rounding up.
This is adequate for small or casual menus. If you create a
large menu with unpredictable sizes of items, you may wish to
influence yume's automatic sizing by changing buxMargin or
buQuanta; see, for example, examples/example-starter3 and its
.txt file. In short, "-bw widthcodes" lets you set up fixed
widths of buttons -- or, at least, ratios of widths -- fairly
easily.
Two widthcodes apply to each -iv value-field -- one for the
label button, one for the edit-box. Three widthcodes apply to
each -dl entry -- one for the EE button, one for the label but-
ton, and one for the command edit box.
Examples: See examples/button-widths, which creates three menus
using "-bw dc" and "-bw bbba" to illustrate -bw usage. In menus
1 and 3, note that 12 M's and 9 M's completely fill left and
right buttons. In menu 2, the last two buttons of the last row
have calculated widths. Those widths, added to the -bw widths
of the first two buttons, make the natural width of menu 2 more
than that of menus 1 and 3. Note that the first two buttons of
the last row of menu 2 are of exactly the same width (~58mm and
43mm resp.) as the button pairs in the other menus.
Note, -bw processing does not check whether widthcodes are lower
case letters; it merely uses the low 5 bits of each character
it's given. For ASCII characters, -bw 43 has the same effect as
-bw dc. See e.g. examples/calc-wrap2, which egregiously cre-
ates eight menus, with -bw settings identified in menu-window
title bars.
[commands]
Parameters that are not option switches (and not part of a
parameter-required switch, -at, -bw, -de, -in, -iv, -la, or -ti)
are stored as commands to be performed when the user desires.
Rev.23 yume has three ways of storing commands: -bu, -do, -iv.
In -bu mode, the command is represented by a labeled button, and
will be performed when the user clicks the button. In -do mode,
the command is represented by a do: item, as described earlier.
It will be performed when the user clicks the Do: button, or if
EE-enabled is on, when the user moves the mouse onto the Do:
button. A -iv command will be performed when the user clicks
the labeled button next to a value-edit-box.
In all modes, command lists are executed the same way. Usually
this way is analogous to "execl("/bin/sh", "-c", "commandlist",
0) in a forked copy of yume. See 'COMMENTS: Commands' section
for other ways commands can be performed: with %% or %# command
echoing for shell-command testing or debugging; %+ or %- non-
forked; and %- or %: non-SHELL.
Basically, command lists that don't begin with % are sent to a
shell, where they are treated much like ordinary shell commands.
Output from command execution appears just as output from yume
would appear; for example, on the terminal window where yume was
started. If yume output is redirected, so is command output,
unless the executed command list has redirection of its own.
For example,
yume ./abc ./def "./ghi > u" > t &
directs output from programs abc and def to file t, and output
from program ghi to file u. See examples/abc-def-ghi for a
slightly-extended version of this example; when you click the
abc or def buttons, output is fed to t, as you can see after the
command finishes, or while it is running by clicking the 'cat t
to stderr' button. As stderr is not redirected, its output will
appear on the terminal where the example is started.
-de valpair
Decode valpair to change one of yume's default attribute values.
In a previous example, -de was used to change the color of the
EE-action do: button to cyan:
yume -de ddRolCol:CYAN 'ls -al' 'cal -3' -ex
The general form of a valpair is: wacwvwvwv... where each let-
ter represents a character string. w is optional whitespace, a
is an attribute name, c is a colon or other non-attribute char-
acter, v is a value. Whitespace consists of spaces and tabs.
Values can be numbers or xforms-related constants (see lists
below). If multiple values appear, they are combined using OR.
With some whitespace added (thus requiring quotes) and using '='
rather than ':' after the attribute name, the above example
could read:
yume -de ' ddRolCol= CYAN ' 'ls -al' 'cal -3' -ex
In Rev.23 yume, attribute names are BuDef, to set default button
type; buAltCol, buBoxCol, buTxtCol, buTxtSiz, buTxtStyl, buxMar-
gin, and buyMargin to set alternate color, box color, text
color/size/style, and x,y margins of buttons; buQuanta to quan-
tumize button width; ddAltCol, ddPshCol, ddRolCol, ddTxtCol,
ddTxtSiz, and ddTxtStyl to set similar attributes of Do:
buttons; doBoxCol, doTxtCol, doTxtSiz, and doTxtStyl to set
attributes of command-editing boxes; eeAltCol, eeBoxCol, eeTxt-
Siz, eeTxtStyl, eexMargin, eexOffset, eeyMargin, and eeyOffset
to set attributes of EE buttons; lvTxtCol, lvTxtSiz, lvTxtStyl,
and lvBoxCol, for setting attributes of -iv buttons; and
ivTxtCol, ivTxtSiz, ivTxtStyl, ivAltCol, ivBoxCol, and ivBoxTyp,
for setting attributes of -iv edit-boxes. Concise lists of con-
stants known to yume appear in yume-initV.h, which program yume-
def-init creates.
Recognized constant values for setting BuDef are BuFix, BuHid,
and BuVar.
Color constant values are: BLACK, BLUE, BOTTOM_BCOL, CHARTREUSE,
COL1, CYAN, DARKCYAN, DARKER_COL1, DARKGOLD, DARKORANGE, DARK-
TOMATO, DARKVIOLET, DEEPPINK, DODGERBLUE, GREEN, INDIANRED,
LEFT_BCOL, LIGHTER_COL1, MAGENTA, MCOL, ORCHID, PALEGREEN, RED,
RIGHT_BCOL, SLATEBLUE, SPRINGGREEN, TOMATO, TOP_BCOL, WHEAT,
WHITE, and YELLOW. The value of a constant x in the above list
(and the next two lists) is the same as the xforms constant
FL_x; for example, DARKGOLD == FL_DARKGOLD, HUGE_SIZE ==
FL_HUGE_SIZE, and so forth.
Box-style constant values are: UP_BOX, DOWN_BOX, FLAT_BOX, BOR-
DER_BOX, SHADOW_BOX, ROUNDED_BOX, RFLAT_BOX, RSHADOW_BOX, and
NO_BOX.
Text-size constant values are: HUGE_SIZE, LARGE_SIZE,
MEDIUM_SIZE, NORMAL_SIZE, SMALL_SIZE, and TINY_SIZE.
Text-style constant values are: BOLDITALIC_STYLE, BOLD_STYLE,
EMBOSSED_STYLE, ENGRAVED_STYLE, FIXEDBOLDITALIC_STYLE, FIXED-
BOLD_STYLE, FIXEDITALIC_STYLE, FIXED_STYLE, ITALIC_STYLE, MIS-
CBOLD_STYLE, MISCITALIC_STYLE, MISC_STYLE, NORMAL_STYLE,
SHADOW_STYLE, SYMBOL_STYLE, TIMESBOLDITALIC_STYLE, TIMES-
BOLD_STYLE, TIMESITALIC_STYLE, and TIMES_STYLE. The constants
EMBOSSED_STYLE, ENGRAVED_STYLE, and SHADOW_STYLE are intended to
be OR'd with other values; for example:
yume -de 'doTxtStyl: MISCITALIC_STYLE \
EMBOSSED_STYLE' date &
creates a menu intended to use embossed italics in the command
editing box [but see BUGS section].
The -de option will not recognize abbreviated names. It uses
hash values based on entire names to recognize names. See 'COM-
MENTS: -de' re this.
-dl Turn on -dl mode for following commands. That is, commands
among the following parameters will be put into -dl items, until
a -bu, -do, -ex, or -iv appears.
Briefly, -dl items are treated much like -do items, except are
embedded within a button row, instead of taking two rows as -do
items do.
That is, like each -do item, each -dl item has an EE button, a
do: button, and a command editing box. Each -do item is pre-
sented on two rows of a menu; the upper row has an EE button and
a do: button, while the lower row has a command editing box. By
contrast, the elements of a -dl item are in line within a button
row. A button row can contain any number of -dl items. In the
sequence of commands after a -dl, other -dl switches would be
redundant. For example, these are equivalent:
... -dl c1 -dl c2 ...
... -dl c1 c2 ...
After -do, -dl will start a new row in the menu; after -bu, it
won't. For example,
yume -do -dl c1 -do -dl c2 -do c3 -bu -ex -dl c4&
creates a menu with 5 rows; the first two are -dl items for com-
mands c1 and c2, the third and fourth rows are a -do item for
command c3, and the fifth row contains an exit button and a -dl
item for c4.
-do Start a new row in the menu and turn on do: mode for following
commands. That is, commands among the parameters after -do will
be put into do: items, until a -bu, -dl, -ex, or -iv appears.
By default, yume is in do: mode when it begins parameter pars-
ing.
The general idea of the -do switch is that commands and switches
following it, up until a -bu, -dl, -ex, or -iv appears, will
form do: entries in the menu. A do: entry occupies two rows of
the menu layout; the upper row has an EE button and a do: but-
ton, while the lower row has a command editing box. In the
sequence of commands after a -do before a -bu, -dl, -ex, or -iv
switch, other -do switches would be redundant. Thus, all three
of the following are equivalent, and produce three do: items for
commands c1, c2, c3, in a menu with 6 rows:
yume c1 c2 c3
yume -do c1 c2 c3
yume -do c1 -do c2 -do c3
-ex Creates an Exit button in button mode, labeled from top of label
stack.
In more detail, -ex acts as follows: (1) If -do mode is on, then
turn on -bu mode and start a row of buttons. (2) If label stack
is empty, push "exit". (3) In current row of buttons, pop label
from stack and create a labeled button, with exit-from-yume
action.
-in file
Process yume options from specified file. The file contents
should look very much like an ordinary yume parameter list, with
certain exceptions: (1) In a line that ends with backslash, the
backslash and newline characters are stripped, while in other
lines, a blank replaces newline; (2) Lines that begin with a
number mark (#) are treated as comments and ignored; and (3)
Expansion of unquoted variables occurs when the file is pro-
cessed, as explained below.
After all lines are read in and concatenated, the text is shell-
expanded with wordexp(3) and the result is processed as a yume
parameter list. File-includes may be nested to depth given by
parameter FStackLim, with default value 400 (ie: -de FStack-
Lim:400).
If a user-defaults options-file $HOME/.yumerc exists, it is read
at the outset and treated like other included files, except for
having pride of place and not being mentioned in yume's command
line.
The button label stack can be set up with -la parameters in an
include file and used by buttons generated after that file. But
an include file cannot end with -at, -bw, -de, -in, -iv, -la, or
-ti. That is, if a parameter is required for a switch in an
include file, both the switch and its parameter must be in that
same file.
If your file includes shell-type expressions for file-globbing,
command substitution, or variable substitution, the following
applies: By its specification, wordexp(3) is allowed to fail to
recognize some shell special parameter expressions, such as $0,
$#, and $*. See wordexp(3) and test any cases that are relevant
on your own system. Also see examples/wordexp-vals which uses
"-in wordexp-in" to test the special parameter cases just men-
tioned.
In a script that starts a yume menu with an included file,
"yume" (or a path to it) will be the value of $0, rather than
the script name, because substitution in an included file's text
occurs at yume run time. Of course, in a script one can work
around such issues by setting intermediate variables.
Use -Y1, -Y2, or other -Y<d> options to see some of the pro-
cessed results of including a file. See the "-Y<d>" section for
details.
-la svar -la blab -iv ival
Set up a value-field for shell variable svar, initialized with
ival, and no-command button labeled blab. See -iv val below.
-la cmd -la svar -la blab -iv ival
Set up a value-field for shell variable svar, initialized with
ival, and button labeled blab for command cmd. See -iv val
below.
-iv val
Set up a value-field, initialized with val. A value-field has
an optional command, a name, a label, and an editing box. The
name is a shell-variable name that can be used to refer to the
field's value elsewhere in the menu. The label is text that is
displayed on the label button. If you click the button, the
optional command is executed. The editing box is a small text-
editing window pane, used to change the value of the named shell
variable.
Example: To construct a value-field entry for shell-variable
HIPIX, with label 'Screen Height, Pixels', and initial value of
1024, use: -la HIPIX -la 'Screen Height, Pixels' -iv 1024. To
reference the contents of the value editing field elsewhere in
the menu, quote $HIPIX for substitution at command execution
time. Eg: -do "echo 'Screen height is $HIPIX pixels'".
When you change the text in the edit-box, yume changes the shell
variable that belongs to it, via setenv(name,value,1). If the
value-field setup specifies an empty name, yume instead uses
putenv(value); use text in form "name=value" in the edit-box in
this case. If you have several value-fields with the same name,
the last one specified gives the shell variable its initial
value. That is, yume sets variables as it processes -iv parame-
ters; if a variable belongs to several value-fields, it will be
assigned several times during yume initialization.
If you click the label button next to the edit-box, the optional
command will be executed, in the usual yume manner. The com-
mand, if given, is specified by a previous -la parameter. For
example, the sequence
-la 'svn help $H' -la H -la 'Help Topic:' -iv propget
in examples/svn-buttons uses the first -la to specify a command,
'svn help $H' (single-quoted to avoid early shell substitution
for H); a second -la to specify shell variable H; and a third
-la to specify the label 'Help Topic:' for the button next to
the edit-box. The edit-box is initialized to "propget". If you
click the button when the menu appears, the command "svn help
propget" will be performed, causing svn's help-text about
propget to appear on the console where examples/svn-buttons was
started.
-la label
Push a string value onto the label stack. These values are used
to label buttons and as commands, names and labels for value-
fields. When a label is needed, the stack is popped. Some
examples:
yume -la al date -bu 'ls -al' -ex &
creates a menu with a do: item initialized with command "date";
a button labeled "al", with command "ls -al"; and a button
labeled "exit", with a command that exits from yume.
yume -la al date -bu -ex 'ls -al' &
creates a menu with a do: item initialized with command "date";
a button labeled "al", with command to exit from yume; and a
button labeled "ls -al", with command "ls -al".
If the stack is empty,
yume -la AA -la 'File:' -iv report.t &
creates a no-command value-field for shell variable AA with ini-
tial value "report.t", while
yume -la 'date -r $FF' -la FF -la\
'File to Date:' -iv report.u &
creates a value-field for shell variable FF with initial value
"report.u", and command 'date -r $FF'.
Stack depth is limited by available memory and is not program
limited. The label stack is freed up after parameter process-
ing. An empty stack tells -iv processing to use 'true' as the
-iv button command. That is, when there are enough items on the
label stack, -iv processing will use one of them as a command,
else will default the command to 'true'.
-ti title
Set menu window title to specified title. If yume isn't given a
-ti option, it sets the menu window title to "yume2".
-Y[adefghilnotuvwx]
Each of the two-letter options -Ya ... -Yx indicated by
-Y[aefghinotuvwx] is synonymous with another yume option with
the same second letter. For example, -Ya = -la, -Ye = -de, ...
-Yx = -ex. When it starts, yume converts all of the 2-letter
option codes that it recognizes to -Y. form. It also converts
-geometry, if present, to -Yt. Then it does fl_initial-
ize(&argc, argv, "Yume2", 0, 0) to let xforms interpret any
options that it supports, which are: -fldebug, -name, -flver-
sion, -sync, -display, -visual, -depth, -vid, -private, -shared,
-stdcmap, -double, -bw, -rgamma, -ggamma, -and -bgamma. See
page 250 of xforms manual, section 32.2.
-Y<d> For this option, d is a digit 0...9. The lower 4 bits of d con-
trol 4 parameter and command debugging functions; a function is
turned on when its bit is set, else is turned off.
If you just want to list parameters as they are processed, put
-Y2 at the beginning of the parameter list (or at the point
where you want parameter listing to begin). If you just want to
see commands as buttons are clicked, put -Y8 near the end of the
parameter list.
Briefly:
-Y0 Turn off parameter and command debugging.
-Y1 Use this to list the wordexp result array for %- or
%:-prefaced commands, or for -in expansions.
-Y2 Use this to list parameters as they are processed, for
example if you are having problems with correct levels of
quoting.
-Y3 Like -Y1 plus -Y2
-Y4 Use this to list the objects of the menu form, for exam-
ple if you want to see actual sizes of menu elements.
-Y5 Like -Y1 plus -Y4
-Y6 Like -Y2 plus -Y4
-Y7 Like -Y1 plus -Y2 plus -Y4
-Y8 Use this to print the executed command each time a button
is clicked or has a mouse event. (Or use %% at beginning
of command; see "COMMENTS: Commands")
-Y9 Like -Y1 plus -Y8
In more detail:
-Y1, ShoWExp
List the result array from wordexp expansion for commands
prefaced with %: or %-, or for -in expansions.
-Y2, ShoParProc
List parameters as they are processed. For example,
yume -Y2 -bw ab -ex -la info xwininfo -Y7
prints 4 lines as it processes parameters:
ParProc 0. 2 <-Yw> <ab>
ParProc 0. 4 <-Yx> <-Ya>
ParProc 2. 5 <-Ya> <info>
ParProc 2. 7 <xwininfo> <(null)>
The first of those four lines represents the "-bw ab"
sequence; -bw has been converted to -Yw. In other lines,
-ex -> -Yx and -la -> -Ya. The two numbers in each
ParProc line are item number and parameter number. As
-Yw (from -bw) and -Ya (from -la) each require a parame-
ter, the parameter number increases from 2 to 4 and from
5 to 7 when they are processed. -Yx (from -ex) generated
two items (see next example). Note, -Y7 turns on Y1, Y2,
and Y4 all at the same time; by contrast, "-Y1 -Y2 -Y4"
would turn on -Y1, then turn it off and turn on -Y2, then
turn that off and turn on -Y4.
-Y4, ShoAddObj
List objects as they are added to form. For example,
yume -Y4 -bw ab -ex -la info xwininfo
prints three lines due to -Y4. The first two lines show
the row-beginning BuList item and an Exitor item. The
third line,
AddObj 2. BuGen 39 0 78 30 <info> <xwininfo>
shows that item 2 of the form is a general button with
x=39, y=0, w=78, h=30, label="info", value="xwininfo".
-Y8, ShoAssert
List objects when they are clicked on or have a mouse
event. For example,
yume -Y4 -bw ab -ex -la info xwininfo -Y8
prints the same 3 AddObj lines as the previous example,
and prints a line like the following when the "info" but-
ton is clicked:
AssertET 2. BuGen 39 0 78 30 <info> <xwininfo> L235
"L235" indicates that assertET() was called from line 235
of yume2.c
Note that when a do-group button is clicked, two AssertET
lines will print, one for the button and one for the
edit-box.
EXAMPLES
See example scripts in the yume2/examples directory. The examples
listed below are described in yume-examples(1). The command yume-exam-
ples starts a small menu to display a list of yume examples. On the
list of examples, "Code" and "Note" buttons appear next to the names of
some examples. If you click a Code button, an xterm will appear with
source code of the example. If you click a Note button, an xterm will
appear with a brief description of the example. Pressing q in a Code
or Note xterm will close it. The *.txt files in yume2/examples contain
Note text.
lac - Latest-C script
Make menu to edit / compile / make / run latest C program
lala - Latest-Latex script
Make menu to edit / latex / pdf / view latest .tex file
yume-examples - A menu to start some yume examples
Make menu to start menu to start example scripts, such as lac,
lacc, lacx, lala, find-ls-count, play-sound-delay, url-and-misc,
url-clip ...
COMMENTS: -de
In Rev.23 yume2, some aspects of -de processing that should be position
sensitive are not. For example, button color changes affect all but-
tons, not just to those that follow in the parameter list. This will
be fixed in a later version. Menus with button colors set up front or
in .yumerc won't be affected by the fix, which will entail adding some
property fields in yume's items list.
-de does not recognize abbreviated names. It uses hash values based on
entire names to recognize names. The aim is to keep yume's memory
footprint small (eg 32KB) by using a few small arrays for names and
default values data.
To see current lists of attribute and constant names and their values,
use
yume-def-init -v
To see current compiled-defaults settings of yume, use
yume-def-init -d
Note, yume-def-init writes a file, yume-initV.h, when it runs.
A future program yume-opttest may allow interactive attribute settings
and resource-file writing. For now, if you want to change button col-
ors, sizes, etc. at runtime, -de is the only way.
Perhaps should provide constants for fonts listed in xforms manual: 0
helvetica-medium-r, 1 helvetica-bold-r, 2 helvetica-medium-o, Chapter
3: Defining Forms 28, 3 helvetica-bold-o, 4 courier-medium-r, 5
courier-bold-r, 6 courier-medium-o, 7 courier-bold-o, 8 times-medium-r,
9 times-bold-r, 10 times-medium-o, 11 times-bold-o, 12 charter-medium-
r, 13 charter-bold-r, 14 charter-medium-i, and 15 Symbol.
COMMENTS: -at geometry
yume treats "-geometry" as a synonym for "-at". If a -geometry switch
appears, yume converts it to -at. It does this conversion before it
calls fl_initialize(); hence the user cannot send a -geometry specifi-
cation to xforms.
COMMENTS: Commands
As noted above, most command lists are executed analogously to
"execl("/bin/sh", "-c", "commandlist", 0), in a forked copy of yume.
More precisely, the value of environment variable SHELL is used as the
first parameter, unless the command list begins with a percent sign.
Use of $SHELL has several ramifications:
- SHELL should be defined in yume's environment. If it
isn't, yume probably won't work.
- SHELL probably will be defined by your shell, such that
menu commands will act much the same way when yume runs
them as when you type them at a shell prompt.
- If your shell doesn't support or allow -c, set SHELL to
be the path to a shell that does support -c. Many UNIX
shells, such as ash, bash, csh, ksh, sh, tcsh, and zsh,
use -c to specify a command to a shell.
- If you want to write a filter for menu commands to pass
through, set SHELL to the path to the filter, and make
the filter accept -c as its first parameter, and a raw
command list as its second parameter.
A command list that starts with a percent sign (%) is handled differ-
ently than described above -- it is processed in "meta-mode". See
yume-meta(1) for details. Generally, use meta-mode if you want to
closely control how commands are invoked, or if you want to echo com-
mands for debugging. In brief, if command list begins as shown below
left, it will act as shown below right.
%% Print command on stdout before it is executed
%# Print command on stdout, don't execute.
%+ Exit from yume, execute command.
%- Non-fork, non-SHELL.
%: Non-SHELL.
See examples/date-of-file for examples of the five %x forms shown
above, and see examples/date-of-file.txt for explanation of same.
DIAGNOSTICS, WARNINGS, CAVEATS
This section includes: yume's error messages and error exits; how to
deal with errors in shell commands when you click on buttons; what
environment is available to shell commands; yume interaction with
"script" command; and undesired visibility of parameter lists and shell
history lists.
yume's error messages and exits
Messages as listed below may appear on stderr if any of the fol-
lowing errors occur. This section shows symbolic names for the
numbers that will appear in actual error messages. In revision
19, error names ERR_EXECV, ERR_SEGV, ERR_FILE, ERR_MALLOC,
ERR_MISSARG, ERR_GEOM, ERR_WEXP, ERR_BADET, and ERR_DECODE cor-
respond in that order to numbers 10 through 18. For current
list, see typedef enum {...} ErrorCode, near the beginning of
yume-initA.h.
The yume error number is the numeric result returned to the
shell if a yume error occurs. That is, for error number n, yume
quits with exit(n). In each message, the phrase "at L:n D:n"
shows L, the source-file line number where the error was
detected, and D, the current depth of file-inclusion. Note, no
message appears for error ERR_EXECV.
*** Error ERR_EXECV, execv problem
If a child process started by yume is unable to execv its
command, it uses _exit(ERR_EXECV) to terminate. This has
no effect on yume and no messages are printed.
*** Error ERR_MISSARG at L:n D:n Switch argument is missing for
-Yx
(where x is a letter and -Yx stands for -at, -bw, -de,
-in, -iv, -la, or -ti) An option switch that needs a
parameter was the last parameter in the parameter list or
in an included file. For example,
yume -at
will cause a message like above.
*** Error ERR_BADET at L:n D:n Expected entry type n but have
type n
(where n's are integers). This message should never
appear; if it does, please report the input that caused
it, and the yume version number, to the author.
*** Error ERR_FILE at L:n D:n Unable to open file F
(where F is a filename with path and the n's are inte-
gers) appears if a file specified in a -in option setting
failed to open. The path should start from current
directory or be absolute, and should name an existing
readable file, and any chain of includes should be of
finite depth. For example, "yume -de FStackLim:567 -in
in-test-7" (where in-test-7 is a yume examples include
file that includes itself) will end with a message like
"*** Error 12 at L:476 D:567 Unable to open file in-
test-7"
*** Error ERR_GEOM at L:n D:n Geometry code X not recognized
(where X is a string). This message will appear if the
geometry parameter to -at is not in one of the following
forms:
widexhigh+xo+yo
widexhigh+xo-yo
widexhigh-xo-yo
widexhigh-xo+yo
where wide, high, xo, and yo are integers that specify
numbers of pixels, in the usual X Window System -geometry
manner. (See BUGS re forms like widexhigh+-xo+-yo.)
*** Error ERR_WEXP at L:n D:n wordexp failure n
(where n's are integers) appears if -in or %- or %: com-
mand processing leads to a wordexp problem.
*** Error ERR_DECODE at L:n D:n Lookup error in X
(where X is a string). This message will appear if a -de
string contains an unrecognized constant name.
Dealing with errors in shell commands:
If your command list is wrong or malformed, you probably will
see error messages in the window where yume was started. Some
general techniques for troubleshooting include:
- Try out the command at a shell prompt
- Add temporary echo commands to display command text, or
preface the command list with %% (to echo command list
before execution) or %# (to echo command list, but not
execute it). (See yume-meta(1), examples/date-of-file,
and examples/date-of-file.txt.)
- Or, add -Y4 to the parameter list. See -Y<d> OPTIONS
section.
- Add a temporary -do group with the problematic command
But before you can use those techniques, you need to identify what com-
mand has a problem. Don't depend on line numbers. For an example of
this, run examples/test-y-6; click the buttons, and note that different
lines of the menu, from different lines of the file, give exactly the
same two error messages, attributed to lines 0 and 1.
/bin/bash: -c: line 0: unexpected EOF while looking for matching `''
/bin/bash: -c: line 1: syntax error: unexpected end of file
Because the commands in test-y-6 are so simple, it is no problem to
figure out what is causing the problem there. Just copy the text of
the command you clicked on, eg "echo 'Ok, let's check'", into a shell
prompt. Then the error will be as obvious as it's going to get and you
can quickly resolve the problem. Here, it is that between single
quotes, backslash is literal, ie, the first two quotes quote It\, leav-
ing the third quote dangling.
If the problem is in the command behind a button, you can add a tempo-
rary echo or %%, or a -do group with the same command list, so it is
readily visible and possible to edit while testing. Also, read about
shell quoting in various man pages; for example, see section QUOTING in
bash(1), and in xargs(1) see --null and --delimiter=delim sections.
The --delimiter option in xargs allows you to specify an alternative
character to delimit parameters.
<< re -Y<d> command for debug use >>
Environment of menu commands:
In the usual UNIX scheme of things, parent and child have sepa-
rate environments; the child starts out with a copy of the par-
ent's environment, after which they go their own ways. For
example, suppose process P creates child processes R, S. R and
S start out with their own copies of P's environment. After
that, changes to the environment in any one of the processes has
no effect upon that of the other two.
yume's -iv value-fields allows you to change variables in yume's
environment while yume is running.
yume and script interaction:
script(1) is a unix command to make a typescript of a terminal
session. The sequence
script t
yume ...
will result in file t containing the output of any commands
started from the yume menu, along with other session activity,
and that output will also appear on the terminal. (But t will
not show the yume-invoked commands themselves.) On the other
hand, the sequence
yume ...
script t
will result in file t not containing the output of commands
started from the yume menu, although that output will appear on
the terminal along with other session activity.
Undesired visibility of parameter lists and shell history lists:
On many multiuser unix systems, parameter lists to processes can
be viewed by anyone who enters a ps command. This can be a
problem for you if the commands of your yume menu should be
secret. In such a case, put the commands into a file with an
innocuous name and use the -in switch.
It is common advice to never use SUID shell scripts (that is, a
script one user can run with another's uid). If, against this
advice you make a SUID script for a yume menu, it would be bla-
tantly unsafe to include any -do commands, and probably unsafe
to have any -iv value fields. That is, limit the menu to but-
tons with fixed, hidden command text. This increases the diffi-
culty of a user somehow getting shell access.
If, for whatever reason, you decide to include -do or -iv items
in such a menu, then use chroot to limit file access, and use
history -c to limit its view of past shell commands.
HISTORY
The source file of yume as documented in this man page is yume2.c.
yume2.c began as a translation of Tcl/Tk program yume.tcl into C, using
the xforms API. yume.tcl began as a program called me-me in October,
1997. In December, 1997 it was renamed to yume (a Japanese word that
translates to English as "dream"), and then released for public use in
1998; for example, several early releases appear at
http://yangtze.cs.uiuc.edu/~j-waldby/yume/ . Further notes regarding
translation of yume.tcl to yume2.c, and subsequent development of
yume2.c, appear in the HISTORY section of yume-plan(1).
yume is not related in any way to yum(8), the Yellowdog Updater Modi-
fied, nor is it related to Yume Linux (a 2005 SourceForge project, to
which virtual host yume.sourceforge.net is assigned), aside from pre-
dating both of them by a few years. The virtual host of the yume2.c
yume menu program will, most likely, be yume2.sourceforge.net and its
website http://yume2.sourceforge.net.
yume is a work in progress. Suggestions for improvement requested.
Also useful or ingenious yume scripts or hacks, for addition to yume
examples directory. If you find bugs not shown in BUGS section, please
report them via the yume2 website. [Interim: email to jiw, <j-waldby
at pat7 dot com>]
FILES
$HOME/.yumerc An optional user configuration file for yume default val-
ues. If this file exists, it should be a text file containing yume
option strings to be treated in the same way as an -in file.
INSTALL Not needed after yume is installed, this file explains how to
install yume and how to obtain the xforms library that yume uses to
draw graphics objects on the X Window System screen.
$YI/examples/* Two dozen examples of yume usage appear in the examples
directory of the yume distribution. See yume-examples(1) for details.
ENVIRONMENT
SHELL yume uses the value of environment variable SHELL as the shell
it invokes to perform commands.
Please see section DIAGNOSTICS, WARNINGS, CAVEATS regarding the
environment available to the shell commands that yume runs.
BUGS
-at fails to recognize some valid and useful X geometry forms like
widexhigh+-xo+-yo. No plan to fix -- don't know how to tell xforms to
locate corner of window off-screen.
-bd option not accepted in Rev.24, and does nothing so far. See com-
mented-out part of "-bd buttondata" in man page source file yume.1.
Will be fixed later.
Some -de settings don't work as one would expect from xforms documenta-
tion; for example, embossed, engraved, and shadow text settings don't
appear as such on my system, and result in wrong size or style of text.
To be fixed later.
At Rev.26, %: not working in test-y-4 but ok in date-of-file and
xterms-w-sh examples
date-of-file needs exit button
When pasting a selection from a command-editing box to somewhere else,
three messages like "In handle_clipboard_event [clipboard.c:330]
Unknown target: 265" appear. These are issued by clipboard.c, part of
the XForms library package. To be fixed later. I imagine some event
handler code is needed, but haven't looked at details.
This man page is not yet formatted in compliance with usual man page
conventions. In particular, examples, option codes and file names are
mostly not in proper font or format. To be fixed later.
AUTHOR
James Waldby <j-waldby at pat7 dot com>
SEE ALSO
yume-examples(1),yume-meta(1),yume-plan(1)
Linux $Date:: 2009-04-01#$ YUME(1)