rdf_context 0.5.6 → 0.5.7

data/lib/rdf_context/rdfxmlparser.rb

@@ -6,14 +6,38 @@ module RdfContext
     OLD_TERMS = %w(aboutEach aboutEachPrefix bagID).map {|n| "http://www.w3.org/1999/02/22-rdf-syntax-ns##{n}"}
 
     # The Recursive Baggage
+    # @private
     class EvaluationContext # :nodoc:
+      # The base.
+      #
+      # This will usually be the URL of the document being processed,
+      # but it could be some other URL, set by some other mechanism,
+      # such as the (X)HTML base element. The important thing is that it establishes
+      # a URL against which relative paths can be resolved.
+      #
+      # @return [URIRef]
       attr_reader :base
+      # @return [URIRef]
       attr :subject, true
+      # A list of current, in-scope URI mappings.
+      #
+      # @return [Hash{String => Namespace}]
       attr :uri_mappings, true
+      # The language. Note that there is no default language.
+      #
+      # @return [String]
       attr :language, true
+      # Graph for binding Namespaces
+      # @return [Graph]
       attr :graph, true
+      # Counter for creating rdf:_n values
+      # @return [Integer]
       attr :li_counter, true
 
+      # @param [String] base Base URI for creating absolute URIs from relative URIs
+      # @param [Nokogiri::XML::Element] element XML Element context
+      # @param [Graph] graph Graph for binding Namespaces
+      # @return [RdfXmlParser::EvaluationContext]
       def initialize(base, element, graph)
         # Initialize the evaluation context, [5.1]
         self.base = base
@@ -27,6 +51,8 @@ module RdfContext
       end
       
       # Clone existing evaluation context adding information from element
+      # @param [Nokogiri::XML::Element] element XML Element context
+      # @return [RdfXmlParser::EvaluationContext]
       def clone(element, options = {})
         new_ec = EvaluationContext.new(@base, nil, @graph)
         new_ec.uri_mappings = self.uri_mappings.clone
@@ -39,26 +65,32 @@ module RdfContext
       end
       
       # Extract Evaluation Context from an element by looking at ancestors recurively
-      def extract_from_ancestors(el)
-        ancestors = el.ancestors
+      # @param [Nokogiri::XML::Element] element XML Element context
+      # @return [Hash{URIRef => Namespace}]
+      def extract_from_ancestors(element)
+        ancestors = element.ancestors
         while ancestors.length > 0
           a = ancestors.pop
           next unless a.element?
           extract_from_element(a)
         end
-        extract_from_element(el)
+        extract_from_element(element)
       end
 
       # Extract Evaluation Context from an element
-      def extract_from_element(el)
-        b = el.attribute_with_ns("base", XML_NS.uri.to_s)
-        lang = el.attribute_with_ns("lang", XML_NS.uri.to_s)
+      # @param [Nokogiri::XML::Element] element XML Element context
+      # @return [Hash{URIRef => Namespace}]
+      def extract_from_element(element)
+        b = element.attribute_with_ns("base", XML_NS.uri.to_s)
+        lang = element.attribute_with_ns("lang", XML_NS.uri.to_s)
         self.base = URIRef.new(b.to_s.rdf_unescape, self.base, :normalize => false) if b
         self.language = lang if lang
-        self.uri_mappings.merge!(extract_mappings(el))
+        self.uri_mappings.merge!(extract_mappings(element))
       end
       
       # Extract the XMLNS mappings from an element
+      # @param [Nokogiri::XML::Element] element XML Element context
+      # @return [Hash{URIRef => Namespace}]
       def extract_mappings(element)
         mappings = {}
 
@@ -75,6 +107,8 @@ module RdfContext
       end
       
       # Produce the next list entry for this context
+      # @param [URIRef] predicate
+      # @return [URIRef]
       def li_next(predicate)
         @li_counter += 1
         predicate = Addressable::URI.parse(predicate.to_s)
@@ -83,6 +117,8 @@ module RdfContext
       end
 
       # Set XML base. Ignore any fragment
+      # @param [Nokogiri::XML::Element] b
+      # @return [String] b.to_s
       def base=(b)
         b = Addressable::URI.parse(b.to_s)
         b.fragment = nil
@@ -103,12 +139,13 @@ module RdfContext
     #
     # Optionally, the stream may be a string or Nokogiri::XML::Document
     # 
