alterator-woo(3)

Alterator user manual

alterator-woo(3)

NAME

(alterator woo) - Scheme library to communicate with alterator backends

SYNOPSIS

(use-modules (alterator woo))

(woo-query cmd)

(woo action url . args)
(woo-read url . args)
(woo-write url . args)
(woo-new url . args)
(woo-delete url . args)
(woo-list url . args)

(woo-get-option cmd name . default)

(woo-error . reason)
(woo-catch thunk handler)

(woo-read-first url . args)

DESCRIPTION

This library provides a standard API to made requests to alterator's backends. Each query looks like a property list:

(url arg1 "value1" arg2 "value2" arg3 "value3" arg4 #f)

First argument is a string. It specifies a backend and looks like a path in filesystem. First component this path is a name of backend's file, and the rest of this path is an interface name inside backend. For example, "/foo/a/b" specifies an interface "a/b" of backend "foo".

Other arguments are an additional parameters of the query. Each argument's name should be a symbol, and each argument's value should be of type string or boolean.

Backend's answer has a same format. This is a list of a such "property lists". For example:

(("/users" name "test1" gecos "Test1 user" admin #t) ("/users" name "test2" gecos "Test2 user" admin #f))

This format can be changed in the future, therefore, you should prefer a high level procedures. Traditionally all requests contain attribute named "action". Library provides a high level procedures for a typical values of this attributes, e.g for "read".

FUNCTIONS

Basic functions

(woo-query cmd): Sends command to backend. This is a low level procedure and you should avoid to use it.
Example: (woo-query '("/users" action "read" name "test"))
(woo action url . args): Special version of (woo-query). Send request containing an action attribute with appropriate value. You can also specify an additional query parameters in format described above.
Example: (woo "read" "/users" 'name "test")
(woo-get-option cmd name . default): Get value of some attribute. Argument cmd is a query or one list item from answer. If attribute doesn't exist in cmd, then this function will return an empty string. You can also specify your own default value for nonexistent attributes.

Additional helpers

(woo-read url . args)

Same as a (woo "read" url . args).

Example: (woo-read "/users" 'name "test")

(woo-write url . args)

Same as a (woo "write" url . args).

(woo-new url . args)

Same as a (woo "new" url . args).

(woo-delete url . args)

Same as a (woo "delete" url . args).

(woo-list url . args)

Same as a (woo "list" url . args).

(woo-error . reason)

Backends can throw exceptions of type 'woo-error. You can throw a such exceptions using this function.

Example: (woo-error "Some reason")

(woo-catch thunk handler)

Special version of a standard catch function to catch exceptions from alterator's backends. Usually you don't need this function, because all interface libraries contain a more powerfull functions to catch exceptions from different alterator subsystems.

Example:

(woo-catch
(lambda() you code ...)
(lambda(reason) (format #f "woo-error:~S~%" reason)))

(woo-read-first url . args)

Typical answer for a "read" request contains only one component. This function is same as (cond-car (woo-read url . args).

DEPRECATED FUNCTIONS

woo-throw is obsoleted by woo-error.
woo-try is obsoleted by woo.

AUTHOR

Stanislav Ievlev <inger@altlinux.org>

22/04/2009

ALT Linux