rdf 0.2.3 → 0.3.0.pre

data/lib/rdf/transaction.rb

@@ -0,0 +1,161 @@
+module RDF
+  ##
+  # An RDF transaction.
+  #
+  # Transactions consist of a sequence of RDF statements to delete from and
+  # a sequence of RDF statements to insert into a given named graph.
+  #
+  # @example Executing a transaction against a repository
+  #   repository = ...
+  #   RDF::Transaction.execute(repository) do |tx|
+  #     subject = RDF::URI("http://example.org/article")
+  #     tx.delete [subject, RDF::DC.title, "Old title"]
+  #     tx.insert [subject, RDF::DC.title, "New title"]
+  #   end
+  #
+  # @since 0.3.0
+  class Transaction
+    include RDF::Mutable
+
+    ##
+    # Executes a transaction against the given RDF repository.
+    #
+    # @param  [RDF::Repository]         repository
+    # @param  [Hash{Symbol => Object}]  options
+    # @yield  [tx]
+    # @yieldparam [RDF::Transaction] tx
+    # @return [void]
+    def self.execute(repository, options = {}, &block)
+      self.new(&block).execute(repository, options)
+    end
+
+    ##
+    # RDF graph to modify when executed.
+    #
+    # @return [RDF::Resource]
+    attr_reader :graph
+
+    ##
+    # RDF statements to delete when executed.
+    #
+    # @return [RDF::Enumerable]
+    attr_reader :deletes
+
+    ##
+    # RDF statements to insert when executed.
+    #
+    # @return [RDF::Enumerable]
+    attr_reader :inserts
+
+    ##
+    # Any additional options for this transaction.
+    #
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    ##
+    # Initializes this transaction.
+    #
+    # @param  [Hash{Symbol => Object}]  options
+    # @option options [RDF::Resource]   :graph  (nil)
+    # @option options [RDF::Enumerable] :insert (RDF::Graph.new)
+    # @option options [RDF::Enumerable] :delete (RDF::Graph.new)
+    # @yield  [tx]
+    # @yieldparam [RDF::Transaction] tx
+    def initialize(options = {}, &block)
+      @options = options.dup
+      @graph   = @options.delete(:graph)  || @options.delete(:context)
+      @inserts = @options.delete(:insert) || RDF::Graph.new
+      @deletes = @options.delete(:delete) || RDF::Graph.new
+      @inserts.extend(RDF::Enumerable) unless @inserts.kind_of?(RDF::Enumerable)
+      @deletes.extend(RDF::Enumerable) unless @deletes.kind_of?(RDF::Enumerable)
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
+    end
+
+    ##
+    # Returns `false` to indicate that this transaction is append-only.
+    #
+    # Transactions do not support the `RDF::Enumerable` protocol directly.
+    # To enumerate the RDF statements to be inserted or deleted, use the
+    # {#inserts} and {#deletes} accessors.
+    #
+    # @return [Boolean]
+    # @see    RDF::Readable#readable?
+    def readable?
+      false
+    end
+
+    ##
+    # Executes this transaction against the given RDF repository.
+    #
+    # @param  [RDF::Repository]         repository
+    # @param  [Hash{Symbol => Object}]  options
+    # @return [void]
+    def execute(repository, options = {})
+      before_execute(repository, options) if respond_to?(:before_execute)
+
+      deletes.each_statement do |statement|
+        statement = statement.dup
+        statement.context = graph
+        repository.delete(statement)
+      end
+
+      inserts.each_statement do |statement|
+        statement = statement.dup
+        statement.context = graph
+        repository.insert(statement)
+      end
+
+      after_execute(repository, options) if respond_to?(:after_execute)
+      self
+    end
+
+    ##
+    # Returns a developer-friendly representation of this transaction.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(graph: %s, deletes: %d, inserts: %d)>", self.class.name, __id__,
+        graph ? graph.to_s : 'nil', deletes.count, inserts.count)
+    end
+
+    ##
+    # Outputs a developer-friendly representation of this transaction to
+    # `stderr`.
+    #
+    # @return [void]
+    def inspect!
+      warn(inspect)
+    end
+
+    ##
+    # Appends an RDF statement to the sequence to insert when executed.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @see    RDF::Writable#insert_statement
+    def insert_statement(statement)
+      inserts << statement
+    end
+
+    ##
+    # Appends an RDF statement to the sequence to delete when executed.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @see    RDF::Mutable#delete_statement
+    def delete_statement(statement)
+      deletes << statement
+    end
+
+    undef_method :load, :update, :clear
+    protected :insert_statement
+    protected :delete_statement
+  end # Transaction
+end # RDF

data/lib/rdf/util/cache.rb

@@ -7,6 +7,11 @@ module RDF; module Util
   # evicting most objects if memory pressure increases to the point of
   # scarcity.
   #
+  # While this cache is something of an internal implementation detail of
+  # RDF.rb, some external libraries do currently make use of it as well,
+  # including [Spira](http://spira.rubyforge.org/). Do be sure to include
+  # any changes here in the RDF.rb changelog.
+  #
   # @see   RDF::URI.intern
   # @see   http://en.wikipedia.org/wiki/Weak_reference
   # @since 0.2.0

data/lib/rdf/util/file.rb