-    # @param [IO] stream:: the RDF/XML IO stream, string or Nokogiri::XML::Document
-    # @param [String] uri:: the URI of the document
-    # @param [Hash] options:: Parser options, one of
-    # <em>options[:debug]</em>:: Array to place debug messages
-    # <em>options[:strict]</em>:: Raise Error if true, continue with lax parsing, otherwise
-    # @return [Graph]:: Returns the graph containing parsed triples
+    # @param  [Nokogiri::XML::Document, #read, #to_s] stream the HTML+RDFa IO stream, string, Nokogiri::HTML::Document or Nokogiri::XML::Document
+    # @param [String] uri (nil) the URI of the document
+    # @option options [Array] :debug (nil) Array to place debug messages
+    # @option options [Boolean] :strict (false) Raise Error if true, continue with lax parsing, otherwise
+    # @return [Graph] Returns the graph containing parsed triples
+    # @yield  [triple]
+    # @yieldparam [Triple] triple
     # @raise [Error]:: Raises RdfError if _strict_
     def parse(stream, uri = nil, options = {}, &block) # :yields: triple
       super

data/lib/rdf_context/serializer/abstract_serializer.rb

@@ -3,8 +3,15 @@ require File.join(File.dirname(__FILE__), '..', 'uriref')
 module RdfContext
   # Abstract serializer
   class AbstractSerializer
-    attr_accessor :graph, :base
+    # @return [Graph]
+    attr_accessor :graph
     
+    # @return [String]
+    attr_accessor :base
+    
+    # New AbstractSerializer
+    # @param [Graph] graph
+    # @return [AbstractSerializer]
     def initialize(graph)
       @graph = graph
       @base = nil
@@ -12,12 +19,15 @@ module RdfContext
     
     # Serialize the graph
     #
-    # @param [IO, StreamIO] stream:: Stream in which to place serialized graph
-    # @param [Hash] options:: Options for parser
-    # <em>options[:base]</em>:: Base URI of graph, used to shorting URI references
+    # @param [IO, StreamIO] stream Stream in which to place serialized graph
+    # @option options [URIRef, String] :base (nil) Base URI of graph, used to shorting URI references
+    # @return [void]
     def serialize(stream, options = {})
     end
     
