Standard Library

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.

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

Booleans

The standard boolean objects are #t and #f.

Note: the empty list is true.

not objlibrary 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
.keep

boolean? objlibrary procedure

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

(boolean? #f)                           #t
(boolean? 0)                            #f
(boolean? '())                          #f
.keep

Equivalence predicates

eqv? obj1 obj2procedure

eq? obj1 obj2procedure

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

equal? obj1 obj2library 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
.keep
R5RS, for more details.

Pairs and lists

The form () is illegal.

pair? objprocedure

.keep

cons a dprocedure

.keep

pair-or-null? objbigloo procedure

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

car pairprocedure

cdr pairprocedure

set-car! pair objprocedure

set-cdr! pair objprocedure

.keep

caar pairlibrary procedure

cadr pairlibrary procedure

cadar pairlibrary procedure

caadr pairlibrary procedure

caaar pairlibrary procedure

caddr pairlibrary procedure

cadar pairlibrary procedure

cdddar pairlibrary procedure

cddddr pairlibrary procedure

.keep

null? objlibrary procedure

list? objlibrary procedure

list obj ...library procedure

length listlibrary procedure

append list ...library procedure

append! list ...bigloo procedure

A destructive append.
.keep

reverse listlibrary procedure

reverse! listbigloo procedure

A destructive reverse.
.keep

list-ref list klibrary procedure

take list klibrary procedure

drop list klibrary procedure

list-tail list klibrary 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.
.keep

last-pair listbigloo procedure

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

memq obj listlibrary procedure

memv obj listlibrary procedure

member obj listlibrary procedure

assq obj alistlibrary procedure

assv obj alistlibrary procedure

assoc obj alistlibrary procedure

remq obj listbigloo procedure

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

remq! obj listbigloo procedure

Same as remq but in a destructive way.
.keep

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

delete! obj list [eq equal?]bigloo procedure

Same as delete but in a destructive way.
.keep

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

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

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

find pred clistbigloo 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) =&gt; (lambda (pair) ...)) ; Handle (CAR PAIR)
      (else ...)) ; Search failed.
.keep

find-tail pred clistbigloo 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.
.keep

reduce f ridentity listbigloo 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)
.keep

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

list-tabulate n init-procbigloo 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)
.keep

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

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

list-copy lbigloo procedure

tree-copy lbigloo 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.
.keep

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.
.keep
R5RS, for more details.

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

symbol->string symbolprocedure

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-&gt;string 'foo))
R5RS, for more details.

