5. BRL Reference

5.1 String Functions

brl-string

takes an arbitrary number of arguments of any type, and returns a string that is the concatenation of their display representations.

brl-simple-date-formatter

takes a string argument that specifies a format according to java.text.SimpleDateFormat specifications, an optional second string argument to use for null values, and returns a procedure that takes a date or null argument and returns an appropriately formatted string.

brl-decimal-formatter

takes a string argument that specifies a format according to java.text.DecimalFormat specifications, an optional second string argument to use for null values, and returns a procedure that takes a real or null argument and returns an appropriately formatted string.

brl-format

takes a number or date argument followed by a string argument specifying an appropriate format, and returns a string representation of the first argument.

brl-string-escaper

takes an argument that is a list of pairs, the car of each pair being a character and the cdr being a string that represents the escape sequence for that character. It returns a procedure that takes one string argument and returns that string if no escaping is needed, or an escaped version otherwise.

brl-html-escape

takes a string argument and returns a string with the following characters appropriately escaped for HTML: < > " &

brl-scheme-escape

takes a string argument and returns a string with backslashes and double quote characters appropriately escaped for use in Scheme strings. Usually Scheme's write procedure is better for this purpose.

brl-msft-escape

takes a string argument and returns a string with certain non-standard characters converted into ASCII-standard equivalents or approximations.

brl-sql-escape

takes a string argument and returns a string with single quote characters appropriately escaped for use in Scheme strings. Usually brl-sql-string is better for this purpose.

brl-sql-string

takes a string or null argument and returns either a SQL string enclosed in single quotes and properly escaped, or the string "NULL".

brl-sql-number

takes a number, string or null argument and returns a string representation of the number or "NULL" as appropriate. An error will be thrown if a string argument does not represent a number.

brl-latex-escape

takes a string argument and returns a string with backslash-escaping for characters that are special to the LaTeX typesetting language.

brl-ends-with?

takes a suffix argument and a string argument, and returns false unless the string ends with the suffix.

brl-starts-with?

takes a prefix argument and a string argument, and returns false unless the string starts with the prefix.

brl-nonblank?

takes any argument, and returns false only if the argument is null, the empty string, or false.

brl-blank?

takes any argument, and returns false unless the argument is null, the empty string, or false.

brl-nonblanks

takes a list argument, and returns a subset of that list containing only non-blank items.

brl-all-blank?

Takes any number of arguments and returns true only if all are blank.

brl-any-blank?

Takes any number of arguments and returns true if any are blank.

brl-all-nonblank?

Takes any number of arguments and returns true only if none are blank.

brl-any-nonblank?

Takes any number of arguments and returns true if any are not blank.

brl-trim

takes a string argument and returns a string formed by trimming whitespace from both sides.

brl-split

takes a string argument specifying a separator, then a string argument to split, and returns a list of strings found in the second argument delimited by the first argument.

brl-string-join

takes a string argument specifying a separator, then a list argument of objects. A string is returned that concatenates the display representations, separated by the separator string. This function is named in a different style from brl-trim and brl-split to avoid confusion with SQL joins.

5.2 Web Functions

brl-referer-ok?

takes a BRL context argument and returns false only if the HTTP Referer header has been supplied and indicates that the referring page is on a different site from the current page.

brl-referer-check

takes a BRL context argument and throws an error if brl-referer-ok? returns false, otherwise an empty string is returned.

brl-content-type!

takes a BRL context argument and a string representing a MIME type. Sets the Content-Type header to be delivered to the browser.

brl-http-redirect!

takes a BRL context argument and a string containing an absolute URL. The browser is redirected to that URL.

brl-http-status!

takes a BRL context argument, an HTTP status code and a string. The HTTP status for the current page is set.

brl-http-header!

takes a BRL context argument, an HTTP header name and a value. The HTTP header of that name is set to that value.

brl-context-cookies

takes a BRL context argument and returns a list of lists. Each inner list consists of a cookie name (symbol), a cookie value (string), and possibly other elements.

brl-cookie-value

takes a BRL context argument and a symbol argument representing a cookie name. A string representing the value of that cookie is returned.

brl-cookie-set!

takes a BRL context argument, a symbol argument representing a cookie name, a string argument representing the value of that cookie, and any optional arguments. Optional arguments must be in pairs that change attributes of the cookie: comment: string, domain: string, maxage: int (seconds), path: string, secure: boolean, version: int.

brl-url-arg

