6. Bigloo The Programming Language (4.6a) User manual for version 4.6a January 2025 -- Standard Library

main page

top: | Bigloo The Programming Language (4.6a) User manual for version 4.6a January 2025

Standard Library

Chapters

This chapter presents the Bigloo standard library. Bigloo is mostly R5RS compliant but it proposes many extensions to this standard. In a first section Scheme Library the Bigloo R5RS support is presented. This section also contains various function that are not standard (for instance, various functions used to manage a file system). Then, in the following sections Serialization, Bit Manipulation, and System Programming Bigloo specific extensions are presented. Bigloo input and output facilities constitute a large superset of the standard Scheme definition. For this reason they are presented in a separate section Input and Output.

### 6.1 Scheme Library

When the definition of a procedure or a special form is the same in Bigloo and Scheme, we just mention its name; otherwise, we explain it and qualify it as a ``bigloo procedure''.

### 6.1.1 Booleans

The standard boolean objects are `#t` and `#f`.
Note: the empty list is true.

not obj | library procedure

`not` returns `#t` if `obj` is false, and returns `#f` otherwise.

    (not #t)                               => #f
    (not 3)                                => #f
    (not (list 3))                         => #f
    (not #f)                               => #t
    (not '())                              => #f
    (not (list))                           => #f
    (not 'nil)                             => #f

boolean? obj | library procedure

`Boolean?` returns `#t` if `obj` is either `#t` or `#f` and returns `#f` otherwise.

    (boolean? #f)                          => #t
    (boolean? 0)                           => #f
    (boolean? '())                         => #f

### 6.1.2 Equivalence predicates

eqv? obj1 obj2 | procedure

eq? obj1 obj2 | procedure

`eqv?` and `eq?` are equivalent in Bigloo.

    (eq? 'a 'a)                            =>  #t
    (eq? '(a) '(a))                        =>  unspecified
    (eq? (list 'a) (list 'a))              =>  #f
    (eq? "a" "a")                          =>  unspecified
    (eq? "" "")                            =>  unspecified
    (eq? '() '())                          =>  #t
    (eq? 2 2)                              =>  unspecified
    (eq? #\A #\A)                          =>  unspecified
    (eq? car car)                          =>  #t
    (let ((n (+ 2 3)))
      (eq? n n))                           =>  unspecified
    (let ((x '(a)))
      (eq? x x))                           =>  #t
    (let ((x '#()))
      (eq? x x))                           =>  #t
    (let ((p (lambda (x) x)))
      (eq? p p))                           =>  #t

Since Bigloo implements `eqv?` as `eq?`, the behavior is not always conforming to R5RS.

    (eqv? 'a 'a)                           =>  #t
    (eqv? 'a 'b)                           =>  #f
    (eqv? 2 2)                             =>  #t
    (eqv? '() '())                         =>  #t
    (eqv? 100000000 100000000)             =>  #t
    (eqv? (cons 1 2) (cons 1 2))           =>  #f
    (eqv? (lambda () 1)
          (lambda () 2))                   =>  #f
    (eqv? #f 'nil)                         =>  #f
    (let ((p (lambda (x) x)))
      (eqv? p p))                          =>  unspecified

The following examples illustrate cases in which the above rules do not fully specify the behavior of `eqv?`. All that can be said about such cases is that the value returned by `eqv?` must be a boolean.

    (eqv? "" "")                           =>  unspecified
    (eqv? '#() '#())                       =>  unspecified
    (eqv? (lambda (x) x)
          (lambda (x) x))                  =>  unspecified
    (eqv? (lambda (x) x)
          (lambda (y) y))                  =>  unspecified

    (define gen-counter
      (lambda ()
        (let ((n 0))
          (lambda () (set! n (+ n 1)) n))))
    (let ((g (gen-counter)))
      (eqv? g g))                          =>  #t
    (eqv? (gen-counter) (gen-counter))
                                           =>  #f
    (define gen-loser
      (lambda ()
        (let ((n 0))
          (lambda () (set! n (+ n 1)) 27))))
    (let ((g (gen-loser)))
      (eqv? g g))                          =>  #t
    (eqv? (gen-loser) (gen-loser))
                                           =>  unspecified

    (letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
             (g (lambda () (if (eqv? f g) 'both 'g))))
      (eqv? f g))
                                           =>  unspecified

    (letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
             (g (lambda () (if (eqv? f g) 'g 'both))))
      (eqv? f g))
                                           =>  #f
    (eqv? '(a) '(a))                       =>  unspecified
    (eqv? "a" "a")                         =>  unspecified
    (eqv? '(b) (cdr '(a b)))               =>  unspecified
    (let ((x '(a)))
      (eqv? x x))                          =>  #t

equal? obj1 obj2 | library procedure

    (equal? 'a 'a)                         =>  #t
    (equal? '(a) '(a))                     =>  #t
    (equal? '(a (b) c)
            '(a (b) c))                    =>  #t
    (equal? "abc" "abc")                   =>  #t
    (equal? 2 2)                           =>  #t
    (equal? (make-vector 5 'a)
            (make-vector 5 'a))            =>  #t
    (equal? (lambda (x) x)
            (lambda (y) y))                =>  unspecified

See r5rs, Equivalence predicates, for more details.

### 6.1.3 Pairs and lists

The form `()` is illegal.

pair? obj | procedure

cons a d | procedure

pair-or-null? obj | bigloo procedure

Returns `#t` if `obj` is either a pair or the empty list. Otherwise it returns `#f`.

car pair | procedure

cdr pair | procedure

set-car! pair obj | procedure

set-cdr! pair obj | procedure

caar pair | library procedure

cadr pair | library procedure

cadar pair | library procedure

caadr pair | library procedure

caaar pair | library procedure

caddr pair | library procedure

cadar pair | library procedure

cdddar pair | library procedure

cddddr pair | library procedure

null? obj | library procedure

list? obj | library procedure

list obj ... | library procedure

length list | library procedure

append list ... | library procedure

append! list ... | bigloo procedure

A destructive append.

reverse list | library procedure

reverse! list | bigloo procedure

A destructive reverse.

list-ref list k | library procedure

take list k | library procedure

drop list k | library procedure

list-tail list k | library procedure

`list-ref` returns the `k` element of the list.
`take` returns a new list made of the first `k` element of the list.
`Drop` and `list-tail` returns the sublist of `list` obtained by omitting the first `k` elements.

last-pair list | bigloo procedure

Returns the last pair in the nonempty, possibly improper, `list`.

memq obj list | library procedure

memv obj list | library procedure

member obj list | library procedure

assq obj alist | library procedure

assv obj alist | library procedure

assoc obj alist | library procedure

remq obj list | bigloo procedure

Returns a new list which is a copy of `list` with all items `eq?` to `obj` removed from it.

remq! obj list | bigloo procedure

Same as `remq` but in a destructive way.

delete obj list [eq equal?] | bigloo procedure

Returns a new list which is a copy of `list` with all items `equal?` to `obj` deleted from it.

delete! obj list [eq equal?] | bigloo procedure

Same as `delete` but in a destructive way.

cons* obj ... | bigloo procedure

Returns an object formed by consing all arguments together from right to left. If only one `obj` is supplied, that `obj` is returned.

every fun clist1 clist2 ... | bigloo procedure

Applies the function `fun` across the lists, returning the last non-false if the function returns non-false on every application. If non-false, the result of `every` is the last value returned by the last application of `fun`.

    (every < '(1 2 3) '(2 3 4))            => #t
    (every < '(1 2 3) '(2 3 0))            => #f

any fun clist1 clist2 ... | bigloo procedure

Applies the function `fun` across the lists, returning non-false if the function returns non-false for at least one application. If non-false, the result of `any` is the first non-false value returned by `fun`.

    (any < '(1 2 3) '(2 3 4))            => #t
    (any < '(1 2 3) '(2 3 0))            => #t

find pred clist | bigloo procedure

Return the first element of `clist` that satisfies predicate `pred`; false if no element does.

    (find even? '(3 1 4 1 5 9))          => 4

Note that `find` has an ambiguity in its lookup semantics -- if find returns `#f`, you cannot tell (in general) if it found a `#f` element that satisfied `pred`, or if it did not find any element at all. In many situations, this ambiguity cannot arise -- either the list being searched is known not to contain any `#f` elements, or the list is guaranteed to have an element satisfying pred. However, in cases where this ambiguity can arise, you should use find-tail instead of find -- find-tail has no such ambiguity:

    (cond ((find-tail pred lis) => (lambda (pair) ...)) ; Handle (CAR PAIR)
          (else ...)) ; Search failed.

find-tail pred clist | bigloo procedure

Return the first pair of `clist` whose car satisfies `pred`. If no pair does, return false.
`find-tail` can be viewed as a general-predicate variant of the member function.
Examples:

    (find-tail even? '(3 1 37 -8 -5 0 0)) => (-8 -5 0 0)
    (find-tail even? '(3 1 37 -5)) => #f

    ;; MEMBER X LIS:
    (find-tail (lambda (elt) (equal? x elt)) lis)

In the circular-list case, this procedure "rotates" the list.

reduce f ridentity list | bigloo procedure

If `list` if null returns `ridentity`, if `list` has one element, returns that element. Otherwise, returns `f` applied to the first element of the `list` and to `reduce` of the rest of the list.
Examples:

    (reduce max 0 l) <=> (apply max l)

make-list n [fill] | bigloo procedure

Returns an `n`-element list, whose elements are all the value `fill`. If the `fill` argument is not given, the elements of the list may be arbitrary values.

    (make-list 4 'c)                     => (c c c c)

list-tabulate n init-proc | bigloo procedure

Returns an `n`-element list. Element i of the list, where 0 <= i < `n`, is produced by `(init-proc i)`. No guarantee is made about the dynamic order in which `init-proc` is applied to these indices.

    (list-tabulate 4 values)             => (0 1 2 3)

list-split list n [filler] | bigloo procedure

Split a `list` into a list of lists of length `n`. Last smaller list is filled with `filler`.

    (list-split '(1 2 3 4 5 6 7 8) 3 0) => ((1 2 3) (4 5 6) (7 8 0))
    (list-split (iota 10) 3)            => ((0 1 2) (3 4 5) (6 7 8) (9))
    (list-split (iota 10 3) '-1)        => ((0 1 2) (3 4 5) (6 7 8) (9 -1 -1))

iota count [start step] | bigloo procedure

Returns a list containing the elements

    (start start+step ... start+(count-1)*step)

The `start` and `step` parameters default to `0` and `1`, respectively. This procedure takes its name from the APL primitive.

    (iota 5) => (0 1 2 3 4)
    (iota 5 0 -0.1) => (0 -0.1 -0.2 -0.3 -0.4)

list-copy l | bigloo procedure

tree-copy l | bigloo procedure

The function `list-copy` copies the spine of the of the list. The function `tree-copy` recursively copies its arguments, descending only into the list cells.

delete-duplicates list [eq equal?] | bigloo procedure

delete-duplicates! list [eq equal?] | bigloo procedure

`delete-duplicates` removes duplicate elements from the `list` argument. If there are multiple equal elements in the argument list, the result list only contains the first or leftmost of these elements in the result. The order of these surviving elements is the same as in the original list -- `delete-duplicates` does not disorder the list (hence it is useful for "cleaning up" association lists).
The `equal` parameter is used to compare the elements of the list; it defaults to `equal?`. If x comes before y in list, then the comparison is performed (= x y). The comparison procedure will be used to compare each pair of elements in list no more than once; the order in which it is applied to the various pairs is not specified.
`delete-duplicates` is allowed to share common tails between argument and result lists -- for example, if the list argument contains only unique elements, it may simply return exactly this list.

See r5rs, Pairs and lists, for more details.

### 6.1.4 Symbols

Symbols are case sensitive and the reader is case sensitive too. So:

    (eq? 'foo 'FOO) => #f
    (eq? (string->symbol "foo") (string->symbol "FOO")) => #f

Symbols may contain special characters (such as #\Newline or #\Space). Such symbols that have to be read must be written: `|[^]+|`. The function `write` uses that notation when it encounters symbols containing special characters.

    (write 'foo) => foo
    (write 'Foo) =>Foo
    (write '|foo bar|) => |foo bar|

symbol? obj | procedure

symbol->string symbol | procedure

Returns the name of the symbol as a string. Modifying the string result of `symbol->string` could yield incoherent programs. It is better to copy the string before any physical update. For instance, don't write:

    (string-downcase! (symbol->string 'foo))

See r5rs, Symbols, for more details.
but prefer:

    (string-downcase (symbol->string 'foo))

string->symbol string | procedure

string->symbol-ci string | bigloo procedure

symbol-append symbol ... | bigloo procedure

`String->symbol` returns a symbol whose name is `string`. `String->symbol` respects the case of `string`. `String->symbol-ci` returns a symbol whose name is `(string-upcase `string`)`. `Symbol-append` returns a symbol whose name is the concatenation of all the `symbol`'s names.

gensym [obj] | bigloo procedure

Returns a new fresh symbol. If `obj` is provided and is a string or a symbol, it is used as prefix for the new symbol.

genuuid | bigloo procedure

Returns a string containing a new fresh Universal Unique Identifier (see http://fr.wikipedia.org/wiki/Universal_Unique_Identifier).

symbol-plist symbol-or-keyword | bigloo procedure

Returns the property-list associated with `symbol-or-keyword`.

getprop symbol-or-keyword key | bigloo procedure

Returns the value that has the key `eq?` to `key` from the `symbol-or-keyword`'s property list. If there is no value associated with `key` then `#f` is returned.

putprop! symbol-or-keyword key val | bigloo procedure

Stores `val` using `key` on `symbol-or-keyword`'s property list.

remprop! symbol-or-keyword key | bigloo procedure

Removes the value associated with `key` in the `symbol-or-keyword`'s property list. The result is unspecified.

Here is an example of properties handling:

    (getprop 'a-sym 'a-key)       => #f
    (putprop! 'a-sym 'a-key 24)
    (getprop 'a-sym 'a-key)       => 24
    (putprop! 'a-sym 'a-key2 25)
    (getprop 'a-sym 'a-key)       => 24
    (getprop 'a-sym 'a-key2)      => 25
    (symbol-plist 'a-sym)         => (a-key2 25 a-key 24)
    (remprop! 'a-sym 'a-key)
    (symbol-plist 'a-sym)         => (a-key2 25)
    (putprop! 'a-sym 'a-key2 16)
    (symbol-plist 'a-sym)         => (a-key2 16)

### 6.1.5 Keywords

Keywords constitute an extension to Scheme required by Dsssl [Dsssl96]. Keywords syntax is either `<ident>:` or `:<ident>`.
Keywords are autoquote and case sensitive. So

    (eq? toto: TOTO:) => #f

The colon character ```:`'' does not belong to they keyword. Hence

    (eq? toto: :toto) => #t

keyword? obj | bigloo procedure

keyword->string keyword | bigloo procedure

string->keyword string | bigloo procedure

keyword->symbol keyword | bigloo procedure

symbol->keyword symbol | bigloo procedure

### 6.1.6 Numbers

Bigloo has only three kinds of numbers: fixnum, long fixnum and flonum. Operations on complexes and rationals are not implemented but for compatibility purposes, the functions `complex?` and `rational?` exist. (In fact, `complex?` is the same as `number?` and `rational?` is the same as `real?` in Bigloo.) The accepted prefixes are `#b`, `#o`, `#d`, `#x`, `#e`, `#ex`, `#l`, `#lx`, `#z`, and `#zx`. For each generic arithmetic procedure, Bigloo provides two specialized procedures, one for fixnums and one for flonums. The names of these two specialized procedures is the name of the original one suffixed by `fx` (fixnum), `fl` (flonum), `elong` (exact C long), `llong` (exact C long long), and `bx` (big integer). A fixnum has the size of a C `long` minus 2 bits. A flonum has the size of a C `double`. An elong has the size of a C long. An llong has the size of a C long long. A big integer has an unbounded size.

number? obj | procedure

real? obj | procedure

integer? obj | procedure

complex? x | bigloo procedure

rational? x | bigloo procedure

fixnum? obj | bigloo procedure

flonum? obj | bigloo procedure

These two procedures are type checkers on types `integer` and `real`.

elong? obj | bigloo procedure

llong? obj | bigloo procedure

The `elong?` procedures is a type checker for "hardware" integers, that is integers that have the very same size has the host platform permits (e.g., 32 bits or 64 bits integers). The `llong?` procedure is a type checker for "hardware" long long integers. Exact integers literal are introduced with the special `#e` and `#ex` prefixes. Exact long integers literal are introduced with the special `#l` and `#lx` prefixes.

bignum? obj | bigloo procedure

This type checker tests if its argument is a big integer.

make-elong int | bigloo procedure

make-llong int | bigloo procedure

Create an exact fixnum integer from the fixnum value `int`.

minvalfx | bigloo procedure

maxvalfx | bigloo procedure

minvalelong | bigloo procedure

maxvalelong | bigloo procedure

minvalllong | bigloo procedure

maxvalllong | bigloo procedure

Returns the minimal value (respectively the maximal value) for fix integers.

exact? z | procedure

inexact? z | procedure

zero? z | library procedure

positive? z | library procedure

negative? z | library procedure

odd? n | library procedure

even? n | library procedure

zerofx? z | library procedure

positivefx? z | library procedure

negativefx? z | library procedure

oddfx? n | library procedure

evenfx? n | library procedure

zerofl? z | library procedure

positivefl? z | library procedure

negativefl? z | library procedure

oddfl? n | library procedure

evenfl? n | library procedure

zeroelong? z | library procedure

positiveelong? z | library procedure

negativeelong? z | library procedure

oddelong? n | library procedure

evenelong? n | library procedure

zerollong? z | library procedure

positivellong? z | library procedure

negativellong? z | library procedure

oddllong? n | library procedure

evenllong? n | library procedure

zerobx? z | library procedure

positivebx? z | library procedure

negativebx? z | library procedure

oddbx? n | library procedure

evenbx? n | library procedure

min x1 x2 ... | library procedure

max x1 x2 ... | library procedure

minfx x1 x2 ... | bigloo procedure

maxfx x1 x2 ... | bigloo procedure

minfl x1 x2 ... | bigloo procedure

maxfl x1 x2 ... | bigloo procedure

minbx x1 x2 ... | bigloo procedure

maxbx x1 x2 ... | bigloo procedure

= z1 z2 z3 ... | procedure

=fx i1 i2 | bigloo procedure

=fl r1 r2 | bigloo procedure

=elong r1 r2 | bigloo procedure

=llong r1 r2 | bigloo procedure

=bx r1 r2 | bigloo procedure

< z1 z2 z3 ... | procedure

<fx i1 i2 | bigloo procedure

<fl r1 r2 | bigloo procedure

<elong r1 r2 | bigloo procedure

<lllong r1 r2 | bigloo procedure

<bx r1 r2 | bigloo procedure

> z1 z2 z3 ... | procedure

>fx i1 i2 | bigloo procedure

>fl r1 r2 | bigloo procedure

>elong r1 r2 | bigloo procedure

>lllong r1 r2 | bigloo procedure

>bx r1 r2 | bigloo procedure

<= z1 z2 z3 ... | procedure

<=fx i1 i2 | bigloo procedure

<=fl r1 r2 | bigloo procedure

<=elong r1 r2 | bigloo procedure

<=llong r1 r2 | bigloo procedure

<=bx r1 r2 | bigloo procedure

>= z1 z2 z3 ... | procedure

>=fx i1 i2 | bigloo procedure

>=fl r1 r2 | bigloo procedure

>=elong r1 r2 | bigloo procedure

>=llong r1 r2 | bigloo procedure

>=bx r1 r2 | bigloo procedure

+ z ... | procedure

+fx i1 i2 | bigloo procedure

+fl r1 r2 | bigloo procedure

+elong r1 r2 | bigloo procedure

+llong r1 r2 | bigloo procedure

+bx r1 r2 | bigloo procedure

* z ... | procedure

*fx i1 i2 | bigloo procedure

*fl r1 r2 | bigloo procedure

*elong r1 r2 | bigloo procedure

*llong r1 r2 | bigloo procedure

*bx r1 r2 | bigloo procedure

- z | procedure

- z1 z2 ... | procedure

-fx i1 i2 | bigloo procedure

-fl r1 r2 | bigloo procedure

-elong r1 r2 | bigloo procedure

-llong r1 r2 | bigloo procedure

-bx r1 r2 | bigloo procedure

negfx i | bigloo procedure

negfl r | bigloo procedure

negelong r | bigloo procedure

negllong r | bigloo procedure

negbx r | bigloo procedure

These two functions implement the unary function `-`.

/ z1 z2 | procedure

/ z1 z2 ... | procedure

/fx i1 i2 | bigloo procedure

/fl r1 r2 | bigloo procedure

/elong r1 r2 | bigloo procedure

/llong r1 r2 | bigloo procedure

/bx r1 r2 | bigloo procedure

abs z | library procedure

absfl z | bigloo procedure

quotient z1 z2 | procedure

quotientelong z1 z2 | procedure

quotientllong z1 z2 | procedure

remainder z1 z2 | procedure

remainderelong z1 z2 | procedure

remainderllong z1 z2 | procedure

remainderfl z1 z2 | procedure

modulo z1 z2 | procedure

gcd z ... | procedure

lcm z ... | procedure

floor z | procedure

floorfl z | procedure

ceiling z | procedure

ceilingfl z | procedure

truncate z | procedure

truncatefl z | procedure

round z | procedure

roundfl z | procedure

random z | bigloo procedure

randomfl | bigloo procedure

randombx z | bigloo procedure

seed-random! z | bigloo procedure

the `random` function returns a pseudo-random integer between 0 and `z`.
If no seed value is provided, the `random` function is automatically seeded with a value of 1.
The function `randomfl` returns a double in the range [0..1].

exp z | procedure

expfl z | procedure

log z | procedure

logfl z | procedure

log2 z | procedure

log2fl z | procedure

log10 z | procedure

log10fl z | procedure

sin z | procedure

sinfl z | procedure

cos z | procedure

cosfl z | procedure

tan z | procedure

tanfl z | procedure

asin z | procedure

asinfl z | procedure

acos z | procedure

acosfl z | procedure

atan z1 z2 | procedure

atanfl z1 z2 | procedure

sqrt z | procedure

sqrtfl z | procedure

expt z1 x2 | procedure

exptfl z1 x2 | procedure

exact->inexact z | procedure

inexact->exact z | procedure

number->string z | procedure

integer->string i [radix 10] | bigloo procedure

integer->string/padding i padding [radix 10] | bigloo procedure

elong->string i [radix 10] | bigloo procedure

llong->string i [radix 10] | bigloo procedure

bignum->string i [radix 10] | bigloo procedure

real->string z | bigloo procedure

unsigned->string i [radix 16] | bigloo procedure

The function `integer->string/padding` converts its arguments into a string with a left padding filled of characters `0`.

    (integer->string/padding 3 5)       => "00003"

The function `unsigned->string` only accepts the following radixes: `2`, `8`, and `16`. It converts its argument into an unsigned representation.

    (unsigned->string 123 16)           => "7b"
    (unsigned->string -123 16)          => "ffffff85"

nanfl? z | bigloo procedure

Returns `#t` if the floating `z` is `not-a-number`. Returns `#f` otherwise.

infinitefl? z | bigloo procedure

finitefl? z | bigloo procedure

The predicate `infinitefl?` returns `#t` if the floating `z` is positive or negative infinite. Returns `#f` otherwise.
The predicate `finitefl?` is true if and only if `z` is finite.

signbitfl z | bigloo procedure

Returns `0` is `z` is positive or null. Returns a positive integer otherwise.

bignum->octet-string bignum | bigloo procedure

Returns a binary big-endian representation of the given bignum `bignum`.

    (string-hex-extern (bignum->octet-string #zx1234567)) => "01234567"

double->ieee-string z | bigloo procedure

float->ieee-string z | bigloo procedure

Returns a big-endian representation of the given number.

string->number string [radix 10] | procedure

string->elong string radix | bigloo procedure

string->llong string radix | bigloo procedure

string->bignum string radix | bigloo procedure

Bigloo implements a restricted version of `string->number`. If `string` denotes a floating point number then, the only radix `10` may be send to `string->number`. That is:

    (string->number "1243" 16)          => 4675
    (string->number "1243.0" 16)        -|
    # *** ERROR:bigloo:string->number
    # Only radix `10' is legal for floating point number -- 16
    (string->elong "234456353")         => #e234456353

    (string->number "#x1243")          => #f

string->integer string [radix 10] [startpos 0] | bigloo procedure

string->real string | bigloo procedure

In addition, `string->number` does not support radix encoded inside `string`. That is:
For efficiency, `string->real` and `string->integer` do not test whether the string can be read as a number. Therefore the result might be wrong if the string cannot be read as a number.

octet-string->bignum string | bigloo procedure

Counterpart to `bignum->octet-string`. Takes the bignum representation in big-endian format `string` and returns the corresponding bignum.

    (octet-string->bignum (bignum->octet-string #z1234)) => #z1234

ieee-string->double string | bigloo procedure

ieee-string->float string | bigloo procedure

Convert the big-endian representations to their numeric values.

fixnum->flonum i | bigloo procedure

flonum->fixnum r | bigloo procedure

elong->fixnum i | bigloo procedure

fixnum->elong r | bigloo procedure

llong->fixnum i | bigloo procedure

fixnum->llong r | bigloo procedure

elong->flonum i | bigloo procedure

flonum->elong r | bigloo procedure

llong->flonum i | bigloo procedure

flonum->llong r | bigloo procedure

These last procedures implement the natural translation from and to fixnum, flonum, elong, and llong.

double->llong-bits z | bigloo procedure

float->int-bits z | bigloo-procedure

Returns the double-bits as a llong.

llong-bits->double llong | bigloo procedure

int-bits->float int | bigloo procedure

Converts the given llong bits to a double.

See r5rs, Numerical operations, for more details.

### 6.1.7 Characters

Bigloo knows named characters `#\alarm`, `#\backspace`, `#\delete`, `#\escape`, `#\tab`, `#\return`, and `#\null` in addition to the `#\space` and `#\newline` of R5RS.
A new alternate syntax exists for characters: `#a<ascii-code>` where `<ascii-code>` is the three digit decimal ASCII number of the character to be read. Thus, for instance, the character `#\space` can be written `#a032`. Bigloo also supports the R7Rs syntax `#\x<hex-code>`.

char? obj | procedure

char=? char1 char2 | procedure

char<? char1 char2 | procedure

char>? char1 char2 | procedure

char<=? char1 char2 | procedure

char>=? char1 char2 | procedure

char-ci=? char1 char2 | library procedure

char-ci<? char1 char2 | library procedure

char-ci>? char1 char2 | library procedure

char-ci<=? char1 char2 | library procedure

char-ci>=? char1 char2 | library procedure

char-alphabetic? char | library procedure

char-numeric? char | library procedure

char-whitespace? char | library procedure

char-upper-case? char | library procedure

char-lower-case? char | library procedure

char->integer char | procedure

integer->char i | procedure

char-upcase char | library procedure

char-downcase char | library procedure

### 6.1.8 UCS-2 Characters

UCS-2 Characters are two byte encoded characters. They can be read with the syntax: `#u<unicode>` where `<unicode>` is the four digit hexadecimal Unicode value of the character to be read. Thus, for instance, the character `#\space` can be written `#u0020`.

ucs2? obj | bigloo procedure

ucs2=? ucs2a ucs2b | bigloo procedure

ucs2<? ucs2a ucs2b | bigloo procedure

ucs2>? ucs2a ucs2b | bigloo procedure

ucs2<=? ucs2a ucs2b | bigloo procedure

ucs2>=? ucs2a ucs2b | bigloo procedure

ucs2-ci=? ucs2a ucs2b | bigloo procedure

ucs2-ci<? ucs2a ucs2b | bigloo procedure

ucs2-ci>? ucs2a ucs2b | bigloo procedure

ucs2-ci<=? ucs2a ucs2b | bigloo procedure

ucs2-ci>=? ucs2a ucs2b | bigloo procedure

ucs2-alphabetic? ucs2 | bigloo procedure

ucs2-numeric? ucs2 | bigloo procedure

ucs2-whitespace? ucs2 | bigloo procedure

ucs2-upper-case? ucs2 | bigloo procedure

ucs2-lower-case? ucs2 | bigloo procedure

ucs2->integer ucs2 | bigloo procedure

integer->ucs2 i | bigloo procedure

ucs2->char ucs2 | bigloo procedure

char->ucs2 char | bigloo procedure

ucs2-upcase ucs2 | bigloo procedure

ucs2-downcase ucs2 | bigloo procedure

### 6.1.9 Strings

There are three different syntaxes for strings in Bigloo: traditional, foreign or Unicode. The traditional syntax for strings may conform to the Revised Report, see r5rs, Lexical structure. With the foreign syntax, C escape sequences are interpreted as specified by ISO-C. In addition, Bigloo's reader evaluate `\x??` sequence as an hexadecimal escape character. For Unicode syntax, see Unicode (UCS-2) Strings. Only the reader distinguishes between these three appearances of strings; i.e., there is only one type of string at evaluation-time. The regular expression describing the syntax for foreign string is: `#"([^"]|\")*"`. Escape characters are controlled by the parameter `bigloo-strict-r5rs-strings` (see Parameters).
The library functions for string processing are:

string? obj | procedure

string-null? s | SRFI-13 procedure

Is `s` an empty string?

make-string k | procedure

make-string k char | procedure

string char ... | library procedure

string-length string | procedure

string-ref string k | procedure

string-set! string k char | procedure

string=? string1 string2 | library procedure

This function returns `#t` if the `string1` and `string2` are made of the same characters. It returns `#f` otherwise.

substring=? string1 string2 len | bigloo procedure

This function returns `#t` if `string1` and `string2` have a common prefix of size `len`.

    (substring=? "abcdef" "ab9989898" 2)
       => #t
    (substring=? "abcdef" "ab9989898" 3)
       => #f

substring-at? string1 string2 offset [len] | bigloo procedure

substring-ci-at? string1 string2 offset [len] | bigloo procedure

This function returns `#t` if `string2` is at position `offset` in the string `string1`. It returns `#f` otherwise.

    (substring-at? "abcdefghij" "def" 3)
       => #t
    (substring-at? "abcdefghij" "def" 2)
       => #f
    (substring-at? "abcdefghij" "defz" 3)
       => #f
    (substring-at? "abcdefghij" "defz" 3 3)
       => #t

string-ci=? string1 string2 | library procedure

substring-ci=? string1 string2 len | bigloo procedure

string<? string1 string2 | library procedure

string>? string1 string2 | library procedure

string<=? string1 string2 | library procedure

string>=? string1 string2 | library procedure

string-ci<? string1 string2 | library procedure

string-ci>? string1 string2 | library procedure

string-ci<=? string1 string2 | library procedure

string-ci>=? string1 string2 | library procedure

string-index string charset [start 0] [count -1] | bigloo procedure

string-char-index string char [start 0] | bigloo procedure

string-index-right string charset [start len-1] | bigloo procedure

Returns the first occurrence of a character of `char-or-set` in `string`. The argument `charset` is either a character or a string. If no character is found, `string-index` returns `#f` The argument `count`, if provided, is the number of characters to be scanned in the string.

string-skip string charset [start 0] | bigloo procedure

string-skip-right string charset [start len-1] | bigloo procedure

`string-skip` (resp. `string-skip-right`) searches through the `string` from the left (resp. right), returning the index of the first occurrence of a character which

- is not equal to c (if c is a character);
- is not in c (if c is a character set);
- does not satisfy the predicate c (if c is a procedure).

If no such index exists, the functions return false.
The start and end parameters specify the beginning and end indices of the search; the search includes the start index, but not the end index. Be careful of "fencepost" considerations: when searching right-to-left, the first index considered is end-1 whereas when searching left-to-right, the first index considered is start. That is, the start/end indices describe a same half-open interval [start,end).

string-contains string1 string2 [start 0] | bigloo procedure

string-contains-ci string1 string2 [start 0] | bigloo procedure

Does string `string1` contain string `string2`?
Return the index in `string1` where `string2` occurs first as a substring, or false.
`string-contains-ci` is the case-insensitive variant. Case-insensitive comparison is done by case-folding characters with the operation:

    (char-downcase (char-upcase c))

string-compare3 string1 string2 | bigloo procedure

string-compare3-ci string1 string2 | bigloo procedure

This function compares `string1` and `string2`. It returns a negative integer if `string1` < `string2`. It returns zero if the `string1` equal `string2`. It returns a positive integer if `string1` > `string2`.

string-natural-compare3 string1 string2 [start1 0] [start2 0] | bigloo procedure

string-natural-compare3-ci string1 string2 [start1 0] [start2 0] | bigloo procedure

This function compares `string1` and `string2` according to a natural string order. It returns a negative integer if `string1` < `string2`. It returns zero if the `string1` equal `string2`. It returns a positive integer if `string1` > `string2`.

    (string-natural-compare "foo" "foo")
       => 0
    (string-natural-compare "foo0" "foo1")
       => -1
    (string-natural-compare "foo1" "foo0")
       => 1
    (string-natural-compare "rfc822.txt" "rfc1.txt")
       => -1
    (string-natural-compare "rfc1.txt" "rfc2086.txt")
       => -1
    (string-natural-compare "rfc2086.txt" "rfc1.txt")
       => 1
    (string-natural-compare "rfc822.txt" "rfc2086.txt")
       => -1
    (string-natural-compare "a0" "a1")
       => -1
    (string-natural-compare "a1" "a1a")
       => -1
    (string-natural-compare "a1a" "a1b")
       => -1
    (string-natural-compare "a1b" "a2")
       => -1
    (string-natural-compare "a2" "a10")
       => -1
    (string-natural-compare "a10" "a20")
       => -1
    (string-natural-compare "a2" "a20")
       => -1
    (string-natural-compare "x2-g8" "x2-y7")
       => -1
    (string-natural-compare "1.001" "1.002")
       => -1
    (string-natural-compare "1.002" "1.010")
       => -1
    (string-natural-compare "1.010"  "1.02")
       => 1
    (string-natural-compare "1.02" "1.1")
       => -1
    (string-natural-compare "1.1" "1.02")
       => 1
    (string-natural-compare "1.02" "1.3")
       => -1

substring string start [end] | library procedure

`string` must be a string, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (string-length STRING)

The optional argument `end` defaults to `(string-length STRING)`.
`substring` returns a newly allocated string formed from the characters of `STRING` beginning with index `START` (inclusive) and ending with index `END` (exclusive).

    (substring "abcdef" 0 5)
       => "abcde"
    (substring "abcdef" 1 5)
       => "bcde"

string-shrink! string end | library procedure

`string` must be a string, and `end` must be an exact integers satisfying:

      0 <= END <= (string-length STRING)

`string-shrink!` returns a new string formed from the characters of `STRING` beginning with index 0 (inclusive) and ending with index `END` (exclusive). As much as possible `string-shrink!` changes the argument `string`. That is, as much as possible, and for the back-ends that enable it, `string-shrink!` operates a side effect on its argument.

    (let ((s (string #\a #\b #\c #\d #\e)))
       (set! s (string-shrink! s 3))
       s)
       => "abc"

string-append string ... | library procedure

string->list string | library procedure

list->string list | library procedure

string-copy string | library procedure

string-fill! string char | bigloo procedure

Stores `char` in every element of the given `string` and returns an unspecified value.

string-downcase string | bigloo procedure

Returns a newly allocated version of string where each upper case letter is replaced by its lower case equivalent.

string-upcase string | bigloo procedure

Returns a newly allocated version of string where each lower case letter is replaced by its upper case equivalent.

string-capitalize string | bigloo procedure

Builds a newly allocated capitalized string.

string-downcase! string | bigloo procedure

Physically downcases the `string` argument.

string-upcase! string | bigloo procedure

Physically upcases the `string` argument.

string-capitalize! string | bigloo procedure

Physically capitalized the `string` argument.

string-for-read string | bigloo procedure

Returns a copy of `string` with each special character replaced by an escape sequence.

blit-string! string1 o1 string2 o2 len | bigloo procedure

Fill string `string2` starting at position `o2` with `len` characters taken out of string `string1` from position `o1`.

    (let ((s (make-string 20 #\-)))
    	(blit-string! "toto" 0 s 16 4)
    	s)
       => "----------------toto"

string-replace string char1 char2 | bigloo procedure

string-replace! string char1 char2 | bigloo procedure

Replace all the occurrence of `char1` by `char2` in `string`. The function `string-replace` returns a newly allocated string. The function `string-replace!` modifies its first argument.

string-split string | bigloo procedure

string-split string delimiters | bigloo procedure

Parses `string` and returns a list of tokens ended by a character of the `delimiters` string. If `delimiters` is omitted, it defaults to a string containing a space, a tabulation and a newline characters.

    (string-split "/usr/local/bin" "/") => ("usr" "local" "bin")
    (string-split "once   upon a time") => ("once" "upon" "a" "time")

string-cut string | bigloo procedure

string-cut string delimiters | bigloo procedure

The function `string-cut` behaves as `string-split` but it introduces empty strings for consecutive occurrences of delimiters.

    (string-cut "/usr//local/bin" "/") => ("usr" "" "local" "bin")
    (string-cut "once   upon a time") => ("once" "" "" "" "upon" "a" "time")

string-delete string char/charset/pred s [start end] | SRFI-13 procedure

Filter the string `string`, retaining only those characters that are not equal to `char`, not present in `charset`, or not satisfying `pred`. This function returns a fresh string no larger than `end` - `start`.

string-prefix-length s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-suffix-length s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-prefix-length-ci s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-suffix-length-ci s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

Return the length of the longest common prefix/suffix of the two strings. For prefixes, this is equivalent to the "mismatch index" for the strings (modulo the starti index offsets).
The optional start/end indices restrict the comparison to the indicated substrings of s1 and s2.

string-prefix? s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-suffix? s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-prefix-ci? s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

string-suffix-ci? s1 s2 [start1 end1 start2 end2] | SRFI-13 procedure

Is s1 a prefix/suffix of s2?
The optional start/end indices restrict the comparison to the indicated substrings of s1 and s2.

string-hex-intern string | bigloo procedure

string-hex-intern! string | bigloo procedure

Converts an hexadecimal `string` of `n` characters into an actual string of `n/2` characters.

    (string-hex-intern "4a4b4c") => "JKL"

string-hex-extern string [start [end]] | bigloo procedure

Converts a `string` into a hexadecimal representation.
`string` must be a string, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (string-length STRING)

The optional argument `start` default to 0. The optional argument `end` defaults to `(string-length STRING)`.

    (string-hex-extern "JKL") => "4a4b4c"

### 6.1.10 Unicode (UCS-2) Strings

UCS-2 strings cannot be read by the standard reader but UTF-8 strings can. The special syntax for UTF-8 is described by the regular expression: `#u"([^]|\")*"`.
The library functions for Unicode string processing are:

ucs2-string? obj | bigloo procedure

make-ucs2-string k | bigloo procedure

make-ucs2-string k char | bigloo procedure

ucs2-string k ... | bigloo procedure

ucs2-string-length s-ucs2 | bigloo procedure

ucs2-string-ref s-ucs2 k | bigloo procedure

ucs2-string-set! s-ucs2 k char | bigloo procedure

ucs2-string=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string-ci=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string<? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string>? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string<=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string>=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string-ci<? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string-ci>? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string-ci<=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-string-ci>=? s-ucs2a s-ucs2b | bigloo procedure

ucs2-substring s-ucs2 start end | bigloo procedure

ucs2-string-append s-ucs2 ... | bigloo procedure

ucs2-string->list s-ucs2 | bigloo procedure

list->ucs2-string chars | bigloo procedure

ucs2-string-copy s-ucs2 | bigloo procedure

ucs2-string-fill! s-ucs2 char | bigloo procedure

Stores `char` in every element of the given s-ucs2 and returns an unspecified value.

ucs2-string-downcase s-ucs2 | bigloo procedure

Builds a newly allocated ucs2-string with lower case letters.

ucs2-string-upcase s-ucs2 | bigloo procedure

Builds a new allocated ucs2-string with upper case letters.

ucs2-string-downcase! s-ucs2 | bigloo procedure

Physically downcases the `s-ucs2` argument.

ucs2-string-upcase! s-ucs2 | bigloo procedure

Physically upcases the `s-ucs2` argument.

ucs2-string->utf8-string s-ucs2 | bigloo procedure

utf8-string->ucs2-string `string` | bigloo procedure

Convert UCS-2 strings to (or from) UTF-8 encoded ascii strings.

utf8-string? string [strict `#f`] | bigloo procedure

Returns `#t` if and only if the argument `string` is a well formed UTF-8 string. Otherwise returns `#f`.
If the optional argument `strict` is `#t`, half utf16-surrogates are rejected. The optional argument `strict` defaults to `#f`.

ascii-string? string | bigloo procedure

Returns `#t` if and only if the argument `string` is only composed of ascii characters. Otherwise returns `#f`.

utf8-string-encode string [strict `#f`] | bigloo procedure

Returns a copy of `string` where all the illegal UTF-8 prefix are replaced with the Unicode Replacement Character EF BF BD. The result is a well formed UTF-8 string.

utf8-string-length string | bigloo procedure

Returns the number of characters of an UTF-8 string. It raises an error if the string is not a well formed UTF-8 string (i.e., it does satisfies the `utf8-string?` predicate.

utf8-codepoint-length string | bigloo procedure

Returns the number of code points of an UTF-8 string. The code points length is the number of 16bits long values needed to encode the utf8 strings in utf16.

utf8-string-ref string i | bigloo procedure

Returns the character (represented as an UTF-8 string) at the position `i` in `string`.

utf8-substring string start [end] | library procedure

`string` must be a string, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (string-length STRING)

The optional argument `end` defaults to `(utf8-string-length STRING)`.
`utf8-substring` returns a newly allocated string formed from the characters of `STRING` beginning with index `START` (inclusive) and ending with index `END` (exclusive).
If the argument `string` is not a well formed UTF-8 string an error is raised. Otherwise, the result is also a well formed UTF-8 string.

iso-latin->utf8 string | bigloo procedure

iso-latin->utf8! string | bigloo procedure

utf8->iso-latin `string` | bigloo procedure

utf8->iso-latin! `string` | bigloo procedure

utf8->iso-latin-15 `string` | bigloo procedure

utf8->iso-latin-15! `string` | bigloo procedure

Encode and decode iso-latin strings into utf8. The functions `iso-latin->utf8-string!`, `utf8->iso-latin!` and `utf8->iso-latin-15!` may return, as result, the string they receive as argument.

cp1252->utf8 string | bigloo procedure

cp1252->utf8! string | bigloo procedure

utf8->cp1252 `string` | bigloo procedure

utf8->cp1252! `string` | bigloo procedure

Encode and decode cp1252 strings into utf8. The functions `cp1252->utf8-string!` and `utf8->cp1252!` may return, as result, the string they receive as argument.

8bits->utf8 string table | bigloo procedure

8bits->utf8! string table | bigloo procedure

utf8->8bits string inv-table | bigloo procedure

utf8->8bits! string inv-table | bigloo procedure

These are the general conversion routines used internally by `iso-latin->utf8` and `cp1252->utf8`. They convert any 8 bits `string` into its equivalent UTF-8 representation and vice versa.
The argument `table` should be either `#f`, which means that the basic (i.e., iso-latin-1) 8bits -> UTF-8 conversion is used, or it must be a vector of at least 127 entries containing strings of characters. This table contains the encodings for the 8 bits characters whose code range from 128 to 255.
The table is not required to be complete. That is, it is not required to give the whole character encoding set. Only the characters that need a non-iso-latin canonical representation must be given. For instance, the CP1252 table can be defined as:

    (define cp1252
       '#("\xe2\x82\xac" ;; 0x80
          ""             ;; 0x81
          "\xe2\x80\x9a" ;; 0x82
          "\xc6\x92"     ;; 0x83
          "\xe2\x80\x9e" ;; 0x84
          "\xe2\x80\xa6" ;; 0x85
          "\xe2\x80\xa0" ;; 0x86
          "\xe2\x80\xa1" ;; 0x87
          "\xcb\x86"     ;; 0x88
          "\xe2\x80\xb0" ;; 0x89
          "\xc5\xa0"     ;; 0x8a
          "\xe2\x80\xb9" ;; 0x8b
          "\xc5\x92"     ;; 0x8c
          ""             ;; 0x8d
          "\xc5\xbd"     ;; 0x8e
          ""             ;; 0x8f
          ""             ;; 0x90
          "\xe2\x80\x98" ;; 0x91
          "\xe2\x80\x99" ;; 0x92
          "\xe2\x80\x9c" ;; 0x93
          "\xe2\x80\x9d" ;; 0x94
          "\xe2\x80\xa2" ;; 0x95
          "\xe2\x80\x93" ;; 0x96
          "\xe2\x80\x94" ;; 0x97
          "\xcb\x9c"     ;; 0x98
          "\xe2\x84\xa2" ;; 0x99
          "\xc5\xa1"     ;; 0x9a
          "\xe2\x80\xba" ;; 0x9b
          "\xc5\x93"     ;; 0x9c
          ""             ;; 0x9d
          "\xc5\xbe"     ;; 0x9e
          "\xc5\xb8"))   ;; 0x9f

The argument `inv-table` is an inverse table that can be build from a table and using the function `inverse-utf8-table`.

inverse-utf8-table vector | procedure

Inverse an UTF-8 table into an object suitable for `utf8->8bits` and `utf8->8bits!`.

### 6.1.11 Vectors

Vectors are not autoquoted objects.

vector? obj | procedure

make-vector k | procedure

make-vector k obj | procedure

vector obj ... | library procedure

vector-length vector | procedure

vector-ref vector k | procedure

vector-set! vector k obj | procedure

vector->list vector | library procedure

list->vector list | library procedure

vector-fill! vector obj [start [end]] | library procedure

Stores `obj` in every element of `vector`. For instance:

    (let ((v (make-vector 5 #f)))
       (vector-fill! v #t)
       v)

copy-vector vector len | bigloo procedure

Allocate a new vector of size `len` and fills it with the first `len` element of `vector`. The new length `len` may be bigger than the old vector length.

vector-copy vector start end | bigloo procedure

`vector` must be a vector, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (vector-length VECTOR)

`vector-copy` returns a newly allocated vector formed from the elements of `VECTOR` beginning with index `START` (inclusive) and ending with index `END` (exclusive).

    (vector-copy '#(1 2 3 4) 0 4)
       => '#(1 2 3 4)
    (vector-copy '#(1 2 3 4) 1 3)
       => '#(2 3)

vector-copy! target tstart source [sstart [send]] | bigloo procedure

Copies a block of elements from `source` to `target`, both of which must be vectors, starting in target at `tstart` and starting in source at `sstart`, ending when `send - sstart` elements have been copied. It is an error for `target` to have a length less than `tstart + (send - sstart)`. `Sstart` defaults to `0` and `send` defaults to the length of `source`.

See r5rs, Vectors, for more details.

vector-append vector ... | bigloo procedure

Returns a newly allocated vector that contains all elements in order from the subsequent locations in vector ....
Examples:

    (vector-append '#(x) '#(y)) => #(x y)
    (vector-append '#(a) '#(b c d)) => #(a b c d)
    (vector-append '#(a #(b)) '#(#(c))) => #(a #(b) #(c))

vector-for-each proc vector ... | bigloo procedure

Apply `proc` to all the elements of the `vectors`. The arity of `proc` must be the number of passed vectors. All vectors must have the same length. The procedure is applied from elements of index `0` to `(vector-length vector) - 1`.

vector-map proc vector ... | bigloo procedure

vector-map! proc vector ... | bigloo procedure

The function `vector-map` creates a new vector whose size the is the size of its argument `vector`. Each elements of the new vector is the result of apply `proc` to the corresponding elements of the initial vectors.
The function `vector-map!` modifies the elements of the argument `vector`.

vector-shrink! vector end | bigloo procedure

Shrink a vector. The argument `vector` must be a vector, and `end` must be an exact integers satisfying:

      0 <= END <= (vector-length STRING)

Shrink a vector. The resulting vector's len is the minimum value of `(vector-length vec)` and `nlen`.
`vector-shrink!` returns a new vector formed from the values of `VECTOR` beginning with index 0 (inclusive) and ending with index `END` (exclusive). As much as possible `vector-shrink!` changes the argument `vector`. That is, as much as possible, and for the back-ends that enable it, `vector-shrink!` operates a side effect on its argument.

### 6.1.12 Homogeneous Vectors (SRFI-4)

Bigloo fully supports SRFI-4 specification of homogeneous vectors (see http://srfi.schemers.org/srfi-4/srfi-4.html).
Each homogeneous vector is represented by a Bigloo type. That is:

- `::s8vector` signed exact integer in the range -(2^7) to (2^7)-1
- `::u8vector` unsigned exact integer in the range 0 to (2^8)-1
- `::s16vector` signed exact integer in the range -(2^15) to (2^15)-1
- `::u16vector` unsigned exact integer in the range 0 to (2^16)-1
- `::s32vector` signed exact integer in the range -(2^31) to (2^31)-1
- `::u32vector` unsigned exact integer in the range 0 to (2^32)-1
- `::s64vector` signed exact integer in the range -(2^63) to (2^63)-1
- `::u64vector` unsigned exact integer in the range 0 to (2^64)-1
- `f32vector` inexact small real
- `f64vector` inexact largest real

Each homogeneous vector datatype has an external representation which is supported by the read and write procedures and by the program parser. Each datatype also has a set of associated predefined procedures analogous to those available for Scheme's heterogeneous vectors.
As noted by Marc Feeley's specification, for each value of TAG in { s8, u8, s16, u16, s32, u32, s64, u64, f32,f64 }, if the datatype TAGvector is supported, then

- the external representation of instances of the datatype TAGvector is #TAG( ...elements... ).
  For example, `#u8(0 100 #xff)` is an u8vector of length 3 containing 0, 100 and 255; `#f64(-1.5)` is an f64vector of length 1 containing -1.5.
  Note that the syntax for float vectors conflicts with Standard Scheme which parses `#f32()` as 3 objects: `#f`, `32` and `()`. For this reason, conformance to this SRFI implies this minor nonconformance to Standard Scheme.
  This external representation is also available in program source code. For example, `(set! x '#u8(1 2 3))` will set x to the object `#u8(1 2 3)`. Literal homogeneous vectors must be quoted just like heterogeneous vectors must be. Homogeneous vectors can appear in quasiquotations but must not contain unquote or unquote-splicing forms (i.e. ``(,x #u8(1 2))` is legal but ``#u8(1 ,x 2)` is not). This restriction is to accomomdate the many Scheme systems that use the read procedure to parse programs.
- the following predefined procedures are available:

  TAGvector? obj | SRFI-4 procedure

  make-TAGvector n [ TAGvalue ] | SRFI-4 procedure

  TAGvector TAGvalue ... | SRFI-4 procedure

  TAGvector-length TAGvect | SRFI-4 procedure

  TAGvector-ref TAGvect i | SRFI-4 procedure

  TAGvector-set! TAGvect i TAGvalue | SRFI-4 procedure

  TAGvector->list TAGvect | SRFI-4 procedure

  list->TAGvector TAGlist | SRFI-4 procedure

  where obj is any Scheme object, n is a nonnegative exact integer, i is a nonnegative exact integer less than the length of the vector, TAGvect is an instance of the TAGvector datatype, TAGvalue is a number of the type acceptable for elements of the TAGvector datatype, and TAGlist is a proper list of numbers of the type acceptable for elements of the TAGvector datatype.
  It is an error if TAGvalue is not the same type as the elements of the TAGvector datatype (for example if an exact integer is passed to f64vector). If the fill value is not specified, the content of the vector is unspecified but individual elements of the vector are guaranteed to be in the range of values permitted for that type of vector.

### 6.1.13 Control features

procedure? obj | procedure

apply proc arg1 ... args | procedure

map proc list1 list2 ... | library procedure

map! proc list1 list2 ... | bigloo procedure

for-each proc list1 list2 ... | library procedure

filter pred list ... | library procedure

filter! pred list ... | library procedure

Strip out all elements of `list` for which the predicate `pred` is not true. The second version `filter!` is destructive:

    (filter number? '(1 2 #\a "foo" foo 3)) => (1 2 3)
    (let ((l (list 1 2 #\a "foo" 'foo 3)))
       (set! l (filter! number? l))
       l)                                   => (1 2 3)

append-map proc list1 list2 ... | library procedure

append-map! proc list1 list2 ... | library procedure

The expression

      (append-map f clist1 clist2 ...)

is equivalent to:

      (apply append (map f clist1 clist2 ...))

The expression

      (append-map! f clist1 clist2 ...)

is equivalent to:

      (apply append! (map f clist1 clist2 ...))

filter-map pred list ... | bigloo procedure

As `map` but only none `#f` values are accumulated in the resulting list. The Bigloo implementation complies with the SRFI-1 description.

    (filter-map (lambda (x) (if (number? x) '- #f)) '(1 2 #\a "foo" foo 3)) => (- - -)

sort proc obj | bigloo procedure

sort obj proc | bigloo procedure

Sorts `obj` according to `proc` test. The argument `obj` can either be a vector or a list. In either case, a copy of the argument is returned. For instance:

    (let ((l '(("foo" 5) ("bar" 6) ("hux" 1) ("gee" 4))))
       (sort (lambda (x y) (string<? (car x) (car y))) l))
       => ((bar 6) (foo 5) (gee 4) (hux 1))

The second form (which uses `obj` before `proc` ensures backward compatibility with old Lisp systems, and older Bigloo versions. It is deprecated.

force promise | library procedure

call/cc proc | bigloo procedure

This function is the same as the `call-with-current-continuation` function of the R5RS, see r5rs, call-with-current-continuation, but it is necessary to compile the module with the `-call/cc` option to use it, see Section See The Bigloo command line.
Note: Since `call/cc` is difficult to compile efficiently, one might consider using `bind-exit` instead. For this reason, we decided to enable `call/cc` only with a compiler option.

bind-exit escape body | bigloo syntax

This form provides an escape operator facility. `bind-exit` evaluates the `body`, which may refer to the variable `escape` which will denote an ``escape function'' of one argument: when called, this escape function will return from the `bind-exit` form with the given argument as the value of the `bind-exit` form. The `escape` can only be used while in the dynamic extent of the form. Bindings introduced by `bind-exit` are immutable.

    (bind-exit (exit)
     (for-each (lambda (x)
                 (if (negative? x)
                     (exit x)))
               '(54 0 37 -3 245 19))
     #t)                                  => -3

    (define list-length
      (lambda (obj)
        (bind-exit (return)
         (letrec ((r (lambda (obj)
                        (cond ((null? obj) 0)
                              ((pair? obj)
                               (+ (r (cdr obj)) 1))
                              (else (return #f))))))
              (r obj)))))

    (list-length '(1 2 3 4))               => 4
    (list-length '(a b . c))               => #f

unwind-protect expr protect | bigloo syntax

This form provides protections. Expression `expr` is evaluated. If this evaluation requires the invocation of an escape procedure (a procedure bounded by the `bind-exit` special form), `protect` is evaluated before the control jump to the exit procedure. If `expr` does not raise any exit procedure, `unwind-protect` has the same behaviour as the `begin` special form except that the value of the form is always the value of `expr`.

    (define (my-open f)
       (if (file-exists? f)
           (let ((port (open-input-file f)))
              (if (input-port? port)
                  (unwind-protect
                     (bar port)
                     (close-input-port port))))))

dynamic-wind before thunk after | procedure

Calls `thunk` without arguments, returning the result(s) of this call. `Before` and `after` are called, also without arguments, as required by the following rules (note that in the absence of calls to continuations captured using `call/cc` the three arguments are called once each, in order). `Before` is called whenever execution enters the dynamic extent of the call to `thunk` and `after` is called whenever it exits that dynamic extent. The dynamic extent of a procedure call is the period between when the call is initiated and when it returns. In Scheme, because of `call/cc`, the dynamic extent of a call may not be a single, connected time period. It is defined as follows:

- The dynamic extent is entered when execution of the body of the called procedure begins.
- The dynamic extent is also entered when execution is not within the dynamic extent and a continuation is invoked that was captured (using `call/cc`) during the dynamic extent.
- It is exited when the called procedure returns.
- It is also exited when execution is within the dynamic extent and a continuation is invoked that was captured while not within the dynamic extent.

If a second call to `dynamic-wind` occurs within the dynamic extent of the call to `thunk` and then a continuation is invoked in such a way that the `after`s from these two invocations of `dynamic-wind` are both to be called, then the `after` associated with the second (inner) call to `dynamic-wind` is called first.
If a second call to `dynamic-wind` occurs within the dynamic extent of the call to `thunk` and then a continuation is invoked in such a way that the `before`s from these two invocations of `dynamic-wind` are both to be called, then the `before` associated with the first (outer) call to `dynamic-wind` is called first.
If invoking a continuation requires calling the `before` from one call to `dynamic-wind` and the `after` from another, then the `after` is called first.
The effect of using a captured continuation to enter or exit the dynamic extent of a call to `before` or `after` is undefined.

    (let ((path '())
          (c #f))
      (let ((add (lambda (s)
                   (set! path (cons s path)))))
        (dynamic-wind
          (lambda () (add 'connect))
          (lambda ()
            (add (call/cc
                   (lambda (c0)
                     (set! c c0)
                     'talk1))))
          (lambda () (add 'disconnect)))
        (if (< (length path) 4)
            (c 'talk2)
            (reverse path))))

       => (connect talk1 disconnect connect talk2 disconnect)

unspecified | bigloo procedure

Returns the unspecified (noted as `#unspecified`) object with no specific property.

try exp handler | bigloo syntax

This form is documented in Section Errors Assertions and Traces.

values obj ... | procedure

Delivers all of its arguments to its continuation. Except for continuations created by the `call-with-values` procedure, all continuations take exactly one value. `Values` might be defined as follows:

    (define (values . things)
      (call/cc
        (lambda (cont) (apply cont things))))

call-with-values producer consumer | procedure

Calls its `producer` argument with no values and a continuation that, when passed some values, calls the `consumer` procedure with those values as arguments. The continuation for the call to `consumer` is the continuation of the call to `call-with-values`.

    (call-with-values (lambda () (values 4 5))
                      (lambda (a b) b))
        => 5
    (call-with-values * -)
        => -1

multiple-value-bind (var ...) producer exp ... | bigloo syntax

receive (var ...) producer exp ... | bigloo syntax

Evaluates `exp` ... in a environment where `var` ... are bound from the evaluation of `producer`. The result of `producer` must be a call to `values` where the number of argument is the number of bound variables.

    (define (bar a)
       (values (modulo a 5) (quotient a 5)))

    (define (foo a)
       (multiple-value-bind (x y)
          (bar a)
          (print x " " y)))

    (foo 354)
       -| 4 70

### 6.2 Input and output

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

### 6.2.1 Library functions

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

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

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

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

call-with-output-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

input-port-name-set! obj name | bigloo procedure

output-port-name obj | bigloo procedure

output-port-name-set! obj name | bigloo procedure

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

input-port-length obj | bigloo (>=3.8d) procedure

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

input-port-timeout port | bigloo (>=3.6b) procedure

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

output-port-timeout port | bigloo (>=3.6b) procedure

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

Setting a port timeout limits 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.

output-port-flush-hook port | bigloo procedure

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

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.

output-port-flush-buffer port | bigloo procedure

output-port-flush-buffer-set! port buffer | bigloo procedure

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.

output-port-close-hook port | bigloo procedure

output-port-close-hook-set! port proc | bigloo procedure

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.

input-port-close-hook port | bigloo procedure

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

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

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-append-to-file string thunk | optional 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 | 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 [buffer #f] [timeout 5000000] | 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.
- `fd:` Opens a file descriptor.

      (with-input-from-file "fd:0"
         (lambda ()
            (read)))

- `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.

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

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

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

This can be decomposed as:

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

open-input-zlib-file file-name [buffer #t] | bigloo procedure

open-input-zlib-port input-port [buffer #t] | bigloo procedure

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.

open-input-descriptor fd [buffer #t] | bigloo procedure

Open a file descriptor (as C `fdopen`).

open-input-string string [start 0] [end] | bigloo procedure

open-input-string! string [start 0] [end] | bigloo procedure

`string` must be a string, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (string-length STRING)

The optional argument `end` defaults to `(string-length 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.

open-input-c-string string | bigloo procedure

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.

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

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

open-input-mmap mmap [start 0] [end] | bigloo procedure

`mmap` must be a mmap, and `start` and `end` must be exact integers satisfying:

      0 <= START <= END <= (mmap-length STRING)

The optional argument `end` defaults to `(mmap-length STRING)`.
Returns an `input-port` able to deliver characters from `mmap`.

open-input-procedure procedure [buffer #t] | 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 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))

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

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

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

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

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.

open-output-procedure proc [flush [close]] | bigloo procedure

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.

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.

closed-input-port? input-port | procedure

closed-output-port? output-port | procedure

Predicates that return `#t` if and if their associated port is closed. Return `#f` otherwise.

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 procedure 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.

define-reader-ctor symbol procedure | bigloo 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

set-read-syntax! char procedure | bigloo 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))))))))

read-char [port] | procedure

read-byte [port] | procedure

peek-char [port] | procedure

peek-byte [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

read-line-newline [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.
The strings returned by `read-line` do not contain the newline delimiters. The strings returned by `read-line-newline` do contain them.

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

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

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.

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

port->string-list input-port | bigloo procedure

Returns a list of strings composed of the elements of `input-port`.

port->list input-port reader | bigloo procedure

port->sexp-list input-port | bigloo procedure

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

file->string path | bigloo procedure

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.

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

send-file filename output-port [len] [offset] | 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. 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`.

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.

write-char char [output-port] | procedure

write-byte byte [output-port] | procedure

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

newline [output-port] | procedure

flush-output-port output-port | bigloo procedure

This procedure flushes the output port `output-port`. This function does not reset characters accumulated in string port. For this uses, `reset-output-port`.

newline [output-port] | procedure

reset-output-port output-port | bigloo procedure

This function is equivalent to `flush-output-port` but in addition, for string ports, it reset the internal buffer that accumulates the displayed characters.

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.
- `~%` 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

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`.

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

display-string string output-port | bigloo procedure

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

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

password [prompt] | bigloo procedure

Reads a password from the current input port. The reading stops when the user hits the ,(code "Enter") key.

open-pipes [name] | bigloo procedure

Opens a bi-directional pipes. Returns two values, an `input-port` and an `output-port`. The optional argument `name` is only used for debugging.
Example:

    (multiple-value-bind (in out)
      (open-pipes "my pipe")
      (write-char #\z out)
      (flush-output-port out))

select [:timeout 0] [:read '()] [:write '()] [:except '()] | bigloo procedure

A wrapper of the Posix `select` function. Returns three values, the three lists of objects that are ready for reading, respectively writing, or that are in error.
Example:

    (define *inpipe* #f)
    (define *outpipe* #f)
    (define *watch-mutex* (make-mutex "watch"))
    (define *sockets* '())

    (define (watch socket onclose)
       (synchronize *watch-mutex*
          (set! *sockets* (cons socket *sockets*))
          (if *outpipe*
    	  (begin
    	     (write-char *outpipe*)
    	     (flush-output-port *outpipe*))
    	  (thread-start!
    	     (instantiate::hopthread
    		(body (watch-thread onclose)))))))

    (define (watch-thread onclose)
       (let loop ()
          (synchronize *watch-mutex*
    	 (unless *inpipe*
    	    (multiple-value-bind (in out)
    	       (open-pipes)
    	       (set! *inpipe* in)
    	       (set! *outpipe* out))))
          (multiple-value-bind (readfs _ _)
    	 (select :read (cons *inpipe* *sockets*))
    	 (let ((socks (filter socket? readfs)))
    	    (for-each onclose socks)
    	    (synchronize *watch-mutex*
    	       (for-each (lambda (s)
    			    (set! *sockets* (remq! s *sockets*)))
    		  socks)
    	       (unless (pair? *sockets*)
    		  (close-input-port *inpipe*)
    		  (close-output-port *outpipe*)
    		  (set! *inpipe* #f)
    		  (set! *outpipe* #f)))
    	    (when *outpipe*
    	       (loop))))))

lockf output-port command [len 0] | bigloo procedure

Lock a file descriptor or an output port. It is an error to call `lockf` with an port not open on a plain file (i.e., a port open with `open-output-file`, or its variants).
The `command` argument is one of:

- `lock`: locks the file, raises an error on failure.
- `ulock`: unlocks the file, raises an error on failure.
- `test`: tests whether a file is locked or not.
- `tlock`: tries to lock a file, return `#t` upon success and `#f` otherwise.

The argument `len` is the portion of the file to be locked.

### 6.2.2 mmap

The `mmap` function asks to map a file into memory. This memory area can be randomly accessed as a string. In general using `mmap` improves performance in comparison with equivalent code using regular ports.

mmap? obj | bigloo procedure

Returns `#t` if and only if `obj` has been produced by `open-mmap`. Otherwise, it returns `#f`.

open-mmap path [mode] | bigloo procedure

Maps a file `path` into memory. The optional argument `mode` specifies how the file is open. The argument can be:

- `read: #t` The memory can be read
- `read: #f` The memory cannot be read
- `write: #t` The memory can be written
- `write: #f` The memory is read-only.

string->mmap string [mode] | bigloo procedure

Wrap a Bigloo string into a mmap object.

mmap-name mm | bigloo procedure

Returns the file name of the memory map `mm`.

close-mmap mm | bigloo procedure

Closes the memory mapped. Returns `#t` on success, `#f` otherwise.

mmap-length mm | bigloo procedure

Returns the length, an exact integer, of the memory mapped.

mmap-read-position mm | bigloo procedure

mmap-read-position-set! mm offset | bigloo procedure

mmap-write-position mm | bigloo procedure

mmap-write-position-set! mm offset | bigloo procedure

Returns and sets the read and write position of a memory mapped memory. The result and the argument are exact integers.

mmap-ref mm offset | bigloo procedure

Reads the character in `mm` at `offset`, an exact long (::elong). This function sets the read position to `offset + 1`.

mmap-set! mm offset char | bigloo procedure

Writes the character `char` in `mm` at `offset`, an exact long (::elong). This function sets the write position to `offset + 1`.

mmap-substring mm start end | bigloo procedure

Returns a newly allocated string made of the characters read from `mm` starting at position `start` and ending at position `end - 1`. If the values `start` and `end` are not ranged in `[0...(mmap-length mm)]`, an error is signaled. The function `mmap-substring` sets the read position to `end`.

mmap-substring-set! mm start str | bigloo procedure

Writes the string `str` to `mm` at position `start`. If the values `start` and `start + (string-length str)` are not ranged in `[0...(mmap-length mm)[`, an error is signaled. The function `mmap-substring` sets the write position to `start + (string-length str)`.

mmap-get-char mm | bigloo procedure

mmap-put-char! mm c | bigloo procedure

mmap-get-string mm len | bigloo procedure

mmap-put-string! mm str | bigloo procedure

These functions get (resp. put) character and strings into a memory mapped area. They increment the read (resp. write) position. An error is signaled if the characters read (resp. writen) outbound the length of the memory mapped.

### 6.2.3 zip

port->gzip-port input-port [buffer #t] | bigloo procedure

port->zlib-port input-port [buffer #t] | bigloo procedure

port->inflate-port input-port [buffer #t] | bigloo procedure

These functions take a regular port as input (`input-port`). They construct a new port that automatically unzip the read characters. The `inflate` version does not parse a gunzip-header before inflating the content.

open-input-inflate-file path [buffer #t] | bigloo procedure

These function open a gzipped file for input. The file is automatically unzipped when the characters are read. It is equivalent to:

    (let ((p (open-input-port path)))
      (port->gzip-port p))

The function `open-input-inflate-file` is similar to `open-input-gzip-file` but it does not parse a gunzip-header before inflating the content.

gunzip-sendchars input-port output-port | bigloo procedure

inflate-sendchars input-port output-port | bigloo procedure

Transmit all the characters from the gzipped `input-port` to the `output-port`.
Note that the function `send-chars` can also be used on gzipped input-ports.

gunzip-parse-header input-port | bigloo procedure

Parse the header of `input-port`. Returns `#f` if and only if the port is not gzipped.

### 6.2.4 tar

tar-read-header [input-port] | bigloo procedure

Reads a tar header from `input-port`. If the input-port does not conform the tar format, an IO exception is raised. On success a tar-header descriptor is returned.

tar-read-block tar-header [input-port] | bigloo procedure

Reads the content of the `tar-header` block.

tar-round-up-to-record-size int | bigloo procedure

Rounds up tar-block sizes.

tar-header-name tar-header | bigloo procedure

tar-header-mode tar-header | bigloo procedure

tar-header-uid tar-header | bigloo procedure

tar-header-gid tar-header | bigloo procedure

tar-header-size tar-header | bigloo procedure

tar-header-mtim tar-header | bigloo procedure

tar-header-checksum tar-header | bigloo procedure

tar-header-type tar-header | bigloo procedure

tar-header-linkname tar-header | bigloo procedure

tar-header-uname tar-header | bigloo procedure

tar-header-gname tar-header | bigloo procedure

tar-header-devmajor tar-header | bigloo procedure

tar-header-devminir tar-header | bigloo procedure

Return various information about `tar-header`.

The following example simulates the Unix command `tar xvfz`:

    (define (untar path)
       (let ((pz (open-input-gzip-port path)))
          (unwind-protect
    	 (let loop ((lst '()))
    	    (let ((h (tar-read-header pz)))
    	       (if (not h)
    		   lst
    		   (case (tar-header-type h)
    		      ((dir)
    		       (let ((path (tar-header-name h)))
    			  (if (make-directory path)
    			      (loop lst)
    			      (error 'untar
    				     "Cannot create directory"
    				     path))))
    		      ((normal)
    		       (let* ((path (tar-header-name h))
    			      (dir (dirname path)))
    			  (when (and (file-exists? dir) (not (directory? dir)))
    			     (delete-file dir))
    			  (unless (file-exists? dir)
    			     (make-directory dir))
    			  (with-output-to-file path
    			     (lambda ()
    				(display (tar-read-block h pz))))
    			  (loop (cons path lst))))
    		      (else
    		       (error 'untar
    			      (format "Illegal file type `~a'"
    				      (tar-header-type h))
    			      (tar-header-name h)))))))
    	 (close-input-port pz))))

untar input-port [:directory (pwd)] [:file #f] | bigloo procedure

Untars the archive whose content is provided by the input port `input-port`.

- If `:file` is provided, `untar` extract the content of the file named `:file` and returns a string. The file name must exactly matches the files of the archive files names. If the file does not exist, `untar` returns `#f`.
- If `:file` is not provided, it untars the whole content, in the directory denoted by `:directory`, which defaults to `(pwd)`. The function `untar`, returns the whole list of created directories and files.

### 6.3 Serialization

string->obj string #!optional extension | bigloo procedure

This function converts a `string` which has been produced by `obj->string` into a Bigloo object.
New in Bigloo 4.2a: The `extension` parameter is used to decode extension sequences. Theses sequences of characters are introduced by the `X` character. To decode an extension, the unserializer starts decoding the item following the `X` as a regular serialized item. Then, if the `extension` parameter is bound to a function, the unserializer calls that function and use the returned value as the unserialized object. If the `extension` argument is not a function, the unserializer return the ream item.

obj->string object | bigloo procedure

This function converts into a string any Bigloo `object` which does not contain a procedure.

The implementation of the last two functions ensures that for every Bigloo object `obj` (containing no procedure), the expression:

    (equal? obj (string->obj (obj->string obj)))
       => #t

binary-port? obj | bigloo procedure

open-output-binary-file file-name | bigloo procedure

append-output-binary-file file-name | bigloo procedure

open-input-binary-file file-name | bigloo procedure

close-binary-port binary-port | bigloo procedure

flush-binary-port binary-port | bigloo procedure

input-obj binary-port | bigloo procedure

output-obj binary-port obj | bigloo procedure

Bigloo allows Scheme objects to be dumped into, and restored from, files. These operations are performed by the previous functions. The dump and the restore use the two functions `obj->string` and `string->obj`.
It is also possible to use a binary file as a flat character file. This can be done by the means of `output-char`, `input-char`, `output-string`, and `input-string` functions.

input-char binary-port | bigloo procedure

output-char binary-port char | bigloo procedure

output-byte binary-port byte | bigloo procedure

The function `input-char` reads a single character from a `binary-port`. It returns the read character or the `end-of-file` object. The function `output-char` and `output-byte` writes a character, respectively a byte, into a `binary-port`.

input-string binary-port len | bigloo procedure

output-string binary-port | bigloo procedure

The function `input-string` reads a string from a `binary-port` of maximum length `len`. It returns a newly allocated string whose length is possibly smaller than `len`. The function `output-string` writes a string into a `binary-port`.

input-fill-string! binary-port string | bigloo procedure

Fills a string with characters read from `binary-port` with at most the length of `string`. The function returns the number of filled characters.

register-procedure-serialization! serializer unserializer | bigloo procedure

register-custom-serialization! ident serializer unserializer | bigloo procedure

register-process-serialization! serializer unserializer | bigloo procedure

register-opaque-serialization! serializer unserializer | bigloo procedure

There is no existing portable method to dump and restore a procedure. Thus, if `obj->string` is passed a procedure, it will emit an error message. Sometime, using strict restrictions, it may be convenient to use an ad-hoc framework to serialize and unserialize procedures. User may specify there own procedure serializer and unserializer. This is the role of `register-procedure-serialization!`. The argument `serializer` is a procedure of one argument, converting a procedure into a characters strings. The argument `unserializer` is a procedure of one argument, converting a characters string into a procedure. It belongs to the user to provide correct serializer and unserializer.
Here is an example of procedure serializer and unserializer that may be correct under some Unix platform:

    (module foo
       (extern (macro %sprintf::int (::string ::string ::procedure) "sprintf")))

    (define (string->procedure str)
       (pragma "(obj_t)(strtoul(BSTRING_TO_STRING($1), 0, 16))" str))

    (define (procedure->string proc)
       (let ((item (make-string 10)))
          (%sprintf item "#p%lx" proc)
          item))

    (register-procedure-serialization! procedure->string string->procedure)

    (let ((x 4))
       (let ((obj (cons "toto" (lambda (y) (+ x y)))))
          (let ((nobj (string->obj (obj->string obj))))
    	 (print ((cdr nobj) 5)))))

register-class-serialization! class serializer unserializer | bigloo procedure

Register a serializer/unserializer for a class. Subclasses of `class` inherit this serializer.

    (module class-serialization-example
       (static (class point::object (x (default 10)) (y (default 20)))))

    (register-class-serialization! point
    			       (lambda (o)
    				  (with-access::point o (x y)
    				     (cons x y)))
    			       (lambda (l)
    				  (instantiate::point
    				     (x (car l))
    				     (y (cdr l)))))

    (let ((o (instantiate::point)))
       (let ((s (obj->string (list o o))))
          (print (string-for-read s))
          (let ((l (string->obj s)))
    	 (print l)
    	 (eq? (car l) (cadr l))))) => #t

get-procedure-serialization | bigloo procedure

get-custom-serialization ident | bigloo procedure

get-process-serialization | bigloo procedure

get-opaque-serialization | bigloo procedure

get-class-serialization class | bigloo procedure

Returns the a multiple-values whose first element is the current procedure serializer and whose second element is the current procedure unserializer. If no serializer/unserializer is defined, these procedures return the values `#f #f`.

### 6.4 Bit manipulation

These procedures allow the manipulation of fixnums as bit-fields.

bit-or i1 i2 | bigloo procedure

bit-orbx z1 z2 | bigloo procedure

bit-orelong i1 i2 | bigloo procedure

bit-orllong i1 i2 | bigloo procedure

bit-xor i1 i2 | bigloo procedure

bit-xorbx z1 z2 | bigloo procedure

bit-xorelong i1 i2 | bigloo procedure

bit-xorllong i1 i2 | bigloo procedure

bit-and i1 i2 | bigloo procedure

bit-andbx z1 z2 | bigloo procedure

bit-andelong i1 i2 | bigloo procedure

bit-andllong i1 i2 | bigloo procedure

bit-not i | bigloo procedure

bit-notbx z | bigloo procedure

bit-notelong i | bigloo procedure

bit-notllong i | bigloo procedure

bit-lsh i1 i2 | bigloo procedure

bit-lshbx z1 i2 | bigloo procedure

bit-lshelong i1 i2 | bigloo procedure

bit-lshllong i1 i2 | bigloo procedure

bit-rsh i1 i2 | bigloo procedure

bit-rshbx z1 i2 | bigloo procedure

bit-ursh i1 i2 | bigloo procedure

bit-rshelong i1 i2 | bigloo procedure

bit-rshllong i1 i2 | bigloo procedure

bit-urshelong i1 i2 | bigloo procedure

bit-urshllong i1 i2 | bigloo procedure

    (bit-or 5 3)                           => 7
    (bit-orelong #e5 #e3)                  => #e7
    (bit-xor 5 3)                          => 6
    (bit-xorbx #z5 #z3)                    => #z6
    (bit-andllong #l5 #l3)                 => #l1
    (bit-not 5)                            => -6
    (bit-lsh 5 3)                          => 40
    (bit-rsh 5 1)                          => 2
    (bit-rsh #z5 1)                        => #z2

### 6.5 Weak Pointers

Bigloo may support weak pointers. In order to activate this support, Bigloo must be configured with the `finalization` enabled. That is, the `configure` script must be invoked with the option `--finalization=yes`. When the finalization and weak pointers support is enabled, Bigloo defines the `cond-expand` properties `bigloo-finalizer` and `bigloo-weakptr`. Then a program may test the support with expressions such as:

    (cond-expand
      (bigloo-weakptr <something>)
      (else <something-else>))

Weak pointers are pointers to objects which can be collected by the garbage collector if they are weakly pointed to. An object is weakly pointed to if the only pointers to it are weak pointers. Weakly pointed objects can be collected by the garbage collector, and all the weak pointers to such objects will cease to point to it and point to `#unspecified` instead.

make-weakptr data | bigloo procedure

make-weakptr data ref | bigloo procedure

Creates a weak pointer to `data` and `ref`.

weakptr? obj | bigloo procedure

Returns `#t` if `obj` is a weak pointer, constructed by `make-weakptr`.

weakptr-data ptr | bigloo procedure

Returns the `data` object pointed to by `ptr`. If the object has been collected, it returns `#unspecified`.

weakptr-data-set! ptr data | bigloo procedure

Set a new `data` to the weak pointer.

weakptr-ref ptr | bigloo procedure

Returns the `ref` object pointed to by `ptr`. If the object has been collected, it returns `#unspecified`.

weakptr-ref-set! ptr ref | bigloo procedure

Set a new `ref` to the weak pointer.

### 6.6 Hash Tables

Bigloo offers hash tables with support for weak pointers. Here are described functions which define and use them.

make-hashtable [bucket-len] [max-bucket-len] [eqtest] [hash] [weak-keys] [weak-data] | bigloo procedure

create-hashtable [:size] [:max-bucket-len] [:eqtest] [:hash] [:weak] [:max-length] [:bucket-expansion] [:persistent #f] | bigloo procedure

Defines a hash table for which the number of buckets is `size`. The variable `max-bucket-len` specify when the table should be resized. If provided, these two values have to be exact integers greater or equal to 1. Normally you could ignore `size` and `max-bucket-len` arguments and call `make-hashtable` with no argument at all. The argument `eqtest` enables the specification of a comparison function. The first argument of this function is the keys contained in the table. The second argument is the searched key. By default, hash tables rely on `hashtable-equal?`, which is defined as:
Persistent hashtables are serializable. Non persistent hashtables are not.

    (define (hashtable-equal? obj1 obj2)
       (or (eq? obj1 obj2)
           (and (string? obj1)
                (string? obj2)
                (string=? obj1 obj2))))

The argument `hash` specifies an hashing function. It defaults to `get-hashnumber`. The arguments `weak-keys`, `weak-data`, and `weak-both` specify respectively whether the hash table should use weak pointers to store the keys and/or the data. By default a hash table uses strong pointers for both keys and data. Each optional arguments `size`, `max-bucket-len`, `eqtest`, `hash`, `weak-keys`, and `weak-data` can be bound to the Bigloo value `#unspecified` which forces its default.
The argument `max-length` specifies a maximum length (in number of buckets) for this hashtable. It defaults to `16384`. If during the execution, the hashtable tries to expand itself more than `max-length`, an exception is raised. This feature helps debugging incorrect hashtable uses because excessive expansion is generally the signs of an incorrect behavior. Excessive expansions, cause the garbage collector to crash at some point. This debugging feature can be disabled by specifying a negative max length, in which case, no check is performed at runtime.
The argument `bucket-expansion` controls how `max-bucket-len` is expanded each time the table grows. This is a floating point number that is a multiplicative coefficient. It defaults to `1.2`.
The function `create-hashtable` is equivalent to `make-hashtable` but it uses a keyword interface. The keyword argument `weak` can either be `none`, `data`, or `keys`.

hashtable? obj | bigloo procedure

Returns `#t` if `obj` is an hash table, constructed by `make-hashtable`.

hashtable-weak-keys? table | bigloo procedure

Returns `#t` if `table` is a hash table with weakly pointed keys.

hashtable-weak-data? table | bigloo procedure

Returns `#t` if `table` is a hash table with weakly pointed data.

hashtable-size table | bigloo procedure

Returns the number of entries contained in `table`. Note that for a weak hash table the size does not guarantee the real size, since keys and/or data can dissapear before the next call to the hash table.

hashtable-contains? table key | bigloo procedure

Returns the boolean `#t` if it exists at least one entry whose key is `key` in `table`. If not entry is found `#f` is returned. Note that for a weak hash table, the fact this procedure returns `#t` does not guarantee that the key (or its associated data) will not dissapear before the next call to the hash table.

hashtable-get table key | bigloo procedure

Returns the entry whose key is `key` in `table`. If no entry is found, or if the key and/or value is weakly pointed to and has dissapeard, `#f` is returned.

hashtable-put! table key obj | bigloo procedure

Puts `obj` in `table` under the key `key`. This function returns the object bound in the table. If there was an object `obj-old` already in the table with the same key as `obj`, this function returns `obj-old`; otherwise it returns `obj`.

hashtable-remove! table key | bigloo procedure

Removes the object associated to `key` from `table`, returning `#t` if such object was bound in table and `#f` otherwise.

hashtable-add! table key update-fun obj init-value | bigloo procedure

If key is already in table, the new value is calculated by `(update-fun obj current-value)`. Otherwise the `table` is extended by an entry linking key and `(update-fun obj init-value)`.

hashtable-update! table key update-fun init-value | deprecated bigloo procedure

If key is already in table, the new value is calculated by `(update-fun current-value)`. Otherwise the `table` is extended by an entry linking key and `init-value`.

hashtable->vector table | bigloo procedure

hashtable->list table | bigloo procedure

Returns the hash table `table`'s data as a vector (respectively a list). If the hash table is weak, the result will consist only of the data which haven't dissapeared yet and whose keys haven't dissapeared either.

hashtable-key-list table | bigloo procedure

Returns the list of keys used in the `table`. If the hash table is weak, the result will consist only of the keys which haven't dissapeared yet and whose data haven't dissapeared either.

hashtable-map table fun | bigloo procedure

Returns a list whose elements are the result of applying `fun` to each of the keys and elements of `table` (no order is specified). In consequence, `fun` must be a procedure of two arguments. The first one is a key and the second one, an associated object. If the hash table is weak, `fun` will only be mapped on sets of key/datum which haven't dissapeared yet.

hashtable-for-each table fun | bigloo procedure

Applies `fun` to each of the keys and elements of `table` (no order is specified). In consequence, `fun` must be a procedure of two arguments. The first one is a key and the second one, an associated object. If the hash table is weak, `fun` will only be called on sets of key/datum which haven't dissapeared yet.

hashtable-filter! table fun | bigloo procedure

Filter out elements from `table` according to predicate `fun`. If the hash table is weak, `fun` will only be called on sets of key/datum which haven't dissapeared yet.

hashtable-clear! table | bigloo procedure

Remove all the elements from `table`.

Here is an example of hash table.

    (define *table* (make-hashtable))

    (hashtable-put! *table* "toto" "tutu")
    (hashtable-put! *table* "tata" "titi")
    (hashtable-put! *table* "titi" 5)
    (hashtable-put! *table* "tutu" 'tutu)
    (hashtable-put! *table* 'foo 'foo)

    (print (hashtable-get *table* "toto"))
       -| "tutu"
    (print (hashtable-get *table* 'foo))
       -| 'foo
    (print (hashtable-get *table* 'bar))
       -| #f

    (hashtable-for-each *table* (lambda (key obj) (print (cons key obj))))
       -| ("toto" . "tutu")
          ("tata" . "titi")
          ("titi" . 5)
          ("tutu" . TUTU)
          (foo . foo)

hashtable-collisions table | bigloo procedure

Returns a list of collisions for the keys from `table`. A collision is represented by the number of extra steps (comparisons) needed for a key. The length of the result gives the number of keys with collisions, and the sum of all list elements is the sum of all extra steps needed. This function can help to test different hash functions and other hash table parameters.

get-hashnumber obj | bigloo procedure

get-hashnumber-persistent obj | bigloo procedure

Computes a hash number of the value `obj`, which can be of any type. The function `get-hashnumber-persistent` returns a hash number that is persistent accross program executions and execution platforms.

object-hashnumber object | bigloo generic

This generic function computes a hash number of the instance `object`.
Example:

    (define-method (object-hashnumber pt::point)
       (with-access::point pt (x y)
          (+fx (*fx x 10) y)))

string-hash string [start 0] [len (string-length string)] | bigloo procedure

Compute a hash value for `string`, starting at index `start`, ending at length `len`.

### 6.7 Algorithms

### 6.8 Single Source Reachability Graphs

Single source reachability (SSR) graphs enable constant time ownership of a node. They can be used to build graphs, add nodes and edges, remove and replace edges, and then test if after such a modification a certain node is still reachable from the root. A naive implementation would traverse the whole graph from the root, paying attention to cycle to check the ownership. SSR does this efficiently without any traversal.
The algorithm assumes that nodes are represented by integer labels.
Example:

    (define g (ssr-make-graph :source 1))
    (ssr-add-edge! g 1 2 :onconnect (lambda (n) (print n)))       -| 2
    (ssr-add-edge! g 2 3 :onconnect (lambda (n) (print n)))       -| 3
    (ssr-add-edge! g 3 4 :onconnect (lambda (n) (print n)))       -| 4
    (ssr-add-edge! g 4 2 :onconnect (lambda (n) (print n)))
    (ssr-connected? g 3)                                          => #t
    (ssr-add-edge! g 2 5 :onconnect (lambda (n) (print n)))       -| 5
    (ssr-connected? g 3)                                          => #t
    (ssr-redirect! g 3 5 :onconnect (lambda (n) (print n)))
    (ssr-connected? g 3)                                          => #f
    (ssr-redirect! g 5 3 :onconnect (lambda (n) (print n)))       -| 3 4
    (ssr-connected? g 3)                                          => #t
    (ssr-remove-edge! g 3 4 :ondisconnect (lambda (n) (print n))) -| 4
    (ssr-connected? g 4)                                          => #f

ssr-make-graph #!key (source 0) | bigloo procedure

Builds an SSR graph.

ssr-add-edge! graph from to #!key onconnect | bigloo procedure

Add an edge to an SSR graph. If FROM and TO, two integers, are not already members of the graph, they are added as well as a connecting edge. The optional argument ONCONNECT is a function of one argument.

ssr-remove-edge! graph from to #!key ondisconnect | bigloo procedure

Remove the edge from an SSR graph connecting FROM and TO (two integers). The optional argument ONDISCONNECT is a function of one argument.

ssr-redirect! graph node other #!key onconnect ondisconnect | bigloo procedure

Redirect edges from an SSR graph. Edges pointing to NODE are redirected to OTHER. The optional arguments ONCONNECT and ONDISCONNECT are functions of one argument.

ssr-connected? graph node | bigloo procedure

Check is NODE is reachable from the graph source.

### 6.9 System programming

### 6.9.1 Operating System interface

bigloo-config | bigloo procedure

bigloo-config key | bigloo procedure

The function `bigloo-config` returns an alist representing the configuration of the running Bigloo system. When used with one parameter, the function `bigloo-config` returns the value associated with the key.
Examples:

    (bigloo-config) => ((release-number . 3.4b) ... (endianess . little-endian))
    (bigloo-config 'endianess) => little-endian
    (bigloo-config 'int-size) => 61

register-exit-function! proc | bigloo procedure

unregister-exit-function! proc | bigloo procedure

Register `proc` as an exit functions. `Proc` is a procedure accepting of one argument. This argument is the numerical value which is the status of the exit call. The registered functions are called when the execution ends.

exit int | bigloo procedure

Apply all the registered exit functions then stops an execution, returning the integer `int`.

gc-verbose-set! bool | bigloo procedure

Enable/disable GC traces.
Bigloo defines the `cond-expand` `gc` keyword, which enables applications to use this function.

gc [:finalize #t] | bigloo procedure

Force a garbage collection. If `finalize` is non-false, invoke the finalizers.
Bigloo defines the `cond-expand` `gc` keyword, which enables applications to use this function.

gc-finalize | bigloo procedure

Force a garbage collection finalization.
Bigloo defines the `cond-expand` `gc` keyword, which enables applications to use this function.

signal n proc | bigloo procedure

Provides a signal handler for the operating system dependent signal `n`. `proc` is a procedure of one argument.

get-signal-handler n | bigloo procedure

Returns the current handler associated with signal `n` or `#f` if no handler is installed.

system . strings | bigloo procedure

Append all the arguments `strings` and invoke the native host `system` command on that new string which returns an integer.

system->string . strings | bigloo procedure

Append all the arguments `strings` and invoke the native host `system` command on that new string. If the command completes, `system->string` returns a string made of the output of the command.

getenv [name] | bigloo procedure

Returns the string value of the Unix shell's `name` variable. If no such variable is bound, `getenv` returns `#f`. If `name` is not provided, `getenv` returns an alist composed of all the environment variables.

putenv string val | bigloo procedure

Adds or modifies the global environment variable `string` so that it is bound to `val` after the call. This facility is not supported by all back-end. In particular, the JVM back-end does not support it.

date | bigloo procedure

Returns the current date in a `string`. See also Date.

sleep micros | bigloo procedure

Sleeps for a delay during at least `micros` microseconds.

command-line | bigloo procedure

Returns a list of strings which are the Unix command line arguments.

executable-name | bigloo procedure

Returns the name of the running executable.

os-class | bigloo procedure

Gives the OS class (e.g. `unix`).

os-name | bigloo procedure

Gives the OS name (e.g. `Linux`).

os-arch | bigloo procedure

Gives the host architecture (e.g. `i386`).

os-version | bigloo procedure

Gives the operating system version (e.g. `RedHat 2.0.27`).

os-tmp | bigloo procedure

Gives the regular temporary directory (e.g. `/tmp`).

os-charset | bigloo procedure

Gives the charset used for encoding names of the file system (e.g. `UTF-8`).

file-separator | bigloo procedure

Gives the operating system file separator (e.g. `#\/`).

path-separator | bigloo procedure

Gives the operating system file path separator (e.g.`#\:`).

For additional functions (such as `directory->list`) see Input and Output.

unix-path->list | bigloo procedure

Converts a Unix path to a Bigloo list of strings.

    (unix-path->list ".")           => (".")
    (unix-path->list ".:/usr/bin")  => ("." "/usr/bin")

hostname | bigloo procedure

Returns the fully qualified name of the current host.

time thunk | bigloo procedure

Evaluates the `thunk` and returns four values: the result of calling `thunk`, the actual execution time, the system time, and the user time in millisecond.

    (multiple-value-bind (res rtime stime utime)
      (time (lambda () (fib 35)))
      (print "real: " rtime " sys: " stime " user: " utime))

getuid | bigloo procedure

getgid | bigloo procedure

setuid uid | bigloo procedure

setgid uid | bigloo procedure

The procedure `getuid` (resp. `getgid`) returns the UID (resp. GID) of the user the current process is executed on behalf of.
The procedure `setuid` (resp. `setgid`) set the UID (resp. GID) of the current process. In case of failure, this procedure raises an error.

getpid | bigloo procedure

Get the current process identifier.

getppid | bigloo procedure

Get the parent process identifier.

getgroups | bigloo procedure

Maps the Posix `getgroups` function, which returns the supplementary group IDs of the calling process. The result is a vector of IDs. On error, an IO exception is raised.

getpwnam name | bigloo procedure

getpwuid uid | bigloo procedure

These two procedures returns information about a user. The procedure `getpwname` accepts a string denoting the user name as argument. The procedure `getpwuid` accepts an UID as returned by the procedure `getuid`.
If the user is found, these two procedures returns a list of seven elements:

- the user name,
- his encrypted password,
- his uid,
- his group id,
- his real name,
- his home directory,
- his preferred shell.

When no user is found, these procedures returns `#f`.

openlog name option facility | bigloo procedure

syslog level . obj | bigloo procedure

closelog | bigloo procedure

syslog-option | bigloo procedure

syslog-level | bigloo procedure

syslog-facility | bigloo procedure

Wrapper to Unix syslog facilities. See the `syslog` man page for detail. Example.

    (openlog "foo.scm" (syslog-option 'LOG_PID 'LOG_ODELAY) (syslog-facility 'LOG_MAIL))
    (syslog (syslog-level 'LOG_INFO) "this is a log message")
    (closelog)

getrlimit resource | bigloo procedure

setrlimit! resource soft hard | bigloo procedure

Get/set system limits. Only suppported by the C backend!
The function `getrlimit` expects as argument a resource and it returns two values: a soft and a hard limit. Both values are `elong`.
The function `setrlimit!` accepts a resource, a soft limit, and a hard limit. The soft and hard limits are either a `elong` value or `+inf.0` to denote unlimited value. The function returns a boolean, which is `#t` if the limit has been changed, and `#f` otherwise.
A resource is either a fixnum, which must correspond to a native resource identifier, or a symbol amongst:

- `CORE`
- `CPU`
- `DATA`
- `FSIZE`
- `LOCKS`
- `MEMLOCK`
- `MSGQUEUE`
- `NICE`
- `NOFILE`
- `NPROC`
- `RSS`
- `RTTIME`
- `SIGPENDING`
- `STACK`

All other symbols trigger an error.
Bigloo defines the `cond-expand` `rlimit` keyword, which enables applications to use the two functions conditionally.

    (multiple-value-bind (soft hard)
      (getrlimit 'NOFILE)
      (cons soft hard)) => (#e1024 . #e1048576)
    (setrlimit 'NOFILE #e256 #e1048576) => #t
    (cond-expand
       (rlimit 'supported)
       (else 'unsupported)) => supported

### 6.9.2 Files

See Input and Output for file and directory handling. This section only deals with name handling. Four procedures exist to manipulate Unix filenames.

basename string | bigloo procedure

Returns a copy of `string` where the longest prefix ending in `/` is deleted if any existed.

prefix string | bigloo procedure

Returns a copy of `string` where the suffix starting by the char `#\.` is deleted. If no prefix is found, the result of `prefix` is a copy of `string`. For instance:

    (prefix "foo.scm")
       => "foo"
    (prefix "./foo.scm")
       => "./foo"
    (prefix "foo.tar.gz")
       => "foo.tar"

suffix string | bigloo procedure

Returns a new string which is the suffix of `string`. If no suffix is found, this function returns an empty string. For instance,

    (suffix "foo.scm")
       => "scm"
    (suffix "./foo.scm")
       => "scm"
    (suffix "foo.tar.gz")
       => "gz"

dirname string | bigloo procedure

Returns a new string which is the directory component of `string`. For instance:

    (dirname "abc/def/ghi")
       => "abc/def"
    (dirname "abc")
       =>  "."
    (dirname "abc/")
       => "abc"
    (dirname "/abc")
       => "/"

pwd | bigloo procedure

Returns the current working directory.

chdir dir-name | bigloo procedure

Changes the current directory to `dir-name`. On success, `chdir` returns `#t`. On failure it returns `#f`.

make-file-name dir-name name | bigloo procedure

Make an absolute file-name from a directory name `dir-name` and a relative name `name`.

make-file-path dir-name name . names | bigloo procedure

Make an absolute file-name from a directory name `dir-name` and a relative name `name`s.

file-name->list name | bigloo procedure

Explodes a file name into a list.

    (file-name->list "/etc/passwd")
       => '("" "etc" "passwd")
    (file-name->list "etc/passwd")
       => '("etc" "passwd")

file-name-canonicalize name | bigloo procedure

file-name-canonicalize! name | bigloo procedure

file-name-unix-canonicalize name | bigloo procedure

file-name-unix-canonicalize! name | bigloo procedure

Canonicalizes a file name. If the file name is malformed this function raises an `&io-malformed-url-error` exception.
The function `file-name-canonicalize!` may returns its argument if no changes in the string is needed. Otherwise, as `file-name-canonicalize` is returns a new string.
In addition to handling `..` directory name, the function `file-name-unix-canonicalize` also handles the `~` character.

    (file-name-canonicalize "/etc/passwd")
       => "/etc/passwd"
    (file-name-canonicalize "/etc/../tmp/passwd")
       => "/tmp/passwd"
    (file-name-canonicalize "~/passwd")
       => "~/passwd"
    (file-name-unix-canonicalize "~/passwd")
       => "/home/a-user/passwd"
    (file-name-unix-canonicalize "~foo/passwd")
       => "/home/foo/passwd"

relative-file-name name base | bigloo procedure

Builds a file name relative to `base`.

    (relative-file-name "/etc/passwd" "/etc"
       => "passwd"

find-file/path name path | bigloo procedure

Search, in sequence, in the directory list `path` for the file `name`. If `name` is an absolute name, then `path` is not used to find the file. If `name` is a relative name, the function `make-file-name` is used to build absolute name from `name` and the directories in `path`. The current path is not included automatically in the list of `path`. In consequence, to check the current directory one may add `"."` to the `path` list. On success, the absolute file name is returned. On failure, `#f` is returned. Example:

    (find-file/path "/etc/passwd" '("/toto" "/titi"))
       => "/etc/passwd"
    (find-file/path "passwd" '("/toto" "/etc"))
       => "/etc/passwd"
    (find-file/path "pass-wd" '("." "/etc"))
       => #f

make-static-library-name name | bigloo procedure

Make a static library name from `name` by adding the static library regular suffix.

make-shared-library-name name | bigloo procedure

Make a shared library name from `name` by adding the shared library regular suffix.

file-exists? string | bigloo procedure

This procedure returns `#t` if the file (respectively directory, and link) `string` exists. Otherwise it returns `#f`.

file-gzip? string | bigloo procedure

This procedure returns `#t` if and only if the file `string` exists and can be unzip by Bigloo. Otherwise it returns `#f`.

delete-file string | bigloo procedure

Deletes the file named `string`. The result of this procedure is `#t` is the operation succeeded. The result is `#f` otherwise.

rename-file string1 string2 | bigloo procedure

Renames the file `string1` as `string2`. The two files have to be located on the same file system. If the renaming succeeds, the result is `#t`, otherwise it is `#f`.

truncate-file path size | bigloo procedure

Truncates shall cause the regular file named by path to have a size which shall be equal to length bytes.
Returns `#t` on success. Returns `#f` otherwise.

copy-file string1 string2 | bigloo procedure

Copies the file `string1` into `string2`. If the copy succeeds, the result is `#t`, otherwise it is `#f`.

make-symlink target linkpath | bigloo procedure

Creates a symbolic link named `linkpath` which contains the string `target`.

directory? string | bigloo procedure

This procedure returns `#t` if the file `string` exists and is a directory. Otherwise it returns `#f`.

make-directory string | bigloo procedure

Creates a new directory named `string`. It returns `#t` if the directory was created. It returns `#f` otherwise.

make-directories string | bigloo procedure

Creates a new directory named `string`, including any necessary but nonexistent parent directories. It returns `#t` if the directory was created. It returns `#f` otherwise. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories.

delete-directory string | bigloo procedure

Deletes the directory named `string`. The directory must be empty in order to be deleted. The result of this procedure is unspecified.

directory-length string | bigloo procedure

If file `string` exists and is a directory, the function `directory-length` returns the number of entries contained in `string`.

directory->list string | bigloo procedure

directory->path-list string | bigloo procedure

If file `string` exists and is a directory, the function `directory->list` returns the list of files in `string`. The function `directory->path-list` returns a list of files whose dirname is `string`.

directory->vector string | bigloo procedure

directory->path-vector string | bigloo procedure

If file `string` exists and is a directory, the function `directory->vector` returns a vector of files in `string`. The function `directory->path-vector` returns a vector of files whose dirname is `string`.

file-modification-time string | bigloo procedure

file-change-time string | bigloo procedure

file-access-time string | bigloo procedure

file-times-set! string atime mtime | bigloo procedure

The date (in second) of the last modification (respec. access) for file `string`. The number of seconds is represented by a value that may be converted into a date by the means of `seconds->date` (see Date).

file-size string | bigloo procedure

Returns the size (in bytes) for file `string`. The return type is `long`. If an full-sized integer is needed, one may write:

    (let ((sz::llong (file-size <PATH>)))
     ...)

    On error, -1 is returned.

file-uid string | bigloo procedure

file-gid string | bigloo procedure

The functions return the user id (an integer) and group id (an integer) for file `string`. On error, `-1` is returned.

file-mode string | bigloo procedure

Returns the file access mode (an integer). On error `-1` is returned.

file-type string | bigloo procedure

Returns the file type (a symbol). The possible returned values are:

- `regular`
- `directory`
- `link`
- `block`
- `fifo`
- `character`
- `socket`
- `resource`
- `unknown`
- `does-not-exist`

chmod string [option] | bigloo procedure

Change the access mode of the file named `string`. The `option` must be either a list of the following symbols `read`, `write` and `execute` or an integer. If the operation succeeds, `chmod` returns `#t`. It returns `#f` otherwise. The argument `option` can also be an integer that represents the native file permission. Example:

    (chmod (make-file-name (getenv "HOME") ".bigloorc") 'read 'write)
    (chmod (make-file-name (getenv "HOME") ".bigloorc") #o777)

### 6.9.3 Process support

Bigloo provides access to Unix-like processes as first class objects. The implementation and this documentation are to a great extent copies of the STk [Gallesio95] process support. Basically, a process contains four informations: the standard Unix process identification (aka PID) and the three standard files of the process.

run-process command arg... | bigloo procedure

`run-process` creates a new process and run the executable specified in `command`. The `arg` correspond to the command line arguments. When is process completes its execution, non pipe associated ports are automatically closed. Pipe associated ports have to be explicitly closed by the program. The following values of `p` have a special meaning:

- `input:` permits to redirect the standard input file of the process. Redirection can come from a file or from a pipe. To redirect the standard input from a file, the name of this file must be specified after `input:`. Use the special keyword `pipe:` to redirect the standard input from a pipe.
- `output:` permits to redirect the standard output file of the process. Redirection can go to a file or to a pipe. To redirect the standard output to a file, the name of this file must be specified after `output:`. Use the special keyword `pipe:` to redirect the standard output to a pipe.
- `error:` permits to redirect the standard error file of the process. Redirection can go to a file or to a pipe. To redirect the standard error to a file, the name of this file must be specified after `error:`. Use the special keyword `pipe:` to redirect the standard error to a pipe.
- `wait:` must be followed by a boolean value. This value specifies if the process must be ran asynchronously or not. By default, the process is run asynchronously (i.e. `wait:` if `#f`).
- `host:` must be followed by a string. This string represents the name of the machine on which the `command` must be executed. This option uses the external command `rsh`. The shell variable `PATH` must be correctly set for accessing it without specifying its absolute path.
- `fork:` must be followed by a boolean value. This value specifies if the process must substitute the current execution. That is, if the value is `#t` a new process is spawned otherwise, the current execution is stopped and replaced by the execution of `command`. It defaults to `#t`.
- `env:` must be followed by a string of the form ``var`=`val``. This will bound an environment variable in the spawned process. A `run-process` command may contain several `env:` arguments. The current variables of the current process are also passed to the new process.

The following example launches a process which execute the Unix command `ls` with the arguments `-l` and `/bin`. The lines printed by this command are stored in the file `tmp/X`.

    (run-process "ls" "-l" "/bin" output: "/tmp/X")

The same example with a pipe for output:

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

One should note that the same program can be written with explicit process handling but making use of the `|` notation for `open-input-file`.

    (let ((port (open-input-file "| ls -l /bin")))
       (let loop ((line (read-line port)))
          (if (eof-object? line)
              (close-input-port port)
              (begin
                 (print line)
                 (loop (read-line port))))))

Both input and output ports can be piped:

    (let* ((proc (run-process "/usr/bin/dc" output: pipe: input: pipe:))
           (inport (process-input-port proc))
           (port (process-output-port proc)))
       (fprint inport "16 o")
       (fprint inport "16 i")
       (fprint inport "10")
       (fprint inport "10")
       (fprint inport "+ p")
       (flush-output-port inport)
       (let loop ((line (read-line port)))
          (if (eof-object? line)
    	  (close-input-port port)
    	  (begin
    	     (print line)
    	     (loop (read-line port))))))   -| 20

Note: The call to `flush-output-port` is mandatory in order to get the `dc` process to get its input characters.
Note: Thanks to Todd Dukes for the example and the suggestion of including it this documentation.

process? obj | bigloo procedure

Returns `#t` if `obj` is a process, otherwise returns `#f`.

process-alive? process | bigloo procedure

Returns `#t` if `process` is currently running, otherwise returns `#f`.

close-process-ports command arg... | bigloo procedure

Close the three ports associated with a process. In general the ports should not be closed before the process is terminated.

process-pid process | bigloo procedure

Returns an integer value which represents the Unix identification (PID) of the `process`.

process-input-port process | bigloo procedure

process-output-port process | bigloo procedure

process-error-port process | bigloo procedure

Return the file port associated to the standard input, output and error of `process` otherwise returns `#f`. Note that the returned port is opened for reading when calling `process-output-port` or `process-error-port`. It is opened for writing when calling `process-input-port`.

process-wait process | bigloo procedure

This function stops the current process until `process` completion. This function returns `#f` when `process` is already terminated. It returns `#t` otherwise.

process-exit-status process | bigloo procedure

This function returns the exit status of `process` if it is has finished its execution. It returns `#f` otherwise.

process-send-signal process s | bigloo procedure

Sends the signal whose integer value is `s` to `process`. Value of `s` is system dependent. The result of `process-send-signal` is undefined.

process-kill process | bigloo procedure

This function brutally kills `process`. The result of `process-kill` is undefined.

process-stop process | bigloo procedure

process-continue process | bigloo procedure

Those procedures are only available on systems that support job control. The function `process-stop` stops the execution of `process` and `process-continue` resumes its execution.

process-list | bigloo procedure

This function returns the list of processes which are currently running (i.e. alive).

### 6.9.4 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 supports both "stream-oriented" sockets and "datagram" sockets (see info-file ` libc', The GNU C Library Reference Manual). Stream-oriented sockets are created and manipulated with the following procedures.

make-client-socket hostname port-number #!key (timeout 0) (inbuf #t) (outbuf #t) (domain 'inet) | bigloo procedure

`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 keyword arguments `inbuf` and `outbuf` describe the buffer to be used. Each can either be:

- A positive fixnum, this gives the size of the buffer.
- The boolean `#t`, a buffer is allocated by the Bigloo runtime system with a default size.
- The boolean `#f`, the socket is unbufferized.
- A string, it is used as buffer.

Unbuffered sockets are useful for socket clients connected to servers that do not emit #\Newline character after emissions. If the optional argument `timeout` is missing or is `0`, the execution blocks until the connection is established. If the `timeout` is provided, the execution unblocks after `timeout` microseconds unless the connection is established.
The `domain` argument specifies the protocol used by the socket. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.
- `unix`: Unix sockets for local inter-process communications.
- `local`: Same as `unix`.
- `unspec`: uses IPv4 or IPv6 as determined by getaddrinfo.

If the connection cannot be established, an `&io-error` is raised (see Errors Assertions and Traces).
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 Regular Parsing) that intrinsicly associates buffers with regular grammars. If the current Rgc implementation is improved on the coming version this restriction will be eliminated.
Example:

    ;; open a client socket on port 80:
    (make-client-socket "www.inria.fr" 80)
    ;; open an unbufferized connection
    (make-client-socket "www.inria.fr" 80 :inbuf #f :outbuf #f)

socket? obj | bigloo procedure

socket-server? obj | bigloo procedure

socket-client? obj | bigloo procedure

Returns `#t` if `obj` is a socket, a socket server a socket client. Otherwise returns `#f`. Socket servers and socket clients are sockets.

socket-hostname socket | bigloo procedure

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`.

socket-host-address socket | bigloo procedure

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`.

socket-local-address socket | bigloo procedure

Returns a string which contains the IP number of the local host attached to `socket`.

socket-port-number socket | bigloo procedure

Returns the integer number of the port used for `socket`.

socket-input socket | bigloo procedure

socket-output socket | bigloo procedure

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:

    (let ((s (make-client-socket "kaolin.unice.fr" 13)))
      (print "Time is: " (read-line (socket-input s)))
      (socket-shutdown  s))

make-server-socket #!optional (port 0) #!key (name #f) (backlog 5) (domain 'inet) | bigloo procedure

`make-server-socket` returns a new socket object. The socket will be listening on the network interface `name`, either on the specified `port`, or on a port chosen by the system (usually the first port available on the network interface). The `name` can be an IP number as a string, or a host name, whose first IP address will be used (as returned by the name server lookup).
The `backlog` argument specifies the size of the wait-queue used for accepting connections.
The `domain` argument specifies the address family to use. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.
- `unix`: Unix sockets for local inter-process communications.
- `local`: Same as `unix`.

socket-accept socket #!key (errp #t) (inbuf #t) (outbuf #t) | bigloo procedure

`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`.
The arguments `inbuf` and `outbuf` are similar to the ones used by `make-client-socket`. That is, each 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 keyword argument `errp` is a boolean. The value `#t` means that if an error is raised it is signaled. Otherwise, it is omitted.
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 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 12342. 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 s2) "Length is: " (string-length l))
        (flush-output-port (socket-output s2)))
      (socket-close s2)
      (socket-shutdown s))

socket-close socket | bigloo procedure

The function `socket-close` closes the connection established with a `socket-client`.

socket-shutdown socket #!optional (how #t) | bigloo procedure

`Socket-shutdown` shutdowns the connection associated to `socket`.
`Close` is either a boolean or one of the symbols `RDWR`, `RD`, or `WR`. The meaning of the optional how (which defaults to `#t`) is as follows:

- `#t`, the socket is shutdown for reading and writing and the socket is closed.
- `#f`, the socket is shutdown for reading and writing.
- `RDWR`, the socket is shutdown for reading and writing.
- `RD`, the socket is shutdown for reading.
- `WD`, the socket is shutdown for writing.

The function `socket-shutdown` returns an integer which is `0` is the operation has succeeded and a positive integer otherwise.

socket-down? socket | bigloo procedure

Returns `#t` if `socket` has been previously closed with `socket-shutdown`. It returns `#f` otherwise.

Here is another example of making use of stream 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 :outbuf #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 :inbuf #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)))))

Bigloo also provides primitives dealing with "datagram" sockets, for use with transports such as UDP. These are shown below:

make-datagram-client-socket hostname port #!optional broadcast (domain 'inet) | bigloo procedure

return a datagram client socket connected to `hostname` on `port` whose address family is specified by `domain`.
The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.

make-datagram-server-socket #!optional (port 0) (domain 'inet) | bigloo procedure

Return a datagram server socket listening on `port`, and whose address family is specified by `domain`. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.

make-datagram-unbound-socket [(domain 'inet)] | bigloo procedure

Return an unbound datagram socket,whose address family is specified by `domain`. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.

It may then be used in conjunction with `datagram-socket-send` and `datagram-socket-receive`, for instance send to and receive from a UDP multicast address.

datagram-socket-input socket | bigloo procedure

datagram-socket-output socket | bigloo procedure

Returns the file port associated for reading or writing with the program connected with datagram `socket`. If no connection has already been established, these functions return `#f`.

datagram-socket-receive sock size | bigloo procedure

Receive up to `size` bytes from datagram socket `sock`, and return them as a string.

datagram-socket-send sock message host port | bigloo procedure

Send string `message` over datagram socket `sock` to `host` and `port`. `host` must be a string denoting an IPv4 or IPv6 address. On success, return the number of bytes actually sent.

host hostname | bigloo procedure

hostinfo hostname | bigloo procedure

Returns the IP number of `hostname`. When `hostname` is not found, the `io-unknown-host-error` exception is raided (see Errors Assertions and Traces).
The function `hostinfo` possibly returns more information about the host. It returns an association list made out the information about the host. This list might contain a `name` entry, an `addresses` entry, and a `aliases` entry.
Some back-ends (e.g., the C back-end) implements DNS caching. This may dramatically improve the performance of intensive networking applications. DNS caching can be control by the means of two parameters: `bigloo-dns-enable-cache` and `bigloo-dns-cache-validity-timeout` (see Parameters).

get-interfaces | bigloo procedure

Returns the list of configured interfaces, their associated IP addresses, their protocol, and, if supported by the system, the hardware address (the mac address).

get-protocols | bigloo procedure

Reads all the entries from the protocols database and returns a list of protocol entries. Each entries consists in a list of three elements:

- a string denoting the protocol name,
- an integer denoting the protocol number,
- a list of strings denoting the protocol aliases.

get-protocol number-or-name | bigloo procedure

Returns the protocol entry found in the protocols database. The argument `number-of-name` is either an integer or a string.

socket-option socket option-name | bigloo procedure

socket-option-set! socket option-name val | bigloo procedure

These two functions get and set socket option. The argument `option-name` must be a keyword. If the `option-name` is not supported by the Bigloo runtime system, the function `socket-option` returns the value `#unspecified` otherwise, it returns the option value. If the `option-name` is not supported, the function `socket-option-set!` returns `false`. Otherwise it returns a non false value.
Here is a list of possibly supported option-name values:

- `:SO_KEEPALIVE`
- `:SO_OOBINLINE`
- `:SO_RCVBUF`
- `:SO_SNDBUF`
- `:SO_REUSEADDR`
- `:SO_TIMEOUT`
- `:SO_SNDTIMEO`
- `:SO_RCVTIMEO`
- `:TCP_CORK`
- `:TCP_QUICKACK`
- `:TCP_NODELAY`

The `:SO_KEEPALIVE` option can be use to implement automatic notification of client disconnection. It requires system tuning for enabling TCP keeplive support. On Linux additional information may be found on the ``TCP Keepalive HOWTO'' (see http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/).

### 6.9.5 SSL

Bigloo allows access to SSL sockets, certificates and private keys, in order to build secure encrypted and/or signed communications.

ssl-version | SSL library procedure

Returns a string representing the SSL library version number.

#### 6.9.5.1 SSL Sockets

Bigloo defines SSL sockets, on systems that support them, as first class objects. SSL Sockets permits processes to communicate even if they are on different machines securely via encrypted connections. SSL Sockets are useful for creating secure client-server applications.

ssl-socket? obj | SSL library procedure

Returns `#t` if an only if obj is a SSL socket (either client or server). Returns `#f` otherwise.

make-ssl-client-socket hostname port-number #!key (buffer #t) (timeout 0) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f) (domain 'inet) | SSL library procedure

`make-ssl-client-socket` returns a new client socket object. This object satisfies the `socket?` predicate (see Socket) can be used in any context where a socket created by `make-client-socket` can be used.
A SSL client socket establishes a link between the running application (client) and a remote application (server) listening on port `port-number` of `hostname`. If optional argument `bufsiz` is lesser or equal to `1` 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. 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.

If the optional argument `timeout` is `0`, the execution blocks until the connection is established. If the `timeout` is provided, the execution unblocks after `timeout` microseconds unless the connection is established. If the `protocol` option argument is given, it specifies the encryption protocol. Accepted values are `'sslv2`, `'sslv3`, `'sslv23` (alias `'ssl`), `'tlsv1` (alias `'tls`), `'tlsv1_1`, `'tlsv1_2`, `'tlsv1_3`, or `'dtlsv1` (alias `'dtls`). The default value is `'sslv23`.
The SSL socket will sign the connection using the optional arguments `cert` (for the certificate) and `pkey` (for the private key). The certificate `cert` must be of type `certificate`, and the private key `pkey` must be of type `private-key`. If any of those two arguments is given, they must both be given. If those optional arguments are missing the connection will be encrypted but not signed from the client side.
The `CAs` optional argument specifies the list of certificates to trust as CA (Certificate Authority) for the connection. It must be a list of values of type `certificate`. If the list is empty, the default list of trusted CA is used (set by the system). Note that giving a list of trusted certificates turns on the peer (server) certificate validation: an `&io-error` will be raised if the peer (server) certificate is not signed directly or indirectly by one of the certificates in `CAs`.
The `accepted-certs` optional argument gives a list of certificate objects (of type `certificate`) which are accepted as peer (server) certificate. If `accepted-certs` is `#f` then every peer (server) certificate is accepted (aside from eventual certificate validation). If `accepted-certs` is a list, the peer (server) certificate must match one of the given certificates. Otherwise, an `&io-error` will be raised.
The optional `domain` argument specifies the protocol used by the socket. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.
- `unspec`: uses IPv4 or IPv6 as determined by getaddrinfo.

If the connection cannot be established, an `&io-error` is raised (see Errors Assertions and Traces).
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 Regular Parsing) that intrinsicly associates buffers with regular grammars. If the current Rgc implementation is improved on the coming version this restriction will be eliminated.
The function `make-ssl-client-socket` is defined in the SSL library. A module that needs this facility must then use a `library` clause (see Modules). The SSL library can also be loaded from the interpreter using the `library-load` function (see Bigloo Libraries).

    (module imap
       (library ssl)
       (main main))

    (let* ((s (make-ssl-client-socket "localhost" 993))
           (p (socket-output s)))
       (display "string" p)
       (newline p)
       (display "abc" p)
       (flush-output-port p)
       (let loop ()
          (loop)))

client-socket-use-ssl! socket #!key (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f) | SSL library procedure

Returns an SSL socket built from a socket obtained by `make-client-socket` (see Socket). Depending on the implementation and back-end the returned socket may or may not be `eq?` to `socket`.

make-ssl-server-socket #!key (port 0) (name #f) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f) (domain 'inet) | SSL library procedure

`make-ssl-server-socket` returns a new server socket object which satisfies the `socket?` predicate and which can be used in any context where a socket created by `make-server-socket` can be used (see Socket).
A SSL server socket opens the port `port` on the current host `name` (the server), and allows remote applications (clients) to connect to it. listening on port `port-number` of `hostname`. If the optional argument `port` is not given or is `0`, the server socket will use the first availailable port number. If the optional argument `name` is given, the server socket will be bound to the network interface representing the given host name. If it is `#f` (the default) the socket will be bound on every local network interface. If the `protocol` option argument is given, it specifies the encryption protocol. Accepted values are `'sslv2`, `'sslv3`, `'sslv23` (alias `'ssl`), `'tlsv1` (alias `'tls`), `'tlsv1_1`, `'tlsv1_2` `'tlsv1_3`, or `'dtlsv1` (alias `'dtls`). The default value is `'sslv23`.
The SSL socket will sign the connection using the optional arguments `cert` (for the certificate) and `pkey` (for the private key). The certificate `cert` must be of type `certificate`, and the private key `pkey` must be of type `private-key`. If any of those two arguments is given, they must both be given. If those optional arguments are missing the connection will be encrypted but not signed from the server side, which means the peer (client) will have to provide a certificate/private key pair to encrypt the connection, and that seldom happens. Typical SSL servers provide their certificate and private key.
Note that since the peer (client) certificate is only known when we are accepting a client socket (with `socket-accept`) the `CAs` and `accepted-certs` optional arguments are only checked during the accept operation of a server socket.
The `CAs` optional argument specifies the list of certificates to trust as CA (Certificate Authority) for the connection. It must be a list of values of type `certificate`. If the list is empty, the default list of trusted CA is used (set by the system). Note that giving a list of trusted certificates turns on the peer (client) certificate validation: an `&io-error` will be raised if the peer (client) certificate is not signed directly or indirectly by one of the certificates in `CAs` when accepting the client socket.
The `accepted-certs` optional argument gives a list of certificate objects (of type `certificate`) which are accepted as peer (client) certificate. If `accepted-certs` is `#f` then every peer (client) certificate is accepted (aside from eventual certificate validation). If `accepted-certs` is a list, the peer (client) certificate must match one of the given certificates. Otherwise, an `&io-error` will be raised when accepting the client socket.
The optional `domain` argument specifies the protocol used by the socket. The supported domains are:

- `inet`: IPv4 Internet protocols.
- `inet6`: IPv6 Internet protocols.

If the connection cannot be established, an `&io-error` is raised (see Errors Assertions and Traces).
The function `make-ssl-server-socket` is defined in the SSL library. A module that needs this facility must then use a `library` clause (see Modules). The SSL library can also be loaded from the interpreter using the `library-load` function (see Bigloo Libraries).

    (module secure-echo
       (library ssl))

    (let* ((cert (read-certificate "/etc/ssl/my_cert.crt"))
           (pkey (read-private-key "/etc/ssl/my_key.pkey"))
           (cas (read-pem-file "/etc/ssl/ca.cert"))
           (s (make-ssl-server-socket 1055 :CAs cas :cert cert :pkey pkey))
           (cs (socket-accept s))
           (ip (socket-input cs))
           (op (socket-output cs)))
       (let loop ((e (read ip)))
          (when (not (eof-object? e))
             (write e op)
             (loop (read ip))))
       (socket-close s))

#### 6.9.5.2 Certificates

Certificates are instances of the `certificate` class. There type can be checked with `(isa? expr certificate)`.

read-certificate file | SSL library procedure

Reads an X509 certificate stored in PEM format in the given `file` name. If the file cannot be read, it raises an `&io-error` condition. Otherwise the certificate is returned.

read-pem-file file | SSL library procedure

Reads a list of X509 certificate stored in PEM format in the given `file` name. If the file cannot be read, it raises an `&io-error` condition. Otherwise the list of certificate contained in the file is returned.

certificate-subject cert | SSL library procedure

Returns the CommonName (CN) part of the subject of the given certificate.

certificate-issuer cert | SSL library procedure

Returns the CommonName (CN) part of the issuer of the given certificate.

#### 6.9.5.3 Private Keys

Private keys are instances of the `private-key` class. There type can be checked with `(isa? expr private-key)`.

read-private-key file | SSL library procedure

Reads a private key stored in PEM format in the given `file` name. If the file cannot be read, it raises an `&io-error` condition. Otherwise the private key is returned.

### 6.10 Date

date? obj | bigloo procedure

Returns `#t` if and only if `obj` is a date as returned by `make-date`, `current-date`, `seconds->date`, or `seconds->gmtdate`. It returns `#f` otherwise.

make-date #!key (nsec 0) (sec 0) (min 0) (hour 0) (day 1) (month 1) (year 1970) timezone (dst -1) | bigloo procedure

Creates a `date` object from the integer values passed as argument.
The argument `timezone`, if provided, is expressed in minute.
Example:

    (write (make-date :sec 0 :min 22 :hour 17 :day 5 :month 2 :year 2003 :dst 0))
      -| #<date:Wed Feb  5 17:22:00 2003>

The argument `dst` is either `-1` when the information is not available, `0` when daylight saving is disabled, `1` when daylight saving is enabled.

date-copy date #!key sec min hour day month year timezone isdst | bigloo procedure

date-update! date #!key sec min hour day month year | bigloo procedure

Creates a new date or update an existing from the argument `date`.
Example:

    (date-copy (current-date) :sec 32 :min 24 :day 5)

date->gmtdate! date | bigloo procedure

Update the date to switch to an UTC representation. Returns the modified date object.

current-date | bigloo procedure

Returns a `date` object representing the current date.

current-seconds | bigloo procedure

current-microseconds | bigloo procedure

current-milliseconds | bigloo procedure

current-nanoseconds | bigloo procedure

Returns an `elong` integer representing the current epoch (i.e., the date since 0:00:00 UTC on the morning of 1 January 1970, expressed in seconds (resp. in micro seconds).

date->seconds | bigloo procedure

date->nanoseconds | bigloo procedure

date->milliseconds | bigloo procedure

seconds->date | bigloo procedure

seconds->gmtdate | bigloo procedure - 4.3h

milliseconds->gmtdate | bigloo procedure - 4.3i

nanoeconds->date | bigloo procedure

milliseconds->date | bigloo procedure

Convert from `date` and `elong`.

date->string date | bigloo procedure

date->utc-string date | bigloo procedure

seconds->string elong | bigloo procedure

seconds->utc-string elong | bigloo procedure

Construct a textual representation of the date passed in argument

date-second date | bigloo procedure

Returns the number of seconds of a date, in the range `0...59`.

date-nanosecond date | bigloo procedure

date-millisecond date | bigloo procedure

Returns the number of nano/milli seconds of a date (to be added to `date-second`).

date-minute date | bigloo procedure

Returns the minute of a date, in the range `0...59`.

date-hour date | bigloo procedure

Returns the hour of a date, in the range `0...23`.

date-day date | bigloo procedure

Returns the day of a date, in the range `1...31`.

date-wday date | bigloo procedure

date-week-day date | bigloo procedure

Returns the week day of a date, in the range `1...7`.

date-yday date | bigloo procedure

date-year-day date | bigloo procedure

Returns the year day of a date, in the range `1...366`.

date-month date | bigloo procedure

Returns the month of a date, in the range `1...12`.

date-year date | bigloo procedure

Returns the year of a date.

date-timezone date | bigloo procedure

Returns the timezone (in seconds) of a date.

date-is-dst date | bigloo procedure

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.

integer->second | bigloo procedure

Converts a Bigloo fixnum integer into a second number.

day-seconds | bigloo procedure

Returns the number of seconds contained in one day.

day-name int | bigloo procedure

day-aname int | bigloo procedure

Return the name and the abbreviated name of a week day.

month-name int | bigloo procedure

month-aname int | bigloo procedure

Return the name and the abbreviated name of a month.

date-month-length date | bigloo procedure

Return the length of the month of `date`.

leap-year? int | bigloo procedure

Returns `#t` if and only if the year `int` is a leap year. Returns `#f` otherwise.

rfc2822-date->date string | bigloo procedure

rfc2822-parse-date input-port | bigloo procedure

Parses RFC2822 string representing a date. These functions produce a Bigloo date object.

date->rfc2822-date date | bigloo procedure

Converts a Bigloo date into a string representation compliant with the RFC2822 format.

iso8601-date->date string | bigloo procedure

iso8601-parse-date input-port | bigloo procedure

Parses ISO8601 string representing a date. These functions produce a Bigloo date object.

date->iso8601-date date | bigloo procedure

Converts a Bigloo date into a string representation compliant with the iso8601 format.

### 6.11 Digest

base64-encode string [padding 64] | bigloo procedure

base64-decode string [no-eof-padding] | bigloo procedure

Encodes (respec. decodes) a string into a base64 representation.
When decoding, if the optional parameter `no-eof-padding` is `#t`, the decoding success even if the input stream is not padded with `=` characters.

base64-encode-port input-port output-port [padding 64] | bigloo procedure

base64-decode-port input-port output-port [no-eof-padding] | bigloo procedure

Encodes (respec. decodes) an input port into a base64 representation.
When decode succeeds, `base64-decode-port` returns `#t`, it returns `#f` otherwise.
When decoding, if the optional parameter `no-eof-padding` is `#t`, the decoding success even if the input stream is not padded with `=` characters.

pem-read-file file-name | bigloo procedure

pem-decode-port input-port output-port | bigloo procedure

Reads a PEM (Privacy Enhanced Mail) base64 encoded file.

md5sum obj | bigloo procedure

md5sum-string string | bigloo procedure

md5sum-mmap mmap | bigloo procedure

md5sum-file string | bigloo procedure

md5sum-port input-port | bigloo procedure

Computes MD5 message digest.
The function `md5sum` dispatches over its argument and invokes the ad-hoc function. That is, it invokes `md5sum-string` if its argument is a string, `md5sum-mmap` if it is a mmap, `md5sum-port` if its argument is an input port.

hmac-md5sum-string key string | bigloo procedure

Computes the Hmac MD5 authentication:

    (hmac-md5sum-string (make-string 16 #a011) "Hi There")
      => "9294727a3638bb1c13f48ef8158bfc9d"

cram-md5sum-string user key string | bigloo procedure

Challenge-Response Authentication Mechanism as specified in RFC 2195.
The function `cram-md5sum-string` assumes that data is base64 encoded. The result is also base64 encoded.

sha1sum obj | bigloo procedure

sha1sum-string string | bigloo procedure

sha1sum-mmap mmap | bigloo procedure

sha1sum-file string | bigloo procedure

sha1sum-port input-port | bigloo procedure

Computes SHA1 message digest.
The function `sha1sum` dispatches over its argument and invokes the ad-hoc function. That is, it invokes `sha1sum-string` if its argument is a string, `sha1sum-mmap` if it is a mmap, `sha1sum-port` if its argument is an input port.

hmac-sha1sum-string key string | bigloo procedure

Computes the Hmac SHA1 authentication:

sha256sum obj | bigloo procedure

sha256sum-string string | bigloo procedure

sha256sum-mmap mmap | bigloo procedure

sha256sum-file string | bigloo procedure

sha256sum-port input-port | bigloo procedure

sha512sum obj | bigloo procedure

sha512sum-string string | bigloo procedure

sha512sum-mmap mmap | bigloo procedure

sha512sum-file string | bigloo procedure

sha512sum-port input-port | bigloo procedure

Computes SHA256 and SHA512 message digest.
The function `sha256sum` (respec. `sha512sum`) dispatches over its argument and invokes the ad-hoc function. That is, it invokes `sha256sum-string` if its argument is a string, `sha256sum-mmap` if it is a mmap, `sha256sum-port` if its argument is an input port.

hmac-sha256sum-string key string | bigloo procedure

hmac-sha512sum-string key string | bigloo procedure

Computes the Hmac SHA256 and SHA512 authentication.

### 6.12 Cyclic Redundancy Check (CRC)

Bigloo provides several known cyclic redundancy checks as well as means to create custom checks.
Usually CRCs are executed starting with the leftmost bit inside a byte (big endian). However, especially for serial-port transmissions, a scheme where the least-significant bit is processed first is desirable. Bigloo's CRC procedures accept a key-parameter (`:big-endian`) (by default `#t`) which allows to change this behavior.
The following CRCs (given with the associated polynomial) are provided:

- `itu-4`: 0x3
- `epc-5`: 0x9
- `itu-5`: 0x15
- `usb-5`: 0x5
- `itu-6`: 0x3
- `7`: 0x9
- `atm-8`: 0x7
- `ccitt-8`: 0x8d
- `dallas/maxim-8`: 0x31
- `8`: 0xd5
- `sae-j1850-8`: 0x1d
- `10`: 0x233
- `11`: 0x385
- `12`: 0x80f
- `can-15`: 0x4599
- `ccitt-16`: 0x1021
- `dnp-16`: 0x3d65
- `ibm-16`: 0x8005
- `24`: 0x5d6dcb
- `radix-64-24`: 0x864cfb
- `30`: 0x2030b9cf
- `ieee-32`: 0x4c11db7
- `c-32`: 0x1edc6f41
- `k-32`: 0x741b8cd7
- `q-32`: 0x814141ab
- `iso-64`: 0x1b
- `ecma-182-64`: 0x42f0e1eba9ea3693

crc-names | bigloo procedure

Returns a list of all provided CRCs (`itu-4`, `epc-5`, etc.).

crc-polynomial name | bigloo procedure

crc-polynomial-le name | bigloo procedure

Returns the polynomial for the given name. The `-le` variant returns the little endian polynomial.

    (crc-polynomial 'ieee-32)
        -| #e79764439 ;; == #ex4c11bd7
    (crc-polynomial 24)
        -| 6122955    ;; == #x5d6dcb

crc-length name | bigloo procedure

Returns the length of the specified CRC.

crc name obj [:init 0] [:final-xor 0] [:big-endian? #t] | bigloo procedure

crc-string name str::bstring [:init 0] [:final-xor 0] [:big-endian? #t] | bigloo procedure

crc-port name p::input-port [:init 0] [:final-xor 0] [:big-endian? #t] | bigloo procedure

crc-mmap name m::mmap [init 0] [:final-xor 0] [big-endian? #t] | bigloo procedure

crc-file name f::bstring [init 0] [:final-xor 0] [big-endian? #t] | bigloo procedure

Computes the CRC of the given object. `name` must be one of the provided CRC-algorithms. The optional parameter `init` can be used to initialize the CRC. The result of the CRC will be XORed with `final-xor`. The result will however be of the CRC's length. That is, even if `final-xor` is bigger then the CRC's length only the relevant bits will be used to perform the final XOR.
The result will be a number. Depending on the CRC this number can be a fixnum, an elong, or an llong.
The following example mimicks the UNIX `cksum` command:

    (module cksum (main main))
    (define (main args)
      (let loop ((sum (crc-file 'ieee-32 (cadr args)))
                 (size (elong->fixnum (file-size (cadr args)))))
        (if (=fx size 0)
            (printf "~a ~a ~a\n"
                    (bit-andllong #lxFFFFFFFF (elong->llong (bit-notelong sum)))
                    (file-size (cadr args))
                    (cadr args))
            (loop (crc-string 'ieee-32
                              (string (integer->char-ur (bit-and size #xFF)))
                              :init sum)
    	      (bit-rsh size 8)))))

In the following example we implement OpenPGP's CRC-24:

    (define (openpgp-crc-24 str)
      (crc-string 'radix-64-24 str :init #xB704CE))

Be aware that many common CRCs use -1 as init value and invert the result. For compatibility with other implementations you might want to try one of the following alternatives:

    (define (alt1 name obj) (crc name obj :init -1))
    (define (alt2 name obj) (crc name obj :final-xor -1))
    (define (alt3 name obj) (crc name obj :init -1 :final-xor -1))

Bigloo provides means to create additional CRCs: one can either simply provide a new polynomial or use Bigloo's low level functions.

register-crc! name poly len | bigloo procedure

Adds the given CRC to Bigloo's list. Name can be of any type (`crc` will use `assoc` to find it in its list). The polynomial can be either a fixnum, an elong or an llong. `len` should give the CRCs size. The type of the polynomial and the given `len` must be consistent. On a 32 bit machine the following CRC registration would be invalid and yield undefined results:

    (register-crc! 'invalid 1337 55)

As 55 is bigger than the fixnum's bit-size calling `crc` with this CRC will yield undefinde results.

crc-long::long c::char crc::long poly::long len::long | bigloo procedure

crc-elong::elong c::char crc::elong poly::elong len::long | bigloo procedure

crc-llong::llong c::char crc::llong poly::llong len::long | bigloo procedure

crc-long-le::long c::char crc::long poly::long len::long | bigloo procedure

crc-elong-le::elong c::char crc::elong poly::elong len::long | bigloo procedure

crc-llong-le::llong c::char crc::llong poly::llong len::long | bigloo procedure

These function perform a CRC operation on one byte. The previously described functions are based on these low level functions. The result of all the low level functions will return values that are not cut to the correct length. Usually a crc is done in a loop, and one needs to `bit-and` only when returning the result. Polynomials can be given with or without the high-order bit.
For instance we could implement `openpgp-crc24` as follows:

    (define *openpgp-init* #xB704CE)
    (define *radix-64-24-poly* #x864CFB)
    (define (openpgp-crc-24 str)
      (let loop ((i 0)
                 (crc *openpgp-init*))
        (if (=fx i (string-length str))
            (bit-and crc #xFFFFFF) ;; cut to correct length (24 bits)
            (loop (+fx i 1)
                  (crc-long (string-ref str i) crc *radix-64-24-poly* 24)))))

crc-polynomial-be->le len polynomial | bigloo procedure

Returns the little endian variant of a given polynomial.

### 6.13 Internet

This section presents the Bigloo function aimed at helping internet programming.

### 6.14 URLs

url-parse url | bigloo procedure

The argument `url` can either be a string or an input-port. The function `url-parse` parses the url and returns four values:

- the protocol,
- the optional user info,
- the host name,
- the port number,
- the absolute path

Example

    (multiple-value-bind (protocol uinfo host port abspath)
       (url-parse "http://www.inria.fr/sophia/teams/indes/index.html")
       (list protocol uinfo host port abspath))
          => ("http" #f "www.inria.fr" 80 "/sophia/teams/indes/index.html'')
    (multiple-value-bind (protocol uinfo host port abspath)
       (url-parse "https://foo:bar@www.inria.fr/sophia/teams/indes/index.html")
       (list protocol uinfo))
          => ("https" "foo@bar")

url-sans-protocol-parse url protocol | bigloo procedure

The argument `url` can either be a string or an input-port.
This function behaves as `url-parse` except it assumes that the protocol part of the url has already been extracted from the URI. It is explicitly provided using the `protocol` argument.

http-url-parse url | bigloo procedure

The argument `url` can either be a string or an input-port. As `url-parse`, it returns four values.
This function parses URL found in HTTP GET responses.

url-path-encode path | bigloo procedure

Encode a path that can be used in valid URL.

    (url-path-encode "/tmp/foo") => "/tmp/foo"
    (url-path-encode "/tmp/foo&bar") => "/tmp/foo%26bar"
    (url-path-encode "http:///tmp/foo") => "http%3A//tmp/foo"

url-encode url | bigloo procedure

uri-encode url | bigloo procedure

uri-encode-component url | bigloo procedure

Encode a URL by removing any illegal character.

    (url-encode "http:///tmp/foo") => "http://tmp:80/foo"
    (url-encode "http:///tmp/foo&bar") => "http://tmp:80/foo%26"

url-decode url | bigloo procedure

url-decode! url | bigloo procedure

uri-decode url | bigloo procedure

uri-decode! url | bigloo procedure

uri-decode-component url | bigloo procedure

uri-decode-component! url | bigloo procedure

Decode a URL. The function `url-decode!` may return its argument unmodified if no decoding is for the URL.
The variants `-component` treat do not escape URI reserved characters (i.e., #, /, ?, :, @, &, =, +, and $).

### 6.15 HTTP

http [:in #f] [:out #f] [:socket #f] | bigloo procedure

[:protocol 'http] [:method 'get] [:timeout 0] [:proxy #f] [:host "localhost"] [:port 80] [:path "/"] [:login #f] [:authorization #f] [:username #f] [:password #f] [:http-version "HTTP/1.1"] [:content-type #f] [:connection "close"] [:header '((user-agent: "Mozilla/5.0"))] [:args '()] [:body #f]
Opens an HTTP connection. Returns a socket.
It is an error to specify a header twice. In particular, it is illegal to re-define keyword-ed arguments in the `:header` list. For instance, it is illegal to include in the `:header` actual list value a value for the `Connection` HTTP connection.

    (define (wget url)

       (define (parser ip status-code header clen tenc)
          (if (not (and (>=fx status-code 200) (<=fx status-code 299)))
    	  (case status-code
    	     ((401)
    	      (raise (instantiate::&io-port-error
    			(proc 'open-input-file)
    			(msg "Cannot open URL, authentication required")
    			(obj url))))
    	     ((404)
    	      (raise (instantiate::&io-file-not-found-error
    			(proc 'open-input-file)
    			(msg "Cannot open URL")
    			(obj url))))
    	     (else
    	      (raise (instantiate::&io-port-error
    			(proc 'open-input-file)
    			(msg (format "Cannot open URL (~a)" status-code))
    			(obj url)))))
    	  (cond
    	     ((not (input-port? ip))
    	      (open-input-string ""))
    	     (clen
    	      (input-port-fill-barrier-set! ip (elong->fixnum clen))
    	      ip)
    	     (else
    	      ip))))

       (multiple-value-bind (protocol login host port abspath)
          (url-parse url)
          (let* ((sock (http :host host :port port :login login :path abspath))
    	     (ip (socket-input sock))
    	     (op (socket-output sock)))
    	 (with-handler
    	    (lambda (e)
    	       (if (isa? e &http-redirection)
                       (with-access::&http-redirection e (url)
    		      (wget url))
    		   (raise e)))
    	    (read-string (http-parse-response ip op parser))))))

The optional argument `args` is used for `post` method. The actual value should be a list of lists. Each of these sublists must have two values:

- the argument name
- the argument actual value

The argument name can be either a string which is the name of the argument or a list of two elements. In that case, the first element of these list is the argument name. The second element should be a string that denotes additional parameter.
Example:

    (http :host "localhost" :port 8080 :method 'post
       :header '((enctype: "multipart/form-data"))
       :args `(("x" "foo") (("foo.scm" "filename=\"foo.scm\"\nContent-type: application/octet-stream" ,(with-input-from-file "foo.scm" read-string))))
       ...)

An http connection blocks until the connection is established. If the optional argument `timeout` is provided, the connection must be established before the specified time interval elapses. The timeout is expressed in microseconds.

http-read-line input-port | bigloo procedure

http-read-crlf input-port | bigloo procedure

Reads a line or an end-of-line of an HTTP response.

http-parse-status-line input-port | bigloo procedure

Parses the status-line of an HTTP response. This returns a three values:

- The http version
- The status code
- the explanation phrase

http-parse-header input-port output-port | bigloo procedure

Parses the whole header of an HTTP response. It returns multiple values which are:

- the whole header as an alist.
- the host given in the `host` header.
- the port given `host` field.
- the optional `content-length` header field.
- the optional `transfer-encoding` header field.
- the optional `authorization` header field.
- the optional `proxy-authorization` header field.
- the optional `connection` header field.

http-parse-response input-port output-port procedure | bigloo procedure

Parses the whole response of an HTTP request. The argument `procedure` is invoked with five arguments:

- the input port to read the characters of the response,
- the status code,
- the header of the response,
- the content length,
- the type encoding.

http-response-body->port input-port output-port | bigloo procedure

Parses an HTTP response and build an output port that delivers the characters of the content.

http-chunks->procedure input-port | bigloo procedure

http-chunks->port input-port | bigloo procedure

http-send-chunks input-port output-port | bigloo procedure

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`

This Html page has been produced by Skribe.
Last update Mon Jan 27 07:55:49 2025.