but prefer:
(string-downcase (symbol-&gt;string 'foo))
.keep

string->symbol stringprocedure

string->symbol-ci stringbigloo 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.
.keep

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

genuuidbigloo procedure

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

symbol-plist symbol-or-keywordbigloo procedure

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

getprop symbol-or-keyword keybigloo 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.
.keep

putprop! symbol-or-keyword key valbigloo procedure

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

remprop! symbol-or-keyword keybigloo procedure

Removes the value associated with key in the symbol-or-keyword's property list. The result is unspecified.
.keep
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)

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? objbigloo procedure

keyword->string keywordbigloo procedure

string->keyword stringbigloo procedure

keyword->symbol keywordbigloo procedure

symbol->keyword symbolbigloo procedure

.keep

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

real? objprocedure

integer? objprocedure

complex? xbigloo procedure

rational? xbigloo procedure

.keep

fixnum? objbigloo procedure

flonum? objbigloo procedure

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

elong? objbigloo procedure

llong? objbigloo 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.
.keep

bignum? objbigloo procedure

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

make-elong intbigloo procedure

make-llong intbigloo procedure

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

minvalfxbigloo procedure

maxvalfxbigloo procedure

minvalelongbigloo procedure

maxvalelongbigloo procedure

minvalllongbigloo procedure

maxvalllongbigloo procedure

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

exact? zprocedure

inexact? zprocedure

.keep

zero? zlibrary procedure

positive? zlibrary procedure

negative? zlibrary procedure

odd? nlibrary procedure

even? nlibrary procedure

zerofx? zlibrary procedure

positivefx? zlibrary procedure

negativefx? zlibrary procedure

oddfx? nlibrary procedure

evenfx? nlibrary procedure

zerofl? zlibrary procedure

positivefl? zlibrary procedure

negativefl? zlibrary procedure

oddfl? nlibrary procedure

evenfl? nlibrary procedure

zeroelong? zlibrary procedure

positiveelong? zlibrary procedure

negativeelong? zlibrary procedure

oddelong? nlibrary procedure

evenelong? nlibrary procedure

zerollong? zlibrary procedure

positivellong? zlibrary procedure

negativellong? zlibrary procedure

oddllong? nlibrary procedure

evenllong? nlibrary procedure

zerobx? zlibrary procedure

positivebx? zlibrary procedure

negativebx? zlibrary procedure

oddbx? nlibrary procedure

evenbx? nlibrary procedure

.keep

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

.keep

= z1 z2 z3 ...procedure

=fx i1 i2bigloo procedure

=fl r1 r2bigloo procedure

=elong r1 r2bigloo procedure

=llong r1 r2bigloo procedure

=bx r1 r2bigloo procedure

< z1 z2 z3 ...procedure

<fx i1 i2bigloo procedure

<fl r1 r2bigloo procedure

<elong r1 r2bigloo procedure

<lllong r1 r2bigloo procedure

<bx r1 r2bigloo procedure

> z1 z2 z3 ...procedure

>fx i1 i2bigloo procedure

>fl r1 r2bigloo procedure

>elong r1 r2bigloo procedure

>lllong r1 r2bigloo procedure

>bx r1 r2bigloo procedure

<= z1 z2 z3 ...procedure

<=fx i1 i2bigloo procedure

<=fl r1 r2bigloo procedure

<=elong r1 r2bigloo procedure

<=llong r1 r2bigloo procedure

<=bx r1 r2bigloo procedure

>= z1 z2 z3 ...procedure

>=fx i1 i2bigloo procedure

>=fl r1 r2bigloo procedure

>=elong r1 r2bigloo procedure

>=llong r1 r2bigloo procedure

>=bx r1 r2bigloo procedure

.keep

+ z ...procedure

+fx i1 i2bigloo procedure

+fl r1 r2bigloo procedure

+elong r1 r2bigloo procedure

+llong r1 r2bigloo procedure

+bx r1 r2bigloo procedure

* z ...procedure

*fx i1 i2bigloo procedure

*fl r1 r2bigloo procedure

*elong r1 r2bigloo procedure

*llong r1 r2bigloo procedure

*bx r1 r2bigloo procedure

- zprocedure

- z1 z2 ...procedure

-fx i1 i2bigloo procedure

-fl r1 r2bigloo procedure

-elong r1 r2bigloo procedure

-llong r1 r2bigloo procedure

-bx r1 r2bigloo procedure

negfx ibigloo procedure

negfl rbigloo procedure

negelong rbigloo procedure

negllong rbigloo procedure

negbx rbigloo procedure

These two functions implement the unary function -.
.keep

/ z1 z2procedure

/ z1 z2 ...procedure

/fx i1 i2bigloo procedure

/fl r1 r2bigloo procedure

/elong r1 r2bigloo procedure

/llong r1 r2bigloo procedure

/bx r1 r2bigloo procedure

.keep

abs zlibrary procedure

absfl zbigloo procedure

quotient z1 z2procedure

quotientelong z1 z2procedure

quotientllong z1 z2procedure

remainder z1 z2procedure

remainderelong z1 z2procedure

remainderllong z1 z2procedure

remainderfl z1 z2procedure

modulo z1 z2procedure

gcd z ...procedure

lcm z ...procedure

floor zprocedure

floorfl zprocedure

ceiling zprocedure

ceilingfl zprocedure

truncate zprocedure

truncatefl zprocedure

round zprocedure

roundfl zprocedure

.keep

random zbigloo procedure

randomflbigloo procedure

randombx zbigloo procedure

seed-random! zbigloo 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].
.keep

exp zprocedure

expfl zprocedure

log zprocedure

logfl zprocedure

sin zprocedure

sinfl zprocedure

cos zprocedure

cosfl zprocedure

tan zprocedure

tanfl zprocedure

asin zprocedure

asinfl zprocedure

acos zprocedure

acosfl zprocedure

atan z1 z2procedure

atanfl z1 z2procedure

sqrt zprocedure

sqrtfl zprocedure

expt z1 x2procedure

exptfl z1 x2procedure

.keep

exact->inexact zprocedure

inexact->exact zprocedure

number->string zprocedure

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 zbigloo 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"
.keep

nanfl? zbigloo procedure

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

infinitefl? zbigloo procedure

finitefl? zbigloo 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.
.keep

signbitfl zbigloo procedure

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

bignum->octet-string bignumbigloo procedure

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

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

double->ieee-string zbigloo procedure

float->ieee-string zbigloo procedure

Returns a big-endian representation of the given number.
.keep

string->number string [radix 10]procedure

string->real stringbigloo procedure

string->elong string radixbigloo procedure

string->llong string radixbigloo procedure

string->bignum string radixbigloo 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
In addition, string->number does not support radix encoded inside string. That is:

(string->number "#x1243")           #f
.keep

octet-string->bignum stringbigloo 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
.keep

ieee-string->double stringbigloo procedure

ieee-string->float stringbigloo procedure

Convert the big-endian representations to their numeric values.
.keep

fixnum->flonum ibigloo procedure

flonum->fixnum rbigloo procedure

elong->fixnum ibigloo procedure

fixnum->elong rbigloo procedure

llong->fixnum ibigloo procedure

fixnum->llong rbigloo procedure

elong->flonum ibigloo procedure

flonum->elong rbigloo procedure

llong->flonum ibigloo procedure

flonum->llong rbigloo procedure

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.

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

.keep

double->llong-bits zbigloo procedure

float->int-bits zbigloo-procedure

Returns the double-bits as a llong.
.keep

llong-bits->double llongbigloo procedure

int-bits->float intbigloo procedure

Converts the given llong bits to a double.
.keep
R5RS, for more details.

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

.keep

char=? char1 char2procedure

char<? char1 char2procedure

char>? char1 char2procedure

char<=? char1 char2procedure

char>=? char1 char2procedure

char-ci=? char1 char2library procedure

char-ci<? char1 char2library procedure

char-ci>? char1 char2library procedure

