Standard Library
Back to library index.
Package std-system (in std.i) - interacting with system
Index of documented functions or symbols:
DOCUMENT after, secs, f
or after, secs, f, arg
of after, -, f, arg
of after, -
Execute yorick statement
F;
or
F, ARG;
when yorick becomes idle, but at least SECS seconds from now.
SECS may be type double to specify fractions of a second.
With SECS = 0.0, this is the same as set_idler, except that
while you may have only a single idler function, you may have
many after functions. F may be either a function (is_func(f)
non-zero), or an oxy object (is_obj(f) non-zero). For example,
after, 0.1, include, ["fma; plg, y, x;"];
can obviously be modified to do anything you want, although you
are probably better off writing a function containing the
executable line, rather than putting it into a string.
As another example,
after, 0.1, object, method;
invokes the object method after a delay of a tenth of a second.
(See help,oxy for more on objects.) If F is an object, and method
is a simple variable reference, the special semantics of object
arguments apply; that is, only the name "method" is significant,
not its value.
In the third form, with the pseudo-index - as the first argument,
cancels the specified after call(s). The ARG, if specified, must
be the same variable, not just the same value. If no ARG is specified,
all pending after callbacks with the given F are cancelled. If
neither ARG nor F is specified, all after callbacks are cancelled.
SEE ALSO: spawn, set_idler, after_error
DOCUMENT after_error = error_handler_func If the variable AFTER_ERROR is set to an interpreted function with no parameters, that function will be invoked after an error, before the next prompt, instead of entering or offering to enter debug mode. The error message will be printed, and also will be stored in the catch_message variable. A fault during the execution of the after_error function will not invoke after_error, but otherwise after_error is persistent (unlike set_idler). An error resets any functions scheduled using after or set_idler, so the after_error function must reschedule these if necessary. The catch function is a more appropriate way to recover from some errors.
DOCUMENT batch, 1
batch, 0
batch()
turns on, turns off, or tests for batch mode, respectively.
If yorick is started with the command line:
yorick -batch batch_include.i ...
then batch mode is turned on, the usual custom.i startup file is
skipped, and the file batch_include.i is parsed and executed. The
-batch and batch_include.i command line arguments are removed from
the list returned by get_argv(). These must be the first two
arguments on the command line.
In batch mode, any error will terminate Yorick (as by the quit
function) rather than entering debug mode. Also, any attempt to
read from the keyboard is an error.
SEE ALSO: process_argv, get_argv, set_idler, after_error
DOCUMENT cd, directory_name
or cd(directory_name)
change current working directory to DIRECTORY_NAME, returning
the expanded path name (i.e.- with leading environment variables,
., .., or ~ replaced by the actual pathname). If called as a
function, returns nil to indicate failure, otherwise failure
causes a Yorick error.
SEE ALSO: lsdir, mkdir, rmdir, get_cwd, get_home, get_env, get_argv
DOCUMENT get_argv() returns string array containing the argv from the command line. The -batch and batch_include.i arguments are removed (not returned).
SEE ALSO: process_argv, cd, get_cwd, get_home, get_env, batch
DOCUMENT get_cwd()
or get_home()
returns the pathname of the current working directory or of your
home directory.
DOCUMENT get_env(environment_variable_name) returns the environment variable (a string) associated with ENVIRONMENT_VARIABLE_NAME (calls ANSI getenv routine).
SEE: get_cwd
DOCUMENT get_path() returns the current include file search path.
SEE ALSO: set_path, get_pkgnames, split_path
DOCUMENT files = lsdir(directory_name)
or files = lsdir(directory_name, subdirs)
List DIRECTORY_NAME. The return value FILES is an array of
strings or nil; the order of the filenames is unspecified;
it does not contain "." or "..". If present, SUBDIRS must be
a simple variable reference, and is set to a list of subdirectory
names (or nil if none). If SUBDIRS is not present (first form),
the return value of lsdir includes both files and subdirectories.
If DIRECTORY_NAME does not exist or is not a directory, the return
value is the integer 0 rather than nil. Hence:
files = lsdir(dirname, subdirs);
if (structof(files) == long) {
directory does not exist
} else {
for (i=1 ; i<=numberof(files) ; ++i) {...use files(i)...}
for (i=1 ; i<=numberof(subdirs) ; ++i) {...use subdirs(i)...}
}
DOCUMENT maybe_prompt Issue prompt for keyboard input if appropriate. This command only makes sense (I think) as the final statement of a function invoked as an idler (via set_idler), when yorick is in a loop with an idler function that continuously re-installs itself. Yorick ordinarily issues a prompt only just before it stops to wait for keyboard input, it will never prompt in this situation, even though it would accept keyboard input if it were typed.
SEE ALSO: set_idler
DOCUMENT mkdir, directory_name
or rmdir, directory_name
Create DIRECTORY_NAME with mkdir, or remove it with rmdir. The rmdir
function only works if the directory is empty. An error is raised if
DIRECTORY_NAME is not a non-nil scalar string. If mkdir or rmdir are
called as subroutines and the operation fails, no error is raised
(so you can use this form even when the directory already exists for
mkdir, or already is missing for rmdir). Otherwise, if
DIRECTORY_NAME is a non-nil scalar string and if mkdir and rmdir are
called as a function, they return an integer: 0 to indicate success and
-1 to indicate failure.
DOCUMENT mkdirp, directory_name Create DIRECTORY_NAME, creating any missing parent directories (like UNIX utility mkdir -p). Unlike mkdir, signals error if the creation is unsuccessful. If DIRECTORY_NAME already exists and is a directory, mkdirp is a no-op.
SEE ALSO: mkdir
DOCUMENT remaining= process_argv()
or remaining= process_argv("your startup message")
Performs standard command line processing. This function is
invoked by the default custom.i file (in $Y_SITE/i); you
can also invoke it from your personal ~/yorick/custom.i file.
The process_argv calls get_argv, removes any arguments of
the form "-ifilename" or "-i filename" (the latter is a pair of
arguments. It returns any arguments not of this form as its
result, after including any filenames it found in the order
they appeared on the command line.
The optional string argument may be an array of strings to print
a multi-line message.
A Yorick package may define the function get_command_line in
order to feed process_argv something other than get_argv.
SEE ALSO: batch
SEE: suspend
SEE: mkdir
DOCUMENT set_idler, idler_function
or set_idler, idler_function, errflags
sets the idler function to IDLER_FUNCTION. Instead of waiting
for keyboard input when all its tasks are finished, the interpreter
will invoke IDLER_FUNCTION with no arguments. The idler function
is normally invoked only once, so input from the keyboard resumes
after one call to the idler. Of course, an idler is free to call
set_idler again before it returns, which will have the effect of
calling that function in a loop.
If present, the ERRFLAGS argument changes the way errors are processed:
0 - default processing, add any combination of:
1 - suppress printing error messages
2 - append [pc] relative program counter to function name in error
message (use disassemble to find corresponding instruction)
4 - call any after_error function in dbug mode (rather than clearing
stack), so it is responsible for calling dbexit
SEE ALSO: batch, maybe_prompt, after, after_error
DOCUMENT set_path, "dir1:dir2:dir3:..."
or set_path
sets the include file search path to the specified list of
directories. The specified directories are searched left to
right for include files specified as relative file names in
#include directives, or to the include or require functions.
If the argument is omitted, restores the default search path,
".:~/yorick:~/Yorick:Y_SITE/i:Y_SITE/contrib:Y_SITE/i0:Y_HOME/lib",
where y_site is the main Yorick directory for this site.
The Y_LAUNCH directory is the directory which contains the
executable; this directory is omitted if it is the same as
Y_SITE.
Only the "end user" should ever call set_path, and then only in
his or her custom.i file, for the purpose of placing a more
elaborate set of personal directories containing Yorick procedures.
For example, if someone else maintains Yorick code you use, you
might put their ~/yorick on your include path.
DOCUMENT process = spawn(argv, on_stdout)
or process = spawn(argv, on_stdout, on_stderr)
starts the process named in ARGV(1) with additional arguments
in any subsequent elements of ARGV (which is a scalar or 1D
array of strings). The ON_STDOUT and optional ON_STDERR
are interpreted functions declared like this:
func ON_STDOUT
commands to process msg on stdout from process
}
Yorick will invoke ON_STDOUT asynchronously if process
emits text to its stdout. Yorick includes the process in
the list of event sources, which it polls whenever it waits
for input. If the optional ON_STDERR is provided, it is
called asynchronously whenever process emits a line to stderr;
with no ON_STDERR, the process will share yorick's stderr,
which generally means the process stderr prints at the terminal.
(Note that you can make the third argument the same as the second
if you want to use the same function to handle stdout and stderr.)
When the process terminates, ON_STDOUT is invoked with
string(0) and the process object becomes inactive. Note that
ON_STDOUT and ON_STDERR are invoked via the name they were
originally defined with (in the func or extern statement for
interpreted and compiled functions, respectively).
The object returned by spawn, process, can be used to send input
or signals to the process:
process, msg;
where msg is a string, sends msg to the process's stdin.
process, signum;
sends process the specified signal (e.g.- signum=2 sends SIGINT,
like hitting control-C, while signum=9 kills the process), if
signum is an integer (as opposed to a string). (Normally you
should not send signals to a process.) If you redefine the
final reference to process, for example by
process = [];
yorick will disconnect from the process, closing its end of
the stdin, stdout, and, optionally, stderr pipes. For many
programs, this will stop the program, but if the program can
continue running without stdin and stdout, it will continue
running. (If yorick were a shell, the process would be running
in the background; if the process would live beyond the shell
which created it, it will also survive its process variable
being freed.)
Note: funcdef may be extremely useful for writing ON_STDOUT.
SEE ALSO: popen, system, suspend, funcdef, after, spawn_callback
DOCUMENT spawn_callback -->
func on_stdout
extern fragment;
lines = spawn_callback(fragment, msg);
for (i=1 ; i<=numberof(lines) ; i++) {
line = lines(i);
if (!line) {
} else {
}
}
}
Here is a template for a callback function to be passed to spawn.
The spawn_callback function buffers any fragmentary lines,
delivering only complete lines as output. Note that FRAGMENT
must somehow be managed between calls to on_stdout; it should
be intialized to [] before calling spawn.
SEE ALSO: spawn
DOCUMENT suspend
resume
Stop execution of the current interpreted program with suspend.
It resumes at the instruction following suspend when yorick
becomes idle after another interpreted task has called resume.
Note that the task which calls resume must be triggered by an
input stream other than stdin, such as the on_stdout or on_stderr
function of a spawned process or the on_elapse of an after.
Use control-c to escape from a hung suspend state.
DOCUMENT system, "shell command line"
Passes the command line string to a shell for execution.
If the string is constant, you may use the special syntax:
$shell command line
(A long command line may be continued by ending the line with \
as usual.) The system function syntax allows Yorick to compute
parts of the command line string, while the simple $ escape
syntax does not. In either case, the only way to get output
back from such a command is to redirect it to a file, then
read the file. Note that Yorick does not regain control
until the subordinate shell finishes. (Yorick will get control
back if the command line backgrounds the job.)
WARNING: If Yorick has grown to a large size, this may crash
your operating system, since the underlying POSIX fork function
first copies all of the running Yorick process before the exec
function can start the shell. See Y_SITE/sysafe.i for a fix.
SEE ALSO: popen
DOCUMENT timer, elapsed
or timer, elapsed, split
updates the ELAPSED and optionally SPLIT timing arrays. These
arrays must each be of type array(double,3); the layout is
[cpu, system, wall], with all three times measured in seconds.
ELAPSED is updated to the total times elapsed since this copy
of Yorick started. SPLIT is incremented by the difference between
the new values of ELAPSED and the values of ELAPSED on entry.
This feature allows for primitive code profiling by keeping
separate accounting of time usage in several categories, e.g.--
elapsed= total= cat1= cat2= cat3= array(double, 3);
timer, elapsed0;
elasped= elapsed0;
... category 1 code ...
timer, elapsed, cat1;
... category 2 code ...
timer, elapsed, cat2;
... category 3 code ...
timer, elapsed, cat3;
... more category 2 code ...
timer, elapsed, cat2;
timer, elapsed0, total;
The wall time is not absolutely reliable, owning to possible
rollover at midnight.
SEE ALSO: timestamp, timer_print
DOCUMENT timer_print, label1, split1, label2, split2, ...
or timer_print
or timer_print, label_total
prints out a timing summary for splits accumulated by timer.
timer_print, "category 1", cat1, "category 2", cat2,
"category 3", cat3, "total", total;
SEE ALSO: timer
DOCUMENT timestamp()
or timestamp(utime)
or timestamp, utime
returns string of the form "Sun Jan 3 15:14:13 1988" -- always
has 24 characters. If a simple variable reference UTIME is supplied,
it will be set to the number of seconds since 1970 Jan 1 0000 UT.
SEE ALSO: timer