The World of Computer Software/World_Of_Computer_Software-02-385-Vol-1of3.iso/m/msh21.zip/MSHFILES.ZIP/STDHLP.MSH

Text File | 1992-08-19 | 15KB | 316 lines

("cur_action"
"Takes a default action based on the cursored file in the active panel
(i.e., the kind of action that might be associated with pressing
'Enter').  If the cursored file is a directory, the current working
directory (system variable 'cwd') is updated and a 'refresh'
is issued to the active panel.  If the cursored file
is an ordinary file, a variable whose name is 'extension_xxx'
(where 'xxx' is the extension of the cursored file) is executed
via the system primitive '#'.  An action must have previously
been defined for 'extension_xxx' or an error occurs.  The
default definitions for various extension_xxx are in the file
EXT.MSH (documentation EXT.DOC); the user may customize
this by overriding these definitions and/or adding further
definitions in the file CUSTOM.MSH (documentation CUSTOM.DOC).
act_on_cur presumes no previous stack contents and has no net
effect on the stack."normal_message)
("basename"
"[top] = that part of a string that precedes the last dot.  Will be
the entire string if there is no dot within it.

Examples:
if the file FOO.X is cursored in the 'active panel',
current.name basename
puts FOO on top of the stack.
\"my.name.is.sam\" basename
puts my.name.is on top of the stack.
\"hello\" basename
puts hello on top of the stack."normal_message)
("cfg_filename"
"Sets [top] to the concatenation of prog_dir and \"config.msh\"."normal_message)
("cmdlist"
"This is a list which "remembers" all the commands which were executed
via 'execsave'."normal_message)
("confirm"
"At entry, [top] should contain a command which is an appropriate
target of 'execute'.  This command is displayed as a message to
the user, and the user is asked if it is OK to execute the command.
If the user says 'OK' (in effect), the command is executed (with
'execute'), else it is not executed.  In any case, the command
is popped off the stack."normal_message)
("deselect"
"All selected files in the current panel are deselected.  No effect
on stack."normal_message)
("directory"
"[top] = the unit and directory part of a pathname; if the pathname
specifies an ordinary file, the unit and directory part is NOT
followed by a backslash; however, if the unit and directory part
consists of only a unit, the colon is retained.  If the pathname
specifies a directory (see below for criteria), a dot is appended
after its terminating colon or backslash.

The criteria for determining if an ambiguous file-specifier
is an ordinary file or a directory are as follows (and are
NOT the same as the corresponding criteria for 'dirpart'):
If the pathname contains one or more backslashes, the
portion up to the last backslash is a directory specifier.
If the pathname contains no backslashes, it is interpreted
as being a directory name (not the name of an ordinary file).
 Note that while these criteria seem 'wrong', they work out
acceptably if 'directory' is used in its proper context and
'dirpart' is used when it is appropriate.

If the full pathname specifies a directory, a dot is appended, e.g.,
\"a:x\\\" -> \"a:x\\.\"  or  \"a:\" -> \"a:.\"
If the full pathname ends with a file (not directory) specification,
nothing is appended:
\"a:\\x\\y.z\" -> \"a:\\x\" or \"a:\\x\" -> \"a:\"

Note that
\"foo.bar\" directory yields \"foo.bar\".

Generally speaking, use 'directory' (rather than 'dirpart') when
referring on a directory alone, such as in panel operations.

See also 'dirpart'."normal_message)
("dirpart"
"[top] = the unit and directory part of a pathname, followed
by its terminating colon or backslash.

The criteria for determining if an ambiguous file-specifier
is an ordinary file or a directory are as follows (and are
NOT the same as the corresponding criteria for 'directory'):
If the pathname ends with a colon or a backslash, it is a
directory.  Else, it is an ordinary file, even if the only
element of the name other than the unit is PRECEDED by a backslash.

If the pathname specifies a directory, the trailing backslash (if any)
or the trailing colon is retained and nothing is appended:
\"a:x\\\" -> \"a:x\\\"  or  \"a:\" -> \"a:\"
Else the part up to and including the last backslash (if any) or the
colon (if there is no backslash present) is retained:
\"a:\\x\\y.z\" -> \"a:\\x\" or \"a:x\" -> \"a:\"

Note that
dirpart & filepart (in effect) yields pathname whereas
directory & filepart (in effect) does not necessarily yield pathname.

Note also that "foo.bar" dirpart yields "".

Generally speaking, use 'dirpart' (rather than 'directory') when
parsing a pathname into its components.

See also 'directory'."normal_message)
("endsby"
"[top] = true or false depending on whether or not the last character
of [top + 1] = [top].
Note that 'endsby' pops [top] and [top + 1] off the stack.  Hence,
if you want the stack after endsby to look like
[top] = true/false
[top + 1] = string under examination
the proper sequence is:
dup \"ending_char\" endsby
(if you forget the 'dup' the string under examination will
disappear from the stack)."normal_message)
("exec"
"This is a combination of 'execute' and 'reread'; it is
the normal means of executing a program that might add or delete files."
normal_message)
("execsave"
"The variable 'cmdlist' is updated by appending first a newline
and then the current contents of the Mi-Shell command-line (i.e., the
system variable 'cmd').  Then the command-line is executed (via
'execute') and cleared, and a 'refresh' is issued to
the active panel.  There is no net effect on the stack.  Unlike
'exec' or 'execshow', execsave takes its central argument from
the command-line rather than from the pre-existing [top] of the stack."
normal_message)
("execshow"
"Executes a command (using the primitive 'execute'), but before doing
so, flashes a message onscreen for 600 milliseconds that the command
is about to be executed.  No effect on the stack."normal_message)
("extension"
"[top] = that part of a string that follows the last dot.  Will push
false if there is no dot in the string.

Examples:
if the file FOO.X is cursored in the 'active panel',
current.name extension
puts X on top of the stack.
\"my.name.is.sam\" extension
puts sam on top of the stack.
\"hello\" extension
puts \"\" (i.e., false) on top of the stack."normal_message)
("filepart"
"[top] = the file part (name.extension) of a full pathname, or
\"\" ('false') if the pathname contains no file part (e.g., consists
only of a device name).

The file part is that part following (but not including) the
last backslash in the path name (if there are one or more backslashes),
or, if there are no backslashes, everything following the device
name and the colon (if such exists)."normal_message)
("foreachbase"
"Identical to 'foreachselected' except that only the basename of each
file is passed (instead of the full filename) as an argument to
the target command.  (See 'basename')."normal_message)
("foreachselected"
"At entry, [top] is presumed to contain an action which takes one
argument; this action is e.g., intended to be used with an executable DOS
program such as 'DEL' (contrast with loop_panels).

This action is executed for each 'selected' file in the current
panel.  If there is no selected file, the action is executed once
(for the cursored file).

Pushes nothing on stack.

Example:
(\"DEL \" swap & execute false current.selected!) foreachselected
deletes all selected files using the DOS 'del' command, and deselects all."normal_message)

("loop_panels"
"At entry, [top] is presumed to contain an action which takes NO
argument; it is thus intended to be used with a Mi-Shell definition
or primitive, not with an external command such as DIR.  Thus,
in its 'pure' form, loop_panels is used to build other definitions.

The action [top] is executed repeatedly for each file in the
active panel, whether or not the file is \"selected\".

Nothing is left on the stack by 'loop_panels'.

Example:
The following definition ('deselect') is implemented as follows:
((current.selected(false current.selected!)if)loop_panels)deselect!

To use loop_panels for a DOS command such as DEL:
(\"DEL \" current.name & execute) loop_panels
will delete all the files in the current panel."normal_message)
("makename"
"[top] = full pathname constructed from two pieces: a path
(device and/or directory) and a filepart (name.extension).

The correct usage is:
\"directory_part\" \"file_part\" makename"normal_message)
("next"
"The index to the relative file within the current panel ('current.pos')
is advanced by 1.  If, however, it reaches the limit ('panel.nbfiles'),
it is reset to 0.  No impact on stack."normal_message)
("nextcmd"
"Sets the system variable 'cmd' (and thus the display on the Mi-Shell
command-line) to the next command in the circular list 'cmdlist'.
No assumptions are made about the previous contents
of the stack and the stack is not altered."normal_message)
("next_dir"
"[top] becomes the directory portion of panel.pattern for the 'next'
panel after the active panel; see 'directory'."normal_message)
("nl"
"Utility variable whose contents are a newline."normal_message)
("panel_stats"
"Displays a message showing the total number of files in the active
panel and their total size in bytes, same for selected files, and statistics
about disk usage, and waits for a keypress.
No effect on the stack."normal_message)
("prevcmd"
"Sets the system variable 'cmd' (and thus the display on the Mi-Shell
command-line) to the previous command in the circular list 'cmdlist'.
No assumptions are made about the previous contents
of the stack and the stack is not altered."normal_message)
("prog_dir"
"Uses 'dirpart' to extract the device and directory from
which Mi-Shell is being executed; sets [top] to this value.  A trailing
backslash or colon is present."normal_message)
("refresh"
"Refills the active panel with the list of files in the current directory
(limited by 'panel.pattern').  No effect on the stack.  It is wise
to issue this command following any operation which might add or
delete files in the current directory, or following any operation
which might change the current directory reflected in the active panel
(or the selection pattern)."normal_message)
("reread"
"Similar to 'refresh' but less comprehensive; the directory reflected
by the active panel is updated from disk, but no change in the current
directory or selection pattern is reflected.  If the command just
executed might add or delete files, but cannot change the current
directory or the selection pattern, reread is a satisfactory alternative
to refresh (see 'exec')."normal_message)
("reread_next"
"Temporarily selects the 'next' panel after the active panel and issues
a 'reread' to it, then reselects the active panel.  No effect on
the stack."normal_message)
("search"
"[top] is interpreted as a regular-expression file-matching pattern.
The filenames in the active panel are matched with the pattern one
by one, starting at the current cursor position and continuing
circularly until either a file is found whose name matches the pattern
or the search wraps back to the start-point.  No indication is given
as to whether the search was successful; at conclusion [top] still
contains the pattern in all cases.  If it is desired to act only
if the search succeeded, you can code something such as:
\"pattern\" search current.name match (code_if_success)(code_if_fail)ifelse"normal_message)
("selected_list"
"A string is created consisting of the filenames of each selected file,
where each name is separated by a blank, and this string becomes [top].
No command is executed, and the selected files are NOT deselected.

Example:
\"pkzip -a myfile \" selected_list & execute
will add all the selected files to the zipfile 'myfile.zip' using
the 'pkzip' shareware utility.

Note that using selected_list in this manner does not extend the DOS
command line beyond 127 characters (except in the case of The
Berkeley Utilities, which can accommodate long command lines).  Thus,
the above example will not execute properly if more than a few files
are selected.  This is a DOS, not a Mi-Shell limitation."normal_message)
("side_by_side"
"Causes the panels to be displayed side-by-side, with each panel occupying
40 columns.  The active panel is displayed at the leftmost, and remains
the active panel.  No effect on the stack."normal_message)
("time_convert"
"Converts a filedate and time encoded as in the system variable 'current.time'
into a string of the form hh:mm:ss dd/mm/yy, and sets [top] to this string."normal_message)
("unit_and_name"
"[top] = that part of string which follows colon.
[top + 1] = that part of string which precedes colon,
including the colon of this part is not null.
Examples:
\"C:FOO.X\" unit_and_name
puts FOO.X on top of the stack, and C: next.
\"FOO.X\" unit_and_name
puts FOO.X on top of the stack and \"\" (false) next
\"C:\" unit_and_name
puts \"\" (i.e., false) on top of the stack and C: next"normal_message)
("with_magic"
"Causes [top] to be executed with 'magic' temporarily set to 'magic_dir'.
Pops [top] but does not alter the permanent setting of the 'magic'
variable."normal_message)
("with_nomagic"
"Causes [top] to be executed with 'magic' off, regardless of the normal
setting of the 'magic' variable.  Pops [top] but does not alter the
permanent setting of the 'magic' variable."normal_message)
"             some Mi-Shell Standard Definitions

These definitions are all found in the file \"STDDEFS.MSH\" which is
part of the Mi-Shell distribution package.  STDDEFS.MSH is read in
by the default operating environment file \"CONFIG.MSH\".  User-written
operating environment files may at their option include STDDEFS.MSH in the
same manner as does CONFIG.MSH.

If the following definitions are altered, the Mi-Shell kernel will not
be affected, but the standard configured operating environments such
as CONFIG.MSH will become inoperable, and you will have to build
your own configured operating environment.

%cur_action%      %basename%        %cfg_filename%    %cmdlist%
%confirm%         %deselect%        %directory%       %dirpart%
%endsby%          %exec%            %execsave%        %execshow%
%extension%       %filepart%        %foreachbase%     %foreachselected%
%loop_panels%     %makename%        %next%            %nextcmd%
%next_dir%        %nl%              %panel_stats%     %prevcmd%
%prog_dir%        %refresh%         %reread%          %reread_next%
%search%          %selected_list%   %side_by_side%    %time_convert%
%unit_and_name%   %with_magic%      %with_nomagic%    "
() "-1" "-1" "hv:Click or <CR> on standard definition you want help for" temp_menu