char-ci<=? char1 char2library procedure

char-ci>=? char1 char2library procedure

.keep

char-alphabetic? charlibrary procedure

char-numeric? charlibrary procedure

char-whitespace? charlibrary procedure

char-upper-case? charlibrary procedure

char-lower-case? charlibrary procedure

.keep

char->integer charprocedure

integer->char iprocedure

.keep

char-upcase charlibrary procedure

char-downcase charlibrary procedure

.keep

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? objbigloo procedure

.keep

ucs2=? ucs2a ucs2bbigloo procedure

ucs2<? ucs2a ucs2bbigloo procedure

ucs2>? ucs2a ucs2bbigloo procedure

ucs2<=? ucs2a ucs2bbigloo procedure

ucs2>=? ucs2a ucs2bbigloo procedure

ucs2-ci=? ucs2a ucs2bbigloo procedure

ucs2-ci<? ucs2a ucs2bbigloo procedure

ucs2-ci>? ucs2a ucs2bbigloo procedure

ucs2-ci<=? ucs2a ucs2bbigloo procedure

ucs2-ci>=? ucs2a ucs2bbigloo procedure

.keep

ucs2-alphabetic? ucs2bigloo procedure

ucs2-numeric? ucs2bigloo procedure

ucs2-whitespace? ucs2bigloo procedure

ucs2-upper-case? ucs2bigloo procedure

ucs2-lower-case? ucs2bigloo procedure

.keep

ucs2->integer ucs2bigloo procedure

integer->ucs2 ibigloo procedure

.keep

ucs2->char ucs2bigloo procedure

char->ucs2 charbigloo procedure

.keep

ucs2-upcase ucs2bigloo procedure

ucs2-downcase ucs2bigloo procedure

.keep

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 Lexical structure,,r5rs.info,R5RS. 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? objprocedure

.keep

string-null? sSRFI-13 procedure

Is s an empty string?
.keep

make-string kprocedure

make-string k charprocedure

string char ...library procedure

.keep

string-length stringprocedure

string-ref string kprocedure

string-set! string k charprocedure

.keep

string=? string1 string2library procedure

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

substring=? string1 string2 lenbigloo 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
.keep

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

string-ci=? string1 string2library procedure

substring-ci=? string1 string2 lenbigloo procedure

string<? string1 string2library procedure

string>? string1 string2library procedure

string<=? string1 string2library procedure

string>=? string1 string2library procedure

string-ci<? string1 string2library procedure

string-ci>? string1 string2library procedure

string-ci<=? string1 string2library procedure

string-ci>=? string1 string2library procedure

.keep

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

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

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

.keep

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

string-compare3 string1 string2bigloo procedure

string-compare3-ci string1 string2bigloo 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.
.keep

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

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"
.keep

string-shrink! string endlibrary 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"
.keep

string-append string ...library procedure

string->list stringlibrary procedure

list->string listlibrary procedure

string-copy stringlibrary procedure

.keep

string-fill! string charbigloo procedure

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

string-downcase stringbigloo procedure

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

string-upcase stringbigloo procedure

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

string-capitalize stringbigloo procedure

Builds a newly allocated capitalized string.
.keep

string-downcase! stringbigloo procedure

Physically downcases the string argument.
.keep

string-upcase! stringbigloo procedure

Physically upcases the string argument.
.keep

string-capitalize! stringbigloo procedure

Physically capitalized the string argument.
.keep

string-for-read stringbigloo procedure

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

blit-string! string1 o1 string2 o2 lenbigloo 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"
.keep

string-replace string char1 char2bigloo procedure

string-replace! string char1 char2bigloo 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.
.keep

string-split stringbigloo procedure

string-split string delimitersbigloo 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")
.keep

string-cut stringbigloo procedure

string-cut string delimitersbigloo 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")
.keep

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

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

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.

.keep

string-hex-intern stringbigloo procedure

string-hex-intern! stringbigloo procedure

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

(string-hex-intern "4a4b4c")  "JKL"
.keep

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"
.keep

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? objbigloo procedure

.keep

make-ucs2-string kbigloo procedure

make-ucs2-string k charbigloo procedure

ucs2-string k ...bigloo procedure

.keep

ucs2-string-length s-ucs2bigloo procedure

ucs2-string-ref s-ucs2 kbigloo procedure

ucs2-string-set! s-ucs2 k charbigloo procedure

.keep

ucs2-string=? s-ucs2a s-ucs2bbigloo procedure

ucs2-string-ci=? s-ucs2a s-ucs2bbigloo procedure

ucs2-string<? s-ucs2a s-ucs2bbigloo procedure

ucs2-string>? s-ucs2a s-ucs2bbigloo procedure

ucs2-string<=? s-ucs2a s-ucs2bbigloo procedure

ucs2-string>=? s-ucs2a s-ucs2bbigloo procedure

ucs2-string-ci<? s-ucs2a s-ucs2bbigloo procedure

ucs2-string-ci>? s-ucs2a s-ucs2bbigloo procedure

ucs2-string-ci<=? s-ucs2a s-ucs2bbigloo procedure

ucs2-string-ci>=? s-ucs2a s-ucs2bbigloo procedure

.keep

ucs2-substring s-ucs2 start endbigloo procedure

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