takes three arguments, the first being a procedure, usually brl-blank? but sometimes null?, which is applied to the third argument. If the result is false, a URL argument string of the form name=value is returned, using the second argument as the name and the third argument as the value. Otherwise an empty string is returned.

brl-url-args

This syntax takes two or more arguments. The first argument is a procedure as with brl-url-arg. Second and subsequent arguments should be variable names. A string is returned suitable for inclusion in a URL with the variable names used as parameter names and the variable values used as parameter values.

brl-url-contents

takes a string argument (URL), fetches its contents and returns the results as a string.

brl-html-options

takes two arguments, the first being a "selected" value, the second being a list of lists. For each inner list, the first element is a value for an HTML OPTION tag, and the second element is a string with which to label the option. A string is returned with appropriate HTML OPTION tags.

brl-get-update

This syntax takes two or more arguments. The first argument is a brl-context structure that includes input from a web form. The second and subsequent arguments must be of the form (validator varname), where validator is a procedure for validating an input value, and varname is an input of the form. The return value is a list of lists. For each inner list, the first element is the name of an input that has changed from its old value (i.e. the value of an input whose name is formed by prepending "o" to name of the input in question), and the second element is the new value.

brl-session

Takes a BRL context argument and returns a procedure of one or two arguments. The returned procedure, when passed one argument (a symbol), will return the value associated with that symbol for this HTTP session, or #f if said symbol is unbound. When passed two arguments, a symbol and any object, it will associate the object with the symbol for later retrieval within the same session.

brl-session-id

When passed a procedure returned by brl-session, brl-session-id returns a unique string identifying the session.

brl-session-new?

When passed a procedure returned by brl-session, brl-session-new? returns true if this session is being created with the current request, i.e. no valid session cookie was sent from the client, so the server will assign one.

brl-session-invalidate!

When passed a procedure returned by brl-session, brl-session-invalidate! will keep any state associated with this session from being retrieved for subsequent HTTP requests. This procedure should be used to log a user out of a session-based application.

5.3 SQL Functions

sql-driver

takes a string argument. For the JVM-based implementation, this string represents the class of a JDBC driver. Future implementations may require different strings. The return value is implementation-specific.

sql-connection

takes a string argument representing a database to connect to, and optional second and third string arguments representing a username and password. For the JVM-based implementation, the first argument is a JDBC URL, and sql-connection may also take exactly two arguments, the second of which is a <java.util.Properties> object. An SQL connection object is returned.

sql-connection?

takes any object as its argument, and returns false unless that object is an SQL connection object.

sql-connection-close

takes an SQL connection argument and closes it.

brl-sql-connection

takes two or more arguments, the first of which is a brl-context structure representing a request. Subsequent arguments are passed to sql-connection. The resulting SQL connection is returned, and will be closed when the request is exited for any reason.

sql-statement

takes an SQL connection argument and returns an SQL statement object that can be used for queries and updates.

sql-statement?

takes any object as its argument, and returns false unless that object is an SQL statement object.

sql-statement-close

takes an SQL statement argument and closes it.

brl-sql-statement

takes two arguments, the first of which is a brl-context structure representing a request. The second argument is passed to sql-statement. The resulting SQL statement is returned, and will be closed when the request is exited for any reason.

sql-execute

takes a statement argument. Subsequent args are passed to brl-string to form an arbitrary SQL statement. Useful for table definitions, etc.

sql-execute-update

takes a statement argument. Subsequent args are passed to brl-string to form an SQL insert, update or delete. The number of rows affected is returned.

sql-statement-results

takes a statement argument and a string argument representing an SQL query. Query result values are returned in the form of a list of lists.

sql-execute-query

takes a statement argument and a string argument representing an SQL query. Query results are returned in the form of an SQL result-set object object that includes meta-data and the potential to retrieve values.

sql-resultset?

takes any object as its argument, and returns false unless that object is an SQL result-set object.

sql-rsmd

takes an SQL result-set argument and returns an SQL result-set meta-data object.

sql-rsmd?

takes any object as its argument, and returns false unless that object is an SQL result-set meta-data object.

sql-rsmd-column-labels

takes an SQL result-set meta-data argument and returns a list of column labels.

sql-rsmd-column-names

takes an SQL result-set meta-data argument and returns a list of column names.

sql-rsmd-column-typenames

takes an SQL result-set meta-data argument and returns a list of column type names, which are implementation-specific.

sql-resultset-nextrow

takes an SQL result-set argument and an integer argument representing the number of columns to retrieve. A list of result values is returned for the next row from the SQL query.

