The Fabl Manual
Function Index
Class Index
Globals Index
Libraries
Contents

Title Page
Introduction
Sample Code
Architecture
Syntax
Strong Typing
Polymorphism
Operators
Help
Errors
Configuration
RDF
Namespaces
Owl
Datatypes
Resources
Dot ops
Coercion
Type Casting
nil

Types
string
id
int
double
boolean
Literal
Containers
Functions
void

Home
Regarding
The Path
Classes
Delegation
Functional Values
Read/Write
Load/Store
Libraries
Imports
CGI
Load/Store

Data stored externally by Fabl (like the data within a Fabl invocation) takes the form of a set of RDF triples. Fabl supports the most widely used format for external storage, RDF/XML and also defines its own binary format, referred to as "RDF/FB" (FB for "Fabl Binary"). RDF/FB is compact, and loads efficiently (currently at about 500,000 triples/second on a Pentium 2Ghz processor). The major part of the Fabl implementation itself is stored as an RDF/FB file.

Fabl uses the Raptor RDF parser for loading the RDF/XML format. The Raptor parser supports three additional syntactic variants: N-triples, turtle (Terse RDF Triple Language), and "RSS tag soup" (for RSS versions other than the RDF-based RSS 1.0). Support for loading, but not storing, these variants is also provided in Fabl, designated by "ttl", and "rss", respectively.

Pages

A crucial aspect of serializing RDF is determining what set of triples to include in the serialization. (Serialization is the process of converting a non-linear structure such as an RDF graph into a sequence of primitive elements - characters or bytes - for storage or transmission). If all of the triples emanating from an object are followed recursively, the resulting set of triples will usually be be too large - for example, it will likely include chunks of standard vocabularies arrived at by traversing rdf:type and rdfs:subClassOf properties, leading to traversal of parts of the standard rdf,rdfs, and xsd vocabularies.

Fabl uses two mechanisms to address this issue. First, each triple and each resource in its store is assigned to a numbered "page"; the page mechanism is described in this section. The second mechanism, discussed in the next section, involves designation of resources as "persistent" or "transient".

The partition of the Fabl store into pages is somewhat similar in effect to partitioning RDF content into a set of separate files. To serialize a resource R relative to a page P, the graph is traversed starting from R along edges (ie triples) which lie on P. Only those edges reached during this traversal are serialized: ie, those triples that are on P, and also reachable from R via other triples on P.

New triples and new resources created during computation are allocated to the current page. Note that a resource may be the subject of triples from different pages. Traversal of triples on a page will often pass through resources from other pages. The following functions query and set the current page:

int currentPage()

void setCurrentPage(int pg)

and the following function returns the page to which rsr has been allocated

int page(Resource rsr)

newPage allocates an unused page (one which has not been the current page during the computation so far), and assigns it as the current page:

int newPage()

Now, the function

void store(string fln,string syntax,Resource rsr,int pg)

saves the resource rsr to the file fln, traversing and saving those triples that lie on page pg. fln, as usual, should be given in URL form, eg, "file:///usr/local/fabl-2.0.11/example/test.fb". syntax specifies which syntax is to be used. The alternatives are "xml" and "fb".

Files that include definitions of Fabl functions should be stored using "fb" format. The Fabl XML serializer does not currently handle storage of code (it does not complain, but emits no content representing code). This is not of practical importance, since only Fabl can make use of Fabl code, and in any case FB is much faster to store and load when dealing with Fabl-specific content.

The variant

void store(string fln,Resource rsr,int int)

determines the syntax from the extension of fln. The extensions ".xml" or ".rdf" signify RDF/XML syntax, and ".fb" signifies RDF/FB.

The variants

void store(string fln,string syntax,Resource rsr)

void store(string fln,Resource rsr)

use page(rsr) as the page for traversal.

Persistence

The function,

void store(int pg,string fln,string syntax)

stores the contents of page pg in the file fl using the specified syntax. The variant

void store(int pg,string fln)