ucs2-string->list s-ucs2bigloo procedure

list->ucs2-string charsbigloo procedure

ucs2-string-copy s-ucs2bigloo procedure

.keep

ucs2-string-fill! s-ucs2 charbigloo procedure

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

ucs2-string-downcase s-ucs2bigloo procedure

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

ucs2-string-upcase s-ucs2bigloo procedure

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

ucs2-string-downcase! s-ucs2bigloo procedure

Physically downcases the s-ucs2 argument.
.keep

ucs2-string-upcase! s-ucs2bigloo procedure

Physically upcases the s-ucs2 argument.
.keep

ucs2-string->utf8-string s-ucs2bigloo procedure

utf8-string->ucs2-string stringbigloo procedure

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

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.

.keep

ascii-string? stringbigloo procedure

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

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.

.keep

utf8-string-length stringbigloo 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.
.keep

utf8-codepoint-length stringbigloo 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.
.keep

utf8-string-ref string ibigloo procedure

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

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

iso-latin->utf8 stringbigloo procedure

iso-latin->utf8! stringbigloo procedure

utf8->iso-latin stringbigloo procedure

utf8->iso-latin! stringbigloo procedure

utf8->iso-latin-15 stringbigloo procedure

utf8->iso-latin-15! stringbigloo 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.
.keep

cp1252->utf8 stringbigloo procedure

cp1252->utf8! stringbigloo procedure

utf8->cp1252 stringbigloo procedure

utf8->cp1252! stringbigloo 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.
.keep

8bits->utf8 string tablebigloo procedure

8bits->utf8! string tablebigloo procedure

utf8->8bits string inv-tablebigloo procedure

utf8->8bits! string inv-tablebigloo 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.
.keep

inverse-utf8-table vectorprocedure

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

Vectors

Vectors are not autoquoted objects.

vector? objprocedure

.keep

make-vector kprocedure

make-vector k objprocedure

vector obj ...library procedure

.keep

vector-length vectorprocedure

vector-ref vector kprocedure

vector-set! vector k objprocedure

.keep

vector->list vectorlibrary procedure

list->vector listlibrary procedure

.keep

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

copy-vector vector lenbigloo 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.
.keep

vector-copy vector start endbigloo 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)
.keep

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.
.keep
r5rs.info, 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))
.keep

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

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

vector-shrink! vector endbigloo 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.

.keep

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:

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

Control features

procedure? objprocedure

.keep

apply proc arg1 ... argsprocedure

.keep

map proc list1 list2 ...library procedure

map! proc list1 list2 ...bigloo procedure

for-each proc list1 list2 ...library procedure

.keep

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

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

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

sort proc objbigloo procedure

sort obj procbigloo 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.
.keep

force promiselibrary procedure

.keep

call/cc procbigloo procedure

This function is the same as the call-with-current-continuation function of the R5RS, see call-with-current-continuation,,r5rs.info,R5RS, but it is necessary to compile the module with the -call/cc option to use it, see Section 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.
.keep

bind-exit escape bodybigloo 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
.keep

unwind-protect expr protectbigloo 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))))))
.keep

dynamic-wind before thunk afterprocedure

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:

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 afters 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 befores 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)
.keep

unspecifiedbigloo procedure

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

try exp handlerbigloo syntax

This form is documented in Section Errors Assertions and Traces.
.keep

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

call-with-values producer consumerprocedure

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

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

Input and output

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

Library functions

call-with-input-file string proclibrary procedure

call-with-input-string string procbigloo procedure

call-with-output-file string proclibrary procedure

call-with-append-file string proclibrary procedure

call-with-output-string proclibrary procedure

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

input-port? obj procedure

input-string-port? obj procedure

output-port? objprocedure

output-string-port? objprocedure

port? objprocedure

.keep

input-port-name objbigloo procedure

input-port-name-set! obj namebigloo procedure

output-port-name objbigloo procedure

output-port-name-set! obj namebigloo procedure

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

input-port-length objbigloo (>=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).
.keep

input-port-timeout-set! port timebigloo (>=2.8b) procedure

output-port-timeout-set! port timebigloo (>=2.8b) procedure

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

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

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

output-port-flush-hook portbigloo procedure

output-port-flush-hook-set! port hookbigloo 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:

.keep

output-port-flush-buffer portbigloo procedure

output-port-flush-buffer-set! port bufferbigloo 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.
.keep

output-port-close-hook portbigloo procedure

output-port-close-hook-set! port procbigloo 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.
.keep

input-port-close-hook portbigloo procedure

input-port-close-hook-set! port procbigloo 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))
.keep

input-port-reopen! objbigloo procedure

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

current-input-portprocedure

current-output-portprocedure

current-error-portbigloo procedure

.keep

with-input-from-file string thunkoptional procedure

with-input-from-string string thunkoptional procedure

with-input-from-procedure procedure thunkoptional procedure

with-output-to-file string thunkoptional procedure

with-append-to-file string thunkoptional procedure

with-error-to-file string thunkbigloo procedure

with-output-to-string thunkbigloo procedure

with-output-to-procedure procedure thunkbigloo procedure

with-error-to-string thunkbigloo procedure

with-error-to-procedure procedure thunkbigloo 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 Ports,,r5rs.info,R5RS, 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))))))))
.keep