sql-repeat-rsmd

This syntax takes five or more arguments. The first argument is a variable name which will be bound to an SQL result-set meta-data object within the scope of the sql-repeat-rsmd expression. The second argument is an open SQL statement object. The third argument is a formal arguments list legal for use with lambda. The fourth argument is of the form )obj ...), consisting of objects, usually strings, which are used to build a query string. Fifth and subsequent arguments are expressions which form the body of a procedure with arguments as specified by the third argument. This procedure is repeatedly applied to result-set rows, and the number of rows is returned.

sql-repeat

This syntax takes four or more arguments exactly like the second and subsequent arguments to sql-repeat-rsmd, but no provision is made to capture the result-set meta-data.

sql-order-prepend

takes a string argument and a list argument. The first argument and the elements of the second argument are strings that represent columns to order SQL results by, and may or may not be followed by "desc" to indicate descending order. A list is returned whose first element is the first argument, reversed by removing or adding "desc" as appropriate if that column was already the first element of the list. Otherwise the first occurrence later in the list is deleted.

sql-order-eqv-di?

takes two string arguments and returns false only if they differ other than by the suffix " desc". Case is ignored.

sql-order-desc?

takes a string argument and returns false unless the string ends in " desc". Case is ignored.

sql-order-member

takes a string argument and a list argument, and returns false only if there is no member of the list that is equivalent (ignoring the suffix " desc"). than by the suffix " desc". Case is ignored.

sql-order-reverse

takes a string argument and returns a copy of the string with " desc" appended if it wasn't already there, deleted otherwise.

sql-partial-update

takes three or more arguments. The first argument is an SQL statement object. The second is a string, the name of a table to update. The third is a list like that returned by brl-get-update. An SQL update is performed if appropriate, with the fourth and subsequent arguments appended to the string forming the query.

5.4 Network Functions

brl-tcp-socket

takes a string representing a hostname and an integer representing a port. Returns a connection for use with brl-tcp-in and brl-tcp-out.

brl-tcp-in

takes a tcp connection as returned by brl-tcp-socket and returns a input port to receive data from the remote host.

brl-tcp-out

takes a tcp connection as returned by brl-tcp-socket and returns a output port to send data to the remote host.

brl-smtp-date

takes a date argument and returns a string representing that date, formatted for use with SMTP. The same format is useful with HTTP.

brl-smtp-sender

takes three strings as arguments. The first is a mail host. The second is the hostname the local host will use to identify itself to the mail host. The third is an "envelope sender" address. A procedure is returned that takes two or more arguments. The first argument is a list of recipients. Subsequent arguments are made into a string forming the headers, a blank line, and the body of an e-mail message.

5.5 Miscellaneous Functions

brl

This syntax causes its arguments to be evaluated left-to-right. The resulting values (if applicable) are displayed.

brl-when

This syntax is convenient shorthand for (if arg1 (brl arg2 ...) "").

brl-unless

This syntax is convenient shorthand for (if arg1 "" (brl arg2 ...)).

silent

This syntax is like Scheme's begin, but produces no output when used in a BRL page.

brl-implementation-version

takes no arguments and returns a string corresponding to the BRL release number.

brl-readall

takes an input port as an argument and returns a list of Scheme objects read from that port using the BRL template syntax.

brl-hash

takes no arguments and returns a hash table.

brl-hash?

takes any Scheme object as an argument and returns false unless that object is a hash table.

brl-hash-size

takes a hash table as an argument and returns the number of items stored therein.

brl-hash-put!

takes a hash table argument, a key argument and a value argument. The key/value pair is stored in the hash table.

brl-hash-get

takes a hash table argument and a key argument, and returns the value if any exists in the hash table for that key, otherwise returns false.

brl-hash-remove!

takes a hash table argument and a key argument, and removes the key/value pair from the hash table.

brl-hash-keys

takes a hash table argument and returns a list of all keys for that hash table.

brl-hash-contains-key?

takes a hash table argument and a key argument, and returns false unless the hash table contains that key.

brl-random

takes one argument. If that argument is a positive exact integer N, a pseudo-random number M is returned such that 0 <= M < N. If that argument is an input port, a few bytes are read from the port to help seed the random number generator. The same input is not guaranteed to produce the same random number sequence each time.

brl-random-typeable

takes a positive integer argument N and returns a string of length N consisting of random numbers and lowercase letters, excluding 0, 1, l, o.

Other functions exist and will be documented later. The curious can peruse `gnu/brl/*.scm' in the source distribution.