Determines the syntax from fln in the usual manner. However, neither variant stores every triple on the page, because some of the content of each page typically consists of intermediate computational results that are of no long term interest. The persistence mechanism allows the programmer to designate some resources as candidates for serialization; resources that have not been so designated are referred to as "transient".

Here are the details. The function

boolean declarePersistent(Resource rsr)

designates rsr as persistent, while

boolean persistent(Resource rsr)

returns a boolean indicating whether rsr is persistent.

Now, The rule for selecting which triples on the page are to be serialized by store[int,string] and store[int,string,string] can be formulated approximately as "serialize every triple on the page that is relevant to persistent resources". Stated more precisely, the selection process involves first finding the set of persistent resources that are subjects of triples on the page. These resources are called the "persistent roots" of the page. Then, the triple graph is traversed along edges (triples) that belong to the page; all triples so traversed are stored. Thus, in effect, any resource, persistent or not, that is reachable on the page from persistent resources is serialized.

Load

The function

Resource load(string url,string syntax)

loads triples from url in the given syntax. The permissable values of syntax are "fb","xml", "nt","ttl", and "rss".

The variant

Resource load(string url)

determines the syntax from the extension of fln; as with store, the extension ".rdf" is taken to indicate RDF/XML syntax.

If the file being loaded was created by storing a resource (ie store or ) rather than a page, then the value returned by load is the stored resource.

The property fabl:hasBeenLoaded of the resource denoted by url is set to true after loading. So, for example,

var tstfl = "file://../lib/geometry/1.1/revision2.fb";
load(tstfl);
resource(tstfl).fabl:hasBeenLoaded;
-->true

The variants

Resource loadOnce(string url,string syntax)

and

Resource loadOnce(string url)

retrieve the contents of a url once; if the resource denoted by a url has a true value for the property fabl:hasBeenLoaded, subsequent invocations of loadOnce on this resource will have no effect.

The variant

Resource load(SeqOf(Resource) subjects,string url,string syntax)

adds into subjects all of those resources that are the subjects of triples in the loaded file. Variants that collect subjects are available for the other argument patterns for load and loadOnce:

Resource load(SeqOf(Resource) subjects,string url)

Resource loadOnce(SeqOf(Resource) subjects,string url,string syntax)

Resource loadOnce(SeqOf(Resource) subjects,string url)

Install

The property rdfs:isDefinedBy tells where a definition of a resource can be found. rdfs:isDefinedBy can have multiple values, meaning that definitions can be spread across multiple files. The function

void install(Resource x)

loads all resources that are values of x..rdfs:isDefinedBy. It returns true if rdfs:isDefinedBy has at least one value, so that there is something to load. For example:

namespace('geom').rdfs:isDefinedBy = 
   resource("http://fabl.net/lib/geometry/1.1/revision1.fb");
install(namespace('geom'));

has the same effect as

loadOnce("http://fabl.net/lib/geometry/1.1/revision1.fb");

The variant

void install(string ns)

installs the namespace with prefix ns. So, for example, 

install(namespace("geom"));

and

install("geom");

are equivalent.

The function,

void reinstall(Resource x)

reloads the resources that are values of x..rdfs:isDefinedBy.

All variants of load,loadOnce,install,and reInstall allocate a new page for the triples added from the loaded file.

Compilation

The function

void compile(string dest,string src)

sets the current page to a new value, loads the contents of the file src, and then stores that new page to dest. So, compilation is a way of converting triples from one format to another. Typically, dest is an .fb file, while src is a .fbl, .xml, or .ttl file.

Compilation is of particular practical imporance when the source file is in fbl syntax and contains definitions of functions, and the destination is an fb file. In fb, programs are represented in their byte-code form. The efficiency of running the code is not affected, but load time is reduced by a factor of more than 100. For example, the Fabl self-implementation takes about 30 seconds to load as source, but about 1/20th of a second in its binary form on a 2ghz Pentium.

For an example of compilation, consider the source file:

http://fabl.net/lib/geometry/1.1/revision2.fbl

The following command compiles the file:

compile("file://../lib/geometry/1.1/revision2.fb","file://../lib/geometry/1.1/revision2.fbl");