with-input-from-port port thunkbigloo procedure

with-output-to-port port thunkbigloo procedure

with-error-to-port port thunkbigloo 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")))
.keep

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:

The optional argument buffer can either be:

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

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

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

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

open-input-c-string stringbigloo 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.
.keep

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

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

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

open-output-file file-nameprocedure

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

append-output-file file-namebigloo 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.
.keep

open-output-stringbigloo 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.
.keep

get-output-string output-portbigloo 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.
.keep

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

close-input-port input-portprocedure

close-output-port output-portprocedure

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

closed-input-port? input-portprocedure

closed-output-port? output-portprocedure

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

input-port-name input-portbigloo procedure

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

input-port-position portbigloo procedure

output-port-position portbigloo procedure

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

set-input-port-position! port posbigloo procedure

set-output-port-position! port posbigloo 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.
.keep

input-port-reopen! input-portbigloo procedure

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

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

read/rp grammar portbigloo procedure

read/lalrp lalrg rg port [emptyp]bigloo procedure

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

define-reader-ctor symbol procedurebigloo 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
.keep

set-read-syntax! char procedurebigloo 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))))))))
.keep

read-char [port]procedure

read-byte [port]procedure

peek-char [port]procedure

peek-byte [port]procedure

eof-object? objprocedure

.keep

char-ready? [port]procedure

As specified in the R5Rs, Ports,,r5rs.info,R5RS, 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.
.keep

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

read-lines [input-port]bigloo procedure

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

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

read-string [input-port]bigloo procedure

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

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

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

port->string-list input-portbigloo procedure

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

port->list input-port readerbigloo procedure

port->sexp-list input-portbigloo 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).
.keep

file->string pathbigloo 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.
.keep

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

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

display* obj ...bigloo procedure

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

fprint output-port obj ...bigloo procedure

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

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

newline [output-port]procedure

flush-output-port output-portbigloo 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.
.keep

newline [output-port]procedure

reset-output-port output-portbigloo 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.
.keep

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

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

pp obj [output-port]bigloo procedure

Pretty print obj on output-port.
.keep

*pp-case*bigloo variable

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

*pp-width*bigloo variable

The width of the pretty-print.
.keep

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

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

display-string string output-portbigloo procedure

display-substring string start end output-portbigloo 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).
.keep

password [prompt]bigloo procedure

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

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

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

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:

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

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

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:

.keep

string->mmap string [mode]bigloo procedure

Wrap a Bigloo string into a mmap object.
.keep

mmap-name mmbigloo procedure

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

close-mmap mmbigloo procedure

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

mmap-length mmbigloo procedure

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

mmap-read-position mmbigloo procedure

mmap-read-position-set! mm offsetbigloo procedure

mmap-write-position mmbigloo procedure

mmap-write-position-set! mm offsetbigloo procedure

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

mmap-ref mm offsetbigloo procedure

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

mmap-set! mm offset charbigloo procedure

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

mmap-substring mm start endbigloo 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.
.keep

mmap-substring-set! mm start strbigloo 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).
.keep

mmap-get-char mmbigloo procedure

mmap-put-char! mm cbigloo procedure

mmap-get-string mm lenbigloo procedure

mmap-put-string! mm strbigloo 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.
.keep

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

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-&gt;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.

.keep

gunzip-sendchars input-port output-portbigloo procedure

inflate-sendchars input-port output-portbigloo 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.
.keep

gunzip-parse-header input-portbigloo procedure

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

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

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

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

tar-round-up-to-record-size intbigloo procedure

Rounds up tar-block sizes.
.keep

tar-header-name tar-headerbigloo procedure

tar-header-mode tar-headerbigloo procedure

tar-header-uid tar-headerbigloo procedure

tar-header-gid tar-headerbigloo procedure

tar-header-size tar-headerbigloo procedure

tar-header-mtim tar-headerbigloo procedure

tar-header-checksum tar-headerbigloo procedure

tar-header-type tar-headerbigloo procedure

tar-header-linkname tar-headerbigloo procedure

tar-header-uname tar-headerbigloo procedure

tar-header-gname tar-headerbigloo procedure

tar-header-devmajor tar-headerbigloo procedure

tar-header-devminir tar-headerbigloo procedure

Return various information about tar-header.
.keep
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.

.keep

Serialization

string->obj string #!optional extensionbigloo 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.

.keep

obj->string objectbigloo procedure

This function converts into a string any Bigloo object which does not contain a procedure.
.keep
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? objbigloo procedure

open-output-binary-file file-namebigloo procedure

append-output-binary-file file-namebigloo procedure

open-input-binary-file file-namebigloo procedure

close-binary-port binary-portbigloo procedure

flush-binary-port binary-portbigloo procedure

input-obj binary-portbigloo procedure

output-obj binary-port objbigloo 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.
.keep

input-char binary-portbigloo procedure

output-char binary-port charbigloo procedure

output-byte binary-port bytebigloo 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.
.keep

input-string binary-port lenbigloo procedure

output-string binary-portbigloo 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.
.keep

input-fill-string! binary-port stringbigloo 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.
.keep

register-procedure-serialization! serializer unserializerbigloo procedure

register-custom-serialization! ident serializer unserializerbigloo procedure