+    # Create a relative version of the _uri_ parameter if a _base_ URI is defined
+    # @param [#to_s] uri
+    # @return [String]
     def relativize(uri)
       uri = uri.to_s
       self.base ? uri.sub(/^#{self.base}/, "") : uri

data/lib/rdf_context/serializer/nt_serializer.rb

@@ -3,6 +3,11 @@ require File.join(File.dirname(__FILE__), 'abstract_serializer')
 module RdfContext
   # Serialize RDF graphs in NTriples format
   class NTSerializer < AbstractSerializer
+    # Serialize the graph
+    #
+    # @param [IO, StreamIO] stream Stream in which to place serialized graph
+    # @option options [URIRef, String] :base (nil) Base URI of graph, used to shorting URI references
+    # @return [void]
     def serialize(stream, base = nil)
       @graph.triples.collect do |t|
         stream.write(t.to_ntriples + "\n")

data/lib/rdf_context/serializer/recursive_serializer.rb

@@ -8,12 +8,16 @@ module RdfContext
     MAX_DEPTH = 10
     INDENT_STRING = " "
     
+    # New RecursiveSerializer
+    # @param [Graph] graph
+    # @return [RecursiveSerializer]
     def initialize(graph)
       super(graph)
       @stream = nil
       self.reset
     end
 
+    protected
     def top_classes; [RDFS_NS.Class]; end
     def predicate_order; [RDF_TYPE, RDFS_NS.label, DC_NS.title]; end
     

data/lib/rdf_context/serializer/turtle_serializer.rb

@@ -7,6 +7,34 @@ module RdfContext
     VERB = 1
     OBJECT = 2
     
+    # Serialize the graph
+    #
+    # @param [IO, StreamIO] stream Stream in which to place serialized graph
+    # @option options [URIRef, String] :base (nil) Base URI of graph, used to shorting URI references
+    # @return [void]
+    def serialize(stream, options = {})
+      puts "\nserialize: #{@graph.inspect}" if $DEBUG
+      reset
+      @stream = stream
+      @base = options[:base]
+      
+      @graph.bind(RDF_NS)
+      @graph.bind(RDFS_NS)
+      
+      preprocess
+      start_document
+
+      order_subjects.each do |subject|
+        #puts "subj: #{subject.inspect}"
+        unless is_done?(subject)
+          statement(subject)
+        end
+      end
+      
+      end_document
+    end
+
+    protected
     def reset
       super
       @shortNames = {}
@@ -188,32 +216,5 @@ module RdfContext
       subject_done(subject)
       s_squared(subject) || s_default(subject)
     end
-    
-    # Serialize the graph
-    #
-    # @param [IO, StreamIO] stream:: Stream in which to place serialized graph
-    # @param [Hash] options:: Options for parser
-    # <em>options[:base]</em>:: Base URI of graph, used to shorting URI references
-    def serialize(stream, options = {})
-      puts "\nserialize: #{@graph.inspect}" if $DEBUG
-      reset
-      @stream = stream
-      @base = options[:base]
-      
-      @graph.bind(RDF_NS)
-      @graph.bind(RDFS_NS)
-      
-      preprocess
-      start_document
-
-      order_subjects.each do |subject|
-        #puts "subj: #{subject.inspect}"
-        unless is_done?(subject)
-          statement(subject)
-        end
-      end
-      
-      end_document
-    end
   end
 end

data/lib/rdf_context/serializer/xml_serializer.rb

@@ -5,6 +5,9 @@ module RdfContext
   class XmlSerializer < RecursiveSerializer
     VALID_ATTRIBUTES = [:none, :untyped, :typed]
     
+    # New XmlSerializer
+    # @param [Graph] graph
+    # @return [XmlSerializer]
     def initialize(graph)
       super
       @force_RDF_about = {}
@@ -12,16 +15,15 @@ module RdfContext
     
     # Serialize the graph
     #
-    # @param [IO, StreamIO] stream:: Stream in which to place serialized graph
-    # @param [Hash] options:: Options for parser
-    # <em>options[:base]</em>:: Base URI of graph, used to shorting URI references
-    # <em>options[:max_depth]</em>:: Maximum depth for recursively defining resources, defaults to 3
-    # <em>options[:lang]</em>:: Output as root xml:lang attribute, and avoid generation xml:lang where possible
-    # <em>options[:attributes]</em>:: How to use XML attributes when serializing, one of :none, :untyped, :typed. The default is none.
-    #
-    # -- Serialization Examples
-    # attributes == :none
+    # @param [IO, StreamIO] stream Stream in which to place serialized graph
+    # @option options [URIRef, String] :base (nil) Base URI of graph, used to shorting URI references
+    # @option options [Integer] :max_depth (3) Maximum depth for recursively defining resources
+    # @option options [String] :lang (nil) Output as root xml:lang attribute, and avoid generation xml:lang where possible
+    # @option options [:none, :untyped, :typed] :attributes (:none) How to use XML attributes when serializing, one of :none, :untyped, :typed. The default is none.
+    # @return [void]
     #
+    # @example
+    #   attributes == :none
     #   serialize(io, :attributes => none)
     def serialize(stream, options = {})
       @max_depth = options[:max_depth] || 3

data/lib/rdf_context/store/abstract_sql_store.rb

@@ -31,8 +31,10 @@ module RdfContext
     
     STRONGLY_TYPED_TERMS = false
     
-    # @param[URIRef] identifier:: URIRef of the Store. Defaults to CWD
-    # @param[Hash] configuration:: Hash containing infomation open can use to connect to datastore.
+    # Create a new AbstractSQLStore Store, should be subclassed
+    # @param [URIRef] identifier
+    # @param[Hash] configuration Specific to type of storage
+    # @return [AbstractSQLStore]
     def initialize(identifier = nil, configuration = {})
       @literalCache = {}
       @otherCache = {}
@@ -50,14 +52,20 @@ module RdfContext
     end
 
     # Supports contexts
+    # @return [true]
     def context_aware?; true; end
     
     # Supports formulae
+    # @return [true]
     def formula_aware?; true; end
 
     # Supports transactions
+    # @return [true]
     def transaction_aware?; true; end
-    
+
+    # Close the store
+    # @param [Boolean] commit_pending_transactions (false)
+    # @return [void]
     def close(commit_pending_transactions = false)
       @db.commit if commit_pending_transactions && @db.transaction_active?
       @db.close
@@ -65,6 +73,11 @@ module RdfContext
     
     # Add a triple to the store
     # Add to default context, if context is nil
+    #
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @param [Boolean] quoted (false) A quoted triple, for Formulae
+    # @return [Triple]
     def add(triple, context = nil, quoted = false)
       context ||= @identifier
       executeSQL("SET AUTOCOMMIT=0") if @autocommit_default
@@ -87,6 +100,10 @@ module RdfContext
     # Remove a triple from the context and store
     #
     # if subject, predicate and object are nil and context is not nil, the context is removed
+    #
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @return [void]
     def remove(triple, context = nil)
       if context
         if triple.subject == nil && triple.predicate.nil? && triple.object.nil?
@@ -147,7 +164,15 @@ module RdfContext
     # triple columns: subject,predicate,object,context,termComb,objLanguage,objDatatype
     # class membership columns: member,klass,context termComb
     # 
-    # FIXME:  These union all selects *may* be further optimized by joins
+    # @todo  These union all selects *may* be further optimized by joins
+    #
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @return [Array<Triplle>]
+    # @raise [StoreException] Not Implemented
+    # @yield [triple, context]
+    # @yieldparam [Triple] triple
+    # @yieldparam [Graph] context
     def triples(triple, context = nil)  # :yields: triple, context
       parameters = []
       
@@ -261,6 +286,11 @@ module RdfContext
       results.uniq
     end
     
+    # Check to see if this store contains the specified triple
+    #
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @return [Boolean]
     def contains?(triple, context = nil)
       #puts "contains? #{triple}"
       object = triple.object
@@ -276,6 +306,8 @@ module RdfContext
     end
     
     # Number of statements in the store.
+    # @param [Graph] context (nil)
+    # @return [Integer]
     def size(context = nil)
       parameters = []
       quotedContext = assertedContext = typeContext = literalContext = nil
@@ -364,6 +396,8 @@ module RdfContext
     end
 
     # Contexts containing the triple (no matching), or total number of contexts in store
+    # @param [Triple] triple (nil) Containing the triple/pattern if not nil
+    # @return [Array<Graph>]
     def contexts(triple = nil)
       parameters = []
       
@@ -505,6 +539,9 @@ module RdfContext
     # Namespace persistence interface implementation
     #
     # Bind namespace to store, returns bound namespace
+    #
+    # @param [Nameespace] namespace the namespace to bind
+    # @return [Namespace] The newly bound or pre-existing namespace.
     def bind(namespace)
       # Remove existing bindings for the same URI
       executeSQL("DELETE FROM #{namespace_binds} WHERE prefix=?", namespace.prefix.to_s)
@@ -521,6 +558,8 @@ module RdfContext
     end
 
     # Namespace for prefix
+    # @param [String] prefix
+    # @return [Namespace]
     def namespace(prefix)
       @namespaceCache ||= {}
       @namespaceUriCache ||= {}
@@ -535,6 +574,8 @@ module RdfContext
     end
     
     # Prefix for namespace
+    # @param [Namespace] namespcae
+    # @return [String]
     def prefix(namespace)
       uri = namespace.is_a?(Namespace) ? namespace.uri.to_s : namespace
 
@@ -550,6 +591,7 @@ module RdfContext
     end
 
     # Hash of prefix => Namespace bindings
+    # @return [Hash{String => Namespace}]
     def nsbinding
       unless @nsbinding.is_a?(Hash)
         @nsbinding = {}
@@ -568,6 +610,7 @@ module RdfContext
     end
     
     # Hash of uri => Namespace bindings
+    # @return [Hash{URIRef => Namespace}]
     def uri_binding
       nsbinding
       @uri_binding

data/lib/rdf_context/store/abstract_store.rb

@@ -3,6 +3,10 @@ module RdfContext
   class AbstractStore
     attr_reader :nsbinding, :uri_binding, :identifier
     
+    # Create a new AbstractStore Store, should be subclassed
+    # @param [Resource] identifier
+    # @param[Hash] configuration Specific to type of storage
+    # @return [AbstractStore]
     def initialize(identifier = nil, configuration = {})
       @nsbinding = {}
       # Reverse namespace binding
@@ -11,17 +15,54 @@ module RdfContext
       @identifier = identifier || BNode.new
     end
     
+    # Is store Context Aware, capable of being used for named graphs?
+    # @return [false]
     def context_aware?; false; end
+    
+    # Is store Formulae Aware, capable of storing variables?
+    # @return [false]
     def formula_aware?; false; end
+    
+    # Is store Transaction Aware, capable of rollback?
+    # @return [false]
     def transaction_aware?; false; end
 
     # Interfaces that must be implemented
+
+    # A generator over all matching triples
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @return [Array<Triplle>]
+    # @raise [StoreException] Not Implemented
+    # @yield [triple, context]
+    # @yieldparam [Triple] triple
+    # @yieldparam [Graph] context
     def triples(triple, context = nil)  # :yields: triple, context
       raise StoreException, "not implemented"
     end
+    
+    # Add triple to store
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @param [Boolean] quoted (false) A quoted triple, for Formulae
+    # @raise [StoreException] Not Implemented
+    # @return [Triple]
     def add(triple, context = nil, quoted = false); raise StoreException, "not implemented"; end
+    
+    # Remove a triple from the store
+    # @param [Triple] triple
+    # @param [Graph] context (nil)
+    # @raise [StoreException] Not Implemented
+    # @return [void]
     def remove(triple, context = nil); raise StoreException, "not implemented"; end
     
+    # Check to see if this store contains the specified triple
+    # @param [Triple] triple
+    # @param [Graph] context (nil) ignored
+    # @raise [StoreException] Not Implemented
+    # @return [Boolean]
+    def contains?(triple, context = nil); raise StoreException, "not implemented"; end
+
     # Default (sub-optimal) implemenations of interfaces
     def inspect
       "#{self.class}[identifier=#{identifier.inspect}]"
@@ -33,7 +74,11 @@ module RdfContext
     def commit; end
     def rollback; end
 
-    # Bind namespace to store, returns bound namespace
+    ## 
+    # Bind a namespace to the store.
+    #
+    # @param [Nameespace] namespace the namespace to bind
+    # @return [Namespace] The newly bound or pre-existing namespace.
     def bind(namespace)
       # Over-write an empty prefix
       uri = namespace.uri.to_s
@@ -45,16 +90,22 @@ module RdfContext
     end
 
     # Namespace for prefix
+    # @param [String] prefix
+    # @return [Namespace]
     def namespace(prefix)
       @nsbinding[prefix.to_s]
     end
     
     # Prefix for namespace
+    # @param [Namespace] namespcae
+    # @return [String]
     def prefix(namespace)
       namespace.is_a?(Namespace) ? @uri_binding[namespace.uri.to_s].prefix : @uri_binding[namespace].prefix
     end
     
     # Get all BNodes with usage count used within graph
+    # @param [Graph] context (nil)
+    # @return [Array<BNode>]
     def bnodes(context = nil)
       bn = {}
       triples(Triple.new(nil, nil, nil), context) do |t, ctx|
@@ -74,10 +125,31 @@ module RdfContext
       bn
     end
 
+    
+    # Number of Triples in the graph
+    # @param [Graph] context (nil)
+    # @return [Integer]
     def size(context = nil); triples(Triple.new(nil, nil, nil), context).size; end
+
+    # List of distinct subjects in graph
+    # @param [Graph] context (nil)
+    # @return [Array<Resource>]
     def subjects(context = nil); triples(Triple.new(nil, nil, nil), context).map {|t| t.subject}.uniq; end
+    
+    # List of distinct predicates in graph
+    # @param [Graph] context (nil)
+    # @return [Array<Resource>]
     def predicates(context = nil); triples(Triple.new(nil, nil, nil), context).map {|t| t.predicate}.uniq; end
+    
+    # List of distinct objects in graph
+    # @param [Graph] context (nil)
+    # @return [Array<Resource>]
     def objects(context = nil); triples(Triple.new(nil, nil, nil), context).map {|t| t.object}.uniq; end
+    
+    # Return an indexed element from the graph
+    # @param [Integer] item Index into the serialized store
+    # @param [Graph] context
+    # @return [Array<Triple>]
     def item(item, context = nil) triples(Triple.new(nil, nil, nil), context)[item]; end
   end
 end