rdf-agraph 0.3.0

data/lib/rdf/allegro_graph/query/prolog_literal.rb

@@ -0,0 +1,29 @@
+class RDF::AllegroGraph::Query
+  # A literal value which can be passed as an argument to a Prolog functor.
+  #
+  # @see @FunctorExpression
+  class PrologLiteral
+    # Constract a new Prolog literal.
+    #
+    # @param [Object] value A Ruby value.
+    def initialize(value)
+      @value = value
+    end
+
+    # Serialize this literal as a string.  We need to be careful about
+    # security here: Our callers might try to pass in untrustworthy values
+    # without thinking through the consequences, and we want to limit the
+    # damage.  We assume that all symbols are trustworthy.
+    #
+    # @return [String]
+    def to_s
+      case @value
+      when Symbol, Numeric
+        @value.to_s
+      else
+        err = "Don't know how to serialize #{@value.inspect} securely"
+        raise ArgumentError.new(err)
+      end
+    end
+  end
+end

data/lib/rdf/allegro_graph/query.rb

@@ -0,0 +1,124 @@
+module RDF::AllegroGraph
+
+  # A query with AllegroGraph-specific extensions.
+  #
+  # Note that many of of the more exotic features of this class can only be
+  # used when running Prolog queries against a Session object.  This
+  # requires both elevated AllegroGraph privileges and dedicated back-end
+  # session resources on the server, so plan accordingly.
+  #
+  # The Functors module contains a wide variety of functors which may be
+  # used when building a Prolog query.
+  #
+  # @see AbstractRepository#build_query
+  # @see Functors
+  class Query < RDF::Query
+    autoload :PrologLiteral, 'rdf/allegro_graph/query/prolog_literal'
+    autoload :FunctorExpression, 'rdf/allegro_graph/query/functor_expression'
+
+    # Include our APIs.
+    include Functors::SnaFunctors
+
+    # Create a new query.
+    # @private
+    def initialize(repository, &block)
+      @repository = repository
+      super(&block)
+    end
+
+    # Run this query against the associated repository.  This method exists
+    # solely to make the following API pleasant to use:
+    #
+    #     repo.build_query do |q|
+    #       q.pattern [:s, :p, :o]
+    #     end.run do |solution|
+    #       puts solution
+    #     end
+    #
+    # Note that this function returns an Enumerator, not an array, because
+    # RDF.rb is committed to streaming results gradually.  If you want to
+    # treat the result as an array, call 'to_a' explicitly:
+    #
+    #     solutions = repo.build_query do |q|
+    #       q.pattern [:s, :p, :o]
+    #     end.run.to_a
+    #
+    # If you forget to do this, you will run a new query each time you
+    # attempt to iterate over the solutions!
+    #
+    # @overload run
+    #   @return [Enumerator<RDF::Query::Solution>]
+    #
+    # @overload run
+    #   @yield solution
+    #   @yieldparam [RDF::Query::Solution]
+    #   @yieldreturn [void]
+    #   @return [void]
+    #
+    # @see Repository#query
+    # @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 run(&block)
+      @repository.query(self, &block)
+    end
+
+    # Add a functor expression to this query.  Functors can only be used
+    # in Prolog queries.
+    #
+    # @param [String] name
+    # @param [Array<Symbol,RDF::Value,value>] arguments
+    #   The arguments to the functor, which may be either variables,
+    #   RDF::Value objects, or Ruby values that we can convert to literals.
+    # @return [void]
+    def functor(name, *arguments)
+      # TODO: Don't abuse duck-typing quite so much.
+      patterns <<
+        RDF::AllegroGraph::Query::FunctorExpression.new(name, *arguments)
+    end
+
+    # Does this query contain Prolog-specific functors that we can't
+    # represent as SPARQL?
+    #
+    # @return [Boolean]
+    def requires_prolog?
+      !patterns.all? {|p| p.kind_of?(RDF::Query::Pattern) }
+    end
+
+    # Convert this query to AllegoGraph Prolog notation.
+    #
+    # @param [RDF::AllegroGraph::Repository] repository
+    # @return [String]
+    # @private
+    def to_prolog(repository)
+      variables = []
+      functors = []
+      patterns.each do |p|
+        # Extract any new variables we see in the query.
+        p.variables.each {|_,v| variables << v unless variables.include?(v) }
+        functors << convert_to_functor(p).to_prolog(repository)
+      end
+      "(select (#{variables.join(" ")})\n  #{functors.join("\n  ")})"
+    end
+
+    protected
+
+    # Convert patterns to functors (and leave functors unchanged).
+    #
+    # @param [RDF::Query::Pattern,FunctorExpression] pattern_or_functor
+    # @return [FunctorExpression]
+    # @private
+    def convert_to_functor(pattern_or_functor)
+      case pattern_or_functor
+      when FunctorExpression then pattern_or_functor
+      else
+      p = pattern_or_functor
+        if p.optional? || p.context
+          raise ArgumentError.new("Can't translate #{p} to Prolog functor")
+        end
+        FunctorExpression.new('q-', p.subject, p.predicate, p.object)
+      end
+    end
+  end
+end