register-process-serialization! serializer unserializerbigloo procedure

register-opaque-serialization! serializer unserializerbigloo 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)))))
.keep

register-class-serialization! class serializer unserializerbigloo 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
.keep

get-procedure-serialization bigloo procedure

get-custom-serialization identbigloo procedure

get-process-serialization bigloo procedure

get-opaque-serialization bigloo procedure

get-class-serialization classbigloo 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.
.keep

Bit manipulation

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

bit-or i1 i2bigloo procedure

bit-orelong i1 i2bigloo procedure

bit-orllong i1 i2bigloo procedure

bit-xor i1 i2bigloo procedure

bit-xorelong i1 i2bigloo procedure

bit-xorllong i1 i2bigloo procedure

bit-and i1 i2bigloo procedure

bit-andelong i1 i2bigloo procedure

bit-andllong i1 i2bigloo procedure

bit-not ibigloo procedure

bit-notelong ibigloo procedure

bit-notllong ibigloo procedure

bit-lsh i1 i2bigloo procedure

bit-lshelong i1 i2bigloo procedure

bit-lshllong i1 i2bigloo procedure

bit-rsh i1 i2bigloo procedure

bit-ursh i1 i2bigloo procedure

bit-rshelong i1 i2bigloo procedure

bit-rshllong i1 i2bigloo procedure

bit-urshelong i1 i2bigloo procedure

bit-urshllong i1 i2bigloo procedure

(bit-or 5 3)                            7
(bit-orelong #e5 #e3)                   #e7
(bit-xor 5 3)                           6
(bit-andllong #l5 #l3)                  #l1
(bit-not 5)                             -6
(bit-lsh 5 3)                           40
(bit-rsh 5 1)                           2
.keep

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

Creates a weak pointer to data.
.keep

weakptr? objbigloo procedure

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

weakptr-data ptrbigloo procedure

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

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]bigloo procedure

Defines an 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:

(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.
.keep

hashtable? objbigloo procedure

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

hashtable-weak-keys? tablebigloo procedure

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

hashtable-weak-data? tablebigloo procedure

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

hashtable-size tablebigloo 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.
.keep

hashtable-contains? table keybigloo 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.
.keep

hashtable-get table keybigloo 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.
.keep

hashtable-put! table key objbigloo 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.
.keep

hashtable-remove! table keybigloo procedure

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

hashtable-add! table key update-fun obj init-valuebigloo 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).
.keep

hashtable-update! table key update-fun init-valuedeprecated 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.
.keep

hashtable->vector tablebigloo procedure

hashtable->list tablebigloo 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.
.keep

hashtable-key-list tablebigloo 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.
.keep

hashtable-map table funbigloo 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.
.keep

hashtable-for-each table funbigloo 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.
.keep

hashtable-filter! table funbigloo 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.
.keep

hashtable-clear! tablebigloo procedure

Remove all the elements from table.
.keep
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)

object-hashnumber objectbigloo 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)))
.keep

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

System programming

Operating System interface

bigloo-configbigloo procedure

bigloo-config keybigloo 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
.keep

register-exit-function! procbigloo procedure

unregister-exit-function! procbigloo 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.
.keep

exit intbigloo procedure

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

signal n procbigloo procedure

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

get-signal-handler nbigloo procedure

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

system . stringsbigloo procedure

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

system->string . stringsbigloo 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.
.keep

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

putenv string valbigloo 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.
.keep

datebigloo procedure

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

sleep microsbigloo procedure

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

command-linebigloo procedure

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

executable-namebigloo procedure

Returns the name of the running executable.
.keep

os-classbigloo procedure

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

os-namebigloo procedure

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

os-archbigloo procedure

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

os-versionbigloo procedure

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

os-tmpbigloo procedure

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

os-charsetbigloo procedure

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

file-separatorbigloo procedure

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

path-separatorbigloo procedure

Gives the operating system file path separator (e.g.#\:).
.keep
For additional functions (such as directory->list) see Input and Output.

unix-path->listbigloo procedure

Converts a Unix path to a Bigloo list of strings.

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

hostnamebigloo procedure

Returns the fully qualified name of the current host.
.keep

time thunkbigloo 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))
.keep

getuidbigloo procedure

getgidbigloo procedure

setuid uidbigloo procedure

setgid uidbigloo 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.
.keep

getpidbigloo procedure

Get the current process identifier.
.keep

getppidbigloo procedure

Get the parent process identifier.
.keep

getgroupsbigloo 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.
.keep

getpwnam namebigloo procedure

getpwuid uidbigloo 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:

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

openlog name option facilitybigloo procedure

syslog level . objbigloo procedure

closelogbigloo procedure

syslog-optionbigloo procedure

syslog-levelbigloo procedure

syslog-facilitybigloo 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)
.keep

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

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

prefix stringbigloo 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"
.keep

suffix stringbigloo 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"
.keep

dirname stringbigloo 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") 
    "/"
.keep

pwdbigloo procedure

Returns the current working directory.
.keep

chdir dir-namebigloo procedure

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

make-file-name dir-name namebigloo procedure

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

make-file-path dir-name name . namesbigloo procedure

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

file-name->list namebigloo procedure

Explodes a file name into a list.

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

file-name-canonicalize namebigloo procedure

