rdf-agraph 0.3.0 → 0.3.1

data/README.md

@@ -1,9 +1,14 @@
 # rdf-agraph: Ruby AllegroGraph adapter for RDF.rb
 
-[RDF.rb][rdfrb] is an excellent Ruby library for working with RDF.
-[AllegroGraph][allegrograph]® is a commercial RDF data store written
-in Lisp.  AllegroGraph supports advanced graph queries and social network
-analysis.
+[AllegroGraph][allegrograph]® is a commercial RDF data store.
+AllegroGraph supports ACID transactions, federation, Prolog-style queries
+and social network analysis.  You can run [AllegroGraph Free Edition][free]
+on 64-bit Linux systems and store up to 50 million triples.  (See below for
+installation instructions.)
+
+[RDF.rb][rdfrb] is an excellent Ruby library for working with RDF.  It
+supports a huge variety of RDF repositories and formats, and it's very
+convenient to use.
 
 This gem provides an optimized implementaton of RDF.rb's `Repository`
 interface.  It supports bulk loads, bulk deletes, optimized statement
@@ -15,8 +20,8 @@ Note, however, that this gem exposes only a small fraction of
 AllegroGraph's features.  To help add more features, see
 [Contributing](#Contributing_to_rdf-agraph) below.
 
-* [`rdf-agraph` documentation][doc]
-* [`rdf-agraph` GitHub project][src]
+* [Documentation][doc]
+* [GitHub project][src]
 
 This code is a wrapper around [phifty's `agraph` gem][agraph_gem], which
 provides a low-level interface to AllegroGraph over HTTP.
@@ -114,8 +119,8 @@ To query for all statements about a subject, try:
     #   <http://example.com/susan> <http://xmlns.com/foaf/0.1/knows> <http://example.com/rachel> .
     #   <http://example.com/susan> <http://xmlns.com/foaf/0.1/knows> <http://example.com/richard> .
 
-AllegroGraph also supports fully-optimized queries using RDF.rb's Basic
-Graph Patterns.  For example, to query for all people with known names:
+You can also perform fully-optimized queries using RDF.rb's Basic Graph
+Patterns.  For example, to query for all people with known names:
 
     repo.build_query do |q|
       q.pattern [:person, RDF.type,  FOAF.Person]
@@ -183,7 +188,7 @@ For more ideas, check out the following websites:
 * [Spira][spira]: Define Ruby model objects for RDF data.
 
 [agraph_doc]: http://www.franz.com/agraph/support/documentation/v4/
-[sna]: http://www.franz.com/agraph/support/documentation/v4/python-tutorial/python-tutorial-40.html#Social Network Analysis
+[sna]: http://www.franz.com/agraph/support/documentation/v4/python-tutorial/python-tutorial-40.html#Social%20Network%20Analysis
 [spira]: http://spira.rubyforge.org/
 
 ## Comparisons with Other Gems
@@ -195,7 +200,8 @@ this information may be out of date!
 ### agraph vs. rdf-agraph
 
 `rdf-agraph` is a wrapper around [phifty's `agraph` gem][agraph_gem], which
-provides a low-level interface to AllegroGraph over HTTP.
+provides a low-level interface to AllegroGraph over HTTP.  This gem relies
+heavily on his work!
 
 * `agraph` provides a richer API for working with geometric primitives,
   which we don't yet export.
@@ -203,8 +209,8 @@ provides a low-level interface to AllegroGraph over HTTP.
   builder, and better support for Social Network Analysis.
 * `agraph` works with raw, serialized RDF values.  URLs, for example are
   represented as `"<http://example.com/>"` and strings are represented as
-  `"\"Hello\""`.  The `rdf-agraph` gem uses high-level Ruby objects defined
-  by RDF.rb.
+  `"\"Hello\""`.  The `rdf-agraph` gem, on the other hand, uses high-level
+  Ruby objects defined by RDF.rb.
 * `rdf-agraph` is compatible with the huge range of RDF formats and
   repositories supported by RDF.rb.
 
@@ -218,7 +224,8 @@ it has very few optimizations.
 * `rdf-sesame` tends to silently ignore network errors and return default
   values.
 * At the time of writing, `rdf-sesame` sends HTTP requests of the form `GET
-  http://example.com/path HTTP/1.1`, which do not work with AllegroGraph.
+  http://example.com/path HTTP/1.1`, which do not work with AllegroGraph's
+  Sesame endpoint.
 
 ### sparql-client vs. rdf-agraph
 
@@ -228,8 +235,8 @@ it has very few optimizations.
   Instead, it implements a custom SPARQL DSL (domain-specific language).
   This means that it can perform sophisticated queries, but it can't update
   the contents of the repository.
-* `rdf-agraph` can run raw SPARQL and queries, but does not provide a
-  complete DSL for building either kind of query.
+* `rdf-agraph` can run raw SPARQL and Prolog queries, but does not provide
+  a complete DSL for building either kind of query.
 
 ## Installing AllegroGraph
 
@@ -261,7 +268,7 @@ Save this as `/usr/local/bin/agraph-service` and run:
 
 ## A Warning About `fork`
 
-If you use insert statements containing blank nodes into an
+If you insert statements containing blank nodes into an
 RDF::AllegroGraph::Repository, the repository will generate and store a
 list of blank node IDs.  If you later call `fork` (perhaps because you are
 running Unicorn or Spork), you may cause this cache of unused blank node
@@ -290,7 +297,7 @@ on constructing the ideal patch:
   in the past. :-)
 * Provide [RSpec][rspec] specifications for the fix.  This may feel like a
   nuisance, but it ensures that your new feature will still work correctly
-  two releases from now!  I can help you with this if you're not familiar
+  two releases from now.  I can help you with this if you're not familiar
   with RSpec.
 * Document any new APIs using [yard][yard].
 
@@ -303,3 +310,9 @@ Thank you for contributing to `rdf-agraph`!
 [git_commit_message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [rspec]: http://relishapp.com/rspec
 [yard]: http://yardoc.org/
+
+## Acknowledgements
+
+Many thanks to the following people for helping to improve `rdf-agraph`:
+
+* Aymeric Brisse: Unit tests for AllegroGraph inference.

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

data/lib/rdf/allegro_graph/abstract_repository.rb

@@ -167,10 +167,16 @@ module RDF::AllegroGraph
     # @see    RDF::Queryable#query
     # @see    RDF::Query#execute
     def query_execute(query, &block)
+      query_options = 
+        if query.respond_to?(:query_options)
+          query.query_options
+        else
+          {}
+        end
       if query.respond_to?(:requires_prolog?) && query.requires_prolog?
-        prolog_query(query.to_prolog(self), &block)
+        prolog_query(query.to_prolog(self), query_options, &block)
       else
-        sparql_query(query_to_sparql(query), &block)
+        sparql_query(query_to_sparql(query), query_options, &block)
       end
     end
     protected :query_execute
@@ -191,13 +197,17 @@ module RDF::AllegroGraph
     #   @return [Enumerator<RDF::Query::Solution>]
     #
     # @param [String] query The query to run.
+    # @param [Hash{Symbol => Object}] query_options
+    #   The query options (see build_query).
     # @return [void]
     # @note This function returns a single-use Enumerator!  If you want to
     #   to treat the results as an array, call `to_a` on it, or you will
     #   re-run the query against the server repeatedly.  This curious
     #   decision is made for consistency with RDF.rb.
-    def sparql_query(query, &block)
-      raw_query(:sparql, query, &block)
+    #
+    # @see #build_query
+    def sparql_query(query, query_options={}, &block)
+      raw_query(:sparql, query, query_options, &block)
     end
 
     # Run a raw Prolog query.
@@ -212,19 +222,32 @@ module RDF::AllegroGraph
     #   @return [Enumerator<RDF::Query::Solution>]
     #
     # @param [String] query The query to run.
+    # @param [Hash{Symbol => Object}] query_options
+    #   The query options (see build_query).
     # @return [void]
     # @note This function returns a single-use Enumerator!  If you want to
     #   to treat the results as an array, call `to_a` on it, or you will
     #   re-run the query against the server repeatedly.  This curious
     #   decision is made for consistency with RDF.rb.
-    def prolog_query(query, &block)
-      raw_query(:prolog, query, &block)
+    #
+    # @see #build_query
+    def prolog_query(query, query_options={}, &block)
+      raw_query(:prolog, query, query_options, &block)
     end
 
     # Run a raw query in the specified language.
-    def raw_query(language, query, &block)
-      @repo.query.language = language
-      results = json_to_query_solutions(@repo.query.perform(query))
+    def raw_query(language, query, query_options={}, &block)
+      # Build our query parameters.
+      params = {
+        :query => query,
+        :queryLn => language.to_s
+      }
+      params[:infer] = query_options[:infer].to_s if query_options[:infer]
+
+      # Run the query and process the results.
+      json = @repo.request_json(:get, path, :parameters => params,
+                                :expected_status_code => 200)
+      results = json_to_query_solutions(json)
       if block_given?
         results.each {|s| yield s }
       else
@@ -235,6 +258,10 @@ module RDF::AllegroGraph
 
     # Construct an AllegroGraph-specific query.
     #
+    # @param [Hash{Symbol => Object}] query_options
+    # @option query_options [true,false,String] :infer
+    #   The AllegroGraph inference mode to use.  Defaults to `false`.  The
+    #   value `true` is equivalent to `'rdfs++'`.
     # @yield query
     # @yieldparam [Query] The query to build.  Use the Query API to add
     #   patterns and functors.
@@ -243,8 +270,8 @@ module RDF::AllegroGraph
     #
     # @see Query
     # @see RDF::Query
-    def build_query(&block)
-      Query.new(self, &block)
+    def build_query(query_options={}, &block)
+      Query.new(self, query_options, &block)
     end
 
 
@@ -351,8 +378,12 @@ module RDF::AllegroGraph
     protected
 
     # Build a repository-relative path.
-    def path(relative_path)
-      "#{@repo.path}/#{relative_path}"
+    def path(relative_path=nil)
+      if relative_path
+        "#{@repo.path}/#{relative_path}"
+      else
+        @repo.path
+      end
     end
 
     # Deserialize an RDF::Value received from the server, or an array of such

data/lib/rdf/allegro_graph/functors.rb

@@ -1,4 +1,9 @@
 # AllegroGraph functors for use in Prolog queries.
+#
+# Note that we only support a few functors right now.  For a list of all
+# available AllegroGraph functors, see
+# <http://www.franz.com/agraph/support/documentation/v4/lisp-reference.html>.
+# Adding new functors is easy; see SnaFunctors for examples.
 module RDF::AllegroGraph::Functors
   autoload :SnaFunctors, 'rdf/allegro_graph/functors/sna_functors'
 end

data/lib/rdf/allegro_graph/query.rb

@@ -19,10 +19,16 @@ module RDF::AllegroGraph
     # Include our APIs.
     include Functors::SnaFunctors
 
+    # Our query options.
+    #
+    # @see AbstractRepository#build_query
+    attr_reader :query_options
+
     # Create a new query.
     # @private
-    def initialize(repository, &block)
+    def initialize(repository, query_options={}, &block)
       @repository = repository
+      @query_options = query_options
       super(&block)
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rdf-agraph
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Eric Kidd
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-18 00:00:00 -05:00
+date: 2011-05-19 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -219,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rdf-agraph
-rubygems_version: 1.5.2
+rubygems_version: 1.4.1
 signing_key: 
 specification_version: 3
 summary: AllegroGraph adapter for RDF.rb