This function is used for loading a Lush source or binary file.

This function starts a new toplevel with the file named in as input file, and the file named out as the output file. Strings in and out represent filenames according to the general filename conventions explained with functions open-read and open-write .

Function load searches its input file in along the current search path. It also tries various suffixes usually associated with Lush program files (ie. .lsh .lshc as well as .sn .tl .snc .tlc for backward compatibility with TL3 and SN).

Function load then enters a loop which reads a Lush expression on the input file, evaluates this expression, and prints the result on the output file. This loop terminates when an end-of-file condition is detected or when function exit is called. Function load returns the full filename of the input file.

When the output file argument is omitted out , function load does not display the evaluation results. This is useful for silently loading a Lush program file. This file however can produce an output because it may contain calls to some printing function (eg. print .)

The optional string prompt indicates the prompts strings displayed by Lush when reading from the standard input. String prompt contains up to three prompt strings separated by the vertical bar character "|" . The first prompt string is used when Lush waits for a new expression. The second prompt string is used when Lush waits for the continuation of an already started expression. The last prompt string is used when the execution of the Lush expression reads information from the console (for instance using function read ).

Example:

;; The toplevel loop is implemented as
(load "$stdin" "$stdout" "? |  |> ")

This macro-character expands into a call to function load . If a filename filename is not provided, the last file name used with macro-character ^L is used. This file name is saved in variable last-loaded-file .

This variable is set when you load a Lush program file using function load . It contains the full name of the file being loaded. It provides a way to know the full filename of the Lush program file in which this variable is checked.

This is the primary function used to load a library or a Lush file into another Lush file or library. A typical Lush program file will begin with a bunch of libload . The difference between load and libload is that libload remembers when a particular file was previously libloaded, and only loads it once. Libload also keeps track of the dependencies between Lush program files (which file libloads which other file). This is the basis of the automatic and transparent on-demand compilation mechanism as described in detail below.

Function libload first searches the file libname . When libload is called from an existing Lush file, it first searches file libname relative to the location of the existing Lush file. If no such file exists, it uses function filepath to locate the file along the lush search path.

Function libload then updates its internal database of dependencies between Lush files. When function libload is called from an existing Lush file, it records the fact that this Lush file depends on the Lush file filename .

Function libload then tests whether it is necessary to load the file. It is necessary to load the file if

• Argument opt is non nil.
  
• File libname has never been loaded,
  
• File libname has been modified since the last time it was loaded,
  
• File libname has not been modified since the last time it was loaded, but depends on a Lush file that has been modified since the last time it was loaded.
  

When this is the case, libload calls load to load the file, and stores a timestamp for the file in its internal database. Function libload always returns the full name of libname .

This function also claims that fname has been successfully loaded. Calling libload on fname will not do anything unless someone modifies file fname after calling libload-add-dependency .

Example:

 (find-file '("local" "lsh") "stdenv" '(".lshc" ".lsh"))

Note: This is somewhat similar to filepath but allows searching through any directory tree.

The first time one of these functions is called, its definition is loaded from file f , and the execution continues. Such autoloading functions often are defined by "stdenv.lsh" . They avoid loading many files while allowing the user to call those functions at any time.

• When argument spec is a number, it indicates how many character should be read from the current input and returned as a string.
  
• When argument spec is a string, it specifies which characters are to be read. For example, "0-9" matches any number, "~0-9" matches anything but a number, "~ \t\n\r\f\e" anything but a blank character or end of file, "yYnN" reads only one of these characters.
  

The default spec for function read-string is "~\n\r\f\e" and means ``read anything until the end of line''.

Example:

This function reads the input stream and builds a list with each line, until it reaches an end-of-file character

 
 (de read-lines()
  (let ((ans ()))
   (while (<> (skip-char "\n\r\f") "\e")
    (setq ans (nconc1 ans (read-string))) ) ) )

This function reads the input stream and builds a list with each word, until it reaches an end-of-file character

 
 (de read-words()
  (let ((ans ()))
   (while (<> (skip-char) "\e")
     (setq ans (nconc1 ans (read-string "~ \t\n\r\f\e"))) ) ) )

Example:

? (ask "Your answer")
Your answer [y/n] ?

Example:

? (print "hello" (+ 3 4) '(a b c d))
"hello" 7 (a b c d)
= (a b c d)

Although the current implementation of pretty is a more complicated, a simple implementation of pretty would be :

 (df pretty(f) (pprint (funcdef f)))

• "%%" is replaced by a single \%.
  
• "%l" is replaced by a representation of a lisp object.
  
• "%[-][n]s" is replaced by a string, right justified in a field of length n if n is specified. When the optional minus sign is present, the string is left justified.
  
• "%[-][n]d" is replaced by an integer, right justified in a field of n characters, if n is specified. When the optional minus sign is present, the string is left justified.
  
• "%[-][n[.m]]c" where c is one of the characters e , f or g , is replaced by a floating point number in a n character field, with m digits after the decimal point. e specifies a format with an exponent, f specifies a format without an exponent, and g uses whichever format is more compact. When the optional minus sign is present, the string is left justified.
  

Function printf is the only way to print the real contents of a character string, without adding surrounding double quotes or escaping the special characters.

Example:

? (printf "%5s%3d is equal to %6.3f\n" "sqrt" 2 (sqrt 2))
 sqrt  2 is equal to  1.414
= ()

? (tab)
= 0

This function makes no reference to the actual contents of the filesystem. It just chops the filename according to the file naming conventions.

This function makes no reference to the actual contents of the filesystem. It just chops the filename according to the file naming conventions.

This function makes no reference to the actual contents of the filesystem. It just concatenates the filenames according to the file naming conventions. Nevertheless, if the resulting filename refers to an actual directory, a directory separator / is appended to the returned filename.

Examples:

? (concat-fname "..")
= "/home/leonb/lush"

? (concat-fname (getenv "HOME") "myfile.lsh")
= "/home/leonb/myfile.lsh"

Examples:

? (relative-fname "/home" "/home/lush/zoo")
= "lush/zoo"

? (relative-fname "/usr/share" "/home/lush/zoo")
= ()

   (concat-fname <todir>
      (or (relative-fname <fromdir> <x>) <x>) )

The optional string dir specifies the directory where the temporary file will be created. A value of () is interpreted as the default system directory for temporary files.

This function generates file names using the optional suffix suffix . If you do not specify this argument, the generated filename will have no suffix.

Examples:

(tmpname)           ;; creates a temporary file.
(tmpname () "sn")   ;; creates a temporary file whose name ends with ".lsh".
(tmpname ".")       ;; creates a temporary file in the current directory.

When Lush is looking for a file, it searches for it among a list of directories stored in variable |*PATH| . Several functions are provided to handle this feature.

The initial path is automatically set while Lush is starting up by retrieving the Lush executable file and scanning up the directories until it finds a suitable library directory.

? (progn
    (printf "--> The current path is:\n")
    (path) )
--> The current path is:
= ("." "/home/leonb/lush/local" "/home/leonb/lush/packages"
    "/home/leonb/lush/contrib" "/home/leonb/lush/lsh/libogre"
    "/home/leonb/lush/lsh/compiler" "/home/leonb/lush/lsh/libidx"
    "/home/leonb/lush/lsh/libstd" "/home/leonb/lush/lsh"
    "/home/leonb/lush/sys" )

The function addpath adds the directory s to the file search path. Directory s is added at the head of the search path. Other occurrences of this directory in the path are removed, in order to keep the search path small and non redundant.

Example:

? (addpath (concat (getenv "HOME") "/mysnlib"))

The function filepath searches file filename along the current search path, using the suffixes specified by argument suffixes . Function filepath returns the absolute path name of the file. The empty list is returned if no file matches the argument along the current search path.

Argument suffixes is a string containing a sequence of possible suffixes (including the initial period) separated by vertical bars ``|''. The sequence represents the priority order. A suffix may have zero characters.

".dump"      Try suffix <.dump>.
".lshc|.lsh|"  Try suffixes <.lshc> and <.lsh>, then try without suffix.
"|.lsh"       Try without suffix, then try suffix <.lsh>.
".lsh|"       Try suffix <sn>, then try without suffix.

Argument suffixes may specify a single suffix without the initial period. This is a shorthand for testing first the specified suffix and then testing without a suffix.

"sn"         Equivalent to ".lsh|"

When argument suffixes is omitted, filepath uses the same suffixes than function load . This default provides a way to determine which file would be loaded by a given call to function load .

? (filepath "sysenv")
= "/home/leonb/lush/sys/sysenv.lsh"

? (files)
= ("latex" "README" "html" "CVS" ".." ".")

? (fileinfo ".")
= ((type . dir) (size . 4096) (mode . 16877) (dev . 2055) (ino . 1049073)
    (nlink . 5) (uid . 1000) (gid . 1000)
    (atime . ::DATE:year-second:(2011-01-29 15:43:30))
    (mtime . ::DATE:year-second:(2011-02-10 22:55:21))
    (ctime . ::DATE:year-second:(2011-02-10 22:55:21)) )

? (dirp "..")
= t

? (filep "..")
= ()

• If this file already exists, function lockfile returns the empty list () .
  
• If this file does not exists already, function lockfile writes the current date into the file and returns t .
  

This function is useful for implementing a simple locking scheme.

This function returns a read file descriptor of the file named s . The empty list is returned when an error occurs while opening the file. The file descriptor is closed when the garbage collector detects that the file is no longer necessary. File descriptors however can be manually closed with the function delete .

Filenames have the following form:

• A legal operating system filename will be searched along the current path.
  
• "$stdin" stands for the Lush standard input.
  
• On some systems, "| shell command" may be used to open a pipe to another process. See the description of function sys to have comments about the implementation of this feature.
  

When string suffixes is specified, the suffixes specified by this string are tried while searching the file along the search path. The possible values of the string suffix are documented with function filepath .

This function returns a write file descriptor of the file named s . The empty list is returned when an error occurs while opening the file. The file descriptor is closed when the garbage collector detects that the file is no longer necessary. File descriptors however can be manually closed with the delete function.

Filenames have the following form:

• A legal operating system filename.
  
• "$stdout" stands for the Lush standard output stream.
  
• "$stderr" stands for the Lush standard error stream.
  
• On some systems, "| shell command" may be used to open a pipe to another process. See the description of function sys to have comments about the implementation of this feature.

  An optional suffix can be specified as argument suffix . This suffix is appended to the filename unless the filename already contains a suffix.

  
  

An optional suffix can be specified as argument suffix . This suffix is appended to the filename unless the filename already contains a suffix.

Calls progn on l1 to ln , while redirecting the current output to f . Argument f may be a filename or a file descriptor obtained by open-write or open-append .

Calls progn on l1 to ln , while redirecting the current input to f . Argument f may be a filename or a read file descriptor obtained by open-read .

Example: This function returns the list of the files in directory s

 (de directory(s)
        (let ((ans ()))
                (reading (concat "|/bin/ls " s)
                        (while (<> (skip-char) "\e")
                                (setq ans (nconc1 ans (read-string))) ) )
                ans ) )

? (reading-string "(1 2 3)" (read))
= (1 2 3)

When no arguments are provided, both the current input and current output are flushed: All characters pending on the current input are removed until a newline is encountered, all characters buffered on the current output are printed out.

Example:

 ;;; This function ask a question and returns a string.
 (de input(question)
        (printf "%s" question)
        (flush)
        (read-string) )

• Function bwrite writes objects by first specifying the class name. This implies the class must be defined and have the same name when reading the object. Function bwrite-exact instead writes a complete definition of the class. This implies that bread will create a new unnamed class regardless of the existing classes.
  
• Function bwrite writes indexes by saving their content regardless of how the index is laid out in the corresponding storages. This implies that bread will create a new storage for each of them. Function bwrite-exact instead writes the storage and the index layout. But this is wasteful if the storage is much larger than the index.

  
  

• Saving an instance of a user defined class with bwrite saves only the slots of the instance and a reference to the class name. Function bread will be able to read this binary file if the class has already been defined in the interpreter. This class must define the same slots with the same order as the class of the actual object stored in the file. Additional slots will just be skipped and left with their default value. Function bread-exact instead causes an error when there are additional slots.
  

Note that both bread and bread-exact can read files produced by either bwrite or bwrite-exact . There is no difference between bread and bread-exact when reading a file produced by bwrite-exact .

This function is useful for converting Lush program files (SN files) into preparsed binary file (SNC files). Loading a preparsed file is much faster than loading a text file. Preparsed copies of certain system libraries are located in directory "lushdir/lib" .

Writes the status of the lisp interpreter into file fname . If fname has no suffix, suffix ".dump" is assummed. This function works by creating a binary file containing a binary description of the state of the current Lush session.

Binary dump files are more useful for lauching Lush with preloaded libraries and application. During startup indeed, Tlisp can load a binary dump file specified by the command line arguments. Moreover, if Tlisp does not find the system library "stdenv.lsh" , it attempts to undump a file names "stdenv.dump" .

This function runs the shell command cmd in the background, stores into symbol fin a file descriptor for reading its standard output , and stores into symbol fout a file descriptor for writing into its standard input.

This commands allows for launching another program, sending commands and receiving the results. Arguments fin and fout are evaluated and must probably be quoted symbols.

This function connects a server process listening on port number port on the remote computer named host . It stores into symbol fin a file descriptor for reading from the server, and stores into symbol fout a file descriptor for writing to the server.

Arguments fin and fout are evaluated and must be quoted symbols.

This function causes an error if the server is not listening for connections. Make the port number negative to prevent this. Function socketopen will then return () if the port cannot be opened.

This commands creates a server side socket listening on port number port . It then waits for a client connection (for instance with socketopen ). Then it stores file descriptors for reading from and writing to the client into symbols fin and fout respectively. Arguments fin and fout are evaluated and must be quoted symbols.

When arguments fin and fout are not provided, it returns a boolean indicating whether it was possible to wait for connections on the specified port.