data/lib/rdf/allegro_graph/repository.rb

@@ -0,0 +1,81 @@
+require 'pathname'
+
+module RDF::AllegroGraph
+  # An AllegroGraph RDF repository.
+  #
+  # Note that this class does not interoperate well with the Unix `fork`
+  # command if you're using blank nodes.  See README.md for details.
+  class Repository < AbstractRepository
+    # Create a new AllegroGraph repository adapter.
+    #
+    # @overload initialize(options)
+    #   @param [Hash{Symbol => Object}] options
+    #   @option options [Server]  :server  The server hosting the repository.
+    #   @option options [String]  :id      The name of the repository.
+    #   @option options [Boolean] :create  Create the repository if necessary?
+    #
+    # @overload initialize(url, options)
+    #   @param [String] url                The URL of the repository.
+    #   @param [Hash{Symbol => Object}] options
+    #   @option options [Boolean] :create  Create the repository if necessary?
+    def initialize(url_or_options, options={})
+      case url_or_options
+      when String
+        # TODO: Clean this up.
+        url = URI.parse(url_or_options)
+        path = Pathname.new(url.path)
+        url.path = path.parent.parent.to_s
+        server = Server.new(url.to_s).server
+        id = path.basename
+      else
+        server = url_or_options[:server].server
+        id = url_or_options[:id]
+        options = url_or_options
+      end
+      super(::AllegroGraph::Repository.new(server, id))
+      @repo.create_if_missing! if options[:create]
+    end
+
+    # Delete this repository if it exists.
+    #
+    # @return [void]
+    def delete!
+      @repo.delete!
+    end
+
+    # Create a new, persistent AllegroGraph session.  If called without a
+    # block, simply returns the new session (and expects the caller to
+    # close it).  If called with a block, automatically commits or rolls
+    # back the transaction, and closes the session.
+    #
+    # @overload session
+    #   @return [Session] The newly created session.  It's a good idea to
+    #     close this manually; doing so frees up server resources.
+    #   @see Session#commit
+    #   @see Session#rollback
+    #   @see Session#close
+    #
+    # @overload session
+    #   @yield session
+    #   @yieldparam [Session] session
+    #   @yieldreturn [Object]
+    #   @return [Object] The result returned from the block.
+    def session
+      if block_given?
+        session = Session.new(@repo)
+        begin
+          result = yield session
+          session.commit
+          result
+        rescue => e
+          session.rollback
+          raise
+        ensure
+          session.close
+        end
+      else
+        Session.new(@repo)
+      end
+    end
+  end
+end

data/lib/rdf/allegro_graph/server.rb

