info bigloo

6.2.1 Library functions

library procedure: call-with-input-file string proc

bigloo procedure: call-with-input-string string proc

library procedure: call-with-output-file string proc

library procedure: call-with-append-file string proc

library procedure: call-with-output-string proc

These two procedures call proc with one argument, a port obtained by opening string. See (R5RS)r5rs.info, for more details.

(call-with-input-file "/etc/passwd"
   (lambda (port)
      (let loop ((line (read-line port)))
         (if (not (eof-object? line))
             (begin
                (print line)
                (loop (read-line port)))))))

procedure: input-port? obj
procedure: input-string-port? obj
procedure: output-port? obj
procedure: output-string-port? obj
procedure: port? obj

bigloo procedure: input-port-name obj
bigloo procedure: output-port-name obj: Returns the file name for which obj has been opened.

bigloo (>=3.8d) procedure: input-port-length obj: Returns the source number of bytes, i.e., the number characters contains in the source. Returns -1 if that number is unknown (typically for a pipe).

bigloo (>=2.8b) procedure: input-port-timeout-set! port time

bigloo (>=2.8b) procedure: output-port-timeout-set! port time

These two functions limit the time an read or write operation may last. If the time limit (expressed in microseconds) exceeded, an exception of time &io-timeout-error is raised.

Setting a timeout equal to 0, restore the socket in blocking mode. Setting a timeout with a value lesser than 0 is ignored.

Note: ports created from sockets share their internal file descriptor. Hence it is erroneous to set a timeout for only one of the two ports. Both must be set.

bigloo procedure: output-port-flush-hook port

bigloo procedure: output-port-flush-hook-set! port hook

Returns (resp. sets) the flush hook of the output port. The flush hook is a procedure of two arguments, the output port and the number of characters that are to be actually written out during the flush. It is unspecified when the hook is invoked, however, one may expect the C back-end to invoke the hook only when output buffers are full. The other back-ends (JVM and DOTNET) are likely to invoke the hook as soon as a character is to be written.

A flush hook can return two types of values:

A string, which is then directly displayed to the system stream associated with the output port.
An integer, which denotes the number of characters of the output port flush buffer (see output-port-flush-buffer) that have to be displayed on the system stream.

bigloo procedure: output-port-flush-buffer port
bigloo procedure: output-port-flush-buffer-set! port buffer: These functions gets and sets a buffer that can be used by program by the flush hooks. The runtime system makes no provision for automatically allocated these buffers that hence must be manually allocated by programs. The motivation for flush buffer is to allow programs to write flush hooks that don’t have to allocate a new string each time invoked.

bigloo procedure: output-port-close-hook port
bigloo procedure: output-port-close-hook-set! port proc: Returns (resp. sets) the close hook of the output port. The close hook is a procedure of one argument, the closed port. The hook is invoked after the port is closed.

bigloo procedure: input-port-close-hook port

bigloo procedure: input-port-close-hook-set! port proc

Returns (resp. sets) the close hook of the input port. The close hook is a procedure of one argument, the closed port.

Example:

(let ((p (open-input-string "/etc/passwd")))
  (input-port-close-hook-set! p (lambda () (display 'done)))
  ...
  (close-input-port p))

bigloo procedure: input-port-reopen! obj: Re-open the input port obj. That is, re-start reading from the first character of the input port.

procedure: current-input-port
procedure: current-output-port
bigloo procedure: current-error-port

optional procedure: with-input-from-file string thunk

optional procedure: with-input-from-string string thunk

optional procedure: with-input-from-procedure procedure thunk

optional procedure: with-output-to-file string thunk

optional procedure: with-append-to-file string thunk

bigloo procedure: with-error-to-file string thunk

bigloo procedure: with-output-to-string thunk

bigloo procedure: with-output-to-procedure procedure thunk

bigloo procedure: with-error-to-string thunk

bigloo procedure: with-error-to-procedure procedure thunk

A port is opened from file string. This port is made the current input port (resp. the current output port or the current error port) and thunk is called. See (R5RS)r5rs.info, for more details.

(with-input-from-file "/etc/passwd"
   (lambda ()
      (let loop ((line (read-line (current-input-port))))
         (if (not (eof-object? line))
             (begin
                (print line)
                (loop (read-line (current-input-port))))))))

bigloo procedure: with-input-from-port port thunk

bigloo procedure: with-output-to-port port thunk

bigloo procedure: with-error-to-port port thunk

with-input-from-port, with-output-to-port and with-error-to-port all suppose port to be a legal port. They call thunk making port the current input (resp. output or error) port. None of these functions close port on the continuation of thunk.

(with-output-to-port (current-error-port) 
   (lambda () (display "hello")))

procedure: open-input-file file-name [buffer #f] [timeout 5000000]

If file-name is a regular file name, open-input-file behaves as the function defined in the Scheme report. If file-name starts with special prefixes it behaves differently. Here are the recognized prefixes:

| (a string made of the characters #\| and #\space) Instead of opening a regular file, Bigloo opens an input pipe. The same syntax is used for output file.

(define pin (open-input-file "| cat /etc/passwd"))
(define pout (open-output-file "| wc -l"))

(display (read pin) pout)
(close-input-port pin)
(newline pout)
(close-output-port pout)

pipe: Same as | .
file: Opens a regular file.

gzip: Opens a port on a gzipped filed. This is equivalent to open-input-gzip-file. Example:

(with-input-from-file "gzip:bigloo.tar.gz"
   (lambda ()
      (send-chars (current-input-port) (current-output-port))))

string: Opens a port on a string. This is equivalent to open-input-string. Example:

(with-input-from-file "string:foo bar Gee"
   (lambda ()
      (print (read))
      (print (read))
      (print (read))))
   -| foo
   -| bar
   -| Gee

http://server/path
Opens an http connection on server and open an input file on file path.
http://server:port-number/path
http://user:password@server:port-number/path
Opens an http connection on server, on port number port with an authentication and open an input file on file path.
ftp://server/path
ftp://user:password@server/path
Opens an ftp connection on server and open an input file on file path. Log in as anonymous.
ressource:
Opens a JVM ressource file. Opening a ressource: file in non JVM backend always return #f. On the JVM backend it returns a input port if the ressource exists. Otherwise, it returns #f.

The optional argument buffer can either be:

A positive fixnum, this gives the size of the buffer.
The boolean #t, a buffer is allocated.
The boolean #f, the socket is unbufferized.
A string, it is used as buffer.

The optional argument timeout, an integer represents a microseconds timeout for the open operation.

bigloo procedure: open-input-gzip-file file-name [buffer #t]

bigloo procedure: open-input-gzip-port input-port [buffer #t]

Open respectively a gzipped file for input and a port on a gzipped stream. Note that closing a gzip port opened from a port pi does not close the pi port.

(let ((p (open-input-gzip-file "bigloo.tar.gz")))
   (unwind-protect
      (read-line p1)
      (close-input-port p)))

(let* ((p1 (open-input-file "bigloo.tar.gz"))
       (p2 (open-input-gzip-port p1)))
   (unwind-protect
      (read-line p2)
      (close-input-port p2)
      (close-input-port p1)))

bigloo procedure: open-input-zlib-file file-name [buffer #t]
bigloo procedure: open-input-zlib-port input-port [buffer #t]: Open respectively a zlib file for input and a port on a zlib stream. Note that closing a zlib port opened from a port pi does not close the pi port.

bigloo procedure: open-input-string string [start 0]

bigloo procedure: open-input-string! string

Returns an input-port able to deliver characters from string.

The function open-input-string! acts as open-input-string but it might modify the string it receives as parameter.

bigloo procedure: open-input-c-string string: Returns an input-port able to deliver characters from C string. The buffer used by the input port is the exact same string as the argument. That is, no buffer is allocated.

bigloo procedure: open-input-ftp-file file-name [buffer #t]

Returns an input-port able to deliver characters from a remote file located on a FTP server.

Example:

(let ((p (open-input-ftp-file "ftp-sop.inria.fr/ls-lR.gz'')))
  (unwind-protect
     (read-string p)
     (close-input-port p)))

The file name may contain user authentication such as:

(let ((p (open-input-ftp-file "anonymous:foo@ftp-sop.inria.fr/ls-lR.gz'')))
  (unwind-protect
     (read-string p)
     (close-input-port p)))

bigloo procedure: open-input-procedure procedure [buffer #t]

Returns an input-port able to deliver characters from procedure. Each time a character has to be read, the procedure is called. This procedure may returns a string of characters, or the boolean #f. This last value stands for the end of file.

Example:

(let ((p (open-input-procedure (let ((s #t))
				  (lambda ()
				     (if s
					 (begin 
                                            (set! s #f)
                                            "foobar")
					 s))))))
   (read))

bigloo procedure: unread-char! char [input-port]

bigloo procedure: unread-string! string [input-port]

bigloo procedure: unread-substring! string start end [input-port]

Pushes the given char, string or substring into the input-port. The next read character(s) will be the pushed ones. The input-port must be buffered and not be closed.

Example:

(define p (open-input-string "a ymbol c"))
(read p)                       ⇒ a
(read-char p)                  ⇒ #\space
(unread-char! #\s p)
(read p)                       ⇒ symbol
(read-char p)                  ⇒ #\space
(read p)                       ⇒ c
(char-ready? p)                ⇒ #f
(unread-string! "sym1 sym2" p)
(char-ready? p)                ⇒ #t
(read p)                       ⇒ sym1
(read p)                       ⇒ sym2

procedure: open-output-file file-name: The same syntax as open-input-file for file names applies here. When a file name starts with ‘| ’, Bigloo opens an output pipe instead of a regular file.

bigloo procedure: append-output-file file-name: If file-name exists, this function returns an output-port on it, without removing it. New output will be appended to file-name. If file-name does not exist, it is created.

bigloo procedure: open-output-string: This function returns an output string port. This object has almost the same purpose as output-port. It can be used with all the printer functions which accept output-port. An output on a output string port memorizes all the characters written. An invocation of flush-output-port or close-output-port on an output string port returns a new string which contains all the characters accumulated in the port.

bigloo procedure: get-output-string output-port: Given an output port created by open-output-string, returns a string consisting of the characters that have been output to the port so far.

bigloo procedure: open-output-procedure proc [flush [close]]: This function returns an output procedure port. This object has almost the same purpose as output-port. It can be used with all the printer functions which accept output-port. An output on a output procedure port invokes the proc procedure each time it is used for writing. That is, proc is invoked with a string denoting the displayed characters. When the function flush-output-port is called on such a port, the optional flush procedure is invoked. When the function close-output-port is called on such a port, the optional close procedure is invoked.

procedure: close-input-port input-port
procedure: close-output-port output-port: According to R5RS, the value returned is unspecified. However, if output-port was created using open-output-string, the value returned is the string consisting of all characters sent to the port.

procedure: closed-input-port? input-port
procedure: closed-output-port? output-port: Predicates that return #t if and if their associated port is closed. Return #f otherwise.

bigloo procedure: input-port-name input-port: Returns the name of the file used to open the input-port.

bigloo procedure: input-port-position port
bigloo procedure: output-port-position port: Returns the current position (a character number), in the port.

bigloo procedure: set-input-port-position! port pos
bigloo procedure: set-output-port-position! port pos: These functions set the file position indicator for port. The new position, measured in bytes, is specified by pos. It is an error to seek a port that cannot be changed (for instance, a string or a console port). The result of these functions is unspecified. An error is raised if the position cannot be changed.

bigloo procedure: input-port-reopen! input-port: This function re-opens the input input-port. That is, it reset the position in the input-port to the first character.

procedure: read [input-port]

bigloo procedure: read/case case [input-port]

bigloo procedure: read-case-sensitive [input-port]

bigloo procedure: read-case-insensitive [input-port]

Read a lisp expression. The case sensitivity of read is unspecified. If have to to enforce a special behavior regarding the case, use read/case, read-case-sensitive or read-case-insensitive. Let us consider the following source code: The value of the read/case’s case argument may either be upcase, downcase or sensitive. Using any other value is an error.

(define (main argv)
   (let loop ((exp (read-case-sensitive)))
      (if (not (eof-object? exp))
          (begin
             (display "exp: ")
             (write exp)
             (display " [")
             (display exp)
             (display "]")
             (print " eq?: " (eq? exp 'FOO) " " (eq? exp 'foo))
             (loop (read-case-sensitive))))))

Thus:

> a.out
foo
  -| exp: foo [foo] eq?: #f #t
FOO
  -| exp: FOO [FOO] eq?: #t #f

bigloo procedure: read/rp grammar port
bigloo procedure: read/lalrp lalrg rg port [emptyp]: These functions are fully explained in Regular parsing, and Lalr(1) parsing.

bigloo procedure: define-reader-ctor symbol procedure

Note: This feature is experimental and might be removed in feature versions.

The present SRFI-10 (http://srfi.schemers.org/srfi-10/srfi-10.html) proposes an extensible external representation of Scheme values, a notational convention for future SRFIs. This SRFI adds #,( as a new token and extends production rules of the grammar for a Scheme reader. The #,() form can be used for example to denote values that do not have a convenient printed representation, as well for conditional code compilation. It is proposed that future SRFIs that contain new read syntax for values use the #,() notation with an appropriate tag symbol.

As a particular example and the reference implementation for the #,() convention, this SRFI describes an interpretation of the #,() external form as a read-time application.

Examples:

(define-reader-ctor 'list list) 
(with-input-from-string "#,(list 1 2 #f \"4 5\")" read) ⇒ (1 2 #f "4 5")

(define-reader-ctor '+ +)
(with-input-from-string "#,(+ 1 2)" read) ⇒ 3

bigloo procedure: set-read-syntax! char procedure

Note: This feature is experimental and might be removed in feature versions.

Registers a function procedure to be invoked with one argument, an input-port, that is invoked when the reader hits an unparsed character.

Example:

(set-read-syntax! #\{
   (lambda (port)
      (let loop ((c (peek-char port)) (exps '()))
	 (cond ((eof-object? c)
		(error "{" "EOF encountered while parsing { ... } clause" port))
	       ((char=? c #\})
		(read-char port)   ; discard
		`(begin ,@(reverse exps)))
	       ((char-whitespace? c)
		(read-char port)   ; discard whitespace
		(loop (peek-char port) exps))
	       (else
		(let ((exp (read port)))
		   (loop (peek-char port)
                      (cons exp exps))))))))

procedure: read-char [port]
procedure: read-byte [port]
procedure: peek-char [port]
procedure: peek-byte [port]
procedure: eof-object? obj

procedure: char-ready? [port]

As specified in the R5Rs, (R5RS)r5rs.info, char-ready? returns #t if a character is ready on the input port and returns #f otherwise. If ‘char-ready’ returns #t then the next ‘read-char’ operation on the given port is guaranteed not to hang. If the port is at end of file then ‘char-ready?’ returns #t. Port may be omitted, in which case it defaults to the value returned by ‘current-input-port’.

When using char-ready? consider the latency that may exists before characters are available. For instance, executing the following source code:

(let* ((proc (run-process "/bin/ls" "-l" "/bin" output: pipe:))
       (port (process-output-port proc)))
   (let loop ((line (read-line port)))
      (print "char ready " (char-ready? port))
      (if (eof-object? line)
          (close-input-port port)
          (begin
             (print line)
             (loop (read-line port))))))

Produces outputs such as:

char ready #f
total 7168
char ready #f
-rwxr-xr-x    1 root     root         2896 Sep  6  2001 arch
char ready #f
-rwxr-xr-x    1 root     root        66428 Aug 25  2001 ash
char ready #t
...

For a discussion of Bigloo processes, see Process support.

Note: Thanks to Todd Dukes for the example and the suggestion of including it this documentation.

bigloo procedure: read-line [input-port]

bigloo procedure: read-line-newline [input-port]

Reads characters from input-port until a #\Newline, a #\Return or an end of file condition is encountered. read-line returns a newly allocated string composed of the characters read.

The strings returned by read-line do not contain the newline delimiters. The strings returned by read-line-newline do contain them.

bigloo procedure: read-lines [input-port]: Accumulates all the line of an input-port into a list.

bigloo procedure: read-of-strings [input-port]: Reads a sequence of non-space characters on input-port, makes a string of them and returns the string.

bigloo procedure: read-string [input-port]: Reads all the characters of input-port into a string.

bigloo procedure: read-chars size [input-port]

bigloo procedure: read-chars! buf size [input-port]

The function read-chars returns a newly allocated strings made of size characters read from input-port (or from (current-input-port) if input-port is not provided). If less than size characters are available on the input port, the returned string is smaller than size. Its size is the number of available characters.

The function read-chars! fills the buffer buf with at most size characters.

bigloo procedure: read-fill-string! s o len [input-port]

Fills the string s starting at offset o with at most len characters read from the input port input-port (or from (current-input-port) if input-port is not provided). This function returns the number of read characters (which may be smaller than len if less characters are available) or the end of file object. The argument len is a small integer.

The function read-fill-string! is similar to read-chars! except that it returns the end-of-file object on termination while read-chars! returns 0.

Example:

(let ((s (make-string 10 #\-)))
   (with-input-from-string "abcdefghijlkmnops"
      (lambda ()
         (read-fill-string! s 3 5)
         s)))
   ⇒ ---abcde--

bigloo procedure: port->string-list input-port: Returns a list of strings composed of the elements of input-port.

bigloo procedure: port->list input-port reader
bigloo procedure: port->sexp-list input-port: Port->list applies reader to port repeatedly until it returns EOF, then returns a list of results. Port->list-sexp is equivalent to (port->list read port).

bigloo procedure: file->string path: This function builds a new string out of all the characters of the file path. If the file cannot be open or read, an IO_EXCEPTION is raised.

bigloo procedure: send-chars input-port output-port [len] [offset]

bigloo procedure: send-file filename output-port [len] [offset]

Transfer the characters from input-port to output-port. This procedure is sometimes mapped to a system call (such as sendfile under Linux) and might thus be more efficient than copying the ports by hand. The optional argument offset specifies an offset from which characters of input-port are sent. The function send-chars returns the number of characters sent.

The function send-file opens the file filename in order to get its input port. On some backends, send-file might be more efficient than send-chars because it may avoid creating a full-fledged Bigloo input-port.

Note that the type of len and offset is elong (i.e., exact long), which is also returned by file-size.

library procedure: write obj [output-port]
library procedure: display obj [output-port]
bigloo procedure: print obj …: This procedure allows several objects to be displayed. When all these objects have been printed, print adds a newline.

bigloo procedure: display* obj …: This function is similar to print but does not add a newline.

bigloo procedure: fprint output-port obj …: This function is the same as print except that a port is provided.

procedure: write-char char [output-port]
procedure: write-byte byte [output-port]: These procedures write a char (respec. a byte, i.e., in integer in the range 0..255) to the output-port.

procedure: newline [output-port]
bigloo procedure: flush-output-port output-port: This procedure flushes the output port output-port. This function does not reset characters accumulated in string port. For this uses, reset-output-port.

procedure: newline [output-port]
bigloo procedure: reset-output-port output-port: This function is equivalent to flush-output-port but in addition, for string ports, it reset the internal buffer that accumulates the displayed characters.

bigloo procedure: format format-string [objs]

Note: Many thanks to Scott G. Miller who is the author of SRFI-28. Most of the documentation of this function is copied from the SRFI documentation.

Accepts a message template (a Scheme String), and processes it, replacing any escape sequences in order with one or more characters, the characters themselves dependent on the semantics of the escape sequence encountered.

An escape sequence is a two character sequence in the string where the first character is a tilde ~. Each escape code’s meaning is as follows:

~a The corresponding value is inserted into the string as if printed with display.
~s The corresponding value is inserted into the string as if printed with write.
~% or ~n A newline is inserted A newline is inserted.
~~ A tilde ~ is inserted.
~r A return (#\Return) is inserted.
~v The corresponding value is inserted into the string as if printed with display followed by a newline. This tag is hence equivalent to the sequence ~a~n.
~c The corresponding value must be a character and is inserted into the string as if printed with write-char.
~d, ~x, ~o, ~b The corresponding value must must be a number and is printed with radix 16, 8 or 2.
~l If the corresponding value is a proper list, its items are inserted into the string, separated by whitespaces, without the surrounding parenthesis. If the corresponding value is not a list, it behaves as ~s.
~(<sep>) If the corresponding value is a proper list, its items are inserted into the string, separated from each other by sep, without the surrounding parenthesis. If the corresponding value is not a list, it behaves as ~s.
~Ndxob Print a number in N columns with space padding.
~N,<padding>dxob Print a number in num columns with padding padding.

~a and ~s, when encountered, require a corresponding Scheme value to be present after the format string. The values provided as operands are used by the escape sequences in order. It is an error if fewer values are provided than escape sequences that require them.

~% and ~~ require no corresponding value.

(format "Hello, ~a" "World!") 
   -| Hello, World!
(format "Error, list is too short: ~s~%" '(one "two" 3)) 
   -| Error, list is too short: (one "two" 3)
(format "a ~l: ~l" "list" '(1 2 3))
   -| a list: 1 2 3
(format "a ~l: ~(, )" "list" '(1 2 3))
   -| a list: 1, 2, 3
(format "~3d" 4)
   -|   4
(format "~3,-d" 4)
   -| --4
(format "~3x" 16)
   -|  10
(format "~3,0d" 5)
   -| 005

bigloo procedure: printf format-string [objs]
bigloo procedure: fprintf port format-string [objs]: Formats objs to the current output port or to the specified port.

bigloo procedure: pp obj [output-port]: Pretty print obj on output-port.

bigloo variable: *pp-case*: Sets the variable to respect, lower or upper to change the case for pretty-printing.

bigloo variable: *pp-width*: The width of the pretty-print.

bigloo procedure: write-circle obj [output-port]: Display recursive object obj on output-port. Each component of the object is displayed using the write library function.

bigloo procedure: display-circle obj [output-port]

Display recursive object obj on output-port. Each component of the object is displayed using the display library function.

For instance:

(define l (list 1 2 3))
(set-car! (cdr l) l)
(set-car! (cddr l) l)
(display-circle l)  -| #0=(1 #0# #0#)

bigloo procedure: display-string string output-port

bigloo procedure: display-substring string start end output-port

String must be a string, and start and end must be exact integers satisfying 0 <= start <= end <= (string-length string).

Display-substring displays a string formed from the characters of string beginning with index start (inclusive) and ending with index end (exclusive).

bigloo procedure: password [prompt]: Reads a password from the current input port. The reading stops when the user hits the ,(code "Enter") key.

This document was generated on March 31, 2014 using texi2html 5.0.