5. Bigloo -- Standard Library 5.2 Input and output

Browsing

Home: | Bigloo A ``practical Scheme compiler'' User manual for version 2.6b December 2003
Previous chapter: | Core Language
Next chapter: | Pattern Matching

Standard Library

5.1 | Scheme Library
| 5.1.1 | Booleans
| 5.1.2 | Equivalence predicates
| 5.1.3 | Pairs and lists
| 5.1.4 | Symbols
| 5.1.5 | Keywords
| 5.1.6 | Numbers
| 5.1.7 | Characters
| 5.1.8 | UCS-2 Characters
| 5.1.9 | Strings
| 5.1.10 | Unicode (UCS-2) Strings
| 5.1.11 | Vectors
| 5.1.12 | Control features
5.2 | Input and output
5.3 | Structures and Records
| 5.3.1 | Structures
| 5.3.2 | Records (SRFI-9)
5.4 | Serialization
5.5 | Bit manipulation
5.6 | Hash Tables
| 5.6.1 | Hash tables
| 5.6.2 | Deprecated Hash tables
5.7 | System programming
| 5.7.1 | Operating System interface
| 5.7.2 | Files
5.8 | Process support
5.9 | Socket support
5.10 | Date
5.11 | Posix Regular Expressions
| 5.11.1 | Regular Expressions Procedures
| 5.11.2 | Regular Expressions Pattern Language
| 5.11.3 | An Extended Example

Chapters

| Acknowledgements
1. | Table of contents
2. | Overview of Bigloo
3. | Modules
4. | Core Language
5. | Standard Library
6. | Pattern Matching
7. | Object System
8. | Threads
9. | Regular parsing
10. | Lalr(1) parsing
11. | Errors and Assertions
12. | Eval and code interpretation
13. | Macro expansion
14. | Command Line Parsing
15. | Explicit typing
16. | The C interface
17. | The Java interface
18. | Bigloo Libraries
19. | Extending the Runtime System
20. | SRFIs
21. | DSSSL support
22. | Compiler description
23. | User Extensions
24. | Bigloo Development Environment
25. | Global Index
26. | Library Index
| Bibliography

This section describes Scheme operation for reading and writing data. The section Files describes functions for handling files.

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

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

These two procedures call `proc` with one argument, a port obtained by opening `string`. See r5rs, Ports, 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)))))))

input-port? obj | procedure

input-string-port? obj | procedure

output-port? obj | procedure

output-string-port? obj | procedure

port? obj | procedure

input-port-name obj | bigloo procedure

Returns the file name for which `obj` has been opened.

input-port-reopen! obj | bigloo procedure

Re-open the input port `obj`. That is, re-start reading from the first character of the input port.

current-input-port | procedure

current-output-port | procedure

current-error-port | bigloo 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-error-to-file string thunk | bigloo procedure

with-output-to-string thunk | bigloo procedure

with-error-to-string thunk | bigloo procedure

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, Ports, 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))))))))

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

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

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

`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")))

open-input-file file-name | procedure

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.
- `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` Opens an http connection on `server`, on port number `port` and open an input file on file `path`.
- `ftp:server/path` Opens an http connection on `server` and open an input file on file `path`.

open-input-string string | bigloo procedure

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

open-input-c-string string | bigloo procedure

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

open-input-procedure procedure | bigloo procedure

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 character, 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))

open-output-file file-name | procedure

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.

append-output-file file-name | bigloo procedure

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.

open-output-string | bigloo procedure

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.

get-output-string output-port | bigloo procedure

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.

close-input-port input-port | procedure

close-output-port output-port | procedure

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.

input-port-name input-port | bigloo procedure

Returns the name of the file used to open the `input-port`.

input-port-position port | bigloo procedure

output-port-position port | bigloo procedure

Returns the current position (a character number), in the `port`.

set-input-port-position! port pos | bigloo procedure

set-output-port-position! port pos | bigloo procedure

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.

input-port-reopen! input-port | bigloo procedure

This function re-opens the input `input-port`. That is, it reset the position in the `input-port` to the first character.

read [input-port] | procedure

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

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

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

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

read/rp grammar port | bigloo procedure

read/lalrp lalrg rg port [emptyp] | bigloo procedure

These functions are fully explained in Regular Parsing, and Lalr Parsing.

read-char [port] | procedure

peek-char [port] | procedure

eof-object? obj | procedure

char-ready? [port] | procedure

As specified in the R5Rs, r5rs, Ports, `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.
Note: Thanks to Todd Dukes for the example and the suggestion of including it this documentation.

read-line [input-port] | bigloo procedure

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.

read-lines [input-port] | bigloo procedure

Accumulates all the line of an `input-port` into a list.

read-of-strings [input-port] | bigloo procedure

Reads a sequence of non-space characters on `input-port`, makes a string of them and returns the string.

read-string [input-port] | bigloo procedure

Reads all the characters of `input-port` into a string.

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

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.

send-chars input-port output-port [len] | bigloo procedure

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.

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

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 fill characters (which may be smaller than `len` if less characters are available).
Example:

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

write obj [output-port] | library procedure

display obj [output-port] | library procedure

print obj ... | bigloo procedure

This procedure allows several objects to be displayed. When all these objects have been printed, `print` adds a newline.

display* obj ... | bigloo procedure

This function is similar to `print` but does not add a newline.

fprint output-port obj ... | bigloo procedure

This function is the same as `print` except that a port is provided.

newline [output-port] | procedure

write-char char [output-port] | procedure

flush-output-port output-port | bigloo procedure

This procedure flushes the output port `output-port`.

format format-string [objs] | bigloo procedure

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.
- `~%` A newline is inserted.
- `~~` A tilde `~` is inserted.

`~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)

printf format-string [objs] | bigloo procedure

fprintf port format-string [objs] | bigloo procedure

Formats `objs` to the current output port or to the specified `port`.

set-write-length! len | bigloo procedure

Sets to `len` the maximum number of atoms that can be printed by `write` and `display`. This facility is useful in preventing the printer from falling into an infinite loop when printing circular structures.

get-write-length | bigloo procedure

Gets the current length of the printer. That is, `get-write-length` returns the maximum number of Bigloo objects that are allowed to be printed when printing compound objects. This function is useful in preventing the system from looping when printing circular data structures.

set-printer! proc | bigloo procedure

Set the current printer to be `proc`; `proc` has to be a procedure expecting at least one argument: an expression to print; an output port is an optional, second argument.

native-printer | bigloo procedure

Returns the native Bigloo's printer.

current-printer | bigloo procedure

Returns the current Bigloo's printer.

pp obj [output-port] | bigloo procedure

Pretty print `obj` on `output-port`.

*pp-case* | bigloo variable

Sets the variable to `respect`, `lower` or `upper` to change the case for pretty-printing.

*pp-width* | bigloo variable

The width of the pretty-print.

write-circle obj [output-port] | bigloo procedure

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

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

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#)

This Scribe page has been generated by `scribeinfo`.
Last update Tue Dec 16 13:46:41 2003