Skip to content

graph library

Jump to bottom Edit New page
Joshua Shinavier edited this page May 21, 2011 · 14 revisions

The graph: library contains primitives for type conversion as well as RDF-specific primitives for querying against and updating sets of RDF statements.

Note: in all of the RDF graph primitives, the default graph context is represented by the nil list (() or rdf:nil).

to-json

This primitive converts the string representation of a JSON object to an equivalent simple value, list, or key/value object. It expects a single argument at the top of the stack. It pops the argument from the stack, converts the argument to a string (see to-string), then parses the string according to JSON syntax to produce a value equivalent to the JSON object represented by the string. If this process succeeds, the resulting value is pushed to the stack. Otherwise, no solution is produced.

The produced object is one of:

  • a simple value (boolean, string, or number)
  • a list of values corresponding to a JSON array
  • a key/value object corresponding to a JSON object

Lists thus produced may contain other objects of any of the above three kinds, while key/value objects thus produced may have key/value pairs, the key of which is a string and the value of which is another object of one of the above three kinds. The resulting value is equivalent to corresponding object in JSON, with the exception that null values are simply ignored. It can be converted to a string to obtain a string representation equivalent to the original representation, again with the exception of nulls, and ignoring the order of key/value pairs.

Examples (see also this blog post):

1)  @list j: "{\\"foo\\": true, \\"bar\\": [6, 9, 42]}" to-json.
2)  :j.

  [1]  {"foo":true,"bar":[6,9,42]}

3)  :j. "foo".

  [1]  true

4)  :j. "bar". each.

  [1]  6
  [2]  9
  [3]  42

RDF queries

in-context

This primitive behaves like an RDF predicate mapping (e.g. like the predicate foaf:knows, which maps a person to a set of people he or she knows) but restricts its solutions to a specified graph context. It expects three arguments on the top of the stack: the subject, predicate, and graph context of matching RDF statements. It pops the arguments from the stack and, for each matching RDF statement, pushes the object of the statement.

Examples:

1)  rdfs:Class rdf:type.

  [1]  owl:Class
  [2]  rdfs:Class

2)  # One of the above types is asserted in the FOAF vocab document, the other in the RDFS schema document.
3)  # Let's select only those from the RDFS document.
4)  rdfs:Class rdf:type <http://www.w3.org/2000/01/rdf-schema> in-context.

  [1]  rdfs:Class

inlinks

This primitive finds all RDF statements with a specified object. It expects one argument on the top of the stack. It pops the argument from the stack, finds all matching RDF statements (in any context) and, for each matching statement, pushes the subject, predicate, and object of the statement.

Note: if otherwise identical RDF statements exist in multiple contexts, then inlinks may produce duplicate solutions.

Example:

1)  <http://identi.ca/user/114> inlinks. 5 limit. 2 2 ary.

  [1]  <http://identi.ca/user/114> foaf:maker <http://identi.ca/user/114> <http://identi.ca/user/114>
  [2]  <http://identi.ca/user/114> foaf:primaryTopic <http://identi.ca/user/114> <http://identi.ca/user/114>
  [3]  <http://identi.ca/user/114#acct> sioc:account_of <http://identi.ca/user/114> <http://identi.ca/user/114>
  [4]  <http://identi.ca/user/114#acct> sioc:account_of <http://identi.ca/user/114> <http://identi.ca/user/22871>
  [5]  <http://identi.ca/user/114#acct> sioc:account_of <http://identi.ca/user/114> <http://identi.ca/user/45468>

links

This primitive finds all RDF statements with a specified subject. It expects one argument on the top of the stack. It pops the argument from the stack, finds all matching RDF statements (in any context) and, for each matching statement, pushes the subject, predicate, and object of the statement.

Note: if otherwise identical RDF statements exist in multiple contexts, then links may produce duplicate solutions.

Example:

