Running Ripple

Getting the software

To get Ripple, you can either [download the latest release](https://github.com/joshsh/ripple/archives/master download) or build from source as follows:

1. check out the source code from GitHub:

git clone [email protected]:joshsh/ripple.git

2. enter the top-level directory

cd ripple

3. build with Maven:

mvn clean install

The Ripple command line

To start the Ripple command line interpreter:

1. get or build a Ripple distribution, as above
2. cd into the ripple/ripple-demo directory
3. execute the script ./ripple.sh
4. from here, you can evaluate expressions and issue commands. For example, type 2 3 add.
5. to exit Ripple, type @quit

Configuration

Using NativeStore instead of MemoryStore

Be default, Ripple uses a Sesame MemoryStore to collect the Linked Data that you stumble upon. When Ripple quits, that collection is lost.

You can run Ripple using NativeStore (as well as other Sail implementations) instead of MemoryStore, which will store the Linked Data cache in a local directory. When you quit Ripple, the collection will remain in that directory, and will be available in subsequent sessions. Make sure to @quit instead of unix kill so that Ripple can shut down the NativeStore.

Ripple uses a NativeStore when the java property net.fortytwo.ripple.demo.linkedDataSailBaseSail is set to org.openrdf.sail.nativerdf.NativeStore. When set, the java property net.fortytwo.ripple.demo.nativeStoreDirectory needs to point to a local directory to use as a NativeStore.

The easiest way to pass these properties to Ripple is to put them into a file and pass the filename to ripple.sh:

desktop-native-store.properties:

# Aggregate linked RDF data on the fly.
net.fortytwo.ripple.demo.sailType = net.fortytwo.linkeddata.sail.LinkedDataSail

# Use Sesame NativeStore for persistent storage of aggregated data.
net.fortytwo.ripple.demo.linkedDataSailBaseSail = org.openrdf.sail.nativerdf.NativeStore
net.fortytwo.ripple.demo.nativeStoreDirectory = /Users/lebot/Desktop/ripple-store 

# invoke with ./ripple.sh this-file.properties

./ripple.sh desktop-native-store.properties

When you don't specify a required property, Ripple falls back on its default configuration.

The Ripple command line

Built-in commands

List the built-in commands available. Type @ at the Ripple command line and hit tab:

1)  @

@help       @list       @prefix     @quit       @relist     @show
@unlist     @unprefix

Know your namespaces

One of the first things to get oriented with is the set of namespaces in scope. A default namespace is already defined, and many other commonly-used prefixes (courtesy of prefix.cc) are defined for the sake of convenience:

bash-3.2$ ./ripple.sh 
1)  @show prefixes

[0] :              http://ripple.fortytwo.net/code/examples#
[1] abc:           http://www.metadata.net/harmony/ABCSchemaV5Commented.rdf#
[2] ac:            http://umbel.org/umbel/ac/
[...]
[546] zoology:     http://purl.org/NET/biol/zoology#

You can define more namespace prefixes using Turtle-esque syntax:

bash-3.2$ ./ripple.sh 
1)  foo:bar to-string.

Warning: prefix 'foo' does not identify a namespace

2)  @prefix foo: <http://example.org/foo/>
3)  foo:bar to-string.

  [1]  "http://example.org/foo/bar"^^xsd:string

Define a program

Defining a program is similar to defining a @prefix, except that the right hand side of the definition expects a list instead of a single URI. The name on the left hand side is the local part of a resource URI (an RDF list representing the program) in the default namespace. For example, this is a trivial program to add one to a number:

1) @define add-one: 1 add.

Execute the program by dequoting the list, e.g.

2) 100 :add-one.

  [1]  101

You can also define parameter names before the name of the list:

1)  @define n triangle: n 1 add. n mul. 2 div.
2)  4 :triangle.

  [1]  10

That's ((n+1)*n)/2 in Ripple's postfix notation. Some lists are simply data structures, and are never executed as programs, e.g.

@define days: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday"

...and some are simply convenient aliases for long, messy URIs:

@define beijing: <http://dbpedia.org/resource/Beijing>

That last list wraps the DBpedia resource for Beijing with a handy name. You can dequote the list and begin exploring the Linked Data neighborhood of the resource like so:

:beijing.

If you traverse to other resource URIs which have been identified with Beijing:

@prefix owl: <http://www.w3.org/2002/07/owl#>
:beijing. owl:sameAs?

...you will discover a place hierarchy in GeoNames which you can explore using regular expression syntax:

@prefix geonames: <http://www.geonames.org/ontology#>
:beijing. owl:sameAs? geonames:parentFeature* geonames:name. distinct.

This gives you the following result (if not, tap the up key to repeat the query; any bad links encountered on the first try will be skipped the next time around):

  [1]  "Beijing"
  [2]  "Beijing Shi"
  [3]  "China"
  [4]  "Asia"
  [5]  "Earth"

Our path is becoming a little complex for copy-and-paste, so let's @define a new program:

@define place hierarchy:    \
    place owl:sameAs?       \
    geonames:parentFeature* \
    geonames:name. distinct.

Note that the @prefix commands for the owl and geonames namespaces are required for this to work properly. Now you can refer to your path by name, and apply it to Beijing:

:beijing. :hierarchy.

If you have the URI for another place in DBpedia or GeoNames, you can re-use the program:

@define spokane: <http://sws.geonames.org/5811696/>
:spokane. :hierarchy.

After one or more runs, this gives you the following result:

  [1]  "Spokane"
  [2]  "Spokane County"
  [3]  "Washington"
  [4]  "United States"
  [5]  "North America"
  [6]  "Earth"