file-name-canonicalize! namebigloo procedure

file-name-unix-canonicalize namebigloo procedure

file-name-unix-canonicalize! namebigloo 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"
.keep

relative-file-name name basebigloo procedure

Builds a file name relative to base.

(relative-file-name "/etc/passwd" "/etc"
    "passwd"
.keep

find-file/path name pathbigloo 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
.keep

make-static-library-name namebigloo procedure

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

make-shared-library-name namebigloo procedure

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

file-exists? stringbigloo procedure

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

file-gzip? stringbigloo procedure

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

delete-file stringbigloo procedure

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

rename-file string1 string2bigloo 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.
.keep

truncate-file path sizebigloo 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.
.keep

copy-file string1 string2bigloo procedure

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

make-symlink target linkpathbigloo procedure

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

directory? stringbigloo procedure

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

make-directory stringbigloo procedure

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

make-directories stringbigloo 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.
.keep

delete-directory stringbigloo procedure

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

directory->list stringbigloo procedure

directory->path-list stringbigloo 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.
.keep

file-modification-time stringbigloo procedure

file-change-time stringbigloo procedure

file-access-time stringbigloo procedure

file-times-set! string atime mtimebigloo 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).
.keep

file-size stringbigloo 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.
.keep

file-uid stringbigloo procedure

file-gid stringbigloo procedure

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

file-mode stringbigloo procedure

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

file-type stringbigloo procedure

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

.keep

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

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: 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.
.keep

process? objbigloo procedure

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

process-alive? processbigloo procedure

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

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

process-pid processbigloo procedure

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

process-input-port processbigloo procedure

process-output-port processbigloo procedure

process-error-port processbigloo 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.
.keep

process-wait processbigloo procedure

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

process-exit-status processbigloo procedure

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

process-send-signal process sbigloo 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.
.keep

process-kill processbigloo procedure

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

process-stop processbigloo procedure

process-continue processbigloo 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.
.keep

process-listbigloo procedure

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

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 Communication Styles, socket communication styles, The GNU C Library Reference Manual, libc). 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:

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:

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

socket? objbigloo procedure

socket-server? objbigloo procedure

socket-client? objbigloo procedure

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

socket-hostname socketbigloo 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.
.keep

socket-host-address socketbigloo 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.
.keep

socket-local-address socketbigloo procedure

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

socket-port-number socketbigloo procedure

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

socket-input socketbigloo procedure

socket-output socketbigloo 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''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.:
(let ((s (make-client-socket "kaolin.unice.fr" 13)))
  (print "Time is: " (read-line (socket-input s)))
  (socket-shutdown  s))
.keep

make-server-socket #!optional (port 0) #!key (name #f) (backlog 5)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.
.keep

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:

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 1234Under 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. 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))
.keep

socket-close socketbigloo procedure

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

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:

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

socket-down? socketbigloo procedure

Returns #t if socket has been previously closed with socket-shutdown. It returns #f otherwise.
.keep
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-&gt;integer (cadr argv))
                10))
         (s (make-server-socket)))
      (print "s: " s)
      (let loop ((i 0))
         (if (&lt;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-server-socket portbigloo procedure

Return a datagram server socket bound to the loopback address on port, and whose address family and protocol family are those normally used for services on port.
.keep

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

Return an unbound datagram socket. 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.
.keep

datagram-socket-receive sock sizebigloo procedure

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

datagram-socket-send sock message host portbigloo 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.
.keep

host hostnamebigloo procedure

hostinfo hostnamebigloo 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).
.keep

get-interfacesbigloo 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).
.keep

get-protocolsbigloo 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:

.keep

get-protocol number-or-namebigloo procedure

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

socket-option socket option-namebigloo procedure

socket-option-set! socket option-name valbigloo 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:

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

.keep

SSL

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

ssl-versionSSL library procedure

Returns a string representing the SSL library version number.
.keep

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? objSSL library procedure

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

make-ssl-client-socket hostname port-number #!key (buffer #t) (timeout 0) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f)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:

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.

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

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

make-ssl-server-socket #!key (port 0) (name #f) (protocol 'sslv23) (cert #f) (pkey #f) (CAs '()) (accepted-certs #f)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.

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

Certificates

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

read-certificate fileSSL 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.
.keep

read-pem-file fileSSL 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.
.keep

certificate-subject certSSL library procedure

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

certificate-issuer certSSL library procedure

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

Private Keys

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

read-private-key fileSSL 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.
.keep

Date

date? objbigloo 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.
.keep

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

date-copy date #!key sec min hour day month year timezonebigloo procedure

Creates a new date from the argument date.

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

current-datebigloo procedure

Returns a date object representing the current date.
.keep

current-secondsbigloo procedure

current-microsecondsbigloo procedure

current-nanosecondsbigloo 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).
.keep

date->secondsbigloo procedure

date->nanosecondsbigloo procedure

seconds->datebigloo procedure

seconds->gmtdatebigloo procedure - 4.3h

nanoeconds->datebigloo procedure

Convert from date and elong.
.keep

date->string datebigloo procedure

date->utc-string datebigloo procedure

seconds->string elongbigloo procedure

seconds->utc-string elongbigloo procedure

Construct a textual representation of the date passed in argument
.keep

