While the package is in alpha development state, the documentation you
may see at project WEB site may differ from that provided with last
bigloo-lib release. Usually the documentation describes the
development "bleeding edge", some of the features described here will be
visible in the next releases only. Use the documentation
included into the package.
This project's CVS repository can be checked out through anonymous
(pserver) CVS with the following instruction set. When prompted for a
password for anonymous, simply press the Enter key.
cvs -d:pserver:anonymous@cvs.bigloo-lib.sourceforge.net:/cvsroot/bigloo-lib login
cvs -d:pserver:anonymous@cvs.bigloo-lib.sourceforge.net:/cvsroot/bigloo-lib co .
All the libraries are compiled, linked and installed using GNU
libtool. libtool makes its own decision about flags it
send to the linker. As a result, the path to installed libraries
(/usr/local/lib/bigloo by default) is not compiled into the
libraries, so you need to care about it by yourself (set either the
LD_LIBRARY_PATH or LD_RUN_PATH environment variable or
edit /etc/ld.so.conf file). See the messages libtool
prints while it installs the libraries (1).
The Common library is a set of miscellaneous types and procedures. Some
other bigloo-lib's libraries require it. This library
includes:
Basic Regular Expression support
SRFI-1 support
iconv (code set conversion utility) support
C runtime crypt() support
Rudimentary Common Lisp formatting
UNIX locale support
md5 support
UNIX operation system selected calls
random number generation
limited srfi-13 support
C runtime time-related functions support
At the moment, the stuff was selected based only on my own practical
needs in course of working on some Web-related projects. By this reason,
the library is not (and probably never will be) completed.
Also, though a few Bigloo procedures are re-implemented in this library,
in no case this library replaces the Bigloo runtime library.
This section describes the regex module, which provides an
interface to C runtime regex functions.
The regex module is optional, i.e. you can disable its
compilation by using --without-regexp flag for
configure. Or the configure may detect that regexps are
broken on your system and disable this feature automatically.
To let you detect whether you have regexps from inside the
interpreted code, the 'regexp symbol is defined through the
register-eval-srfi! construct, so you can test it with
cond-expand. For example, the common library test script
conditionally includes the regexp-test call:
(cond-expand (regexp (regexp-test))
(else (print "regexps are disabled by configure")))
regexp constructor. Allocate regexp object and compile the
string given in str argument into regular expression object. Raise
an exception if something goes wrong during the compilation.
The optional flags arguments may be any of the
following symbols (see regcomp manual page) :
basic
Use POSIX Basic Regular Expression syntax when interpreting regex. If
not set, POSIX Extended Regular Expression syntax is used. See manual
page regex(7) for details.
icase
Do not differentiate case. Subsequent regexec searches using this
pattern buffer will be case insensitive (2).
nosub
Support for substring addressing of matches is not required. The list
resulted from successful match will be always empty. Use it if you just
want to know if match found or not, not the matched substring or
substrings.
newline
Match-any-character operators don't match a newline.
A non-matching list ([^...]) not containing a newline does not match
a newline.
Match-beginning-of-line operator (^) matches the empty string
immediately after a newline, regardless of whether eflags, the
execution flags of regexec, contains notbol.
Match-end-of-line operator ($) matches the empty string immediately
before a newline, regardless of whether eflags argument of
matching function contains noteol.
procedure:regexp-matchrexp-or-string str::bstring #!optional offset::int eflags::regexec-flags => #f or pair
Return #f if string str does not match
pattern. Otherwise return the list object. Unless the nosub
flag was given, the list has at least one element, the whole match
substring found. The rest elements are partial sub-matches. The
pattern argument must be either regexp or scheme string. In
later case pattern is compiled into temporary regexp object,
which is automatically released.
The optional eflag arguments may be any of the following symbols
:
notbol
The match-beginning-of-line operator always fails to match (but see the
compilation flag newline above). This flag may be used when
different portions of a string are passed to regexec and the beginning
of the string should not be interpreted as the beginning of the line.
noteol
The match-end-of-line operator always fails to match (but see the
compilation flag newline above)
(define rexp(regexp "^qwerty"))
(regexp-match rexp "qwerty") ;; BOL matches as usual
=> ("qwerty")
(regexp-match-positions rexp "qwerty" 0 'notbol)
=> #f ;; BOL match suppressed
procedure:regexp-match-positionspattern rexp-or-string str::bstring #!optional offset::int => #f or pair
Same as regexp-match, but returns the matched substrings position
inside the source string instead of substrings itself, for example:
This section describes the mzcompat module, which provides a few
procedures to reuse the code written for MzScheme interpreter.
The mzcompat module is optional and is disabled by default. To
enable, call configure with --with-compat.
To let you detect whether you have mzcompat module included
from inside the interpreted code, the 'mzscheme-compat symbol is
defined through the register-eval-srfi! construct, so you can
test it with cond-expand. For example, the common library
test script conditionally includes the regexp-test call:
(cond-expand (mzscheme-compat (mzscheme-test))
(else (print "MzScheme compatibility is disabled by configure")))
macro:case-lambdapatterns
The simple analog of match-lambda construction. Expands to
lambda-functions with variable number of arguments. The execution flow
depends on number of arguments only only.
Example:
(define print-args
(case-lambda
(()
(print "no args given"))
((a)
(print "one argument only: " a))
(args
(print "a number of arguments is: "(length args)))))
(print-args)
-| no args given
(print-args 'one)
-| one argument only: ONE
(print-args 'one 'two 'three)
-| a number of arguments is: 3
Creates a closure, which being called without arguments returns the
value value, being called with one argument, sets the variable
value to new value. If filter argument of type
procedure is provided, the new value is passed to that procedure,
and procedure return is stored in value variable.
(define my-value (make-parameter 0))
=> #<procedure:400edad0.-1>
(my-value)
=> 0
(my-value 1)
(my-value)
=> 1
;; the following procedure always converts its argument
;; to string before remembering it
(define my-string-value
(make-parameter
""
(lambda(o)
(cond((string? o)
o)
((number? o)
(number->string o))
(else(error "my-string-value" "invalid argument"o))))))
(my-string-value 1)
(pp(my-string-value))
-| #"1"
In MzScheme parameters have their own type and are scoped to
execution threads. Since Bigloo does not provide multi-threading, in
Bigloo parameters are just procedures.
Construct the directory name from path elements chunks. Each chunk
may be the path by itself, i.e. include the slash character. Chunk
should not start with slash character, i.e. all sub-paths must be
relative.
Bigloo-lib provides a limited support for string-lib, the
SRFI-13 string library. The limitations are as follows:
The implementation is currently based on SRFI-13 draft as of 2000/4/30;
No charsets involved;
All string comparisons and case-sensitivity issues are locale-dependent,
as opposed to SRFI document;
unimplemented procedures: string-compare,
string-compare-ci (really I did not understand the specification).
The rest of this chapter is based mostly on original SRFI document,
copyrighted by Olin Shivers. The original SRFI documnet copyright
statement you will find at the end of the chapter.
start and end parameters are half-open string indices
specifying a substring within a string parameter; when optional, they
default to 0 and the length of the string, respectively. When specified,
it must be the case that 0 <= start <= end <=
(string-length S), for the corresponding parameter s. They
typically restrict a procedure's action to the indicated substring.
A pred parameter is a unary character predicate procedure, returning a
true/false value when applied to a character.
A char/char-set/pred parameter is a value used to select/search for a
character in a string. If it is a character, it is used in an equality
test; if it is a character set, it is used as a membership test; if it
is a procedure, it is applied to the characters as a test predicate.
An i parameter is an exact non-negative integers specifying an index
into a string.
len and ncharsparameters are exact non-negative integers specifying a
length of a string or some number of characters.
Passing values to procedures with these parameters that do not satisfy these
types is an error.
procedure:string-everypred::procedure s::string #!optional start end
Checks to see if predicate pred is true of every character in S,
proceeding from left (index start) to right (index end).
If STRING-EVERY returns true, the returned true value is the one
produced by the final application of pred to S[end]. If
STRING-EVERY is applied to an empty sequence of characters, it simply
returns #t.
procedure:string-anypred::procedure s::string #!optional start end
Checks to see if predicate pred is true of any character in S,
proceeding from left (index start) to right (index end).
If STRING-ANY returns true, the returned true value is the one produced
by the application of pred.
proc is an integer->char procedure. Construct a string of
size len by applying proc to each index to produce the
corresponding string element. The order in which proc is applied
to the indices is not specified.
Example:
(string-tabulate (lambda(i)(integer->char(+fx i 32))) 20)
=> " !\"#$%&'()*+,-./0123"
procedure:string->lists::bstring #!optional start end => pair-nil
string->list returns a newly allocated list of the characters
that make up the given string. list->string returns a newly
allocated string formed from the characters in the list
char-list, which must be a list of
characters. string->list and list->string are inverses so
far as equal? is concerned.
string->list is extended from the R5RS definition to take optional
start/end arguments.
An efficient implementation of (compose string->list reverse):
(reverse-list->string '(#\a #\B #\c))
=> "cBa"
This is a common idiom in the epilog of string-processing loops
that accumulate an answer in a reverse-order list. (See also
reverse-string-concatenate for the "chunked" variant.)
This procedure is a simple unparser - it pastes strings together using
the delimiter string.
The grammar argument is a symbol that determines how the delimiter is
used, and defaults to 'infix.
'infix
means an infix or separator grammar: insert the delimiter
between list elements. An empty list will produce an empty string --
note, however, that parsing an empty string with an infix or separator
grammar is ambiguous. Is it an empty list, or a list of one element,
the empty string?
'strict-infix
means the same as 'infix, but will raise an error if given an
empty list.
'suffix
means a suffix or terminator grammar: insert the delimiter
after every list element. This grammar has no ambiguities.
'prefix
means a prefix grammar: insert the delimiter
before every list element. This grammar has no ambiguities.
The delimiter is the string used to delimit elements; it defaults to
a single space " ".
procedure:string-copys::bstring #!optional start end => bstring
string-copy is extended from its R5RS definition by the addition of
its optional start/end parameters. In contrast to SUBSTRING/SHARED,
it is guaranteed to produce a freshly-allocated string.
Use string-copy when you want to indicate explicitly in your code that you
wish to allocate new storage; use SUBSTRING/SHARED when you don't care if
you get a fresh copy or share storage with the original string.
procedure:substring/shareds::bstring #!optional start end => bstring
substring/shared returns a string whose contents are the characters of s
beginning with index start (inclusive) and ending with index end
(exclusive). It differs from the R5RS substring in two ways:
The end parameter is optional, not required.
substring/shared may return a value that shares memory with s or
is eq? to s.
Example:
(let((s "Beta substitution"))
(eq?(substring/shared s 0)s))
=> #t
procedure:string-copy!target::bstring tstart s #!optional start end => bstring
Copy the sequence of characters from index range
(start,end) in string s to string target,
beginning at index tstart. The characters are copied
left-to-right or right-to-left as needed -- the copy is guaranteed to
work, even if target and s are the same string.
It is an error if the copy operation runs off the end of the target
string, e.g.
(string-copy! (string-copy "Microsoft") 0
"Regional Microsoft Operating Companies") error-->
Note: though the result of string-copy! is defined as unspecified
by SRFI document, the implementation always returns the target argument.
If this procedure produces the entire string, it may return either
s or a copy of s; in some implementations, proper
substrings may share memory with s.
Example:
(string-take "Pete Szilagyi" 6) => "Pete S"
It is an error to take more characters than are in the string:
If this procedure produces the entire string, it may return either
s or a copy of s; in some implementations, proper
substrings may share memory with s.
Example:
(string-drop "Pete Szilagyi" 6) => "zilagyi"
It is an error to drop more characters than are in the string:
If this procedure produces the entire string, it may return either
s or a copy of s; in some implementations, proper
substrings may share memory with s.
Example:
(string-take-right "Beta rules" 5) => "rules"
It is an error to take more characters than are in the string:
string-drop-right returns all but the last ncharsof s.
If this procedure produces the entire string, it may return either
s or a copy of s; in some implementations, proper
substrings may share memory with s.
Example:
(string-drop-right "Beta rules" 5) => "Beta "
It is an error to drop more characters than are in the string:
(string-drop-right "foo" 37) error-->
procedure:string-pads::bstring len::int #!optional char start end => bstring
Build a string of length len comprised of s padded on the
left by as many occurrences of the character char as needed. If
s has more than len chars, it is truncated on the left to
length len. char defaults to #\space.
If len <= end - start, the returned value is allowed to share
storage with s, or be exactly s (if len = end -
start).
procedure:string-pad-rights::bstring len::int #!optional char start end => bstring
Build a string of length len comprised of s padded on the
right by as many occurrences of the character char as needed. If
s has more than len chars, it is truncated on the right to
length len. char defaults to #\space.
If len <= end - start, the returned value is allowed to share
storage with s, or be exactly s (if len = end -
start).
procedure:string-trims::bstring #!optional char/char-set/pred start end => bstring
The string-trim, string-trim-right,
string-trim-both procedures trim s by skipping over all
characters on the left / on the right / on both sides that satisfy the
second parameter char/char-set/pred:
if it is a character char, characters equal to char are
trimmed;
If it is a char set cs, characters contained in cs are
trimmed;
If it is a predicate pred, it is a test predicate that is applied
to the characters in s; a character causing it to return true is
skipped.
char/char/set-pred defaults to the character set
char-set:whitespace defined in SRFI-14.
If no trimming occurs, these functions return s.
Example:
(string-trim #" The outlook wasn't brilliant, \n\r")
=> #"The outlook wasn't brilliant, \n\r"
procedure:string-trim-rights::bstring #!optional char/char-set/pred start end => bstring
See description of string-trim.
Example:
(string-trim-right #" The outlook wasn't brilliant, \n\r")
=> #" The outlook wasn't brilliant,"
procedure:string-trim-boths::bstring #!optional char/char-set/pred start end => bstring
See description of string-trim.
Example:
(string-trim-both #" The outlook wasn't brilliant, \n\r")
=> #"The outlook wasn't brilliant,"
These procedures are the lexicographic extensions to strings of the
corresponding orderings on characters. For example, STRING< is the
lexicographic ordering on strings induced by the ordering CHAR<? on
characters. If two strings differ in length but are the same up to the
length of the shorter string, the shorter string is considered to be
lexicographically less than the longer string.
The optional start/end indices restrict the comparison to the indicated
substrings of s1 and s2.
string-ci=, string-ci<>, string-ci<,
string-ci>, string-ci<= and string-ci>= procedures
are case-insensitive variants of string=, string<>,
string<, string>, string<= and string>=
correspondingly.
Comparison is simply done on individual code-points of the string.
True text collation is not handled by this SRFI.
Case-insensitive comparison is done by case-folding characters with
the operation
(char-downcase (char-upcase c))
Test if s1 string is greater than or equal to s2 string
case-insensitive. See notes at the beginning of this section.
procedure:string-hashs::bstring #!optional bound start end => int
Compute a hash value for the string s. bound is either
#f or a non-negative exact integer. If an integer, it gives the
target range of the hash function -- the returned value will be in the
range [0,bound].
If bound is either #f or not given, the implementation may use
an implementation-specific default value, which might be chosen,
for instance, to map all strings into the range of integers that
can be efficiently represented.
The optional start/end indices restrict the hash operation to the
indicated substring of s.
procedure:string-prefix-lengths1::bstring s2::bstring #!optional start1 end1 start2 end2 => int
Return the length of the longest common prefix of the two strings.
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.
procedure:string-suffix-lengths1::bstring s2::bstring #!optional start1 end1 start2 end2 => int
Return the length of the longest common suffix of the two strings.
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.
procedure:string-indexs::bstring char/char-set/pred #!optional start end => int or #f
string-index searches through the string from the left, returning
the index of the first occurrence of a character which
equals char/char-set/pred (if it is a character);
is in char/char-set/pred (if it is a character set);
satisfies the predicate char/char-set/pred (if it is a procedure).
If no match is found, the functions return #f.
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. The first index considered is end-1.
Example:
=>
procedure:string-index-rights::bstring char/char-set/pred #!optional start end => int or #f
string-index-right searches through the string from the right,
returning the index of the first occurrence of a character which
equals char/char-set/pred (if it is a character);
is in char/char-set/pred (if it is a character set);
satisfies the predicate char/char-set/pred (if it is a procedure).
If no match is found, the functions return #f.
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. The first index considered is start.
Example:
=>
procedure:string-skips::bstring char/char-set/pred #!optional start end => int or #f
The string-skip functions is similar to string-index, but
uses the complement of the criteria: is searches for the first char that
*doesn't* satisfy the test. E.g., to skip over initial whitespace, say
(cond ((string-skip s char-set:whitespace) =>
(lambda (i)
;; (string-ref s i) is not whitespace.
...)))
procedure:string-skip-rights::bstring char/char-set/pred #!optional start end => int or #f
The string-skip-right functions is similar to
string-index-right, but uses the complement of the criteria: is
searches for the first char that *doesn't* satisfy the test.
procedure:string-counts char/char-set/pred #!optional start end
The mmap procedure asks to map length bytes starting at
offset offset from the file (or other object) specified by fd into
memory.
length::int
The number of bytes to map. Since the mmap result is returned in
form of Bigloo bstring, the length really passed to libcmmap() includes the bstring object overhead too.
#!key fd
Descriptor of file to map. Since the result always includes the overhead
of bstring object, this mmap implementation is practical
useless if you want to map anything but dummy devices such a
/dev/zero.
If fd argument is omitted, the /dev/zero device is used to
get a file descriptor.
#!key prot
List of protection flag symbols. The valid values are:
exec
Pages may be executed.
read
Pages may be read.
write
Pages may be written.
none
Pages may not be accessed.
#!key flags
List of mmap options. The valid values are fixed,
shared and private. The values denywrite,
executable and anonymous are also valid but have no effect
on systems other than Linux. See the mmap manual pages for
details.
#!key offset
Byte offset from beginning of file to be mapped.
This procedure may be useful if you want to temporary allocate the huge
amount of memory which should be released and returned to operating
system. Besides, the memory allocated with mmap is not accessed
until you really use it, so the allocation is very fast.
In the following example we will illustrate this feature. First we
measure how much memory the application process consumes, using the
ps command:
bash$ ps u 17012
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COM
wowa 17012 2.1 5.7 7108 2236 ttyp4 S 20:32 0:00 /us
Then we mmap 16M of memory:
(define mem (mmap #x1000000))
As we may expect the process virtual memory increases now by 16M:
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COM
wowa 17012 0.1 5.8 23496 2260 ttyp4 S 20:32 0:00 /us
Now we do the unmap:
(munmap mem)
And measure the process memory again:
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COM
wowa 17012 0.0 5.7 7108 2252 ttyp4 S 20:32 0:00 /us
procedure:munmapmem::bstring
Release memory mapped by mmap.
procedure:statwhat => stat
Return information about the specified file. The argument what
should be either the name of the file or open file descriptor.
The result is of type stat, for which the following read accessor procedures are defined:
st-mode
file protection mode. See open procedure description.
Open file name file-name, return the integer file descriptor.
The optional oflag arguments may be any of the following symbols:
rdonly, wronly, rdwr, append,
nonblock, creat, trunc, excl or
noctty. See open(2) manual page for the meaning of the
flag values.
Close a file descriptor, so that it no longer refers to any file and may
be reused.
procedure:fdreadfd::int size::long => bstring
Read the specified number of bytes size using the open file
descriptor fd by calling libcread() function.
procedure:fdwritefd::int str::bstring => int
Try to write the str to specified file descriptor. Return the
number of bytes really wrote.
procedure:getppid=> int
getppid returns the process ID of the parent of the current
process.
procedure:getpid=> int
getpid returns the process ID of the current process. (This is
often used by routines that generate unique temporary file names.)
procedure:getlogin=> bstring or #f
The getlogin procedure returns a pointer to the login name as
found in /var/adm/utmp. It may be used in conjunction when the
same user ID is shared by several login names. See getlogin(3c)
manual page for details.
If getlogin is called within a process that is not attached to a
terminal, it returns #f. In later case use the cuserid
procedure instead.
As example of how the getlogin works, we first run the utility
from non-terminal xemacs window, and then from the rlogin
shell:
bigloo-common
1:=> (getlogin)
=> #f
1:=>
bash-2.03$ rlogin localhost
Password:
Last login: Thu May 4 15:19:55 from localhost
bash-2.03$ bigloo-common
bigloo-common
1:=> (getlogin)
(getlogin)
=> wowa
1:=>
bash-2.03$
procedure:getpwnamwhat::symbol #!optional name => #unspecified
The getpwnam procedure is used to obtain password entries. The what arguments controls which entry will be returned by the procedure. The valid values of what are:
name
user's login name (string)
uid
user's uid (integer)
gid
user's gid (integer)
gecos
typically user's full name (string)
dir
user's home dir (string)
shell
user's login shell (string)
The optional name argument may be integer user ID or string user
name of the user in question. If omitted, the name of current user as
returned by cuserid is used.
The cuserid procedure generates a character-string representation
of the login name under which the owner of the current process is logged
in.
(cuserid)
=> wowa
procedure:strxfrmsrc::bstring => bstring
The strxfrm procedure transforms the src string into a
form such that the result of memcmp on two strings that have been
transformed with strxfrm is the same as the result of
locale-sensitive string-comparing procedures (string=?,
string<? etc.) on the two strings before their
transformation. (See setlocale).
crypt(3) is the password encryption function. It is based on the Data
Encryption Standard algorithm with variations intended (among other
things) to discourage use of hardware implementations of a key search.
passwd is a user's typed password.
salt is a two-character string chosen from the set [a-zA-Z0-9./].
This string is used to perturb the algorithm in one of 4096 different
ways.
This section describes the interface to iconv - a set of
libc functions for character set conversion. See iconv(3)
manual page for details.
The iconv module is optional, i.e. you can disable its
compilation by using --without-iconv flag for
configure. Or the configure may detect that your
libc does not have iconv functions and automatically
disable this feature.
To let you detect whether character conversion is supported by the
library from inside the interpreted code, the 'iconv symbol is
defined through the register-eval-srfi! mechanism, so you can
check it with cond-expand.
foreign type:iconv
The structure holding the information about the source and target
character sets and current state of conversion.
The iconv-open procedure returns a conversion descriptor that
describes a conversion from the codeset specified by the fromcode
argument to the codeset specified by the tocode argument. For
state-dependent encodings, the conversion descriptor will be in a
codeset-dependent initial shift state, ready for immediate use with the
iconv procedure.
The iconv procedure converts the sequence of characters from one code
set, in the array specified by src, into a sequence of corresponding
characters in another code set, in the return string. The
code sets are those specified in the cd argument.
This section describes types and procedures, dealing with time. They let
you measure calendar and UNIX process time, print time using locale
settings, and also do some arithmetics with times and dates.
foreign:tm
A wrapper for C library struct tm structure, broken-down time
representation.
The following read accessors are defined:
tm-tm-sec
The number of seconds after the minute, normally in the range 0 to 59,
but can be up to 61 to allow for leap seconds.
tm-tm-min
The number of minutes after the hour, in the range 0 to 59.
tm-tm-hour
The number of hours past midnight, in the range 0 to 23.
tm-tm-mday
The day of the month, in the range 1 to 31.
tm-tm-mon
The number of months since January, in the range 0 to 11.
tm-tm-year
The number of years since 1900.
See also strftime procedure description to print these objects in
human-readable form.
procedure:make-tm=> tm
Allocate an uninitialized object of type tm. This procedure is
used internally by other time-manipulation procedures. Perhaps, you do
not want to call it explicitly.
Interface for C runtime gmtime call. Take number of seconds
elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time
(UTC), and convert it to broken-down time representation, expressed in
Coordinated Universal Time (UTC).
Same as gmtime, but the result is expressed relative to the user's
specified time zone.
The procedure also sets the values returned by tzname and
timezone and daylight.
procedure:timezone=> int
Return number of seconds west of UTC. For example, here in Moscow:
(timezone)
=> -10800
(/ (timezone) 3600)
=> -3
procedure:tzname=> 2 scheme values
Return names of time zone as two scheme values. See tzset manual
pages for details. The values are also set by localtime. For
example:
(define(tzprint)
(multiple-value-bind
(name name1)
(tzname)
(print name ", " name1)))
(tzprint)
(localtime 0.0) ;; this call for side effects only
(tzprint)
=> GMT, GMT
MSK, MSD
procedure:daylight=> bool
A flag that indicates whether daylight saving time is in effect at the
time described. Return positive value if daylight saving time is in
effect, zero if it is not, and negative value if the information is not
available.
The strftime procedure formats the broken-down time tm
according to the format specification. If format argument is
omitted, the "%x %X" string is used to format output. See
strftime manual pages for details.
Read date/time from port port using the specification
fmt. The format of the specification is a subset that of
strftime specification (only %S, %M, %H,
%I, %d, %m, %Y, %p and %%
escape sequences are supported).
The times procedure measures various time-accounting information.
Depending on value of argument which? of symbol type it
returns the following values:
utime
User time
stime
System time
cutime
User time of children
cstime
System time of children
If argument which? is absent, the times procedure returns
five scheme values: the number of clock ticks that have elapsed since
the system has been up, and all the values just described,
i.e. utime, stime, cutime and cstime.
All the values are measured in system clock ticks. The length of one
tick is system-dependent. Number of clocks per second may be obtained by
calling clocks-per-second procedure.
Examples:
Here number of system clock ticks from the system start-up is measured:
(times)
=> 1720216
The same value but now in seconds:
(/(times)(clocks-per-second))
=> 17340.09
The following example is a complete utility that measures the external
process times.
The initial times are measured and stored in local variables
total, cutime and cstime, external process is spawned
using bigloo run-process procedure See Info file `bigloo', node `Process support'. After the spawned process is finished, the statistics is
printed to standard error port in form similar that of Unix time
utility.
cgen allows you to create wrappers for external C functions and
external C types, such as structures, enums, bit fields and opaque
pointers.
cgen comes to you with bigloo-lib, and is automatically
created before any bigloo-lib library is creates. All the
external C interfaces in bigloo-lib are created with help of
cgen.
In course of evaluation of the foreign interface, I found it not very
suitable for the following reasons :
Too much code is usually auto-generated for every C declaration. Though
most of generated functions are declared as inline, their body is
copied into every module that uses it
The way the foreign types are supported is compiled into the Bigloo
compiler. You cannot change a bit in it without rebuilding Bigloo
executable. Even more, Bigloo documentation does not describes, how to
rebuild Bigloo if you change its scheme sources. cgen is, on the
other hand, quite simple and open-ended. It is not hard to make it to do
anything you like without risk to broke the whole compiler.
The outcome of cgen is readable scheme text. When something goes
not as expected, you can easily check that's going on. Bigloo, in its
turn, does the same thing in course of compilation: it creates the
low-level scheme type expressions to be compiled, but it never reveals
the generated code to the programmer.
cgen was developed in hope to achieve the following goals :
Get more flexible control over that stuff has to be build and that has
not. For example, cgen creates write accessor for C structure
slots only if you specify that directly.
Create more natural interfaces to C enums -- enum values presented as
scheme symbols in cgen-generated functions.
Write interfaces to bit fields. Bit fields are presented in scheme in
form of lists of symbols.
Support of C null pointers. The null pointers are converted to scheme
#f value.
Write GTK+ interface section GTK+ interface compatible with guile-gtk
(http://www.gtk.org). Using the interface specifications from
guile-gtk saved me much of work. The main idea and specification
file format came from guile-gtk also.
Create first-class Bigloo procedures, i.e. they are exported
automatically and may be evaluated in interpreter.
Debug the auto-generated text: temporary insert printing commands, use
Bigloo debugger etc..
On the other hand, Bigloo has excellent capabilities of creating any new
types, using the type and coerce statements in module
declaration. The only bad thing with it is that these capabilities are
not documented at all (though the documented extern type
interface is based upon that low-level layer).
cgen work is based upon these capabilities and it is alternative
to Bigloo foreign interface.
cgen is a preprocessor for bigloo scheme code. It takes one or
more files with C interface specification as input and produces the
readable scheme file on output. The specification itself is bigloo
scheme text with some special constructs. As result of processing this
constructs the new procedures and bigloo module declarations are
created. All other scheme expressions are printed back into output
without changes.
All the cgen input files have extension .defs in
bigloo-lib, you may use it as cgen usage examples.
Note that the current directory is automatically added to search path
only if no any -I option is given. Also note the required space
between the -I and filename.
no backups (suffixed by tilde char) are created anymore (4)
no files are changed if the old target file exists and the contents of
new file and an old one are effectively same. This feature significantly
reduces the stuff that should usually be recompiled due to that
compilation of scheme sources formally depends on this file contents
The RDBMS library is a set of miscellaneous types and procedures,
allowing to access SQL databases from Bigloo application. The library
has two layers: generic RDBMS system interface, implemented as small set
of Bigloo classes, and set of back-ends, which provide the implementation
in form of concrete class methods.
Usually the end-user application relies on generic API only, thus
allowing to use different RDBMS system without changing a line in
application code.
Currently the support for MySQL included. ODBC and INFORMIX support will be added in near future.
In this section specific for database driver types of
objects are described. These types also are used in Scheme function
prototypes declarations.
Bigloo class:connection
The objects of connection type describe the database
connections.
Bigloo class:session
The objects of session type hold the data used
in process of executing of SQL statements (the statement
string, input and output bindings and state of execution).
Every session belongs to only one
connection.
Bigloo class:transaction
Theoretically, transactions are entities, which synchronize changes made
in database through one or more connections. At the moment, there is
no separate class for transaction objects (5).
This procedure creates and opens new database connection. The
dbname is path to database (system specific string). The
username and password are sometimes optional, if the
underlying implementation allows use default values for them.
Instead every RDBMS implementation should supply its own version of
connection-creation procedure. Prefix RDBMS in
RDBMS-connect states for the name of implementation, for example,
the name of procedure, that opens the MySQL connection, will be
mysql-connect(6).
Method: connection dismiss!
This destroys the connection, and releases all connection's
resources (7)
Method: rdbms-object error-string=> string
Abstract method of error string obtaining. RDBMS connections and
sessions may provide their own implementations.
Method: connection begin-transaction!=> bool
This begins the transaction for connection. If
transaction are not supported by underlying RDBMS, #f is
returned.
Method: connection commit-transaction!
This method closes the transaction for connection(8).
Method: connection rollback-transaction!
This ends the transaction, revert all changes made since transaction's
beginning (9).
Method: connection acquire=> session
This creates new session for the given connection.
(10).
Cancel the query answering process, if any, make the
session ready for executing.
Method: session dismiss!=> #unspecified
This destroys the session object and releases all the
session's resources
Method: session execute=> bool
This executes previously prepared statement. If the answer set
is implied by statement, then the answer stream
is opened and #t is returned. Otherwise #f is returned.
Method: session preparesql::bstring => bool
This prepares the SQL query text string for execution. The
position of optional parameters is marked up with question
mark sign. Returns same result as has-answer? method.
Method: session bind!bindings::pair-nil
This supplies the parameter values needed by previously prepared
SQL statement. All the `question marks' in statement are
subsequently substituted by vector elements.
Method: session has-answer?=> bool
This answers #t if the answer set is implied by prepared
statement (usually if the statement is of SELECT type).
Method: session fetch!=> pair-nil
Fetch next record from the query answer stream and return it in form of
scheme list object, or scheme null, if end of answer
stream is reached.
Method: session describe=> pair-nil
Get result set description as scheme list. Generally the format
of result is system-dependent, but usually each column descriptors
contains the following information:
name of column (string)
type id (integer, system-dependent)
length (integer, system-dependent)
nullable? (are NULL values allowed?)
For details see the documentation, supplied with particular implementation.
In the following example, the connection with MySQL database
named dept is established. Next, the table named person
with columns named id, last_name and first_name is
created and a few records inserted into the table. The contents of the table
is retrieved back then and displayed. After that, the table is
destroyed.
The special class named rdbms-error is created for dealing with
database exceptions. The instances of that class provide the application
with (system-specific) error code and error message (11).
Abstract bigloo class, the base class for tree node objects. Each node
may have a number of named attributes. The attribute names are symbols,
the values are usually strings. All the functionality provided as a set
of generic procedures, the base node class objects do not hold any data.
Add the attribute named attname and value attvalue to node
self. The generic procedure modifies the node attribute list
using the node-atts-set! method.
Remove the attributes of node self with name attname. If
optional arguments attvalues are specified, only the attributes which
values are within the attvalues list are removed.
Remove the attributes of node self with name attname. If
optional arguments attvalues are specified, add new attributes
with name attname and values attvalues. Otherwise the
procedure effect is equivalent to that of node-remove-attribute!.
Insert child node child into list of node self children. If
the concrete implementation supports ordering of the children, the
optional after argument may be specified, to define the node
insertion position. The generic procedure uses node-children-set!
to do the insertion.
Insert node self into the tree. The parent node is
registered in self's parent list. The self node prepended
to all parent's children lists using node-add-child!.
Return either the node immediately following self in sibling list,
or the node following parent node of self, if self is the
last node in the list of siblings.
The concrete tree implementation may supply the mechanism for naming
tree nodes to let the node be found given the path string is known. The
described here naming scheme is based upon LDAP entries naming and used
basically by LDAP library See section Bigloo LDAP interface.
Every node has its own Relative Distinct Name (RDN), which must be
unique between node siblings. The node RDN along with RDNs of node
ancestors form the full node path, which is called Distinct Name
(DN). The DN is result of string concatenation of node RDN and RDNs of
node ancestors, delimited by comma character.
This module provides the generic procedures for getting and setting node
DNs and RDNs along with useful procedures for parsing DN strings.
abstract procedure:node-rdnself::node => bstring
Return the RDN (Relative Distinct Name) of node. The RDN must be unique
between node siblings. This method should be redefined in concrete
subclasses.
Change the RDN of the node self. Using of optional
deleteatt? is specific for LDAP node implementation only.
generic procedure:node-dnself::node => bstring
Get the DN (Distinct Name) if the node self. The generic function
constructs DN by concatenating the RDN's of all the ancestors of the
node, beginning with the node self itself, delimited by comma
character. This procedure is relevant mostly for LDAP nodes.
Some of classes derived from node class are assumed to redefine
this method. The generic implementation concatenates the strings
obtained by applying node-data to all the children of self.
See the examples in sgml-node description.
procedure:current-node#!optional value
current-node is parameter procedure See section Bigloo Common Library. Plays the role of global variable to store current position in
any tree of nodes in end user applications. This procedure is defined
for convenience only, none of the library functionality relies on it.
generic procedure:node-titleself::node => bstring
Node printed name. It is assumed that subclasses provide its own
implementation. By default try the value of cn attribute or uses
bigloo class name of the node.
xml2expat is a tool which converts XML text to Bigloo object file
format. It is useful, for example, when working with XML templates to
produce dynamic HTML pages or in any similar situation when all the XML
files are known at the compilation time, so you do not need to add the
XML support into you application.
This chapter describes the interface for GTK+, the Open Source
Free Software GUI Toolkit, primarily developed for use with the X Window
System. The most detailed information about GTK+ may be found at
http://www.gtk.org.
The interface is designed after the popular guile-gtk analog, the
GTK+ interface for using with guile scheme
implementation. My intention was to make the interface as compatible
with that of guile-gtk as possible in order to utilize the
tutorials, examples and other software written for guile-gtk.
For generation of multiple interfaces to GTK+ functions the
cgen utility was developed See section cgen - bigloo preprocessor, which was used to process
the specification of GTK+ interface found in guile-gtk.
Since the main goal of GTK+ is to provide a graphical user interface, it
is practically impossible to test it automatically. Instead, a test
application was derived from analogous program provided with GTK+ (file
gtk/testgtk.c in GTK+ distribution) and guile-gtk.
Also this application may be used as a source of examples how to use
bigloo-gtk.
The testgtk is port of testgtk.c provided with GTK+
distribution, to bigloo-gtk. Initially is was derived from
testgtk.scm provided with guile-gtk. Now most of the text
is redesigned, many tests made more up-to-date than the corresponding
guile-gtk analogs.
All the original tests testgtk.c from latest GTK+ distribution
are listed in main testgtk window, labels for whose that are
still unimplemented are grayed.
The simplest way to run the testgtk is to process its source code
by bigloo-bgtk driver program:
bigloo-bgtk ./testgtk.defs
but to make all the tests work, you probably have to compile and run binary
executable:
Bigloo-gtk provides a small set of examples, derived from whose
provided in "GTK+ Tutorial". You'll find the examples in
gtk/examples/ subdirectory. All the examples are shell scripts,
though may be compiled. You need to install the package before running
this examples.
Currently this reference guide of very far from completeness. Only
selected calls are documented. Look at working tests code in
testgtk.defs for example.
The gdk-color-parse procedure looks up the string name of a
color, given in spec argument, with respect to the screen
associated with the default colormap. On return it initializes the
object given in a color argument with the exact color value. Use
of uppercase or lowercase does not matter. If the color is not
specified, the new instance of type gdk-color is allocated
through gdk-color-alloc. If the color name is not resolved, an
exception is raised.
Every type in GTK+ is given an unique identifier. These identifiers have a type named gtk-type (they are sequential integers really).
A few numbers are preassigned to built-in GTK+ types (such an integers,
strings, booleans etc.). All other type ids are allocated along with the
first instance of that type.
procedure:gtk-type-nametype::gtk-type => string
Get the GTK+ name of an existing type.
Note: the name returned is a GTK+ name, not a Bigloo type name, i.e. the
value "GtkButton" will be returned for buttons, but not
"gtk-button".
Get GTK+ object class reference by instance. The gtk-object-class
structures may be useful for introspection purposes only (to inspect
object signals etc.).
procedure:gtk-signal-emit-stopobject::gtk-object signal
Stop the emission of the signal on object. signal is
the string signal name or the integer identifier for the signal, which
can be determined using the function
gtk-signal-lookup. Attempting to stop the emission of a signal
that isn't being emitted does nothing.
Disconnects a signal handler from an object. The signal handler is
identified by the integer id which is returned by the
gtk-signal-connect function.
Example: disable the button action after the first invocation.
(letrec((but(gtk-button-new "Hello"))
(signal-id
(gtk-signal-connect
but "clicked"
(lambda args
(print "Hello, World")
(gtk-signal-disconnect but signal-id)))))
...)
procedure:gtk-signal-emitobject::gtk-object signal arguments::pair-nil
Emit the signal specified by the integer or string identifier signal
from object. The signal
definition determines the parameters passed in the arguments list.
Connects a signal handling function to a signal emitting
object. function is connected to the signal name emitted by
object. The arguments and returns type of func should match
the arguments and return type of the signal name.
gtk-signal-connect returns an integer identifier for the
connection which can be used to refer to it in the future. Specifically
it is useful for removing the connection and/or blocking it from being
used.
Example: connect a click handler to a button. Being invoked, handler
prints a message and disconnects itself.
Create a new signal and give it the character string identifier
name. name needs to be unique in the context of
object-type's branch of the class hierarchy. That is,
object-type cannot create a signal type with the same name as a
signal type created by one of its parent types.
run-type specifies whether the class function should be run before
('first), after ('last) or both before and after normal
signal handlers ('both). Additionally, the 'no-recurse
value can be specified to specify that the signal should not be
recursive. By default, emitting the same signal on the same widget will
cause the signal to be emitted twice. However, if the 'no-recurse
flag is specified, emitting the same signal on the same widget will
cause the current signal emission to be restarted. This allows the
widget programmer to specify the semantics of signal emission on a per
signal basis. (The 'no-recurse flag is used by the
gtk-adjustment widget).
The return-val and the remaining arguments
specify the return value and the arguments to the signal handler
respectively.
Note: There is an implicit first argument to every signal
handler which is the widget the signal has been emitted from.
The variable argument list params specifies the types of the
arguments (use gtk-type-from-name to get gtk type
identifiers). It is OK to use (gtk-type-from-name "none") for
return-val. (This corresponds to not returning a value.
gtk-signal-new returns the integer identifier of the newly
created signal. Signal identifiers start numbering at 1 and increase
upwards.
Note:gtk-signal-new is only needed by widget writers. A
normal user of GTK will never needed to invoke this function.
(define button(gtk-button-new))
button
=> #<foreign:GTK-WIDGET:3e330>
(define guint-type(gtk-type-from-name "guint"))
guint-type => 6
(define button-type(gtk-type-from-name "GtkButton"))
button-type => 40469
(gtk-signal-new-generic "print-sum"
'(both)
button-type ;; signal object type
guint-type ;; signal return type
guint-type ;; signal 1st arg type
guint-type ;; signal 2st arg type
)
(gtk-signal-connect button
"print-sum"
(lambda (button n1 n2) (print (+ n1 n2))))
=> 4
(gtk-signal-emit button "print-sum" 2 3)
-| 5
Returns the integer identifier for the signal referenced by name
and type. If type does not define the signal name,
then the signal is looked for in type's parent type recursively.
Create gtk-clist type object with optional titles. There are two methods of calling this procedure.
with one argument of integer type. The value of this argument is the
number of columns in a new clist;
with any positive number of arguments of string type. In this
case the number of columns in the new clist is equal to the
number of arguments, and their values used as column titles.
Note: this procedure obsoletes guile-gtkgtk-clist-new-with-titles procedure.
Example1: create 3-column gtk-clist:
(gtk-clist-new 3)
Example1: create 2-column gtk-clist and set the column titles to
"Column1" and "Column2":
Append a row to clist. The columns parameter should be a
list strings to form a new row. The length of columns should be
equal to the number of columns in clist.
Prepend a row to clist. The columns parameter should be a
list strings to form a new row. The length of columns should be
equal to the number of columns in clist.
parent-menu-shell::gtk-widget
No description. It is safe to use #f.
parent-menu-item::gtk-widget
No description. It is safe to use #f.
callback::procedure
Procedure to explicitly define menu onscreen position. It should return
exactly two scheme integer values: X and Y menu coordinates
Yu'll likely leave it #f to use default positioning.
button::int activate-time::int
The number and time of mouse button pressed if this procedure is called
as result of button press.
In the following example a button is created. Pressing the button pops
up the menu menu. Change the callback value from #f to
menu positioning procedure (commented out in this example), the menu
will appear on screen at X=100, Y=300 position.
procedure:gtk-radio-menu-item-new#!optional group label => gtk-radio-menu-item
Create new gtk-radio-menu-item. The optional group argument
may be either #f or other object of gtk-radio-menu-item type. In
a later case all chained items form a group, ensuring only one item may
be active at a time.
Example. This creates three items in a group:
(let*((one (gtk-radio-menu-item-new #f "One"))
(two (gtk-radio-menu-item-new one "Two"))
(many(gtk-radio-menu-item-new two "Many")))
...)
Init the GTK and GDK environment. You must call this procedure prior
making any other GTK+ call. The argv is the same list of arguments
that were passed to the application. The procedure process some of list
elements and returns the copy of argv with all processed arguments
removed.
Example: provided that localhost:0 is valid address of X display:
Add a thunk procedure that will be called (as GTK+ tutorial says) "when nothing
else is happening". Return the idle identifier suitable for passing to
gtk-idle-remove.
The thunk must be procedure of no arguments. If this procedure
returns #f, the idle task is removed just after the first thunk
invocation.
This chapter describes a scheme interface for client LDAP library. The
interface allows to write LDAP clients with Bigloo scheme. It was tested
with OpenLDAP-1.2.9 package from http://www.openldap.org(12).
The chapter includes many verbatim excerpts from corresponding
original manual pages, describing the C interface, which are provided
with the package from http://www.openldap.org
LDAP server connection handle, resulted from successful call of
ldap-open or ldap-init.
Bigloo type:attlist
List of attribute names and values. LDAP types is a scheme list,
each element of which is a scheme list itself, the first element of
which is an attribute name (scheme string), and the rest of which is
(possibly empty) list of attribute values (scheme strings). For example :
LDAP server hostname string. See ldap_init(3) manual page for details.
port
LDAP server port number. See ldap_init(3) manual page for details.
Allocates an LDAP structure but does not open an initial connection
Return LDAP connection handle of type ldap.
See also ldap_init(3) manual page.
Result of a successful call to ldap-open or ldap-init
ldap-unbind! unbinds from directory, terminates current
association, closes connection and frees resources contained in the
corresponding LDAP structure
procedure:ldap-searchld::ldap #!key base scope filter atts attrsonly?
ld
Result of a successful call to ldap-open or ldap-init
base
Search base DN. System default value used if not specified. See
ldap.conf(5) manual page.
scope
Symbol base or integer 0, to search the object itself, symbol
onelevel or integer 1, to search the object's immediate children,
symbol subtree or integer 2 to get all the object subtree. The
default is subtree.
filter
String representation of the filter to apply. See ldap_search(3)
manual page for details. Default is "objectclass=*".
atts
List of names of LDAP attributes to be shown in search results. If
omitted, all the attributes will be shown.
attrsonly
If true, then search result will have only the names of LDAP attributes (no attribute values).
ldap-search returns integer result LDAP message
id or raises an exception in case of error.
See example in ldap-next-entry.
See also ldap_search(3) manual page.
procedure:ldap-count-entriesld::ldap msg::ldap-message => int
ld
Result of a successful call to ldap-open or ldap-init
LDAP message object, resulted from successful invocation of ldap-result
Return value
ldap-count-entries returns the number of entries in search result
or raises an exception in case of error.
Example :
In this example the total number of entries in LDAP tree is measured :
(let*((ld(ldap-open))
(msgid(ldap-search ld atts: '()));; only DN's, no attributes
(result(ldap-result ld msgid)))
(ldap-count-entries ld result))
Result of a successful call to ldap-open or ldap-init
msgid
Specifies LDAP request id, returned by successful invocation of one of LDAP operation routines (e.g., ldap-search, ldap-modify).
timeout
Optionally specifies the response waiting timeout in seconds. If is not
provided the infinite wait assumed.
This routine is used to wait for and return the result of an
operation previously initiated by one of the LDAP operation
routines (e.g., ldap-search, ldap-modify).
ldap-result returns the result LDAP message or raises an
exception in case of error.
Result of a successful call to ldap-open or ldap-init
Deletes cache contents, but does not effect it in any other way
See also ldap_flush_cache(3) manual page.
procedure:ldap-destroy-cache!ld::ldap
ld
Result of a successful call to ldap-open or ldap-init
Turn off caching and completely remove cache from memory
See also ldap_destroy_cache(3) manual page.
procedure:ldap-disable-cache!ld::ldap
ld
Result of a successful call to ldap-open or ldap-init
Temporarily disables use of cache (new requests are
not cached and cache is not checked when returning
results). It does not delete the cache contents from memory
Result of a successful call to ldap-open or ldap-init
timeout
Timeout in seconds. Used to
decide how long to keep cached requests
maxmem
Cache size limit in bytes. Used to set an upper bound on how much memory
cache will use. You can specify 0 for maxmem to restrict cache size by
the timeout only.
Turns on local caching or changes cache parameters
(lifetime of cached requests and memory used).
Given a result of successful ldap-search operation msgid,
returns the list of LDAP entries. Every element of this list is a result
of cons operation on the DN of the entry, and entry attribute
list in a attlist format.
This example code does essentially same operation as the example code
provided in ldap-next-entry section.
This procedure deletes the LDAP entry along with all descendants of that
entry. Return the entry list just deleted in a form described in
ldap-answer section.
procedure:current-ldap#!optional new-value
Realizes the concept of default LDAP connection. Other procedures use
the result of calling current-ldap procedure as a default LDAP
connection handle.
=>
procedure:ldap-defbase#!optional arg => bstring
Realizes the ldap default base concept according to the following rules:
If no arguments given, and value was previously set, returns this value.
If an argument given, and the argument is a string, store and return that value.
If an argument given, and the argument is a LDAP connection handle, perfor a ldap-search operation without giving a base argument, return the DN of entry returned.
If an argument given, and the value was not previously set, resolve the default base using (current-ldap) as a LDAP connection.
Intellectual LDAP entry update. Reads the LDAP entry, examines the
difference between the old attributes and the new ones. Performs the
appropriate updates: removes the obsolete attributes with the use of
ldap-modify-delete, adds the new attributes using
ldap-modify-add, replaces the attribute values with the use of
ldap-modify-replace.