(maxima.info)Functions and Variables for File Input and Output
13.3 Functions and Variables for File Input and Output
======================================================
-- Function: appendfile (<filename>)
Appends a console transcript to <filename>. 'appendfile' is the
same as 'writefile', except that the transcript file, if it exists,
is always appended.
'closefile' closes the transcript file opened by 'appendfile' or
'writefile'.
-- Function: batch
batch (<filename>)
batch (<filename>, 'option')
'batch(<filename>)' reads Maxima expressions from <filename> and
evaluates them. 'batch' searches for <filename> in the list
'file_search_maxima'. See also 'file_search'.
'batch(<filename>, demo)' is like 'demo(<filename>)'. In this case
'batch' searches for <filename> in the list 'file_search_demo'.
See 'demo'.
'batch(<filename>, test)' is like 'run_testsuite' with the option
'display_all=true'. For this case 'batch' searches <filename> in
the list 'file_search_maxima' and not in the list
'file_search_tests' like 'run_testsuite'. Furthermore,
'run_testsuite' runs tests which are in the list 'testsuite_files'.
With 'batch' it is possible to run any file in a test mode, which
can be found in the list 'file_search_maxima'. This is useful,
when writing a test file.
<filename> comprises a sequence of Maxima expressions, each
terminated with ';' or '$'. The special variable '%' and the
function '%th' refer to previous results within the file. The file
may include ':lisp' constructs. Spaces, tabs, and newlines in the
file are ignored. A suitable input file may be created by a text
editor or by the 'stringout' function.
'batch' reads each input expression from <filename>, displays the
input to the console, computes the corresponding output expression,
and displays the output expression. Input labels are assigned to
the input expressions and output labels are assigned to the output
expressions. 'batch' evaluates every input expression in the file
unless there is an error. If user input is requested (by 'asksign'
or 'askinteger', for example) 'batch' pauses to collect the
requisite input and then continue.
It may be possible to halt 'batch' by typing 'control-C' at the
console. The effect of 'control-C' depends on the underlying Lisp
implementation.
'batch' has several uses, such as to provide a reservoir for
working command lines, to give error-free demonstrations, or to
help organize one's thinking in solving complex problems.
'batch' evaluates its argument. 'batch' returns the path of
<filename> as a string, when called with no second argument or with
the option 'demo'. When called with the option 'test', the return
value is a an empty list '[]' or a list with <filename> and the
numbers of the tests which have failed.
See also 'load', 'batchload', and 'demo'.
-- Function: batchload (<filename>)
Reads Maxima expressions from <filename> and evaluates them,
without displaying the input or output expressions and without
assigning labels to output expressions. Printed output (such as
produced by 'print' or 'describe')) is displayed, however.
The special variable '%' and the function '%th' refer to previous
results from the interactive interpreter, not results within the
file. The file cannot include ':lisp' constructs.
'batchload' returns the path of <filename>, as a string.
'batchload' evaluates its argument.
See also 'batch', and 'load'.
-- Function: closefile ()
Closes the transcript file opened by 'writefile' or 'appendfile'.
-- Option variable: file_output_append
Default value: 'false'
'file_output_append' governs whether file output functions append
or truncate their output file. When 'file_output_append' is
'true', such functions append to their output file. Otherwise, the
output file is truncated.
'save', 'stringout', and 'with_stdout' respect
'file_output_append'. Other functions which write output files do
not respect 'file_output_append'. In particular, plotting and
translation functions always truncate their output file, and 'tex'
and 'appendfile' always append.
-- Function: filename_merge (<path>, <filename>)
Constructs a modified path from <path> and <filename>. If the
final component of <path> is of the form '###.<something>', the
component is replaced with '<filename>.<something>'. Otherwise,
the final component is simply replaced by <filename>.
The result is a Lisp pathname object.
-- Function: file_search
file_search (<filename>)
file_search (<filename>, <pathlist>)
'file_search' searches for the file <filename> and returns the path
to the file (as a string) if it can be found; otherwise
'file_search' returns 'false'. 'file_search (<filename>)' searches
in the default search directories, which are specified by the
'file_search_maxima', 'file_search_lisp', and 'file_search_demo'
variables.
'file_search' first checks if the actual name passed exists, before
attempting to match it to "wildcard" file search patterns. See
'file_search_maxima' concerning file search patterns.
The argument <filename> can be a path and file name, or just a file
name, or, if a file search directory includes a file search
pattern, just the base of the file name (without an extension).
For example,
file_search ("/home/wfs/special/zeta.mac");
file_search ("zeta.mac");
file_search ("zeta");
all find the same file, assuming the file exists and
'/home/wfs/special/###.mac' is in 'file_search_maxima'.
'file_search (<filename>, <pathlist>)' searches only in the
directories specified by <pathlist>, which is a list of strings.
The argument <pathlist> supersedes the default search directories,
so if the path list is given, 'file_search' searches only the ones
specified, and not any of the default search directories. Even if
there is only one directory in <pathlist>, it must still be given
as a one-element list.
The user may modify the default search directories. See
'file_search_maxima'.
'file_search' is invoked by 'load' with 'file_search_maxima' and
'file_search_lisp' as the search directories.
-- Option variable: file_search_maxima
-- Option variable: file_search_lisp
-- Option variable: file_search_demo
-- Option variable: file_search_usage
-- Option variable: file_search_tests
These variables specify lists of directories to be searched by
'load', 'demo', and some other Maxima functions. The default
values of these variables name various directories in the Maxima
installation.
The user can modify these variables, either to replace the default
values or to append additional directories. For example,
file_search_maxima: ["/usr/local/foo/###.mac",
"/usr/local/bar/###.mac"]$
replaces the default value of 'file_search_maxima', while
file_search_maxima: append (file_search_maxima,
["/usr/local/foo/###.mac", "/usr/local/bar/###.mac"])$
appends two additional directories. It may be convenient to put
such an expression in the file 'maxima-init.mac' so that the file
search path is assigned automatically when Maxima starts. See also
Note: Introduction for Runtime Environment.
Multiple filename extensions and multiple paths can be specified by
special "wildcard" constructions. The string '###' expands into
the sought-after name, while a comma-separated list enclosed in
curly braces '{foo,bar,baz}' expands into multiple strings. For
example, supposing the sought-after name is 'neumann',
"/home/{wfs,gcj}/###.{lisp,mac}"
expands into '/home/wfs/neumann.lisp', '/home/gcj/neumann.lisp',
'/home/wfs/neumann.mac', and '/home/gcj/neumann.mac'.
-- Function: file_type (<filename>)
Returns a guess about the content of <filename>, based on the
filename extension. <filename> need not refer to an actual file;
no attempt is made to open the file and inspect the content.
The return value is a symbol, either 'object', 'lisp', or 'maxima'.
If the extension is matches one of the values in
'file_type_maxima', 'file_type' returns 'maxima'. If the extension
matches one of the values in 'file_type_lisp', 'file_type' returns
'lisp'. If none of the above, 'file_type' returns 'object'.
See also 'pathname_type'.
See 'file_type_maxima' and 'file_type_lisp' for the default values.
Examples:
(%i2) map('file_type,
["test.lisp", "test.mac", "test.dem", "test.txt"]);
(%o2) [lisp, maxima, maxima, object]
-- Option variable: file_type_lisp
Default value: '[l, lsp, lisp]'
'file_type_lisp' is a list of file extensions that maxima
recognizes as denoting a Lisp source file.
See also 'file_type'.
-- Option variable: file_type_maxima
Default value: '[mac, mc, demo, dem, dm1, dm2, dm3, dmt, wxm]'
'file_type_maxima' is a list of file extensions that maxima
recognizes as denoting a Maxima source file.
See also 'file_type'.
-- Function: load (<filename>)
Evaluates expressions in <filename>, thus bringing variables,
functions, and other objects into Maxima. The binding of any
existing object is clobbered by the binding recovered from
<filename>. To find the file, 'load' calls 'file_search' with
'file_search_maxima' and 'file_search_lisp' as the search
directories. If 'load' succeeds, it returns the name of the file.
Otherwise 'load' prints an error message.
'load' works equally well for Lisp code and Maxima code. Files
created by 'save', 'translate_file', and 'compile_file', which
create Lisp code, and 'stringout', which creates Maxima code, can
all be processed by 'load'. 'load' calls 'loadfile' to load Lisp
files and 'batchload' to load Maxima files.
'load' does not recognize ':lisp' constructs in Maxima files, and
while processing <filename>, the global variables '_', '__', '%',
and '%th' have whatever bindings they had when 'load' was called.
It is also to note that structures will only be read back as
structures if they have been defined by 'defstruct' before the
'load' command is called.
See also 'loadfile', 'batch', 'batchload', and 'demo'. 'loadfile'
processes Lisp files; 'batch', 'batchload', and 'demo' process
Maxima files.
See 'file_search' for more detail about the file search mechanism.
'load' evaluates its argument.
-- System variable: load_pathname
Default value: 'false'
When a file is loaded with the functions 'load', 'loadfile' or
'batchload' the system variable 'load_pathname' is bound to the
pathname of the file which is processed.
The variable 'load_pathname' can be accessed from the file during
the loading.
Example:
Suppose we have a batchfile 'test.mac' in the directory
'"/home/dieter/workspace/mymaxima/temp/"' with the following commands
print("The value of load_pathname is: ", load_pathname)$
print("End of batchfile")$
then we get the following output
(%i1) load("/home/dieter/workspace/mymaxima/temp/test.mac")$
The value of load_pathname is:
/home/dieter/workspace/mymaxima/temp/test.mac
End of batchfile
-- Function: loadfile (<filename>)
Evaluates Lisp expressions in <filename>. 'loadfile' does not
invoke 'file_search', so 'filename' must include the file extension
and as much of the path as needed to find the file.
'loadfile' can process files created by 'save', 'translate_file',
and 'compile_file'. The user may find it more convenient to use
'load' instead of 'loadfile'.
-- Option variable: loadprint
Default value: 'true'
'loadprint' tells whether to print a message when a file is loaded.
* When 'loadprint' is 'true', always print a message.
* When 'loadprint' is ''loadfile', print a message only if a
file is loaded by the function 'loadfile'.
* When 'loadprint' is ''autoload', print a message only if a
file is automatically loaded. See 'setup_autoload'.
* When 'loadprint' is 'false', never print a message.
-- Function: directory (<path>)
Returns a list of the files and directories found in <path> in the
file system.
<path> may contain wildcard characters (i.e., characters which
represent unspecified parts of the path), which include at least
the asterisk on most systems, and possibly other characters,
depending on the system.
'directory' relies on the Lisp function DIRECTORY, which may have
implementation-specific behavior.
-- Function: pathname_directory (<pathname>)
-- Function: pathname_name (<pathname>)
-- Function: pathname_type (<pathname>)
These functions return the components of <pathname>.
Examples:
(%i1) pathname_directory("/home/dieter/maxima/changelog.txt");
(%o1) /home/dieter/maxima/
(%i2) pathname_name("/home/dieter/maxima/changelog.txt");
(%o2) changelog
(%i3) pathname_type("/home/dieter/maxima/changelog.txt");
(%o3) txt
-- Function: printfile (<path>)
Prints the file named by <path> to the console. <path> may be a
string or a symbol; if it is a symbol, it is converted to a string.
If <path> names a file which is accessible from the current working
directory, that file is printed to the console. Otherwise,
'printfile' attempts to locate the file by appending <path> to each
of the elements of 'file_search_usage' via 'filename_merge'.
'printfile' returns <path> if it names an existing file, or
otherwise the result of a successful filename merge.
-- Function: save
save (<filename>, <name_1>, <name_2>, <name_3>, ...)
save (<filename>, values, functions, labels, ...)
save (<filename>, [<m>, <n>])
save (<filename>, <name_1>=<expr_1>, ...)
save (<filename>, all)
save (<filename>, <name_1>=<expr_1>, <name_2>=<expr_2>, ...)
Stores the current values of <name_1>, <name_2>, <name_3>, ..., in
<filename>. The arguments are the names of variables, functions,
or other objects. If a name has no value or function associated
with it, it is ignored. 'save' returns <filename>.
'save' stores data in the form of Lisp expressions. If <filename>
ends in '.lisp' the data stored by 'save' may be recovered by 'load
(<filename>)'. See 'load'.
The global flag 'file_output_append' governs whether 'save' appends
or truncates the output file. When 'file_output_append' is 'true',
'save' appends to the output file. Otherwise, 'save' truncates the
output file. In either case, 'save' creates the file if it does
not yet exist.
The special form 'save (<filename>, values, functions, labels,
...)' stores the items named by 'values', 'functions', 'labels',
etc. The names may be any specified by the variable 'infolists'.
'values' comprises all user-defined variables.
The special form 'save (<filename>, [<m>, <n>])' stores the values
of input and output labels <m> through <n>. Note that <m> and <n>
must be literal integers. Input and output labels may also be
stored one by one, e.g., 'save ("foo.1", %i42, %o42)'. 'save
(<filename>, labels)' stores all input and output labels. When the
stored labels are recovered, they clobber existing labels.
The special form 'save (<filename>, <name_1>=<expr_1>,
<name_2>=<expr_2>, ...)' stores the values of <expr_1>, <expr_2>,
..., with names <name_1>, <name_2>, ... It is useful to apply this
form to input and output labels, e.g., 'save ("foo.1", aa=%o88)'.
The right-hand side of the equality in this form may be any
expression, which is evaluated. This form does not introduce the
new names into the current Maxima environment, but only stores them
in <filename>.
These special forms and the general form of 'save' may be mixed at
will. For example, 'save (<filename>, aa, bb, cc=42, functions,
[11, 17])'.
The special form 'save (<filename>, all)' stores the current state
of Maxima. This includes all user-defined variables, functions,
arrays, etc., as well as some automatically defined items. The
saved items include system variables, such as 'file_search_maxima'
or 'showtime', if they have been assigned new values by the user;
see 'myoptions'.
'save' evaluates <filename> and quotes all other arguments.
-- Function: stringout
stringout (<filename>, <expr_1>, <expr_2>, <expr_3>, ...)
stringout (<filename>, [<m>, <n>])
stringout (<filename>, input)
stringout (<filename>, functions)
stringout (<filename>, values)
'stringout' writes expressions to a file in the same form the
expressions would be typed for input. The file can then be used as
input for the 'batch' or 'demo' commands, and it may be edited for
any purpose. 'stringout' can be executed while 'writefile' is in
progress.
The global flag 'file_output_append' governs whether 'stringout'
appends or truncates the output file. When 'file_output_append' is
'true', 'stringout' appends to the output file. Otherwise,
'stringout' truncates the output file. In either case, 'stringout'
creates the file if it does not yet exist.
The general form of 'stringout' writes the values of one or more
expressions to the output file. Note that if an expression is a
variable, only the value of the variable is written and not the
name of the variable. As a useful special case, the expressions
may be input labels ('%i1', '%i2', '%i3', ...) or output labels
('%o1', '%o2', '%o3', ...).
If 'grind' is 'true', 'stringout' formats the output using the
'grind' format. Otherwise the 'string' format is used. See
'grind' and 'string'.
The special form 'stringout (<filename>, [<m>, <n>])' writes the
values of input labels m through n, inclusive.
The special form 'stringout (<filename>, input)' writes all input
labels to the file.
The special form 'stringout (<filename>, functions)' writes all
user-defined functions (named by the global list 'functions')) to
the file.
The special form 'stringout (<filename>, values)' writes all
user-assigned variables (named by the global list 'values')) to the
file. Each variable is printed as an assignment statement, with
the name of the variable, a colon, and its value. Note that the
general form of 'stringout' does not print variables as assignment
statements.
-- Function: with_stdout
with_stdout (<f>, <expr_1>, <expr_2>, <expr_3>, ...)
with_stdout (<s>, <expr_1>, <expr_2>, <expr_3>, ...)
Evaluates <expr_1>, <expr_2>, <expr_3>, ... and writes any output
thus generated to a file <f> or output stream <s>. The evaluated
expressions are not written to the output. Output may be generated
by 'print', 'display', 'grind', among other functions.
The global flag 'file_output_append' governs whether 'with_stdout'
appends or truncates the output file <f>. When
'file_output_append' is 'true', 'with_stdout' appends to the output
file. Otherwise, 'with_stdout' truncates the output file. In
either case, 'with_stdout' creates the file if it does not yet
exist.
'with_stdout' returns the value of its final argument.
See also 'writefile'.
(%i1) with_stdout ("tmp.out", for i:5 thru 10 do
print (i, "! yields", i!))$
(%i2) printfile ("tmp.out")$
5 ! yields 120
6 ! yields 720
7 ! yields 5040
8 ! yields 40320
9 ! yields 362880
10 ! yields 3628800
-- Function: writefile (<filename>)
Begins writing a transcript of the Maxima session to <filename>.
All interaction between the user and Maxima is then recorded in
this file, just as it appears on the console.
As the transcript is printed in the console output format, it
cannot be reloaded into Maxima. To make a file containing
expressions which can be reloaded, see 'save' and 'stringout'.
'save' stores expressions in Lisp form, while 'stringout' stores
expressions in Maxima form.
The effect of executing 'writefile' when <filename> already exists
depends on the underlying Lisp implementation; the transcript file
may be clobbered, or the file may be appended. 'appendfile' always
appends to the transcript file.
It may be convenient to execute 'playback' after 'writefile' to
save the display of previous interactions. As 'playback' displays
only the input and output variables ('%i1', '%o1', etc.), any
output generated by a print statement in a function (as opposed to
a return value) is not displayed by 'playback'.
'closefile' closes the transcript file opened by 'writefile' or
'appendfile'.
automatically generated by info2www version 1.2.2.9