date-second datebigloo procedure

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

date-nanosecond datebigloo procedure

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

date-minute datebigloo procedure

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

date-hour datebigloo procedure

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

date-day datebigloo procedure

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

date-wday datebigloo procedure

date-week-day datebigloo procedure

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

date-yday datebigloo procedure

date-year-day datebigloo procedure

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

date-month datebigloo procedure

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

date-year datebigloo procedure

Returns the year of a date.
.keep

date-timezone datebigloo procedure

Returns the timezone (in seconds) of a date.
.keep

date-is-dst datebigloo 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.
.keep

integer->secondbigloo procedure

Converts a Bigloo fixnum integer into a second number.
.keep

day-secondsbigloo procedure

Returns the number of seconds contained in one day.
.keep

day-name intbigloo procedure

day-aname intbigloo procedure

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

month-name intbigloo procedure

month-aname intbigloo procedure

Return the name and the abbreviated name of a month.
.keep

date-month-length datebigloo procedure

Return the length of the month of date.
.keep

leap-year? intbigloo procedure

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

rfc2822-date->date stringbigloo procedure

rfc2822-parse-date input-portbigloo procedure

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

date->rfc2822-date datebigloo procedure

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

iso8601-date->date stringbigloo procedure

iso8601-parse-date input-portbigloo procedure

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

date->iso8601-date datebigloo procedure

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

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

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

pem-read-file file-namebigloo procedure

pem-decode-port input-port output-portbigloo procedure

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

md5sum objbigloo procedure

md5sum-string stringbigloo procedure

md5sum-mmap mmapbigloo procedure

md5sum-file stringbigloo procedure

md5sum-port input-portbigloo 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.
.keep

hmac-md5sum-string key stringbigloo procedure

Computes the Hmac MD5 authentication:

(hmac-md5sum-string (make-string 16 #a011) "Hi There") 
   "9294727a3638bb1c13f48ef8158bfc9d"
.keep

cram-md5sum-string user key stringbigloo 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.
.keep

sha1sum objbigloo procedure

sha1sum-string stringbigloo procedure

sha1sum-mmap mmapbigloo procedure

sha1sum-file stringbigloo procedure

sha1sum-port input-portbigloo 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.
.keep

hmac-sha1sum-string key stringbigloo procedure

Computes the Hmac SHA1 authentication:
.keep

sha256sum objbigloo procedure

sha256sum-string stringbigloo procedure

sha256sum-mmap mmapbigloo procedure

sha256sum-file stringbigloo procedure

sha256sum-port input-portbigloo procedure

Computes SHA256 message digest.

The function sha256sum 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.
.keep

hmac-sha256sum-string key stringbigloo procedure

Computes the Hmac SHA256 authentication:
.keep

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:

crc-namesbigloo procedure

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

crc-polynomial namebigloo procedure

crc-polynomial-le namebigloo 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
.keep

crc-length namebigloo procedure

Returns the length of the specified CRC.
.keep

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-&gt;fixnum (file-size (cadr args)))))
    (if (=fx size 0)
        (printf "~a ~a ~a\n"
                (bit-andllong #lxFFFFFFFF (elong-&gt;llong (bit-notelong sum)))
                (file-size (cadr args))
                (cadr args))
        (loop (crc-string 'ieee-32
                          (string (integer-&gt;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))
.keep
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 lenbigloo 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.
.keep

crc-long::long c::char crc::long poly::long len::longbigloo procedure

crc-elong::elong c::char crc::elong poly::elong len::longbigloo procedure

crc-llong::llong c::char crc::llong poly::llong len::longbigloo procedure

crc-long-le::long c::char crc::long poly::long len::longbigloo procedure

crc-elong-le::elong c::char crc::elong poly::elong len::longbigloo procedure

crc-llong-le::llong c::char crc::llong poly::llong len::longbigloo 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)))))
.keep

crc-polynomial-be->le len polynomialbigloo procedure

Returns the little endian variant of a given polynomial.
.keep

Internet

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

URLs

url-parse urlbigloo procedure

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

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))
      &#8658; ("https" "foo@bar")
.keep

url-sans-protocol-parse url protocolbigloo 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.
.keep

http-url-parse urlbigloo 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.
.keep

url-path-encode pathbigloo 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"
.keep

url-encode urlbigloo procedure

uri-encode urlbigloo procedure

uri-encode-component urlbigloo 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"
.keep

url-decode urlbigloo procedure

url-decode! urlbigloo procedure

uri-decode urlbigloo procedure

uri-decode! urlbigloo procedure

uri-decode-component urlbigloo procedure

uri-decode-component! urlbigloo 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 $).
.keep

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 (&gt;=fx status-code 200) (&lt;=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-&gt;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 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.
.keep

http-read-line input-portbigloo procedure

http-read-crlf input-portbigloo procedure

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

http-parse-status-line input-portbigloo procedure

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

.keep

http-parse-header input-port output-portbigloo procedure

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

http-parse-response input-port output-port procedurebigloo procedure

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

.keep

http-response-body->port input-port output-portbigloo procedure

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

http-chunks->procedure input-portbigloo procedure

.keep

http-chunks->port input-portbigloo procedure

.keep

http-send-chunks input-port output-portbigloo procedure

.keep