This is bigloo.info, produced by makeinfo version 4.5 from bigloo.texi.

  This file documents Bigloo, an implementation of an extended version
of the Scheme programming language.

  Copyright (C) 1992-99, 2000-02 Manuel Serrano

     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
     MA 02111-1307, USA.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* bigloo: (bigloo).            The Bigloo Scheme compiler
END-INFO-DIR-ENTRY


File: bigloo.info,  Node: Socket,  Prev: Process,  Up: System Programming

Socket support
==============

  Bigloo defines sockets, on systems that support them, as first class
objects.  Sockets permits processes to communicate even if they are on
different machines. Sockets are useful for creating client-server
applications.  The implementation and this documentation are, to a great
extent copies of the STk [Gallesio95] socket support.

 - bigloo procedure: make-client-socket hostname port-number [buffered]
     `make-client-socket' returns a new socket object. This socket
     establishes a link between the running application listening on
     port PORT-NUMBER of HOSTNAME. If optional argument `buffered' is
     `#f' then the input port associated with the socket is unbuffered.
     This is useful for socket clients connected to servers that do not
     emit #\Newline character after emissions. If optional argument
     `buffered' is missing or is not to `#f' the input port uses a
     buffer.

     When a socket is used in unbufferized mode the characters
     available on the input port _must_ be read exclusively with
     `read-char' or `read-line'. It is forbidden to use `read' or any
     regular grammar.  This limitation is imposed by Rgc (see *Note
     Regular Parsing::) that intrinsicly associate buffers with regular
     grammars. If the current Rgc implementation is improved on the
     coming version this restriction will be suppressed.

 - bigloo procedure: socket? obj
 - bigloo procedure: socket-server? obj
 - bigloo procedure: socket-client? obj
     Returns `#t' if OBJ is a socket, a socket server a socket client.
     Otherwise returns `#f'. Socket servers and socket clients are
     sockets.

 - bigloo procedure: socket-hostname socket
     Returns a string which contains the name of the distant host
     attached to SOCKET. If SOCKET has been created with
     `make-client-socket' this procedure returns the official name of
     the distant machine used for connection. If SOCKET has been
     created with `make-server-socket', this function returns the
     official name of the client connected to the socket.  If no client
     has used yet the socket, this function returns `#f'.

 - bigloo procedure: socket-host-address socket
     Returns a string which contains the IP number of the distant host
     attached to SOCKET. If SOCKET has been created with
     `make-client-socket' this procedure returns the IP number of the
     distant machine used for connection. If SOCKET has been created
     with `make-server-socket', this function returns the address of
     the client connected to the socket.  If no client has used yet the
     socket, this function returns `#f'.

 - bigloo procedure: socket-local-address socket
     Returns a string which contains the IP number of the local host
     attached to SOCKET.

 - bigloo procedure: socket-port-number socket
     Returns the integer number of the port used for SOCKET.

 - bigloo procedure: socket-input socket
 - bigloo procedure: socket-output socket
     Returns the file port associated for reading or writing with the
     program connected with SOCKET. If no connection has already been
     established, these functions return `#f'.

     The following example shows how to make a client socket. Here we
     create a socket on port 13 of the machine "`kaolin.unice.fr'"(1)
     (*note Socket-Footnote-1::):
          (let ((s (make-client-socket "kaolin.unice.fr" 13)))
            (print "Time is: " (read-line (socket-input s)))
            (socket-shutdown  s))

 - bigloo procedure: make-server-socket [port-number]
     `make-server-socket' returns a new socket object. If PORT-NUMBER
     is specified, the socket is listening on the specified port;
     otherwise, the communication port is choosen by the system.

 - bigloo procedure: socket-accept socket [buffered]
     The function `socket-accept' replaces the former Bigloo functions
     `socket-accept-connection' and `socket-dup'.  `socket-accept'
     waits for a client connection on the given SOCKET. It returns a
     `client-socket'.  If no client is already waiting for a
     connection, this procedure blocks its caller; otherwise, the first
     connection request on the queue of pending connections is
     connected to SOCKET. This procedure must be called on a server
     socket created with `make-server-socket'.  If optional argument
     `buffered' is `#f' then the input port associated with the socket
     is unbuffered. This is useful for socket clients connected to
     servers that do not emit #\Newline character after emissions. If
     optional argument `buffered' is missing or is not to `#f' the
     input port uses a buffer. The result of `socket-accept' is
     undefined.

     _Note:_ When a socket is used in unbufferized mode the characters
     available on the input port _must_ be read exclusively with
     `read-char' or `read-line'. It is forbidden to use `read' or any
     regular grammar.  This limitation is imposed by Rgc (see *Note
     Regular Parsing::) that intrinsicly associate buffers with regular
     grammars. If the current Rgc implementation is improved on the
     coming version this restriction will be suppressed.

     The following exemple is a simple server which waits for a
     connection on the port 1234(2) (*note Socket-Footnote-2::). Once
     the connection with the distant program is established, we read a
     line on the input port associated to the socket and we write the
     length of this line on its output port.
          (let* ((s (make-server-socket 1234))
                 (s2 (socket-accept s)))
            (let ((l (read-line (socket-input s2))))
              (fprint (socket-output s) "Length is: " (string-length l))
              (flush-output-port (socket-output s2)))
            (socket-close s)
            (socket-shutdown s))

 - bigloo procedure: socket-accept-connection socket [buffered]
     `socket-accept-connection' waits for a client connection on the
     given SOCKET. If no client is already waiting for a connection,
     this procedure blocks its caller; otherwise, the first connection
     request on the queue of pending connections is connected to SOCKET.

     _note:_This function is part of the old Bigloo API. It was
     intended to be used in conjunction with
     `socket-accept-connection'. The new API made of `socket-accept'
     and `socket-close' should be preferred.

     This procedure must be called on a server socket created with
     `make-server-socket'.  If optional argument `buffered' is `#f'
     then the input port associated with the socket is unbuffered. This
     is useful for socket clients connected to servers that do not emit
     #\Newline character after emissions. If optional argument
     `buffered' is missing or is not to `#f' the input port uses a
     buffer. The result of `socket-accept-connection' is undefined.

     _Note:_ When a socket is used in unbufferized mode the characters
     available on the input port _must_ be read exclusively with
     `read-char' or `read-line'. It is forbidden to use `read' or any
     regular grammar.  This limitation is imposed by Rgc (see *Note
     Regular Parsing::) that intrinsicly associate buffers with regular
     grammars. If the current Rgc implementation is improved on the
     coming version this restriction will be suppressed.

     The following exemple is a simple server which waits for a
     connection on the port 1234(3) (*note Socket-Footnote-3::). Once
     the connection with the distant program is established, we read a
     line on the input port associated to the socket and we write the
     length of this line on its output port.
          (let ((s (make-server-socket 1234)))
            (socket-accept-connection s)
            (let ((l (read-line (socket-input s))))
              (fprint (socket-output s) "Length is: " (string-length l))
              (flush-output-port (socket-output s)))
            (socket-shutdown s))

 - bigloo procedure: socket-close socket
     The function `socket-close' closes the connection established with
     a `socket-client'.

 - bigloo procedure: socket-shutdown socket [close]
     `Socket-shutdown' shutdowns the connection associated to SOCKET.
     CLOSE is a boolean; it indicates if the socket must be closed or
     not, when the connection is destroyed. Closing the socket forbids
     further connections on the same port with the
     `socket-accept-connection' procedure. Omitting a value for CLOSE
     implies the closing of socket.  The result of `socket-shutdown' is
     undefined.

     The following example shows a simple server: when there is a new
     connection on the port number 1234, the server displays the first
     line sent to it by the client, discards the others and go back
     waiting for further client connections.
          (let ((s (make-server-socket 1234)))
            (let loop ()
              (socket-accept-connection s)
              (print "I've read: " (read-line (socket-input s)))
              (socket-shutdown s #f)
              (loop)))

 - bigloo procedure: socket-down? socket
     Returns `#t' if SOCKET has been previously closed with
     `socket-shutdown'. It returns `#f' otherwise.

 - bigloo procedure: socket-dup socket
     Returns a copy of SOCKET.

     _note:_This function is part of the old Bigloo API. It was
     intended to be used in conjunction with
     `socket-accept-connection'. The new API made of `socket-accept'
     and `socket-close' should be preferred.

     The original and the copy socket can be used interchangeably.
     However, if a new connection is accepted on one socket, the
     characters exchanged on this socket are not visible on the other
     socket.  Duplicating a socket is useful when a server must accept
     multiple simultaneous connections.  The following example creates
     a server listening on port 1234. This server is duplicated and,
     once two clients are present, a message is sent on both
     connections.
          (define s1 (make-server-socket 1234))
          (define s2 (socket-dup s1))
          (socket-accept-connection s1)
          (socket-accept-connection s2)
          ;; blocks until two clients are present
          (display #"Hello,\n" (socket-output s1))
          (display #"world\n"  (socket-output s2))
          (flush-output-port (socket-output s1))
          (flush-output-port (socket-output s2))

  Here is another example of making use of sockets:

     (define s1 (make-server-socket))
     (define s2 #unspecified)
     
     (dynamic-wind
        ;; Init: Launch an xterm with telnet running
        ;; on the s listening port and connect
        (lambda ()
           (run-process "/usr/X11R6/bin/xterm" "-display" ":0" "-e" "telnet" "localhost"
     		   (number->string (socket-port-number s1)))
           (set! s2 (socket-accept s1))
           (display #"\nWelcome on the socket REPL.\n\n> " (socket-output s2))
           (flush-output-port (socket-output s2)))
     
        ;; Action: A toplevel like loop
        (lambda ()
           (let loop ()
     	 (let ((obj (eval (read (socket-input s2)))))
     	    (fprint (socket-output s2) "; Result: " obj)
     	    (display "> " (socket-output s2))
     	    (flush-output-port (socket-output s2))
     	    (loop))))
     
        ;; Termination: We go here when
        ;;     -a: an error occurs
        ;;     -b: connection is closed
        (lambda ()
           (print #"Shutdown ......\n")
           (socket-close s2)
           (socket-shutdown s1)))

  Here is a second example that uses sockets. It implements a
client-server architecture and it uses unbufferized (see
`socket-accept') input ports.

  First, here is the code of the client:

     (module client)
     
     (let* ((s (make-client-socket "localhost" 8080 #f))
            (p (socket-output s)))
        (display "string" p)
        (newline p)
        (display "abc" p)
        (flush-output-port p)
        (let loop ()
           (loop)))

  Then, here is the code of the server:

     (module server)
     
     (let* ((s (make-server-socket 8080))
            (s2 (socket-accept s #f)))
        (let ((pin (socket-input s2)))
           (let loop ()
              (display (read-char pin))
              (flush-output-port (current-output-port))
              (loop))))

  At, to conclude here the source code for a server waiting for multiple
consecutive connections:

     (define (main argv)
        (let ((n (if (pair? (cdr argv))
                     (string->integer (cadr argv))
                     10))
     	 (s (make-server-socket)))
           (print "s: " s)
           (let loop ((i 0))
              (if (<fx i n)
                  (let ((s2 (socket-accept s)))
     		(print "i: " i " " s2)
     		(print (read-line (socket-input s2)))
     		(socket-close s2)
                     (loop (+fx i 1)))
     	     (socket-shutdown s)))))


File: bigloo.info,  Node: Socket-Footnotes,  Up: Socket

  (1) Port 13 is generally used for testing: making a connection to it
permits to know the distant system's idea of the time of day.

  (2) Under Unix, you can simply connect to   listening socket with the
`telnet' command. With the given   example, this can be   achived by
typing the following command in a window shell:   `$ telnet localhost
1234'

  (3) Under Unix, you can simply connect to   listening socket with the
`telnet' command. With the given   example, this can be   achived by
typing the following command in a window shell:   `$ telnet localhost
1234'


File: bigloo.info,  Node: Date,  Next: Posix Regular Expressions,  Prev: System Programming,  Up: Standard Library

Date
====

 - bigloo procedure: date? obj
     Returns `#t' if and only if OBJ is a _date_ as returned by
     `make-date', `current-date', or `seconds->date'. It returns `#f'
     otherwise.

 - bigloo procedure: make-date sec min hour day mon year [timezone]
          [dst]
     Creates a `date' object from the integer value passed as argument.

     Example:
          (write (make-date 0 22 17 5 2 2003 0))
            -| #<date:Wed Feb  5 17:22:00 2003>

     This argument DATE is either `-1' when the information is not
     available, `0' when daylight saving is disabled, `1' when daylight
     saving is enabled.

 - bigloo procedure: date-copy date [s] [m] [h] [d] [m] [year]
     Creates a new date from the argument DATE.

     Example:
          (date-copy (current-date) 1 0 0)


 - bigloo procedure: current-date
     Returns a `date' object representing the current date.

 - bigloo procedure: current-seconds
     Returns an `elong' integer representing the current date expressed
     in seconds.

 - bigloo procedure: date->seconds
 - bigloo procedure: seconds->date
     Convert from `date' and `elong'.

 - bigloo procedure: date->string date
 - bigloo procedure: date->utc-string date
 - bigloo procedure: seconds->string elong
 - bigloo procedure: seconds->utc-string elong
     Construct a textual representation of the date passed in argument

 - bigloo procedure: date-second date
     Returns the number of seconds of a date, in the range `0...59'.

 - bigloo procedure: date-minute date
     Returns the minute of a date, in the range `0...59'.

 - bigloo procedure: date-hour date
     Returns the hour of a date, in the range `0...23'.

 - bigloo procedure: date-day date
     Returns the day of a date, in the range `1...31'.

 - bigloo procedure: date-wday date
     Returns the week day of a date, in the range `1...7'.

 - bigloo procedure: date-yday date
     Returns the year day of a date, in the range `1...366'.

 - bigloo procedure: date-month date
     Returns the month of a date, in the range `1...12'.

 - bigloo procedure: date-year date
     Returns the year of a date.

 - bigloo procedure: date-timezone date
     Returns the timezone of a date.

 - bigloo procedure: date-is-dst date
     Returns `-1' if the information is not available, `0' is the date
     does not contain daylight saving adjustment, `1' if it contains a
     daylight saving adjustment.

 - bigloo procedure: +second elong1 elong2
 - bigloo procedure: *second elong1 elong2
 - bigloo procedure: -second elong1 elong2
 - bigloo procedure: =second elong1 elong2
 - bigloo procedure: >second elong1 elong2
 - bigloo procedure: >=second elong1 elong2
 - bigloo procedure: <second elong1 elong2
 - bigloo procedure: <=second elong1 elong2
     Arithmetic operators on seconds.

 - bigloo procedure: integer->second
     Converts a Bigloo fixnum integer into a second number.

 - bigloo procedure: day-seconds
     Returns the number of seconds contained in one day.

 - bigloo procedure: day-name int
 - bigloo procedure: day-aname int
     Return the name and the abbreviated name of a week day.

 - bigloo procedure: month-name int
 - bigloo procedure: month-aname int
     Return the name and the abbreviated name of a month.

 - bigloo procedure: leap-year? int
     Returns `#t' if and only if the year INT is a leap year.  Returns
     `#f' otherwise.


File: bigloo.info,  Node: Posix Regular Expressions,  Prev: Date,  Up: Standard Library

Posix Regular Expressions
=========================

  This whole section has been written by Dorai Sitaram.  It consists in
the documentation of the `pregexp' package that may be found at
<http://www.ccs.neu.edu/~dorai/pregexp/pregexp.html>.


  The regexp notation supported is modeled on Perl's, and includes such
powerful directives as numeric and nongreedy quantifiers, capturing and
non-capturing clustering, POSIX character classes, selective case- and
space-insensitivity, backreferences, alternation, backtrack pruning,
positive and negative lookahead and lookbehind, in addition to the more
basic directives familiar to all regexp users.  A _regexp_ is a string
that describes a pattern.  A regexp matcher tries to _match_ this
pattern against (a portion of) another string, which we will call the
_text string_.  The text string is treated as raw text and not as a
pattern.

  Most of the characters in a regexp pattern are meant to match
occurrences of themselves in the text string.  Thus, the pattern
`"abc"' matches a string that contains the characters `a', `b', `c' in
succession.

  In the regexp pattern, some characters  act as _metacharacters_, and
some character sequences act as _metasequences_.  That is, they specify
something other than their literal selves.  For example, in the pattern
`"a.c"', the characters `a' and `c' do stand for themselves but the
_metacharacter_ `.' can match _any_ character (other than newline).
Therefore, the pattern `"a.c"' matches an `a', followed by _any_
character, followed by a `c'.

  If we needed to match the character `.' itself, we _escape_ it, ie,
precede it with a backslash (`\').  The character sequence `\.' is thus
a _metasequence_, since it doesn't match itself but rather just `.'.
So, to match `a' followed by a literal `.' followed by `c', we use the
regexp pattern `"a\\.c"'.(1) (*note Posix Regular
Expressions-Footnote-1::) Another example of a metasequence is `\t',
which is a readable way to represent the tab character.

  We will call the string representation of a regexp the _U-regexp_,
where _U_ can be taken to mean _Unix-style_ or _universal_, because this
notation for regexps is universally familiar.  Our implementation uses
an intermediate tree-like representation called the _S-regexp_, where
_S_ can stand for _Scheme_, _symbolic_, or _s-expression_.  S-regexps
are more verbose and less readable than U-regexps, but they are much
easier for Scheme's recursive procedures to navigate.

* Menu:

* Regular Expressions Procedures::
* The Regular Expressions Pattern Language::
* An Extended Example::


File: bigloo.info,  Node: Posix Regular Expressions-Footnotes,  Up: Posix Regular Expressions

  (1) The double backslash is an artifact of Scheme strings, not the
regexp pattern itself.  When we want a literal backslash inside a
Scheme string, we must escape it so that it shows up in the string at
all. Scheme strings use backslash as the escape character, so we end up
with two backslashes -- one Scheme-string backslash to escape the
regexp backslash, which then escapes the dot.  Another character that
would need escaping inside a Scheme string is `"'.


File: bigloo.info,  Node: Regular Expressions Procedures,  Next: The Regular Expressions Pattern Language,  Up: Posix Regular Expressions

Regular Expressions Procedures
------------------------------

  Four procedures `pregexp', `pregexp-match-positions',
`pregexp-match', `pregexp-replace', and `pregexp-replace*' enable
compilation and matching of regular expressions.

 - bigloo procedure: pregexp U-regexp
     The procedure `pregexp' takes a U-regexp, which is a string, and
     returns an S-regexp, which is a tree.

          (pregexp "c.r") => (:sub (:or (:seq #\c :any #\r)))

     There is rarely any need to look at the S-regexps returned by
     `pregexp'.

 - bigloo procedure: pregexp-match-positions regexp string
     The procedure `pregexp-match-positions' takes a regexp pattern and
     a text string, and returns a _match_ if the pattern _matches_ the
     text string.  The pattern may be either a U- or an S-regexp.
     (`pregexp-match-positions' will internally compile a U-regexp to
     an S-regexp before proceeding with the matching.  If you find
     yourself calling `pregexp-match-positions' repeatedly with the same
     U-regexp, it may be advisable to explicitly convert the latter
     into an S-regexp once beforehand, using `pregexp', to save
     needless recompilation.)

     `pregexp-match-positions' returns `#f' if the pattern did not
     match the string; and a list of _index pairs_ if it did match. Eg,

          (pregexp-match-positions "brain" "bird")
           => #f
          (pregexp-match-positions "needle" "hay needle stack")
           => ((4 . 10))

     In the second example, the integers 4 and 10 identify the
     substring that was matched. 1 is the starting (inclusive) index
     and 2 the ending (exclusive) index of the matching substring.

          (substring "hay needle stack" 4 10)
           => "needle"

     Here, `pregexp-match-positions''s return list contains only one
     index pair, and that pair represents the entire substring matched
     by the regexp.  When we discuss _subpatterns_ later, we will see
     how a single match operation can yield a list of _submatches_.

     `pregexp-match-positions' takes optional third and fourth
     arguments that specify the indices of the text string within which
     the matching should take place.

          (pregexp-match-positions "needle"
            "his hay needle stack -- my hay needle stack -- her hay needle stack"
            24 43)
           => ((31 . 37))

     Note that the returned indices are still reckoned relative to the
     full text string.

 - bigloo procedure: pregexp-match regexp string
     The procedure `pregexp-match' is called like
     `pregexp-match-positions' but instead of returning index pairs it
     returns the matching substrings:

          (pregexp-match "brain" "bird")
           => #f
          (pregexp-match "needle" "hay needle stack")
           => ("needle")

     `pregexp-match' also takes optional third and fourth arguments,
     with the same meaning as does `pregexp-match-positions'.

 - bigloo procedure: pregexp-replace regexp string1 string2
     The procedure `pregexp-replace' replaces the matched portion of
     the text string by another string.  The first argument is the
     regexp, the second the text string, and the third is the _insert
     string_ (string to be inserted).

          (pregexp-replace "te" "liberte" "ty")
           => "liberty"

     If the pattern doesn't occur in the text string, the returned
     string is identical (`eq?') to the text string.

 - bigloo procedure: pregexp-replace* regexp string1 string2
     The procedure `pregexp-replace*' replaces _all_ matches in the
     text string by the insert string:

          (pregexp-replace* "te" "liberte egalite fraternite" "ty")
           => "liberty egality fratyrnity"

     As with `pregexp-replace', if the pattern doesn't occur in the text
     string, the returned string is identical (`eq?') to the text
     string.

 - bigloo procedure: pregexp-split regexp string
     The procedure `pregexp-split' takes two arguments, a regexp
     pattern and a text string, and returns a list of substrings of the
     text string, where the pattern identifies the delimiter separating
     the substrings.

          (pregexp-split ":" "/bin:/usr/bin:/usr/bin/X11:/usr/local/bin")
           => ("/bin" "/usr/bin" "/usr/bin/X11" "/usr/local/bin")
          
          (pregexp-split " " "pea soup")
           => ("pea" "soup")

     If the first argument can match an empty string, then the list of
     all the single-character substrings is returned.

          (pregexp-split "" "smithereens")
           => ("s" "m" "i" "t" "h" "e" "r" "e" "e" "n" "s")

     To identify one-or-more spaces as the delimiter, take care to use
     the regexp `" +"', not `" *"'.

          (pregexp-split " +" "split pea     soup")
           => ("split" "pea" "soup")
          
          (pregexp-split " *" "split pea     soup")
           => ("s" "p" "l" "i" "t" "p" "e" "a" "s" "o" "u" "p")

 - bigloo procedure: regexp-quote string
     The procedure `pregexp-quote' takes an arbitrary STRING and
     returns a U-regexp (string) that precisely represents it. In
     particular, characters in the input string that could serve as
     regexp metacharacters are escaped with a backslash, so that they
     safely match only themselves.

          (pregexp-quote "cons")
           => "cons"
          
          (pregexp-quote "list?")
           => "list\\?"

     `pregexp-quote' is useful when building a composite regexp from a
     mix of regexp strings and verbatim strings.


File: bigloo.info,  Node: The Regular Expressions Pattern Language,  Next: An Extended Example,  Prev: Regular Expressions Procedures,  Up: Posix Regular Expressions

Regular Expressions Pattern Language
------------------------------------

* Menu:

* Basic assertions::
* Characters and character classes::
* Quantifiers::
* Clusters::
* Alternation::
* Backtracking::
* Looking ahead and behind::

  Here is a complete description of the regexp pattern language
recognized by the `pregexp' procedures.


File: bigloo.info,  Node: Basic assertions,  Next: Characters and character classes,  Up: The Regular Expressions Pattern Language

Basic assertions
................

  The _assertions_ `^' and `$' identify the beginning and the end of
the text string respectively.  They ensure that their adjoining regexps
match at one or other end of the text string.  Examples:

     (pregexp-match-positions "^contact" "first contact") => #f

The regexp fails to match because `contact' does not occur at the
beginning of the text string.

     (pregexp-match-positions "laugh$" "laugh laugh laugh laugh") => ((18 . 23))

The regexp matches the _last_ `laugh'.

  The metasequence `\b' asserts that a _word boundary_ exists.

     (pregexp-match-positions "yack\\b" "yackety yack") => ((8 . 12))

The `yack' in `yackety' doesn't end at a word boundary so it isn't
matched.  The second `yack' does and is.

  The metasequence `\B' has the opposite effect to `\b'.  It asserts
that a word boundary does not exist.

     (pregexp-match-positions "an\\B" "an analysis") => ((3 . 5))

The `an' that doesn't end in a word boundary is matched.


File: bigloo.info,  Node: Characters and character classes,  Next: Quantifiers,  Prev: Basic assertions,  Up: The Regular Expressions Pattern Language

Characters and character classes
................................

  Typically a character in the regexp matches the same character in the
text string.  Sometimes it is necessary or convenient to use a regexp
metasequence to refer to a single character.  Thus, metasequences `\n',
`\r', `\t', and `\.'  match the newline, return, tab and period
characters respectively.

  The _metacharacter_ period (`.') matches _any_ character other than
newline.

     (pregexp-match "p.t" "pet") => ("pet")

It also matches `pat', `pit', `pot', `put', and `p8t' but not `peat' or
`pfffft'.

  A _character class_ matches any one character from a set of
characters.  A typical format for this is the _bracketed character
class_ `['...`]', which matches any one character from the non-empty
sequence of characters enclosed within the brackets.(1) (*note
Characters and character classes-Footnote-1::)  Thus `"p[aeiou]t"'
matches `pat', `pet', `pit', `pot', `put' and nothing else.

  Inside the brackets, a hyphen (`-') between two characters specifies
the ascii range between the characters.  Eg, `"ta[b-dgn-p]"' matches
`tab', `tac', `tad', _and_ `tag', _and_ `tan', `tao', `tap'.

  An initial caret (`^') after the left bracket inverts the set
specified by the rest of the contents, ie, it specifies the set of
characters _other than_ those identified in the brackets.  Eg,
`"do[^g]"' matches all three-character sequences starting with `do'
except `dog'.

  Note that the metacharacter `^' inside brackets means something quite
different from what it means outside.  Most other metacharacters (`.',
`*', `+', `?', etc) cease to be metacharacters when inside brackets,
although you may still escape them for peace of mind.  `-' is a
metacharacter only when it's inside brackets, and neither the first nor
the last character.

  Bracketed character classes cannot contain other bracketed character
classes (although they contain certain other types of character classes
-- see below).  Thus a left bracket (`[') inside a bracketed character
class doesn't have to be a metacharacter; it can stand for itself.  Eg,
`"[a[b]"' matches `a', `[', and `b'.

  Furthermore, since empty bracketed character classes are disallowed, a
right bracket (`]') immediately occurring after the opening left
bracket also doesn't need to be a metacharacter.  Eg, `"[]ab]"' matches
`]', `a', and `b'.

Some frequently used character classes
......................................

  Some standard character classes can be conveniently represented as
metasequences instead of as explicit bracketed expressions.  `\d'
matches a digit (`[0-9]'); `\s' matches a whitespace character; and
`\w' matches a character that could be part of a "word".(2) (*note
Characters and character classes-Footnote-2::)

  The upper-case versions of these metasequences stand for the
inversions of the corresponding character classes.  Thus `\D' matches a
non-digit, `\S' a non-whitespace character, and `\W' a non-"word"
character.

  Remember to include a double backslash when putting these
metasequences in a Scheme string:

     (pregexp-match "\\d\\d" "0 dear, 1 have 2 read catch 22 before 9") => ("22")

  These character classes can be used inside a bracketed expression.
Eg, `"[a-z\\d]"' matches a lower-case letter or a digit.

POSIX character classes
.......................

  A _POSIX character class_ is a special metasequence of the form
`[:'...`:]' that can be used only inside a bracketed expression.  The
POSIX classes supported are

     `[:alnum:]'  letters and digits
     `[:alpha:]'  letters
     `[:algor:]'  the letters `c', `h', `a' and `d'
     `[:ascii:]'  7-bit ascii characters
     `[:blank:]'  widthful whitespace, ie, space and tab
     `[:cntrl:]'  ``control'' characters, viz, those with code `<' 32
     `[:digit:]'  digits, same as `\d'
     `[:graph:]'  characters that use ink
     `[:lower:]'  lower-case letters
     `[:print:]'  ink-users plus widthful whitespace
     `[:space:]'  whitespace, same as `\s'
     `[:upper:]'  upper-case letters
     `[:word:]'   letters, digits, and underscore, same as `\w'
     `[:xdigit:]' hex digits

For example, the regexp  `"[[:alpha:]_]"' matches a letter or
underscore.

     (pregexp-match "[[:alpha:]_]" "--x--") => ("x")
     (pregexp-match "[[:alpha:]_]" "--_--") => ("_")
     (pregexp-match "[[:alpha:]_]" "--:--") => #f

  The POSIX class notation is valid _only_ inside a bracketed
expression.  For instance, `[:alpha:]', when not inside a bracketed
expression, will _not_ be read as the letter class.  Rather it is (from
previous principles) the character class containing the characters `:',
`a', `l', `p', `h'.

     (pregexp-match "[:alpha:]" "--a--") => ("a")
     (pregexp-match "[:alpha:]" "--_--") => #f

  By placing a caret (`^') immediately after `[:', you get the
inversion of that POSIX character class.  Thus, `[:^alpha]' is the
class containing all characters except the letters.


File: bigloo.info,  Node: Characters and character classes-Footnotes,  Up: Characters and character classes

  (1) Requiring a bracketed character class to be non-empty is not a
limitation, since an empty character class can be more easily
represented by an empty string.

  (2) Following regexp custom, we identify "word" characters as
`[A-Za-z0-9_]', although these are too restrictive for what a Schemer
might consider a "word".


File: bigloo.info,  Node: Quantifiers,  Next: Clusters,  Prev: Characters and character classes,  Up: The Regular Expressions Pattern Language

Quantifiers
...........

  The _quantifiers_ `*', `+', and `?' match respectively: zero or more,
one or more, and zero or one instances of the preceding subpattern.

     (pregexp-match-positions "c[ad]*r" "cadaddadddr") => ((0 . 11))
     (pregexp-match-positions "c[ad]*r" "cr")          => ((0 . 2))
     
     (pregexp-match-positions "c[ad]+r" "cadaddadddr") => ((0 . 11))
     (pregexp-match-positions "c[ad]+r" "cr")          => #f
     
     (pregexp-match-positions "c[ad]?r" "cadaddadddr") => #f
     (pregexp-match-positions "c[ad]?r" "cr")          => ((0 . 2))
     (pregexp-match-positions "c[ad]?r" "car")         => ((0 . 3))

Numeric quantifiers
...................

  You can use braces to specify much finer-tuned quantification than is
possible with `*', `+', `?'.

  The quantifier `{m}' matches _exactly_ `m' instances of the preceding
_subpattern_.  `m' must be a nonnegative integer.

  The quantifier `{m,n}' matches at least `m' and at most `n'
instances.  `m' and `n' are nonnegative integers with `m <= n'.  You
may omit either or both numbers, in which case `m' defaults to 0 and
`n' to infinity.

  It is evident that `+' and `?' are abbreviations for `{1,}' and
`{0,1}' respectively.  `*' abbreviates `{,}', which is the same as
`{0,}'.

     (pregexp-match "[aeiou]{3}" "vacuous")  => ("uou")
     (pregexp-match "[aeiou]{3}" "evolve")   => #f
     (pregexp-match "[aeiou]{2,3}" "evolve") => #f
     (pregexp-match "[aeiou]{2,3}" "zeugma") => ("eu")

Non-greedy quantifiers
......................

  The quantifiers described above are _greedy_, ie, they match the
maximal number of instances that would still lead to an overall match
for the full pattern.

     (pregexp-match "<.*>" "<tag1> <tag2> <tag3>")
      => ("<tag1> <tag2> <tag3>")

  To make these quantifiers _non-greedy_, append a `?' to them.
Non-greedy quantifiers match the minimal number of instances needed to
ensure an overall match.

     (pregexp-match "<.*?>" "<tag1> <tag2> <tag3>") => ("<tag1>")

  The non-greedy quantifiers are respectively: `*?', `+?', `??',
`{m}?', `{m,n}?'.  Note the two uses of the metacharacter `?'.


File: bigloo.info,  Node: Clusters,  Next: Alternation,  Prev: Quantifiers,  Up: The Regular Expressions Pattern Language

Clusters
........

  _Clustering_, ie, enclosure within parens `('...`)', identifies the
enclosed _subpattern_ as a single entity.  It causes the matcher to
_capture_ the _submatch_, or the portion of the string matching the
subpattern, in addition to the overall match.

     (pregexp-match "([a-z]+) ([0-9]+), ([0-9]+)" "jan 1, 1970")
      => ("jan 1, 1970" "jan" "1" "1970")

  Clustering also causes a following quantifier to treat the entire
enclosed subpattern as an entity.

     (pregexp-match "(poo )*" "poo poo platter") => ("poo poo " "poo ")

  The number of submatches returned is always equal to the number of
subpatterns specified in the regexp, even if a particular subpattern
happens to match more than one substring or no substring at all.

     (pregexp-match "([a-z ]+;)*" "lather; rinse; repeat;")
      => ("lather; rinse; repeat;" " repeat;")

Here the `*'-quantified subpattern matches three times, but it is the
last submatch that is returned.

  It is also possible for a quantified subpattern to fail to match,
even if the overall pattern matches.  In such cases, the failing
submatch is represented by `#f'.

     (define date-re
       ;match `month year' or `month day, year'.
       ;subpattern matches day, if present
       (pregexp "([a-z]+) +([0-9]+,)? *([0-9]+)"))
     
     (pregexp-match date-re "jan 1, 1970")
      => ("jan 1, 1970" "jan" "1," "1970")
     
     (pregexp-match date-re "jan 1970")
      => ("jan 1970" "jan" #f "1970")

Backreferences
..............

  Submatches can be used in the insert string argument of the procedures
`pregexp-replace' and `pregexp-replace*'.  The insert string can use
`\n' as a _backreference_ to refer back to the _n_th submatch, ie, the
substring that matched the _n_th subpattern.  `\0' refers to the entire
match, and it can also be specified as `\&'.

     (pregexp-replace "_(.+?)_"
       "the _nina_, the _pinta_, and the _santa maria_"
       "*\\1*")
      => "the *nina*, the _pinta_, and the _santa maria_"
     
     (pregexp-replace* "_(.+?)_"
       "the _nina_, the _pinta_, and the _santa maria_"
       "*\\1*")
      => "the *nina*, the *pinta*, and the *santa maria*"
     
     ;recall: \S stands for non-whitespace character
     
     (pregexp-replace "(\\S+) (\\S+) (\\S+)"
       "eat to live"
       "\\3 \\2 \\1")
      => "live to eat"

  Use `\\' in the insert string to specify a literal backslash.  Also,
`\$' stands for an empty string, and is useful for separating a
backreference `\n' from an immediately following number.

  Backreferences can also be used within the regexp pattern to refer
back to an already matched subpattern in the pattern.  `\n' stands for
an exact repeat of the _n_th submatch.(1) (*note Clusters-Footnote-1::)

     (pregexp-match "([a-z]+) and \\1"
       "billions and billions")
      => ("billions and billions" "billions")

Note that the backreference is not simply a repeat of the previous
subpattern.  Rather it is a repeat of _the particular  substring
already matched by the subpattern_.

  In the above example, the backreference can only match `billions'.
It will not match `millions', even though the subpattern it harks back
to -- `([a-z]+)' --  would have had no problem doing so:

     (pregexp-match "([a-z]+) and \\1"
       "billions and millions")
      => #f

  The following corrects doubled words:

     (pregexp-replace* "(\\S+) \\1"
       "now is the the time for all good men to to come to the aid of of the party"
       "\\1")
      => "now is the time for all good men to come to the aid of the party"

  The following marks all immediately repeating patterns in a number
string:

     (pregexp-replace* "(\\d+)\\1"
       "123340983242432420980980234"
       "{\\1,\\1}")
      => "12{3,3}40983{24,24}3242{098,098}0234"

Non-capturing clusters
......................

  It is often required to specify a cluster (typically for
quantification) but without triggering the capture of submatch
information.  Such clusters are called _non-capturing_.  In such cases,
use `(?:' instead of `(' as the cluster opener.  In the following
example, the  non-capturing cluster eliminates the "directory" portion
of a given pathname, and the capturing cluster  identifies the basename.

     (pregexp-match "^(?:[a-z]*/)*([a-z]+)$"
       "/usr/local/bin/mzscheme")
      => ("/usr/local/bin/mzscheme" "mzscheme")

Cloisters
.........

  The location between the `?' and the `:' of a non-capturing cluster
is called a _cloister_.(2) (*note Clusters-Footnote-2::)  You can put
_modifiers_ there that will cause the enclustered subpattern to be
treated specially.  The modifier `i' causes the subpattern to match
_case-insensitively_:

     (pregexp-match "(?i:hearth)" "HeartH") => ("HeartH")

  The modifier `x' causes the subpattern to match
_space-insensitively_, ie, spaces and comments within the subpattern
are ignored.  Comments are introduced as usual with a semicolon (`;')
and extend till the end of the line.  If you need to include a literal
space or semicolon in a space-insensitized subpattern, escape it with a
backslash.

     (pregexp-match "(?x: a   lot)" "alot")
      => ("alot")
     
     (pregexp-match "(?x: a  \\  lot)" "a lot")
      => ("a lot")
     
     (pregexp-match "(?x:
        a \\ man  \\; \\   ; ignore
        a \\ plan \\; \\   ; me
        a \\ canal         ; completely
        )"
      "a man; a plan; a canal")
      => ("a man; a plan; a canal")

The global variable `*pregexp-comment-char*' contains the comment
character (`#\;').  For Perl-like comments,

     (set! *pregexp-comment-char* #\#)

  You can put more than one modifier in the cloister.

     (pregexp-match "(?ix:
        a \\ man  \\; \\   ; ignore
        a \\ plan \\; \\   ; me
        a \\ canal         ; completely
        )"
      "A Man; a Plan; a Canal")
      => ("A Man; a Plan; a Canal")

  A minus sign before a modifier inverts its meaning.  Thus, you can
use `-i' and `-x' in a _subcluster_ to overturn the insensitivities
caused by an enclosing cluster.

     (pregexp-match "(?i:the (?-i:TeX)book)"
       "The TeXbook")
      => ("The TeXbook")

This regexp will allow any casing for `the' and `book' but insists that
`TeX' not be differently cased.


File: bigloo.info,  Node: Clusters-Footnotes,  Up: Clusters

  (1) `\0', which is useful in an insert string, makes no  sense within
the regexp pattern, because the entire regexp has not matched yet that
you could refer back to it.

  (2) A useful, if terminally cute, coinage from the abbots of Perl.


File: bigloo.info,  Node: Alternation,  Next: Backtracking,  Prev: Clusters,  Up: The Regular Expressions Pattern Language

Alternation
...........

  You can specify a list of _alternate_ subpatterns by separating them
by `|'.   The `|' separates subpatterns in the nearest enclosing cluster
(or in the entire pattern string if there are no enclosing parens).

     (pregexp-match "f(ee|i|o|um)" "a small, final fee")
      => ("fi" "i")
     
     (pregexp-replace* "([yi])s(e[sdr]?|ing|ation)"
        "it is energising to analyse an organisation
        pulsing with noisy organisms"
        "\\1z\\2")
      => "it is energizing to analyze an organization
        pulsing with noisy organisms"

  Note again that if you wish to use clustering merely to specify a
list of alternate subpatterns but do not want the submatch, use `(?:'
instead of `('.

     (pregexp-match "f(?:ee|i|o|um)" "fun for all")
      => ("fo")

  An important thing to note about alternation is that the leftmost
matching alternate is picked regardless of its length.  Thus, if one of
the alternates is a prefix of a later alternate, the latter may not have
a chance to match.

     (pregexp-match "call|call-with-current-continuation"
       "call-with-current-continuation")
      => ("call")

  To allow the longer alternate to have a shot at matching, place it
before the shorter one:

     (pregexp-match "call-with-current-continuation|call"
       "call-with-current-continuation")
      => ("call-with-current-continuation")

  In any case, an overall match for the entire regexp is always
preferred to an overall nonmatch.  In the following, the longer
alternate still wins, because its preferred shorter prefix fails to
yield an overall match.

     (pregexp-match "(?:call|call-with-current-continuation) constrained"
       "call-with-current-continuation constrained")
      => ("call-with-current-continuation constrained")


File: bigloo.info,  Node: Backtracking,  Next: Looking ahead and behind,  Prev: Alternation,  Up: The Regular Expressions Pattern Language

Backtracking
............

  We've already seen that greedy quantifiers match the maximal number
of times, but the overriding priority is that the overall match
succeed.  Consider

     (pregexp-match "a*a" "aaaa")

The regexp consists of two subregexps, `a*' followed by `a'.  The
subregexp `a*' cannot be allowed to match all four `a''s in the text
string `"aaaa"', even though `*' is a greedy quantifier.  It may match
only the first three, leaving the last one for the second subregexp.
This ensures that the full regexp matches successfully.

  The regexp matcher accomplishes this via a process called
_backtracking_.  The matcher tentatively allows the greedy quantifier
to match all four `a''s, but then when it becomes clear that the
overall match is in jeopardy, it _backtracks_ to a less greedy match of
_three_ `a''s.  If even this fails, as in the call

     (pregexp-match "a*aa" "aaaa")

the matcher backtracks even further.  Overall failure is conceded only
when all possible backtracking has been tried with no success.

  Backtracking is not restricted to greedy quantifiers.  Nongreedy
quantifiers match as few instances as possible, and progressively
backtrack to more and more instances in order to attain an overall
match.  There is backtracking in alternation too, as the more rightward
alternates are tried when locally successful leftward ones fail to
yield an overall match.

Disabling backtracking
......................

  Sometimes it is efficient to disable backtracking.  For example, we
may wish  to  _commit_ to a choice, or we know that trying alternatives
is fruitless.  A nonbacktracking regexp is enclosed in `(?>'...`)'.

     (pregexp-match "(?>a+)." "aaaa")
      => #f

  In this call, the subregexp `?>a*' greedily matches all four `a''s,
and is denied the opportunity to backpedal.  So the overall match is
denied.  The effect of the regexp is therefore to match one or more
`a''s followed by something that is definitely non-`a'.


File: bigloo.info,  Node: Looking ahead and behind,  Prev: Backtracking,  Up: The Regular Expressions Pattern Language

Looking ahead and behind
........................

  You can have assertions in your pattern that look _ahead_ or _behind_
to ensure that a subpattern does or does not occur.   These "look
around" assertions are specified by putting the subpattern checked for
in a cluster whose leading characters are: `?=' (for positive
lookahead), `?!' (negative lookahead), `?<=' (positive lookbehind),
`?<!' (negative lookbehind).  Note that the subpattern in the assertion
does not generate a match in the final result.  It merely allows or
disallows the rest of the match.

Lookahead
.........

  Positive lookahead (`?=') peeks ahead to ensure that its subpattern
_could_ match.

     (pregexp-match-positions "grey(?=hound)"
       "i left my grey socks at the greyhound")
      => ((28 . 32))

The regexp `"grey(?=hound)"' matches `grey', but _only_ if it is
followed by `hound'.  Thus, the first `grey' in the text string is not
matched.

  Negative lookahead (`?!') peeks ahead to ensure that its subpattern
could not possibly match.

     (pregexp-match-positions "grey(?!hound)"
       "the gray greyhound ate the grey socks")
      => ((27 . 31))

The regexp `"grey(?!hound)"' matches `grey', but only if it is _not_
followed by `hound'.  Thus the `grey' just before `socks' is matched.

Lookbehind
..........

  Positive lookbehind (`?<=') checks that its subpattern _could_ match
immediately to the left of the current position in the text string.

     (pregexp-match-positions "(?<=grey)hound"
       "the hound in the picture is not a greyhound")
      => ((38 . 43))

The regexp `(?<=grey)hound' matches `hound', but only if it is preceded
by `grey'.

  Negative lookbehind (`?<!') checks that its subpattern could not
possibly match immediately to the left.

     (pregexp-match-positions "(?<!grey)hound"
       "the greyhound in the picture is not a hound")
      => ((38 . 43))

  The regexp `(?<!grey)hound' matches `hound', but only if it is _not_
preceded by `grey'.

  Lookaheads and lookbehinds can be convenient when they are not
confusing.