@@ -0,0 +1,31 @@
+module RDF; module Util
+  ##
+  # Wrapper for Kernel.open. Allows implementations to override to get
+  # more suffisticated behavior for HTTP resources
+  #
+  # Classes include this module when they represent some form of a file
+  # as a base resource, for instance an HTTP resource representing the
+  # serialization of a Graph.
+  #
+  # This module may be monkey-patched to allow for more options
+  # and interfaces.
+  #
+  # @since 0.2.4
+  module File
+    # Content
+    # @return [String] 
+    attr_accessor :content_type
+    
+    ##
+    # Open the file, returning or yielding an IO stream and mime_type.
+    #
+    # @param [String] filename_or_url to open
+    # @param  [Hash{Symbol => Object}] options
+    #   any options to pass through to the underlying UUID library
+    # @return [IO] File stream
+    # @yield [IO] File stream
+    def self.open_file(filename_or_url, options = {}, &block)
+      Kernel.open(filename_or_url, &block)
+    end
+  end # File
+end; end # RDF::Util

data/lib/rdf/util/uuid.rb

@@ -0,0 +1,36 @@
+module RDF; module Util
+  ##
+  # Utilities for UUID handling.
+  #
+  # @see http://en.wikipedia.org/wiki/Universally_unique_identifier
+  module UUID
+    ##
+    # Generates a UUID string.
+    #
+    # This will make use of either the [UUID][] gem or the [UUIDTools][]
+    # gem, whichever of the two happens to be available.
+    #
+    # [UUID]:      http://rubygems.org/gems/uuid
+    # [UUIDTools]: http://rubygems.org/gems/uuidtools
+    #
+    # @param  [Hash{Symbol => Object}] options
+    #   any options to pass through to the underlying UUID library
+    # @return [String] a UUID string
+    # @raise  [LoadError] if no UUID library is available
+    # @see    http://rubygems.org/gems/uuid
+    # @see    http://rubygems.org/gems/uuidtools
+    def self.generate(options = {})
+      begin
+        require 'uuid'
+        ::UUID.generate(options[:format] || :default)
+      rescue LoadError => e
+        begin
+          require 'uuidtools'
+          ::UUIDTools::UUID.random_create.hexdigest
+        rescue LoadError => e
+          raise LoadError.new("no such file to load -- uuid or uuidtools")
+        end
+      end
+    end
+  end # UUID
+end; end # RDF::Util

data/lib/rdf/util.rb

@@ -1,4 +1,6 @@
 module RDF; module Util
   autoload :Aliasing, 'rdf/util/aliasing'
   autoload :Cache,    'rdf/util/cache'
+  autoload :File,     'rdf/util/file'
+  autoload :UUID,     'rdf/util/uuid'
 end; end

data/lib/rdf/version.rb

@@ -1,9 +1,9 @@
 module RDF
   module VERSION
     MAJOR = 0
-    MINOR = 2
-    TINY  = 3
-    EXTRA = nil
+    MINOR = 3
+    TINY  = 0
+    EXTRA = :pre
 
     STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
 

data/lib/rdf/vocab.rb

@@ -80,7 +80,7 @@ module RDF
     # Returns the URI for the term `property` in this vocabulary.
     #
     # @param  [#to_s] property
-    # @return [URI]
+    # @return [RDF::URI]
     def self.[](property)
       RDF::URI.intern([to_s, property.to_s].join(''))
     end
@@ -88,7 +88,7 @@ module RDF
     ##
     # Returns the base URI for this vocabulary class.
     #
-    # @return [URI]
+    # @return [RDF::URI]
     def self.to_uri
       RDF::URI.intern(to_s)
     end
@@ -119,11 +119,20 @@ module RDF
       alias_method :__name__, :name
     end
 
+    ##
+    # Returns a suggested CURIE/QName prefix for this vocabulary class.
+    #
+    # @return [Symbol]
+    # @since  0.3.0
+    def self.__prefix__
+      self.__name__.split('::').last.downcase.to_sym
+    end
+
     # Undefine all superfluous instance methods:
     undef_method(*(instance_methods.map(&:to_sym) - [:__id__, :__send__, :__class__, :__eval__, :object_id, :instance_eval, :inspect, :class, :is_a?]))
 
     ##
-    # @param  [URI, String, #to_s]
+    # @param  [RDF::URI, String, #to_s]
     def initialize(uri)
       @uri = case uri
         when RDF::URI then uri.to_s
@@ -164,44 +173,43 @@ module RDF
       sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, to_s)
     end
 
-    protected
+  protected
 
-      def self.create(uri) # @private
-        @@uri = uri
-        self
-      end
+    def self.create(uri) # @private
+      @@uri = uri
+      self
+    end
 
-      def self.inherited(subclass) # @private
-        @@subclasses << subclass
-        unless @@uri.nil?
-          subclass.send(:private_class_method, :new)
-          @@uris[subclass] = @@uri
-          @@uri = nil
-        end
-        super
+    def self.inherited(subclass) # @private
+      @@subclasses << subclass
+      unless @@uri.nil?
+        subclass.send(:private_class_method, :new)
+        @@uris[subclass] = @@uri
+        @@uri = nil
       end
+      super
+    end
 
-      def self.method_missing(property, *args, &block)
-        if args.empty? && @@uris.has_key?(self)
-          self[property]
-        else
-          super
-        end
+    def self.method_missing(property, *args, &block)
+      if args.empty? && @@uris.has_key?(self)
+        self[property]
+      else
+        super
       end
+    end
 
-      def method_missing(property, *args, &block)
-        if args.empty?
-          self[property]
-        else
-          raise ArgumentError.new("wrong number of arguments (#{args.size} for 0)")
-        end
+    def method_missing(property, *args, &block)
+      if args.empty?
+        self[property]
+      else
+        raise ArgumentError.new("wrong number of arguments (#{args.size} for 0)")
       end
+    end
 
-    private
-
-      @@subclasses = [::RDF] # @private
-      @@uris       = {}      # @private
-      @@uri        = nil     # @private
+  private
 
-  end
-end
+    @@subclasses = [::RDF] # @private
+    @@uris       = {}      # @private
+    @@uri        = nil     # @private
+  end # Vocabulary
+end # RDF