Prints all the symbols whose name contains the string str . This is especially useful if you don't remember the exact spelling of a function or variable.

Macro-character for function symbols

? (sizeof "double")
= 8

? (sizeof "gptr")
= 8

? (sizeof "short")
= 2

This function is mainly used for formated I/O.

Example:

? (error 'myfunc "bad number" 4)
*** myfunc : Bad number : 4
Debug toplevel [y/n] ?

Example:

?  (debug (* (+ 3 4) a)))
-> (* (+ 3 4) a)
 -> (+ 3 4)
  -> 3
  <- 3
  -> 4
  <- 4
 <- 7
 -> a
 <- 8
<- 56
= 56

This function prints the entire evaluation stack. Called from a debug toplevel, function where gives useful hints for undertsanding what happened and when.

This function is called before and after each evaluation when the Lush kernel runs in debug mode (see function debug ). Redefining this function allows interactive Lush debugger to execute programs step by step.

• When trace-hook is called before an evaluation, argument level is a positive number indicating the number of recursive calls to the evaluator since Lush entered the debug mode. Argument line is a string displaying the first line of the expression being evaluated. Argument expr is the expression being evaluated. Argument info is the list of the expressions whose recursive evaluation led to the evaluation of expr .

  If function trace-hook returns () , the evaluation will continue without calling trace-hook for recursive evaluations. The next call to trace-hook will occur after the current evaluation returns. If function trace-hook returns t , the recursive calls to the evaluator (calls performed while evaluating the current expression) will be traced.

  
  

• When trace-hook is called after an evaluation, argument level is a negative number representing the opposite of the number of recursive calls to the evaluator since Lush entered the debug mode. Argument line is a string representing the first line of the returned value. Argument expr is the expression being evaluated. Argument info is the value returned by the evaluation.

  If function trace-hook returns () , the remaining evaluations will continue without calling trace-hook until an evaluation with a smaller recursion level returns. If function trace-hook returns t , the next evaluations will be traced normally.

  
  

Example:

? (sqrt 81)
= 9
? (* result result)
= 81

This functions exits the current toplevel, as if a Ctrl-D had been typed. When the optional argument n is given, function exit quits the Lush process with return code n .

Lush calls this function once during the startup procedure as soon as the system library "stdenv.lsh" or "stdenv.dump" has been loaded. The behavior of the default startup procedure is explained in section "Lush Startup.".

The arguments argv are the command line arguments. Neither the executable name nor the magic first command line argument are passed to startup .

This function usually is defined by "sysenv.lsh" and is called after function startup during the startup process. This function is restarted whenever an error occurs.

This function evaluates lists l1 to ln and returns the last result like function progn . If however an errors occur during these evaluations, the expression p is evaluated before the usual error processing.

The function on-error does not stop the error processing, but allows for performing cleanup tasks, or for printing a custom error message.

This function evaluates lists l1 to ln and returns the last result like function progn . If however the user interrupts the evaluation by depressing Ctrl-C , the expression p is evaluated before the usual interruption processing.

The function on-break does not stop the interruption processing, but allows for performing cleanup tasks, or for printing a custom error message.

This function first evaluates list pm and stores the result which is usually an expression to be evaluated if an error occurs. It evaluates then lists l1 to ln and returns the last result like function progn . If however an errors occur during these evaluations, the result of the initial evaluation of pm is evaluated before the usual error processing.

Actually, this function works like on-error , except the expression which will be executed in case of error is the result of the evaluation of pm in the call context of on-error-macro i.e. before l1 ... ln are evaluated.

This allows a safer behaviour than on-error , since the evaluation of pm is made in the call context instead of being made in the error context. Indeed, the error context may have values pushed on the stacks by functions called in l1 ... ln , therefore hiding the expected values.

