This is Info file librep.info, produced by Makeinfo version 1.68 from the input file librep.texi. START-INFO-DIR-ENTRY * librep: (librep). A LISP extension language END-INFO-DIR-ENTRY This is Edition 1.2, last updated 8 September 2000, of `The librep Manual', for librep, Version 0.13. Copyright 1999-2000 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.  File: librep.info, Node: Manipulating Directories, Next: Manipulating Symlinks, Prev: Manipulating Files, Up: Files Manipulating Directories ------------------------ - Command: make-directory DIRECTORY-NAME Create a new directory called DIRECTORY-NAME. - Command: delete-directory DIRECTORY-NAME Delete the directory called DIRECTORY-NAME. This only succeeds if the directory in question is empty, otherwise an error is signalled. - Function: directory-files DIRECTORY-NAME Returns a list of the names of all items in the directory whose name is DIRECTORY-NAME. The names in the list will be relative to the directory DIRECTORY-NAME. (directory-files "/tmp/foo" => ("bar" "subdir" "xyz" "." "..")  File: librep.info, Node: Manipulating Symlinks, Next: File Handlers, Prev: Manipulating Directories, Up: Files Manipulating Symbolic Links --------------------------- - Function: make-symlink NAME CONTENTS Create a symbolic link called NAME, containing the string CONTENTS. - Function: read-symlink NAME Return the string that is the contents of the symbolic link called NAME. Signals an error if no such link exists.  File: librep.info, Node: File Handlers, Next: Remote Files, Prev: Manipulating Symlinks, Up: Files File Handlers ------------- As noted earlier, `librep' supports virtual files; that is it allows file names to be accessed that don't reside on the local filing system, or aren't normally valid as file names. This is achieved through the use of "file handlers", Lisp functions that have signalled that they should be used to redirect all accesses to files whose names match a particular regular expression (*note Regular Expressions::.). For example, there is a convention under Unix that a user's home directory can be accessed via the file name `~', even though there is no such support from the operating system itself. So a file handler can be (and has been) written that recognises all file names starting with a tilde, translating them to the actual file in the file system. - Variable: file-handler-alist This variable contains a list of file handler declarations, each one of the form `(REGEXP . FUNCTION)'. Whenever a file operation is performed on a file whose name matches REGEXP, FUNCTION is invoked to perform the action. The function is called as `(FUNCTION OPERATION ARGS...)', where OPERATION and ARGS are from the original call. For example if the `file-handler-alist' contains the entry `("^~" . tilde-file-handler)', then all file operations on files starting with a tilde are redirected to the `tilde-file-handler' function. Thus if a form `(file-exists-p "~/foo")' is executed, it would result in a call to `tilde-file-handler' as `(tilde-file-handler 'file-exists-p "~/foo")'. The list of operations that may be redirected to a file handler is: `file-name-absolute-p', `expand-file-name', `local-file-name', `canonical-file-name', `file-name-nondirectory', `file-name-directory', `file-name-as-directory', `directory-file-name', `open-file', `close-file', `flush-file', `seek-file', `write-buffer-contents', `read-file-contents', `insert-file-contents', `delete-file', `rename-file', `copy-file', `copy-file-to-local-fs', `copy-file-from-local-fs', `make-directory', `delete-directory', `file-exists-p', `file-regular-p', `file-readable-p', `file-writable-p', `file-directory-p', `file-symlink-p', `file-owner-p', `file-nlinks', `file-size', `file-modes', `file-modes-as-string', `set-file-modes', `file-modtime', `directory-files', `make-symlink', `read-symlink'. There are several undefined functions in this list. The `write-buffer-contents', `read-file-contents', and `insert-file-contents' pertain to the Jade text editor. The other two are defined as follows. - Operation: copy-file-to-local-fs FILE-NAME LOCAL-NAME Called when copying files between file handlers, this operation should copy the file matching the handler FILE-NAME, to the file on the local file system LOCAL-NAME. - Operation: copy-file-from-local-fs LOCAL-NAME FILE-NAME Called when copying files between file handlers, this operation should copy the local file FILE-NAME to the file matching the handler FILE-NAME. To prevent infinite recursion, while a particular operation is being processed by a file handler, that operation may not be passed back to the same handler. To allow file handlers to handle the `open-file' operation, it is possible to create file handles from arbitrary streams. - Function: make-file-from-stream FILE-NAME STREAM HANDLER Return a new file object that refers to the logical file called FILE-NAME, that is not in the local filing system. All access to the file object will be directed through the stream object STREAM, and the file handler function HANDLER. An alternative method of opening remote files is to use a temporary file in the local file system with either one (`read' or `write' modes), or two (`append' mode) synchronisations with the remote system. This is the method used by the FTP remote file backend (see the next section). It has the advantage of simplifying the `seek-file' operation.  File: librep.info, Node: Remote Files, Prev: File Handlers, Up: Files Remote files ------------ Since one of the intentions for file handlers is to allow remote files to be accessed, a common method of providing new methods of doing this has been implemented, in the `remote.jl' Lisp library. Accessing a file name matching the regular expression: ^/(([a-zA-Z0-9._-]+)@)?([a-zA-Z0-9._-]+): for example `/john@host.com:file' refers to a file called `file' owned by the user `john', on the system `host.com'. If no username is specified explicitly, two variables are used to select the user: - Variable: remote-host-user-alist An alist mapping host regexps to the default user name to use for remote file connections to that host. - Variable: remote-default-user User name to use for remote file connections when otherwise unspecified. By default the current user name on the local system. Two variables control how individual hosts are matched to methods of accessing files. - Variable: remote-auto-backend-alist An alist of `(HOST-REGEXP . BACKEND-TYPE)' mapping host names to methods of accessing remote files. - Variable: remote-default-backend A symbol defining the method to use for otherwise unselected hosts. A method of accessing files, or a "backend" is a symbol whose `remote-backend' property names a function to call when files need to be accessed. For example the `ftp' backend is initialised as: (put 'ftp 'remote-backend remote-ftp-handler) The backend function is called as `(FUNCTION SPLIT-NAME OPERATION ARGS)'. The SPLIT-NAME is a three-element list, `(USER-OR-NIL HOST FILE)' defining the file to be accessed. The other options are as usual. Further details can be found in the `remote.jl', `remote-ftp.jl' and `remote-rcp.jl' Lisp source files. The `ftp' backend is currently the most well-developed, several functions and variables may be used to customise its behaviour. - Function: remote-ftp-add-passwd USER HOST PASSWD Add the string PASSWD as the password for the FTP session connecting to USER@HOST. - Variable: remote-ftp-show-messages When true (the default), messages are displayed as FTP commands are executed. - Variable: remote-ftp-display-progress When true (the default) display progress of FTP transfers. - Variable: remote-ftp-anon-users A regular expression matching the user names for "anonymous" FTP sessions. - Variable: remote-ftp-anon-passwd The string to send as the passwd of an anonymous FTP session. By default the current uses email address. There is a problem with the `ftp' backend however; due to limitations in the FTP protocol, not all `librep' file operations are supported, with the most obvious exception being the `make-symlink' function. When this is a problem it may be possible to use rep's custom file transfer protocol. If it is possible to use `rsh' to connect to the remote host in question, then the `rep' backend may be used. The `rep-remote' program distributed with `librep' must exist on the remote host, this is executed via `rsh' and provides a protocol for executing all of `librep''s file operations on that host. See the `lisp/remote-rep.jl' file in the distribution for more details.  File: librep.info, Node: Processes, Next: Regular Expressions, Prev: Files, Up: The language Processes ========= When running on a Unix-style operating system `librep' allows you to launch and control an arbitrary number of subprocesses. These subprocesses can run either synchronously or asynchronously in respect to the Lisp system; data can be sent to the `stdin' channel and any output from the process is automatically written to a specified Lisp output stream. Unless otherwise stated, all functions and variables described in the following sections are exported by the `rep.io.processes' module. * Menu: * Process Objects:: Lisp objects associated with subprocesses * Asynchronous Processes:: Subprocesses running in parallel * Synchronous Processes:: Subprocesses which run to completion * Process I/O:: Input and output with subprocesses * Process States:: Suspending subprocesses * Signalling Processes:: Sending signals to subprocesses * Process Information:: Information stored in a process object  File: librep.info, Node: Process Objects, Next: Asynchronous Processes, Up: Processes Process Objects --------------- A "process object" is a type of Lisp object used to provide a link between a `physical' process running in the operating system and the Lisp system. Each process object consists of a number of values (references to other Lisp objects); these values are used when the object is used to run a subprocess. Process objects which aren't currently being used to run a subprocess store the exit value of the last subprocess which was run on that object. - Function: processp OBJECT This function returns true when its argument is a process object. The programmer-accessible components of a process object are, "Output stream" A normal Lisp output stream (*note Output Streams::.), all data which the subprocess outputs to its `stdout' channel is copied to this output stream. *Note Process I/O::. "Error stream" A normal Lisp output stream (*note Output Streams::.), all data which the subprocess outputs to its `stderr' channel is copied to this output stream. Unless explicitly specified error output goes to the `stdout' stream. *Note Process I/O::. "State change function" A Lisp function, called each time the state of the subprocess being run on the object changes. *Note Process States::. "Program name" The name of the program (a string) to execute when the subprocess is created. "Program arguments" A list of strings defining the arguments which the program executed is given. "Directory" When a subprocess is started its current working directory is set to the directory named by this component of its process object. "Connection type" Asynchronous subprocesses (*note Asynchronous Processes::.) use this component to decide how to connect to the I/O channels of the subprocess. Current options include pseudo-terminals and pipes. - Function: make-process #!OPTIONAL OUTPUT-STREAM STATE-FUNCTION DIRECTORY PROGRAM ARGS This functions creates and returns a new process object. *No subprocess will be started.* The optional arguments are used to define the values of the components of the new process object, any undefined components will be set to default or null values. For each component of a process object two functions exist; one to read the component's value in a specific process object, the other to set the component's value. - Function: process-prog PROCESS Returns the value of the program name component of the process object PROCESS. - Function: set-process-prog PROCESS PROG-NAME Sets the value of the program name component of the process object PROCESS to the string PROG-NAME, then returns PROG-NAME. - Function: process-args PROCESS Returns the value of the program arguments component of the process object PROCESS. - Function: set-process-args PROCESS ARG-LIST Sets the value of the program arguments component of the process object PROCESS to the list ARG-LIST, then returns ARG-LIST. - Function: process-dir PROCESS Returns the value of the directory component of the process object PROCESS. - Function: set-process-dir PROCESS DIRECTORY Sets the value of the directory component of the process object PROCESS to the string DIRECTORY, then returns DIRECTORY. - Variable: process-environment This is a list of environment variable definitions, as well as being used by the `setenv' and `getenv' functions (*note Environment Variables::.), it also provides the environment of all started subprocesses. (car process-environment) => "LOGNAME=john" - Function: active-processes Returns a list containing all active (i.e. running or stopped) process objects.  File: librep.info, Node: Asynchronous Processes, Next: Synchronous Processes, Prev: Process Objects, Up: Processes Asynchronous Processes ---------------------- An "asynchronous process" is one that runs in parallel with Lisp evaluation, basically this means that once the subprocess has been started (by the `start-process' function) `librep' will carry on as normal. The event loop checks for output from asynchronous processes, any found is copied to the process' output stream, and calls the the process' state change function when necessary (*note Process States::.). Alternatively the `accept-process-output' function can be called to explicitly allow output to be processed. When using asynchronous processes you have a choice as to the Unix mechanism used to connect the `stdin', `stdout' and `stderr' streams of the subprocess to `librep''s process. The two options currently available are pipes or pseudo-terminals; in general pseudo-terminals should only be used to provide a direct interface between the user and a process (i.e. the `*shell*' buffer) since they allow job control to work properly. At other times pipes will be more efficient and are used by default. However, there are cases where the buffering characteristics of pipes mean that ptys must be used. - Function: start-process #!OPTIONAL PROCESS PROGRAM #!REST ARGS This function starts an asynchronous subprocess running on the process object PROCESS. If PROCESS is undefined a new process object is created (by calling the function `make-process' with all arguments undefined). The function always returns the process object which the subprocess has been started on. If for some reason the subprocess can't be created an error of type `process-error' is signalled. The optional argument PROGRAM is a string defining the name of the program to execute, it will be searched for in all the directories in the `PATH' environment variable. The ARGS are strings to pass to the subprocess as its arguments. When defined, the optional arguments overrule the values of the related components of the process object. The following example runs the `ls' program asynchronously, its output is sent to the `standard-output' stream. (let ((process (make-process standard-output))) (start-process process "ls" "-s")) Note that when `librep' exits it kills all of its asynchronous subprocesses which are still running without warning. - Function: process-connection-type PROCESS Returns the value of the connection type component of the process object PROCESS. See the documentation of the `set-process-connection-type' function for the values this may take. - Function: set-process-connection-type PROCESS SYMBOL Sets the value of the connection type component of the process object PROCESS to SYMBOL, then returns SYMBOL. SYMBOL should be one of the following symbols, `pty' Use pseudo-terminals to connect to subprocesses running asynchronously on this process object. `pipe' Use standard Unix pipes to connect, this is the default value of this component. `socketpair' Uses a connected pair of sockets. Note that currently only the `pipe' connection type allows the normal and error output streams of the process to be separated.  File: librep.info, Node: Synchronous Processes, Next: Process I/O, Prev: Asynchronous Processes, Up: Processes Synchronous Processes --------------------- When a "synchronous process" is started `librep' waits for it to terminate before continuing; they are usually used when a Lisp program must invoke an external program as part of its function, i.e. the auto-compression feature runs the compression program `gzip' synchronously when it needs to compress a buffer. Unlike asynchronous processes their is no choice between pipes and pseudo-terminals for connecting to a subprocess. Instead, it is possible to link the `stdin' channel of a synchronous process to a named file. - Function: call-process #!OPTIONAL PROCESS INPUT-FILE-NAME PROGRAM #!REST ARGS This function starts a process running on the process object PROCESS. If PROCESS is undefined a new process object is created by calling the `make' function. If defined, the string INPUT-FILE-NAME names the file to connect to the standard input of the subprocess, otherwise the subprocess' input comes from the null device (`/dev/null' on UNIX). The optional arguments PROGRAM and ARGS define the name of the program to invoke and any arguments to pass to it. The program will be searched for in all directories listed in the `process-environment' variable. If any of the optional parameters are unspecified they should have been set in the PROCESS-OBJECT prior to calling this function. After successfully creating the new subprocess, this function simply copies any output from the process to the output stream defined by the output stream component of the process object. When the subprocess exits its exit-value is returned (an integer). Note that the exit-value is the value returned by the `process-exit-value' function, see *Note Process Information::. If, for some reason, the new subprocess can't be created an error of type `process-error' is signalled. The following function definition is taken from the `gzip.jl' file, it shows how the `call-process' function can be used to uncompress a file into a buffer (for Jade). ;; Uncompress FILE-NAME into the current buffer (defun gzip-uncompress (file-name) (let ((proc (make-process (current-buffer)))) (message (concat "Uncompressing `" file-name "'") t) ;; gunzip can do .Z files as well (unless (zerop (call-process proc nil "gunzip" "-c" file-name)) (signal 'file-error (list "Can't gunzip file" file-name))))) The user is able to interrupt synchronous subprocesses (for example if they seem to have got wedged somehow). Each time a user-interrupt is received by `librep' (i.e. the `INT' signal), a stronger signal is sent to the subprocess. First an interrupt signal, then a termination signal, before finally a non-ignoreable quit signal is sent.  File: librep.info, Node: Process I/O, Next: Process States, Prev: Synchronous Processes, Up: Processes Process I/O ----------- It is only possible for lisp programs to explicitly send input data to *asynchronous* processes (by the time it's possible to call a function to send data to a synchronous process, the process will already have terminated!). Simply use the process object which an asynchronous process is running on as a normal Lisp input stream, any strings or characters written to the stream will immediately be copied to the `stdin' channel of the subprocess. With synchronous processes, the only control over input data possible is by giving the `call-process' function the name of a file containing the subprocess' input data. Output data from subprocesses is handled the same way by both asynchronous and synchronous processes: it is simply copied to the stream defined by the output stream component of the subprocess' process object. - Function: process-output-stream PROCESS Returns the value of the output stream component of the process object PROCESS. - Function: set-process-output-stream PROCESS STREAM Sets the value of the output stream component of the process object PROCESS to the stream STREAM, then returns STREAM. By default the `stdout' and `stderr' streams are combined, use the `set-process-error-stream' function to separate them. (Note that this currently only works with `pipe' connection types.) - Function: process-error-stream PROCESS Returns the value of the error stream component of the process object PROCESS. - Function: set-process-error-stream PROCESS STREAM Sets the value of the error stream component of the process object PROCESS to the stream STREAM, then returns STREAM. Output from asynchronous subprocesses (this includes changes of state as well as stream output) is only propagated at well-defined times. Either when in the read stage of the read-eval-print, or input, loop, or when the `accept-process-output' or `sit-for' functions are called. - Function: accept-process-output #!OPTIONAL SECONDS MILLISECONDS Wait SECONDS plus MILLISECONDS for output from any asynchronous subprocesses. If any arrives, process it, then return false. Otherwise return true. If either of the arguments is undefined, they count as zero in the addition. - Function: sit-for #!OPTIONAL SECONDS MILLISECONDS Wait for input to arrive and be processed. No more than SECONDS seconds plus MILLISECONDS milliseconds will be waited. If at the end of this time no input has arrived, return true. Otherwise return false if input was found. Note that this function is only distinct to `accept-process-output' when `librep' is embedded in another application, or an extension has been loaded that provides an event loop (such as the `gtk' binding). In this case other input forms, such as user input, for example, can preempt the timeout. This function is exported by the `rep.system' module. *Note Streams::.  File: librep.info, Node: Process States, Next: Signalling Processes, Prev: Process I/O, Up: Processes Process States -------------- Each process object has a "state" associated with it; this depends on the status of the subprocess currently running on the process object (or not as the case may be). The possible states are, "running" This state means that the subprocess using this process object is currently running, i.e. it hasn't been stopped. "stopped" Means that the subprocess has been temporarily suspended from running. "unused" This means that the process object is free to have a new subprocess created on it. Predicates exist which test whether a given process object is in one of these states. - Function: process-running-p PROCESS-OBJECT Returns true when PROCESS-OBJECT is in the running state. - Function: process-stopped-p PROCESS-OBJECT Returns true when PROCESS-OBJECT is in the stopped state. - Function: process-in-use-p PROCESS-OBJECT Returns true when PROCESS-OBJECT is *not* in the unused state. The following two functions are used to stop and then subsequently continue a process running. - Function: stop-process PROCESS-OBJECT #!OPTIONAL WHOLE-GROUP This function suspends execution of the subprocess running on the process object PROCESS-OBJECT. If WHOLE-GROUP is true all subprocesses in the process group of PROCESS-OBJECT are stopped. - Function: continue-process PROCESS-OBJECT #!OPTIONAL WHOLE-GROUP Use this function to continue a subprocess executing after it has been stopped (by the `stop-process' function). If WHOLE-GROUP is true all subprocesses in the process group of PROCESS-OBJECT are continued. The state change function component of a process object defines a function which will be called each time the state of the process object changes. If your program needs to be informed when an asynchronous process terminates this function is the way to do it. - Function: process-function PROCESS Returns the value of the state change function component of the process object PROCESS. - Function: set-process-function PROCESS FUNCTION Sets the value of the state change function component of the process object PROCESS to the function FUNCTION, then returns FUNCTION.  File: librep.info, Node: Signalling Processes, Next: Process Information, Prev: Process States, Up: Processes Signalling Processes -------------------- - Function: interrupt-process PROCESS-OBJECT #!OPTIONAL WHOLE-GROUP Sends the `SIGINT' signal to PROCESS-OBJECT. - Function: kill-process PROCESS-OBJECT #!OPTIONAL WHOLE-GROUP Sends the `SIGKILL' signal to the PROCESS-OBJECT. Note that the functions `stop-process' and `continue-process' also send signals to the subprocess. - Function: signal-process PROCESS SIGNAL #!OPTIONAL WHOLE-GROUP Send the signal SIGNAL to the process PROCESS; if WHOLE-GROUP is true the signal is also sent to all processes in the process group of PROCESS. PROCESS may be either a Lisp process object, or an integer defining the pid of the process to signal (not necessarily started by `librep'). SIGNAL may either be an integer defining the actual signal number, or a symbol naming the signal. All names are as usual but with the preceding `SIG' removed, for example the `SIGINT' signal would be sent by using the symbol `INT'. If a named signal doesn't exist on the current operating system, an error is raised. Returns true if the signal was sent successfully. As with the UNIX `kill' system call, `signal-process' may also be used to test whether a process with a particular pid is currently active, by using a signal with value zero.  File: librep.info, Node: Process Information, Prev: Signalling Processes, Up: Processes Process Information ------------------- - Function: process-id PROCESS-OBJECT This function returns the operating-system identifier associated with the subprocess currently running on the process object PROCESS-OBJECT. - Function: process-exit-value PROCESS-OBJECT Returns the integer representing the return code of the last subprocess to be run on PROCESS-OBJECT. If no subprocess has been run on PROCESS-OBJECT, PROCESS-OBJECT is currently in the running state or the last subprocess exited abnormally (i.e. from a terminal signal) false is returned. - Function: process-exit-status PROCESS-OBJECT This function returns the integer that was the exit status of the last subprocess which was run on the process object PROCESS-OBJECT. Note that the exit status is *not* the value given to the `exit' function in a C program, use the `process-exit-value' to access this value. If no process has been run on PROCESS-OBJECT, or the process is currently in the running state false is returned.  File: librep.info, Node: Regular Expressions, Next: Time and Date, Prev: Processes, Up: The language Regular Expressions =================== Regular expressions (or "regexps") are a powerful method of matching patterns in strings. `librep' uses the `regexp(3)' implementation by Henry Spencer, with some modifications that I have made. It comes with this banner: Copyright (c) 1986 by University of Toronto. Written by Henry Spencer. Not derived from licensed software. Permission is granted to anyone to use this software for any purpose on any computer system, and to redistribute it freely, subject to the following restrictions: 1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from defects in it. 2. The origin of this software must not be misrepresented, either by explicit claim or by omission. 3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. * Menu: * Regexp Syntax:: How to write regular expressions * Regexp Functions:: How to use them  File: librep.info, Node: Regexp Syntax, Next: Regexp Functions, Up: Regular Expressions Regular Expression Syntax ------------------------- The syntax of a regular expression is as follows (this is adapted from the manual page): A regular expression is zero or more "branches", separated by `|'. It matches anything that matches one of the branches. A branch is zero or more "pieces", concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an "atom" possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a "range" (see below), `.' (matching any single character), `^' (matching the null string at the beginning of the input string), `$' (matching the null string at the end of the input string), one of the strings `\s', `\S', `\w', `\W', `\d', `\D', `\b', `\B', or a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character). A "range" is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character *not* from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character. Also, any of the `*', `+' or `?' operators can be suffixed by a `?' character (i.e. `*?', `+?', `??'). The meaning of the operator remains the same but it becomes "non-greedy". This means that it will match the *smallest* number of characters satisfying the regular expression, instead of the default behaviour which is to match the *largest*. The backslash-introduced atoms have the following meanings: `\s' Match any whitespace character. `\S' Match any non-whitespace character. `\w' Match any alphanumeric or underscore character. `\W' Match any non-(alphanumeric or underscore) character. `\d' Match any numeric character. `\D' Match any non-numeric character. `\b' Match the null string between two adjacent `\w' and `\W' characters (in any order). `\B' Match the null string that is not between two adjacent `\w' and `\W' characters. Some example legal regular expressions could be: `ab*a+b' Matches an `a' followed by zero or more `b' characters, followed by one or more `a' characters, followed by a `b'. For example, `aaab', `abbbab', etc... `(one|two)_three' Matches `one_three' or `two_three'. `^cmd_[0-9]+' `^cmd_\d+' Matches `cmd_' followed by one or more digits, it must start at the beginning of the line.  File: librep.info, Node: Regexp Functions, Prev: Regexp Syntax, Up: Regular Expressions Regexp Functions ---------------- These functions are exported by the `rep.regexp' module. - Function: quote-regexp STRING Return a version of STRING, such that when used as a regexp, it will match the original contents of STRING verbatim, and nothing else. This involves quoting regexp meta-characters. (quote-regexp "abc") => "abc" (quote-regexp "a+c") => "a\\+c" - Function: string-match REGEXP STRING #!OPTIONAL START IGNORE-CASE Returns true if the string STRING matches the regular expression REGEXP. The string matches if executing the regexp at *any* position in the string succeeds. When defined, START is the index of the first character to start matching at (counting from zero). When IGNORE-CASE is true the case of matched strings are ignored. Note that character classes are still case-significant. (string-match "ab+c" "abbbc") => t (string-match "ab+c" "xxxabbbcyyy") => t - Function: string-looking-at REGEXP STRING #!OPTIONAL START IGNORE-CASE Similar to `string-match', but only returns true if STRING matches REGEXP starting at the character at index START in the string (or the first character if START is undefined). (string-looking-at "ab+c" "abbbc" 0) => t (string-looking-at "ab+c" "xxxabbbcyyy" 0) => () (string-looking-at "ab+c" "xxxabbbcyyy" 3) => t - Function: match-start #!OPTIONAL N Returns the position at which the N'th parenthesised expression started in the last successful regexp match. If N is false or zero the position of the start of the whole match is returned instead. When matching strings, all positions are integers, with the first character in the string represented by zero. However, extensions that allow regexps to be matched against other textual inputs may return different position values. (string-match "x*(foo|bar)y" "xxxbary") => t (match-start 1) => 3 - Function: match-end #!OPTIONAL N Similar to `match-start', but returns the position of the character following the matched item. (string-match "x*(foo|bar)y" "xxxbary") => t (match-end 1) => 6 A common use of regular expressions is to match a string, then replace certain portions of the string with other text. - Function: expand-last-match TEMPLATE Expand the TEMPLATE substituting the parenthesised expressions from the most recent successfully matched regular expression. TEMPLATE may contain the following substitution-inducing escape sequences: `\0' `\&' Substitute the whole string matched by the last regexp `\N' Substitute the N'th parenthensised expression, where 1 <= N <= 9. `\\' Substitute a single backslash character. (string-match "x*(foo|bar)y" "xxxbary") => t (expand-last-match "test-\\1-ing") => "test-bar-ing" Note that double backslashes are required due to the read syntax of strings (*note Strings::.). - Function: string-replace REGEXP TEMPLATE STRING Returns the string created by replacing all matches of REGEXP in STRING with the result of expanding TEMPLATE using the `expand-last-match' function. (string-replace "-" "_" "foo-bar-baz") => "foo_bar_baz" (string-replace "&(optional|rest)" "#!\\1" "(a &optional b &rest c)") => "(a #!optional b #!rest c)"  File: librep.info, Node: Time and Date, Next: i18n, Prev: Regular Expressions, Up: The language Time and Date ============= This section describes how time and date values are handled in `librep'. * Menu: * Timestamps:: Internal representation of time * Formatting Dates:: Creating strings from timestamps * Parsing Dates:: Reading textual dates  File: librep.info, Node: Timestamps, Next: Formatting Dates, Up: Time and Date Timestamps ---------- As in UNIX, `librep' measures time as the number of seconds since January 1st, 1970 (known as the "epoch"). For historical reasons rep stores timestamps as a pair of integers, using a cons cell. The first integer records the number of whole days since the epoch, the second records the number of seconds since the start of the day (in universal time). These function are exported by the `rep.system' module: - Function: current-time Return the number of seconds since the epoch, in a cons-cell. (current-time) => (10744 . 61063) - Function: fix-time TIMESTAMP Ensure that the two parts of TIMESTAMP (a pair or integers) are consistent, simply that the number of seconds is less than the number of seconds in a whole day. If not, the timestamp is adjusted to meet this constraint. - Function: time-later-p TIMESTAMP-1 TIMESTAMP-2 Returns true if TIMESTAMP-1 is later than TIMESTAMP-2. On the plus side, this scheme won't wrap around as quickly as UNIX's `time_t' will ;-) The `rep.util.time' module also provides some functions for manipulating timestamps: - Function: time->seconds TIMESTAMP Convert TIMESTAMP to an integer, the number of seconds since the epoch that it represents. - Function: seconds->time SECONDS Convert from an integer SECONDS to a timestamp object. - Function: time- TIMESTAMP-1 TIMESTAMP-2 Return the number of seconds difference between TIMESTAMP-1 and TIMESTAMP-2. - Constant: seconds-per-day The number of seconds in a 24-hour day.  File: librep.info, Node: Formatting Dates, Next: Parsing Dates, Prev: Timestamps, Up: Time and Date Formatting Dates ---------------- Given a timestamp value it is possible to format it as a string, in many different formats. - Function: current-time-string #!OPTIONAL TIMESTAMP FORMAT Return a string defining TIMESTAMP according to the string FORMAT. If TIMESTAMP is undefined, the current time is used. The FORMAT string may include any of the formatting characters from the C library's `strftime(3)' function. If undefined a standard, fixed-width, format is used: (current-time-string) => "Wed Jun 2 18:07:53 1999" Some of the possible formatting substitutions include (this is copied from the GNU libc manual, *note (libc)Formatting Date and Time::.): `%a' The abbreviated weekday name according to the current locale. `%A' The full weekday name according to the current locale. `%b' The abbreviated month name according to the current locale. `%B' The full month name according to the current locale. `%c' The preferred date and time representation for the current locale. `%d' The day of the month as a decimal number (range `01' to `31'). `%H' The hour as a decimal number, using a 24-hour clock (range `00' to `23'). `%I' The hour as a decimal number, using a 12-hour clock (range `01' to `12'). `%j' The day of the year as a decimal number (range `001' to `366'). `%m' The month as a decimal number (range `01' to `12'). `%M' The minute as a decimal number. `%p' Either `am' or `pm', according to the given time value; or the corresponding strings for the current locale. `%S' The second as a decimal number. `%U' The week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week. `%W' The week number of the current year as a decimal number, starting with the first Monday as the first day of the first week. `%w' The day of the week as a decimal number, Sunday being `0'. `%x' The preferred date representation for the current locale, but without the time. `%X' The preferred time representation for the current locale, but with no date. `%y' The year as a decimal number, but without a century (range `00' to `99'). `%Y' The year as a decimal number, including the century. `%Z' The time zone or name or abbreviation (empty if the time zone can't be determined). `%%' A literal `%' character. (current-time-string nil "%Y-%m-%d") => "1999-06-02"  File: librep.info, Node: Parsing Dates, Prev: Formatting Dates, Up: Time and Date Parsing Dates ------------- The `date' Lisp library provides rudimentary support for parsing date and time descriptions to their individual components, and to timestamps. Evaluate the form `(require 'date)' to load this library. - Function: parse-date STRING #!OPTIONAL START Returns a vector encoding the date described by STRING. If START is defined, it specifies the index of the character in the string to start parsing from. Each element of the vector contains a separate component of the overall point in time described by the string. The indices of these elements are defined by the following constants: `date-vec-day-abbrev' The abbreviated name of the day of the week. `date-vec-day' The numeric day of the month, counting from one. `date-vec-month-abbrev' The abbreviated name of the month. `date-vec-month' The numeric month of the year, counting from January equals one. `date-vec-year' The numeric year. `date-vec-hour' The numeric hour of the day. `date-vec-minute' The numeric minute of the hour. `date-vec-second' The numeric second of the minute. `date-vec-timezone' If true, a string defining the timezone. `date-vec-epoch-time' The timestamp (*note Timestamps::.), including the effects of the timezone, if given. (current-time-string) => "Wed Jun 2 18:37:17 1999" (parse-date (current-time-string)) => ["Wed" 2 "Jun" 6 1999 18 37 17 0 (10744 . 67037)] (parse-date "1999-06-02") => ["Tue" 2 "Jun" 6 1999 0 0 0 0 (10744 . 0)] (parse-date "June 6, 1999") => ["" 0 "Jun" 6 1999 0 0 0 0 (10742 . 0)] (aref (parse-date "June 6, 1999") date-vec-epoch-time) => (10742 . 0) XXX provide more information on accepted formats, outputs for incomplete descriptions, etc...  File: librep.info, Node: i18n, Next: System Information, Prev: Time and Date, Up: The language Internationalisation ==================== `librep' has support for internationalisation (or i18n) of text messages, using the GNU `gettext' implementation (*note Overview: (gettext)Top.), a run-time library managing the mapping between text strings in the programmer's native language and in the language of the end user. Three functions are provided to access the message catalogues maintained by GNU `gettext'. Import the `rep.i18n.gettext' module to load them. - Function: _ STRING Attempt to find a native language equivalent of STRING. If no equivalent is found the original string is returned. Note that this function is always defined, even if the `gettext' module hasn't been required. In this case it always returns the original string. - Function: bindtextdomain DOMAIN DIRECTORY Tell `gettext' that message catalogues for message domain DOMAIN (a string) can be found under the directory called DIRECTORY. - Function: textdomain DOMAIN Note that any strings that are to be translated in the future (until the next call to `textdomain') are in the domain called DOMAIN (a string). The usual method of constructing message catalogue templates (`.pot' files) is to run `xgettext' on the C source files of the program (that have been annotated for i18n). librep provides the `rep-xgettext' program to perform the same task for files of Lisp code.  File: librep.info, Node: System Information, Next: User Information, Prev: i18n, Up: The language System Information ================== These definitions are all exported by the `rep.system' module. - Variable: operating-system A symbol naming the current operating system. The only current option is `unix'. - Function: system-name This function returns a string naming the host that the interpreter is running on. When possible this be a fully-qualified name (i.e. including the domain) - Variable: rep-build-id A string describing the environment under which `librep' was built. This will always have the format `DATE by USER@HOST, for ARCH.'. rep-build-id => "Mon May 17 1999 by john@tizer.dcs.warwick.ac.uk, for sparc-sun-solaris2.6." - Variable: rep-version A string describing the current release of `librep'. rep-version => "1.0"  File: librep.info, Node: User Information, Next: Environment Variables, Prev: System Information, Up: The language User Information ================ These functions are exported by the `rep.system' module. - Function: user-login-name This function returns a string containing the login name of the user. (user-login-name) => "john" - Function: user-full-name #!OPTIONAL REAL-NAME This function returns a string containing the `real' name of the user; the format of the string will depend on the host system. If REAL-NAME is a string, it defines the name that will be returned by subsequent calls to this function. (user-full-name) => "John Harper" - Function: user-home-directory #!OPTIONAL USER This function returns the home directory of the user whose login name is USER, or the current user if USER is undefined. The returned string will be as returned by `file-name-as-directory' (i.e. terminated by a `/' character under UNIX) (user-home-directory) => "/home/john/"  File: librep.info, Node: Environment Variables, Next: String Functions, Prev: User Information, Up: The language Environment Variables ===================== These functions are exported by the `rep.system' module. - Function: getenv VARIABLE-NAME This function returns the value (a string) of the environment variable called VARIABLE-NAME. If the specified variable doesn't exist false is returned. (getenv "OSTYPE") => "Linux" - Function: setenv VARIABLE-NAME NEW-VALUE This function sets the value of the environment variable called VARIABLE-NAME to NEW-VALUE. NEW-VALUE can either be a string containing the new contents of the variable or false, in which case the environment variable is deleted. - Function: unsetenv VARIABLE-NAME Deletes any variable in `process-environment' named VARIABLE-NAME. See also *Note Process Objects:: for the description of the `process-environment' variable.