@@ -0,0 +1,93 @@
+module RDF::AllegroGraph
+  # An AllegroGraph server containing several repositories.  We attempt to
+  # mimic the public API of RDF::Sesame::Server for the sake of
+  # convenience, though we do not implement several internal methods, and
+  # we generally attempt to raise errors when we can't connect to the
+  # server, unlike RDF::Sesame::Server, which just returns default values.
+  #
+  # @see RDF::Sesame::Server
+  class Server
+    attr_reader :server # @private
+
+    # Create a new Server object.
+    #
+    # @param [String] url The Sesame URL of the AllegroGraph server.
+    def initialize(url="http://localhost:10035")
+      parsed = URI.parse(url)
+      options = {
+        :host => parsed.host, :post => parsed.port,
+        :username => parsed.user, :password => parsed.password
+      }
+      @server = AllegroGraph::Server.new(options)
+      
+      unless parsed.path.nil? || parsed.path.empty? || parsed.path == "/"
+        err = "AllegroGraph URLs with paths not supported: #{url}"
+        raise ArgumentError.new(err)
+      end
+    end
+
+    # Get the protocol version supported by this server.
+    #
+    # @return [Integer]
+    def protocol
+      @server.request_http(:get, path(:protocol),
+                           :expected_status_code => 200).to_i
+    end
+    alias_method :protocol_version, :protocol
+
+    # Return a hash table of all repositories on this server.
+    #
+    # @return [Hash<String,Repository>]
+    def repositories
+      result = {}
+      @server.request_json(:get, path(:repositories),
+                           :expected_status_code => 200).each do |repo|
+        result[repo['id']] = Repository.new(:server => self, :id => repo['id'])
+      end
+      result
+    end
+
+    # Return true if the specified repository exists on the server.
+    #
+    # @param [String] id The name of the repository.
+    # @return [Boolean]
+    def has_repository?(id)
+      repositories.has_key?(id)
+    end
+
+    # Iterate over all repositories.
+    #
+    # @yield repository
+    # @yieldparam [Repository] repository
+    # @yieldreturn [void]
+    # @return [void]
+    def each_repository(&block)
+      repositories.values.each(&block)
+    end
+    alias_method :each, :each_repository
+
+    # Look up a specific repository by name, and optionally create it.
+    #
+    # @param [String] id The name of the repository.
+    # @param [Hash] options
+    # @option options [Boolean] :create
+    #   If true, and the repository does not exist, create it.
+    # @return [Repository,nil]
+    #   The repository, if it exists or was created, or nil otherwise.
+    def repository(id, options={})
+      result = repositories[id]
+      if result.nil? && options[:create]
+        result = Repository.new(:server => self, :id => id, :create => true)
+      end
+      result
+    end
+    alias_method :[], :repository
+
+    protected
+
+    # Generate a path to a resource on the server.
+    def path(relativate_path) # @private
+      "/#{relativate_path}"
+    end
+  end
+end

data/lib/rdf/allegro_graph/session.rb

@@ -0,0 +1,78 @@
+module RDF::AllegroGraph
+
+  # A persistent AllegroGraph session.  This takes up more server resources
+  # than a normal stateless repository connection, but it allows access to
+  # advanced AllegroGraph features.
+  #
+  # Note that this class does not interoperate well with the Unix `fork`
+  # command if you're using blank nodes.  See README.md for details.
+  #
+  # @see Repository#session
+  class Session < AbstractRepository
+    # Create a new session.  This parameter takes an
+    # ::AllegroGraph::Repository object as an argument, so we've not going
+    # to document it publically.
+    #
+    # @private
+    def initialize(agraph_repo)
+      super(::AllegroGraph::Session.create(agraph_repo))
+      @last_unique_id = 0
+    end
+
+    # Explicitly close the current session and release all server resources.
+    # This function does _not_ commit any outstanding transactions.
+    #
+    # @return [void]
+    # @see #commit
+    # @see #rollback
+    def close
+      @repo.request_http(:post, path('session/close'),
+                         :expected_status_code => 204)
+    end
+
+    # Commit the current changes to the main repository.
+    #
+    # @return [void]
+    # @see #rollback
+    def commit
+      @repo.commit
+    end
+
+    # Roll back the changes made since the last commit.
+    #
+    # @return [void]
+    # @see #commit
+    def rollback
+      @repo.rollback
+    end
+
+    # Define an SNA generator.
+    #
+    # @param [Hash] options
+    # @option options [RDF::Resource,Array<RDF::Resource>] :object_of
+    #   Follow links defined by specified predicates.
+    # @option options [RDF::Resource,Array<RDF::Resource>] :subject_of
+    #   Follow links defined by specified predicates, but from the object
+    #   to the subject.
+    # @option options [RDF::Resource,Array<RDF::Resource>] :undirected
+    #   Follow links defined by specified predicates in both directions.
+    # @return [Query::PrologLiteral]
+    #   A value which may be used in Prolog queries.
+    #
+    # @see Query#ego_group_member
+    def generator(options)
+      id = unique_id
+      generator = SnaGenerator.new(self, options)
+      @repo.request_json(:put, path("snaGenerators/#{id}"),
+                         :parameters => generator.to_params,
+                         :expected_status_code => 204)
+      Query::PrologLiteral.new(id.to_sym)
+    end
+
+    protected
+
+    def unique_id
+      "id#{@last_unique_id += 1}"
+    end
+  end
+end