(let* ((my-window (new windowobject 100 100 200 100 "Handler"
                     (new string "processing...")))
       (errq (new errorrequester my-window)))
  (on-error-macro 
   `(==> ,errq popup (errname))
   (let* ((errq ()))
     (error "this is is a programmed error\nused as test."))))

This function is defined by "sysenv.lsh" and is called whenever an error occurs. Use care when modifying this function, since an incorrect debug-hook function may result into a deadly infinite loop!.

Some functions are not available under all operating systems:

• The function bground is only available on Unix system.
  
• The function xdmc is only available on Apollo Domain/OS computers.
  
• The functions winlushp , winsys and winedit are only available under Windows/95 and Windows/NT.
  

  #!/bin/sh
  exec lush "$0" "$@"
  !#
  (ogre)
  (wait (new autowindowobject 10 10 100 100 "Simple Lush GUI Demo" 
            (new stdbutton "    hit me    " (lambda (c) (printf "OUCH\n")))))

Executes the shell command defined in string shellcmd .

Example (Unix):

? (sys "pwd")
/home/toto/bip
= 0

The implementation of function sys and of the pipe convention in filenames (see open-read and open-write ) is highly system dependent.

• This implementation is extremely reliable on Unix systems. Using pipes and forking background processes has been the tradition of Unix since the origins.

  Function sys will always wait until the spawned process exits and return the process exit code.

  
  

• This implementation is much less reliable under Windows 95 or NT. You can indeed run very different kinds of programs, including legacy MSDOS and WIN16 programs. A number of programs running under Windows have been written with the assumption that they would run using a MSDOS style console. Running them as background processes or with standard handles redirected to pipes will cause problems.

  If you are running the Console based version of Lush, function sys replicates as well as possible the behavior of the Unix version. The spawned process inherits the Lush console and may be controlled by the user. If you are running a MSDOS or WIN32 Console application, function sys returns when the application exits. If you are running a Windows 3.1 or WIN32 GUI application, function sys returns immediately.

  If you are running the GUI based version of Lush, the spawned processed no longer inherit a MSDOS console. We have chosen to handle MSDOS and WIN32 Console application like a GUI application. Function sys will create a new console for the process and return immediately regardless of the application type.

  Using pipes is reasonably reliable under the Console based version of Lush. It becomes very adventurous under the GUI version of Lush because we do not want to create a console and let the user interact with the program. Bugs in Windows 95 make pipes so dangerous that we just forbid them.

  Please investigate function winsys to start a new process with a collection of refined options (redirecting standard handles, using the command interpreter, detaching the process, waiting until the process exits). You should nevertheless remember that these options do not work welle with all application types.

  
  

? #$pwd
/home/toto/bip
= 0

If the string s is provided, this function sets the current working directory to directory s . This function returns the current working directory name.

The current directory specified with chdir is used by all shell commands launched with function sys . When accessing a file, Lush also searches the current directory before the directories specified by function path .

Example:

? (chdir)
= "/home/leonb/lush/doc"

Example:

? (getpid)
= 22646

Example:

? (getuid)
= 1000

Example:

? (getusername)
= "leonb"

Calls the standard editor on file file . The editor name is stored in the symbol edit-call , and is initialized by looking at the environment variable EDITOR or VISUAL .

Copies an indented definition version of func in a temporary file and calls the function edit on this file. When the editor returns, the edited definition of func is loaded.

• "SHELL" The shell interpretor, e.g "/bin/sh" .
  
• "OPTS" The optimization options for the compilers, e.g. "-DNO_DEBUG -O2" .
  
• "DEFS" The symbol definition options for the compilers, e.g. "-DHAVE_CONFIG_H"
  
• "LIBS" Libraries used for linking the main executable, e.g. "-lbfd -liberty -ldl -lm" .
  
• "host" String describing the host computer, e.g. "i686-pc-linux-gnu" .
  
• "CPP" Command for running the C preprocessor, e.g. "gcc -E" .
  
• "CPPFLAGS" The preprocessing options for the compilers.
  
• "CC" Command for running the C compiler, e.g. "gcc" .
  
• "CFLAGS" The C specific compiler options besides those specified in CPPFLAGS , OPTS and DEFS .
  
• "CXX" Command for running the C++ compiler, e.g. "g++" .
  
• "CXXFLAGS" The C++ specific compiler options besides those specified in CPPFLAGS , OPTS and DEFS .
  
• "F77" Command for running the Fortran compiler, e.g. "g++" .
  
• "FFLAGS" The Fortran specific compiler options besides those specified in CPPFLAGS , OPTS and DEFS .
  
• "LDCC" Command for linking executables, e.g. "g++" .
  
• "LDFLAGS" Options for linking executables.
  
• "PTHREAD_FLAGS" Flags for compiling or linking programs that use the Posix thread library.
  
• "PTHREAD_LIBS" Libraries for linking programs that use the Posix thread library.
  
• "AR" Command for creating static libraries, e.g. "/usr/bin/ar" .
  
• "MV" Command for renaming and moving files, e.g. "/bin/mv" .
  
• "CP" Command for copying files, e.g. "/bin/cp" .
  
• "LN_S" Command for creating symbolic links, e.g. "ln -s" .
  
• "TOUCH" Command for updating the modification time of a file, e.g. "/bin/touch" .
  
• "INDENT" Command for running the GNU indent program.
  
• "RANLIB" Command for creating the table of contents of a static library created with AR , e.g. "ranlib" .
  
• "X_LIBS" Options for linking executables using the X11 library, e.g. "-L/usr/X11R6/lib -lSM -lICE -lX11" .
  
• "X_CFLAGS" Options for compiling programs using the X11 library, e.g. "-I/usr/X11R6/include" .
  
• "CC_PIC_FLAG" Compiler flag for producing position independent code appropriate for creating shared libraries, e.g. "-fPIC" .
  
• "CC_EXP_FLAG" Linker flag for linking executables that export their symbol tables to resolve undefined symbols in shared libraries, e.g. "-Wl,-export-dynamic" .
  
• "MAKESO" Command for creating a shared library, e.g. "gcc -shared -o" .
  
• "EXEEXT" Filename extension for executable programs, e.g. "" or "exe" .
  
• "OBJEXT" Filename extension for object files, e.g. "o" or "obj" .
  
• "SOEXT" Filename extension for shared libraries, e.g. "so" or "sl" or "dll" .
  
• "LUSH_MAJOR" The major version of Lush specified in loadable modules.
  
• "LUSH_MINOR" The minor version of Lush specified in loadable modules.
  
• "LUSH_DATE" The date lush was compiled.

  
  

Example:

? (getenv "HOME")
= "/home/leonb"

Example:

? (getconf "CC")
= "gcc"

? (getconf "CFLAGS")
= ""

Note: The deprecated form

 
  (time <l1...ln>)

is equivalent to function cputime but prints a warning message.

Example:

? (cputime (repeat 40000
             (sqrt 2) ))
= 0

On multiprocessor systems, this function adds the times spent by each CPU. If the evaluation of l1 ... ln involves several threads, the returned value might be greater than the real time.

Example:

? (realtime (repeat 40000
              (sqrt 2) ))
= 0.004

Example:

? (ctime)
= "Thu Feb 10 22:55:24 2011"

      ( tm_isdst <day light saving time>
        tm_yday  <day of the year (0..365)>
        tm_wdat  <day of the week (sunday=0)>
        tm_mon   <month number (0..11)>
        tm_mday  <day of the month (1..31)>
        tm_hour  <hour (0..23)>
        tm_min   <minutes (0..59)>
        tm_sec   <seconds (0..59)> )

Example:

? (localtime)
= (tm-isdst 0 tm-yday 40 tm-wday 4 tm-year 111 tm-mon 1 tm-mday 10 tm-hour 22
    tm-min 55 tm-sec 24 )

This function returns t if the Lush interpreter runs in script mode and () if the Lush interpreter runs in interactive mode. This function is useful to print less information when running in script mode.

Lush starts in script mode when arguments are passed on the command line. The initial banner is suppressed. The lush file named as first argument is loaded. Lush terminates as soon as it either reaches the end of file or encounters an error.

Lush starts in interactive mode when no arguments are passed on the command line. It displays a startup banner and generally prints more verbose messages. Then it enters the interactive toplevel loop (read-eval-print) and restarts the toplevel loop whenever an error occurs.

Switching mode changes the verbosity of the various messages. Switching to interactive mode also causes Lush to enter the interactive toplevel loop when it would otherwise exit (i.e. when reaching an end-of-file or encountering an error).

Examples:

  ;; You can test if you are running under windows as follows.
  (cond
       ((not winlushp)
              (printf "Not running under Windows\n") )
       ((winlushp)
              (printf "Running WinLush (GUI version of Lush under WIN32)\n") )
       (t
              (printf "Running Lush (Console version of Lush under WIN32)\n") ) )

Function winedit opens a text editor window for the file named filename . If the name filename ends with suffix ".lsh" , WinLush will allow syntax coloring and automatic indentation.

The optional flag as-untitled tells WinLush to open the file as an untitled window.

• If flag as-untitled is the empty list, WinLush first searches an already open text editor window for this file. If such a window already exists, WinLush just pops up the window. Otherwise, WinLush creates a new window and loads the file. This mode is convenient for editing well defined files.
  
• If flag as-untitled is not nil, WinLush creates a new untitled window and transfers the contents of the file. The new editor window will not remember the file name. This mode is convenient when you are using a temporary text file for transfering some text into an editor.
  
• If you do not specify argument as-untitled , WinLush makes a decision on the basis of the file location. If the file is located under the system temporary directory, WinLush creates an untitled editor window. Otherwise, WinLush creates a regular text editor window.

  
  

This function is available when you are running Lush under Windows 95 or NT.

Function winsys creates a process for the program specified by command line cmdline . The other arguments allow you to tune finely the process parameters.

The legal and reliable combinations depend on:

• whether you are running the console based (Lush) or GUI based (WinLush) version of Lush,
  
• whether you are running Windows 95 or Windows NT,
  
• whether you are executing a MSDOS application, WIN16 application, WIN32 Console based application, WIN32 GUI application, OS2 2.1 application (under NT) or Posix application (under NT).
  

Arguments stdin , stdout and stderr allow you to define the standard input, output and error handles of the program. These argulents may be () , t or a variable name.

• Value () represents an invalid handle. Therefore the process will not be able to use the corresponding standard handle. This may cause Windows to create a MSDOS console as a replacement.
  
• Value t represents the handle inherited from the Lush process. Under WinLush, this value redirects the standard output or standard error to the WinLush console.
  
• A variable name tells Lush to pass one end of the pipe to the process. The other end of the pipe will stored into the specified variable as a Lush file descriptor. If you specify the same variable name for the standard output and error, Lush will use a single pipe for both standard handles.
  

Flag commandp is used to determine how the command line is processed. If this flag is set, the command line is passed to the command interpreter. You can thus run the internal commands implemented by CMD.EXE (Windows NT) or COMMAND.COM (Windows 95 - an MSDOS program!!). If this flag is not set, the command line is directly interpreted by WIN32's CreateProcess function.

Flag detachp is used to run a process in the background. This flag should prevent Windows to create a console or inherit the console handles. It is rather buggy under Windows 95.

Flags waitp tells if function winsys must wait until termination of the process and return the process exit code. If this flag is unset, the function returns immeditely.

Examples:

;; Here is an alias for function SYS under WinLush
(winsys () () () t () () cmdline)
;; Here is an alias for function SYS under Console Lush
(winsys t t t t () t cmdline)
;; Here is a way to open a read pipe
(winsys () 'readpipe t () t () cmdline)

This function is available when you are running Lush under Windows 95 or NT. This function controls the visibility of the graphical interface of the GUI version Lush for Windows (WinLush). Calling this function does nothing if you are running the console version of Lush for Windows.

When argument flag is the empty list, WinLush switches to ``hidden'' mode. The main WinLush window (containing the Lush console, the text editor windows, and possibly a few graphical windows) disappears from the computer screen.

WinLush reverts to normal mode when function win-show-workbench is called again with a non nil argument. There is also a safety feature that automatically reverts WinLush normal mode when some user input is required on the Lush console.

When WinLush runs in ``hidden'' mode, function wbm-window works like function wbm-toplevel-window . Instead of creating a child window of the invisible main WinLush window, wbm-window creates a toplevel window which directly appears on the Windows desktop.

It is possible to directly start WinLush in ``hidden'' mode by specifying option "-hide" as the first command line argument. The remaining argument are interpreted as usual. This command line argument allows for creating self contained WinLush applications.

You can for instance create a file "c:/calctoolapp.lsh" containing the following three lines:

    (setq mainwnd (calctool))
    (while mainwnd (waitevent) (process-pending-events))
    (exit 0)

You can then start WinLush with the following command line:

    winlush -hide stdenv c:/calctoolapp.lsh

This command starts WinLush in hidden mode ( "-hide" ). WinLush will first load the standard environment ( "stdenv" ) and then load our example file ( "c:/calctoolapp.lsh" ). This file will create a calculator window on the Windows desktop, processes graphical events, and terminates execution when the user closes the calculator window.

The user will only see the calculator window. The WinLush main window never appears on the screen because WinLush remains in ``hidden'' mode as long as there is no need for user input on the Lush console.

Numerical computations may encounter three kinds of problems:

• Problems arise when we attempt to perform a clearly forbidden operation, such as taking the logarithm of a negative operand. This attempt causes a low level floating exception which generates a Lush error.
  
• A computation may return a number too large or too small to be represented by the usual floating point data types. Too small number are approximated by zero. Too large numbers are represented using special bit patterns for representing infinities.
  
• Special bit patterns are used to represent infinities or missing data. The special bit pattern representing missing data is called ``NaN'' (NaN stands for ``Not a Number''). Computations involving NaNs usually return NaNs.
  

The special bit patterns representing infinities or NaNs are still Lush numbers and numberp will always return t when applyed on a NaN. However NaNs and Infinities do not behave like regular numbers.

Special bit patterns have no litteral representation for the Lush reader. Most machines however print them as "Nan" or "Inf" or "-Inf" . You should not save these bit patterns into ascii format files because the reader will not be able to read them back. You must save them into binary files.

According to IEEE specifications, testing the equality of two special bit patterns should always return false. Comparing two bit patterns should cause a floating exception. Major operating systems and compilers do not abide with this specification. For instance the Microsoft Visual C++ 4.2 compiler considers that NaNs are equal to anything. It is unclear if this is a bug or a speed compromise (comparisons of actual number are much more frequent).

These problems make us unable to comply fully with the standard. Portable programs can only rely on the following garantees:

• NaNs and Infinities are different from regular numbers. The equality test will return false (we had to hand code this with Visual C++ in the Windoze version of TL3!).
  
• The Negative Infinity is smaller than any regular number. The Positive Infinity is greater than any regular number.
  
• Overflows may produce a floating point exception or return an Infinity. This is operating system and compiler dependent.
  
• Illegal operations (eg. comparing NaNs) are likely to cause a floating exception. They may however return NaNs without causing a floating exception on certain systems.
  

NaNs and Infinities however can be safely manipulated and tested by the following functions:

When NaNs are not supported, this function returns (). This is the only way provided by Lush for checking if NaNs are supported by this machine.

Example

?  (progn-without-fpe (log 0))
= -Inf