10 <http://identi.ca/user/114> links.

  [1]  <http://identi.ca/user/114> foaf:name "Danny Ayers" <http://identi.ca/user/114>
  [2]  <http://identi.ca/user/114> foaf:mbox_sha1sum "669fe353dbef63d12ba11f69ace8acbec1ac8b17" <http://identi.ca/user/114>
  [3]  <http://identi.ca/user/114> foaf:based_near <http://sws.geonames.org/3179523/> <http://identi.ca/user/114>
  [...]

members

This primitive finds all members of an rdfs:Container, according to RDF descriptions in any graph context. It expects a single argument at the top of the stack, which must be (explicitly or implicitly) an instance of rdfs:Container. It pops the container from the stack, then for each member of the container, the member is pushed to the stack.

Example:

1)  <http://identi.ca/rss> rss:items. members.

  [1]  <http://identi.ca/rss>
  [2]  <http://identi.ca/notice/73943987>
  [3]  <http://identi.ca/notice/73943938>
  [4]  <http://identi.ca/notice/73943916>
  [5]  <http://identi.ca/notice/73943897>
  [...]

quads

This primitive combines an HTTP GET operation with an RDF query. It fetches an RDF document based on a URI, then finds all RDF statements (including graph context) in that document. It expects a single argument at the top of the stack, which must be a URI reference. It pops the URI reference from the stack and attempts to fetch a document at the corresponding URL. If successful, it attempts to parse the document according to the specified content type of the retrieved representation, insofar as this corresponds to a supported RDF format. The document is parsed to a set of RDF statements with context, and for each statement, the subject, predicate, object, and graph context of the statement are pushed to the stack.

Example:

1)  <http://www.w3.org/2000/01/rdf-schema> quads.

  [1]  rdfs: rdf:type owl:Ontology ()
  [2]  rdfs: dc11:title "The RDF Schema vocabulary (RDFS)" ()
  [3]  rdfs:Resource rdf:type rdfs:Class ()
  [4]  rdfs:Resource rdfs:isDefinedBy rdfs: ()
  [5]  rdfs:Resource rdfs:label "Resource" ()
  [...]

sparql

This primitive evaluates a SPARQL query against the RDF statements of the knowledge base. It expects a single argument at the top of the stack: a string representing the SPARQL query. It pops the query from the stack, then evaluates it. The result of query evaluation is a series of binding sets of key/value pairs, in which every binding set has the same set of keys (although some of the values may be null). For each binding set, sparql pushes to the stack a key/value value whose keys are the binding set's keys, with the corresponding values. Values for specific variables can then be accessed using key predicates, as with JSON.

Examples:

1) "select ?s ?p ?o where { ?s ?p ?o }" sparql.

  [...]
  [6295]  {s:dcterms:Location, p:rdf:type, o:rdfs:Class
  [6296]  {s:dcterms:Location, p:dcterms:hasVersion, o:<http://dublincore.org/usage/terms/history/#Location-001>
  [6297]  {s:dcterms:Location, p:rdfs:subClassOf, o:dcterms:LocationPeriodOrJurisdiction
  [6298]  {s:dcterms:LocationPeriodOrJurisdiction, p:rdfs:label, o:"Location, Period, or Jurisdiction"@en-us
  [6299]  {s:dcterms:LocationPeriodOrJurisdiction, p:rdfs:comment, o:"A location, period of time, or jurisdiction."@en-us
  [...]

2)  "select ?s ?p ?o where { ?s ?p ?o}" sparql. "p". distinct.

  [1]  <http://fortytwo.net/2008/01/webclosure#memo>
  [2]  rdf:type
  [3]  dc11:title
  [4]  dc11:description
  [5]  rdfs:subClassOf
  [...]

triples

Like quads (see above), this primitive combines an HTTP GET operation with an RDF query. However, it ignores graph context. It fetches an RDF document based on a URI, then finds all RDF statements in that document, in any context. It expects a single argument at the top of the stack, which must be a URI reference. It pops the URI reference from the stack and attempts to fetch a document at the corresponding URL. If successful, it attempts to parse the document according to the specified content type of the retrieved representation, insofar as this corresponds to a supported RDF format. The document is parsed to a set of RDF statements without context, and for each statement, the subject, predicate, and object of the statement are pushed to the stack.

Example:

1)  <http://www.w3.org/2000/01/rdf-schema> triples.

  [1]  rdfs: rdf:type owl:Ontology
  [2]  rdfs: dc11:title "The RDF Schema vocabulary (RDFS)"
  [3]  rdfs:Resource rdf:type rdfs:Class
  [4]  rdfs:Resource rdfs:isDefinedBy rdfs:
  [5]  rdfs:Resource rdfs:label "Resource"
  [...]

RDF graph operations with side effects

These primitives update the RDF knowledge base. Unlike most primitives in Ripple, these exert changes on the scripting environment in a non-monotonic fashion. Their use in a program requires special attention to order of evaluation.

assert

This primitive asserts an RDF statement, i.e. adds it to the knowledge base, in the default graph context. It expects three arguments on the top of the stack: the subject, predicate, and object of the statement. It pops the arguments from the stack, constructs and asserts the corresponding RDF statement, then pushes the subject of the statement back to the stack.

Note: the action of this primitive alters the scripting environment. Its use in a program requires special attention to order of evaluation.

Examples:

1)  ex:FordPrefect rdf:type.

  [1]  foaf:Person

2)  ex:FordPrefect rdf:type ex:Betelgeusian assert.

  [1]  ex:FordPrefect

3)  ex:FordPrefect rdf:type.                       

  [1]  foaf:Person
  [2]  ex:Betelgeusian

assert-in-context

Like assert (see above) this primitive asserts an RDF statement, i.e. adds it to the knowledge base, but in a specified graph context. It expects four arguments on the top of the stack: the subject, predicate, object, and context of the statement. It pops the arguments from the stack, constructs and asserts the corresponding RDF statement, then pushes the subject of the statement back to the stack.

Note: the action of this primitive alters the scripting environment. Its use in a program requires special attention to order of evaluation.

Examples:

1)  ex:TheGalaxy ex:population 5.982915e20 ex:megadodo2009Census assert-in-context.

  [1]  ex:TheGalaxy

2)  ex:TheGalaxy ex:population 6.016003e20 ex:megadodo2010Census assert-in-context.

  [1]  ex:TheGalaxy

3)  ex:TheGalaxy ex:population.

  [1]  5.982915E11
  [2]  6.016003E11

4)  ex:TheGalaxy ex:population ex:megadodo2009Census in-context.

  [1]  5.982915E11

5)  ex:TheGalaxy ex:population ex:megadodo2010Census in-context.

  [1]  6.016003E11

deny

This primitive denies an RDF statement, i.e. removes it from the knowledge base (in all contexts) if it exists. It expects three arguments on the top of the stack: the subject, predicate, and object of matching statements. It pops the arguments from the stack, removes all matching RDF statements from the knowledge base, then pushes the subject of the statement back to the stack.

Note: the action of this primitive alters the scripting environment. Its use in a program requires special attention to order of evaluation.

deny-in-context

Like deny, this primitive denies an RDF statement, i.e. removes it from the knowledge base, but only from a specified graph context. It expects four arguments on the top of the stack: the subject, predicate, object, and context of matching statements. It pops the arguments from the stack, removes all matching RDF statements from the knowledge base, then pushes the subject of the statement back to the stack.

Note: the action of this primitive alters the scripting environment. Its use in a program requires special attention to order of evaluation.

new

This primitive creates a new, unique blank node or a domain-neutral, randomized URI (the two are considered equivalent for Ripple's purposes). It takes no arguments, and pushes a randomized, newly-minted blank node or URI to its input stack.

Example:

1)  new. rdf:type foaf:Person assert. foaf:name "Arthur Dent" assert.

  [1]  <urn:random:dc96970127b7af20c17cec984e0bb228>
          rdf:type
             foaf:Person;
          foaf:name
             "Arthur Dent".
Add a custom footer
Add a custom sidebar
Clone this wiki locally