data/lib/rdf/allegro_graph/sna_generator.rb

@@ -0,0 +1,37 @@
+module RDF::AllegroGraph
+  # Internal helper class for defining SNA generators.
+  #
+  # @private
+  class SnaGenerator 
+    attr_reader :options
+
+    def initialize(repository, options)
+      @repository = repository
+      @options = options
+    end
+
+    def to_params
+      params = {}
+      params.merge!(option_to_hash(:objectOf, :object_of))
+      params.merge!(option_to_hash(:subjectOf, :subject_of))
+      params.merge!(option_to_hash(:undirected, :undirected))
+      params
+    end
+
+    protected
+
+    def option_to_hash(param_name, option_name)
+      if @options.has_key?(option_name)
+        value = @options[option_name]
+        case value
+        when Array
+          { param_name => value.map {|v| @repository.serialize(v) } }
+        else
+          { param_name => @repository.serialize(value) }
+        end
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/rdf/allegro_graph.rb

@@ -0,0 +1,14 @@
+require 'rdf'
+require 'agraph'
+require 'enumerator'
+
+# AllegroGraph integration for RDF.rb.
+module RDF::AllegroGraph
+  autoload :Query, 'rdf/allegro_graph/query'
+  autoload :Server, 'rdf/allegro_graph/server'
+  autoload :AbstractRepository, 'rdf/allegro_graph/abstract_repository'
+  autoload :Repository, 'rdf/allegro_graph/repository'
+  autoload :SnaGenerator, 'rdf/allegro_graph/sna_generator'
+  autoload :Functors, 'rdf/allegro_graph/functors'
+  autoload :Session, 'rdf/allegro_graph/session'
+end

data/lib/rdf-agraph.rb

@@ -0,0 +1,2 @@
+require 'rdf/allegro_graph'
+

metadata

@@ -0,0 +1,227 @@
+--- !ruby/object:Gem::Specification 
+name: rdf-agraph
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Eric Kidd
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-18 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdf
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 17
+        segments: 
+        - 0
+        - 3
+        - 1
+        version: 0.3.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: agraph
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 0
+        - 1
+        - 4
+        version: 0.1.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 0
+        - 5
+        - 1
+        version: 0.5.1
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rdf-spec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 17
+        segments: 
+        - 0
+        - 3
+        - 1
+        version: 0.3.1
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 6
+        - 0
+        version: 0.6.0
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: BlueCloth
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 21
+        segments: 
+        - 1
+        - 0
+        - 1
+        version: 1.0.1
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 2
+        - 5
+        - 0
+        version: 2.5.0
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 41
+        segments: 
+        - 0
+        - 9
+        - 9
+        version: 0.9.9
+  type: :development
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id009
+description: An AllegroGraph adapter for use with RDF.rb.
+email: rdf-agraph@kiddsoftware.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- AUTHORS
+- README.md
+- UNLICENSE
+- VERSION
+- lib/rdf-agraph.rb
+- lib/rdf/allegro_graph.rb
+- lib/rdf/allegro_graph/server.rb
+- lib/rdf/allegro_graph/functors.rb
+- lib/rdf/allegro_graph/functors/sna_functors.rb
+- lib/rdf/allegro_graph/repository.rb
+- lib/rdf/allegro_graph/query.rb
+- lib/rdf/allegro_graph/abstract_repository.rb
+- lib/rdf/allegro_graph/query/functor_expression.rb
+- lib/rdf/allegro_graph/query/prolog_literal.rb
+- lib/rdf/allegro_graph/sna_generator.rb
+- lib/rdf/allegro_graph/session.rb
+has_rdoc: false
+homepage: http://rdf-agraph.rubyforge.org/
+licenses: 
+- Public Domain
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rdf-agraph
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: AllegroGraph adapter for RDF.rb
+test_files: []
+