XLISP: An Object-oriented Lisp

XLISP > XLISP 2.0 - Contents - Reference - Previous | Next

# 33 Nyquist Functions

1. Predicate Functions

- filep - is this a file ?

2. Arithmetic Functions

- rrandom - compute a random real number between 0 and 1 inclusive

3. String Functions

- string-search - search for pattern in string

4. File I/O Functions

- open-binary - open a binary file stream
- setdir - set current directory
- listdir - get a directory listing
- get-temp-path - get a path where a temporary file can be created
- read-int - read a binary integer from a stream
- write-int - write a binary integer to a stream
- read-float - read a binary floating-point number from a stream
- write-float - write a binary floating-point number to a stream

5. System Functions

- info - show information about memory usage
- bigendiap - is this a big-endian machine ?
- setup-console - set default console attributes
- echoenabled - turn console input echoing on or off

6. Profiling

- profile - turn profiling on or off

Note: if you're interested in *all* functions added by Nyquist to the XLISP language, I suggest you download the Nyquist manual from:

- http://www.cs.cmu.edu/~music/music.software.html

The following is a list of all Nyquist functions I have found in the XLISP section of the Nyquist 2.36 manual but I cannot even guarantee that the list is complete. I'm willing to add more functions here if you find that some are missing but the best information source is the Nyquist manual itself. Roger is always a step ahead and I do not want to spread obsolete or wrong information.

## Predicate Functions

(filep expr) - is this a file ?
  expr - the expression to check
  returns - T if the value is an object, NIL otherwise

Back to Top

## Arithmetic Functions

(rrandom) - compute a random real number between 0 and 1 inclusive
  returns - a random floating point number

Back to Top

## String Functions

(string-search pat str &key :start :end) - search for pattern in string
  pat - a string to search for
  str - the string to be searched
  :start - the starting offset in str
  :end - the ending offset + 1
  returns - index of pat in str or NIL if not found

Back to Top

## File I/O Functions

Note: Files are ordinarily opened as text. Binary files [such as standard MIDI files] must be opened with 'open-binary' on non-unix systems.

(open-binary fname &key :direction) - open a binary file stream
  fname - the file name string or symbol
  :direction - :input or :output [default is :input]
  returns - a stream
(setdir path) - set current directory
  path - the path of the new directory
  returns - the resulting full path, e.g. (setdir ".") gets the current working directory, or NIL if an error occurs
(listdir path) - get a directory listing
  path - the path of the directory to be listed
  returns - list of filenames in the directory
(get-temp-path) - get a path where a temporary file can be created
  returns - the resulting full path as a string

Note: Under Windows, the 'get-temp-path' function is based on environment variables. If XLISP is running as a sub-process to Java, the environment may not exist, in which case the default result is the unfortunate choice 'c:\windows\'.

(read-int [stream [length]]) - read a binary integer from a stream
  stream - the input stream [default is standard input]
  length - the length of the integer in bytes [default is 4]
  returns - the integer
(write-int ch [stream [length]]) - write a binary integer to a stream
  ch - the character to write
  stream - the output stream [default is standard output]
  length - the length of the integer in bytes [default is 4]
  returns - the integer
(read-float [stream [length]]) - read a binary floating-point number from a stream
  stream - the input stream (default is standard input)
  length - the length of the float in bytes [default is 4, legal values are -4, -8, 4, and 8]
  returns - the float
(write-float ch [stream [length]]) - write a binary floating-point number to a stream
  ch - the character to write
  stream - the output stream [default is standard output]
  length - the length of the float in bytes [default is 4, legal values are -4, -8, 4, and 8]
  returns - the float

Note: Integers and floats are assumed to be big-endian [high-order byte first] and signed, regardless of the platform. To read little-endian format, use a negative number for the length, e.g. '-4' indicates a 4-bytes, low-order byte first. The file should be opened in binary mode.

Back to Top

## System Functions

Note: in Nyquist, the XLISP load function first tries to load a file from the current directory. A '.lsp' extension is added if there is not already an alphanumeric extension following a period. If that fails, XLISP searches the path, which is obtained from the XLISPPATH environment variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. [The Macintosh version has no search path.]

(info) - show information about memory usage.
  returns - NIL

(bigendiap) - is this a big-endian machine ?
  returns - T if this a big-endian architecture, storing the high-order byte of an integer at the lowest byte address of the integer, otherwise NIL.

Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of "Nyquist." This is normally accomplished by calling 'setup-console' in 'system.lsp'. In Nyquist, you can avoid this behavior by setting *setup-console* to NIL in your 'init.lsp' file. If 'setup-console' is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.

(setup-console) - set default console attributes
  returns - NIL

Note: The 'echoenabled' function is only implemented under Linux and Mac OS X. If Nyquist I/O is redirected through pipes, the Windows version does not echo the input, but the Linux and Mac versions do. You can turn off echoing with this function. Under windows it is defined to do nothing.

(echoenabled flag) - turn console input echoing on or off
  flag - T to enable echo, NIL to disable
  returns - NIL

Back to Top

# Profiling

The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where eval is executed. A separate count is maintained for each named function, closure, or macro, and a count indicates an eval in the immediately [lexically] enclosing named function, closure, or macro. Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls.

The list of all functions executed is maintained on the global *profile* variable. These functions in turn have *profile* properties, which maintain the counts. The profile system merely increments counters and puts symbols on the *profile* list. It is up to the user to initialize data and gather results. Profiling is turned on or off with the 'profile' function.

(profile flag) - turn profiling on or off
  flag - NIL turns profiling off, otherwise on
  returns - the previous state of profiling

Unfortunately, methods cannot be profiled with this facility.

[Nyquist sources: xlsys.c, xleval.c]

Back to Top

XLISP > XLISP 2.0 - Contents - Reference - Previous | Next