update.rb in sparql-client-1.1.6

- old
+ new

@@ -1,29 +1,131 @@
 class SPARQL::Client
   ##
   # SPARQL 1.1 Update operation builders.
   module Update
+    ##
+    # Insert statements into the graph
+    #
+    # @example INSERT DATA \{ <http://example.org/jhacker> <http://xmlns.com/foaf/0.1/name> \"J. Random Hacker\" .\}
+    #   data = RDF::Graph.new do |graph|
+    #     graph << [RDF::URI('http://example.org/jhacker'), RDF::FOAF.name, "J. Random Hacker"]
+    #   end
+    #   insert_data(data)
+    #
+    # @example INSERT DATA \{ GRAPH <http://example.org/> \{\}\}
+    #   insert_data(RDF::Graph.new, :graph => 'http://example.org/')
+    #   insert_data(RDF::Graph.new).graph('http://example.org/')
+    #
+    # @param (see InsertData#initialize)
     def self.insert_data(*arguments)
       InsertData.new(*arguments)
     end
 
+    ##
+    # Delete statements from the graph
+    #
+    # @example DELETE DATA \{ <http://example.org/jhacker> <http://xmlns.com/foaf/0.1/name> \"J. Random Hacker\" .\}
+    #   data = RDF::Graph.new do |graph|
+    #     graph << [RDF::URI('http://example.org/jhacker'), RDF::FOAF.name, "J. Random Hacker"]
+    #   end
+    #   delete_data(data)
+    #
+    # @example DELETE DATA \{ GRAPH <http://example.org/> \{\}\}
+    #   delete_data(RDF::Graph.new, :graph => 'http://example.org/')
+    #   delete_data(RDF::Graph.new).graph('http://example.org/')
+    #
+    # @param (see DeleteData#initialize)
     def self.delete_data(*arguments)
       DeleteData.new(*arguments)
     end
 
+    ##
+    # Load statements into the graph
+    #
+    # @example LOAD <http://example.org/data.rdf>
+    #   load(RDF::URI(http://example.org/data.rdf))
+    #
+    # @example LOAD SILENT <http://example.org/data.rdf>
+    #   load(RDF::URI(http://example.org/data.rdf)).silent
+    #   load(RDF::URI(http://example.org/data.rdf), silent: true)
+    #
+    # @example LOAD <http://example.org/data.rdf> INTO <http://example.org/data.rdf>
+    #   load(RDF::URI(http://example.org/data.rdf)).into(RDF::URI(http://example.org/data.rdf))
+    #   load(RDF::URI(http://example.org/data.rdf), into: RDF::URI(http://example.org/data.rdf))
+    #
+    # @param (see Load#initialize)
     def self.load(*arguments)
       Load.new(*arguments)
     end
 
+    ##
+    # Load statements into the graph
+    #
+    # @example CLEAR GRAPH <http://example.org/data.rdf>
+    #   clear.graph(RDF::URI(http://example.org/data.rdf))
+    #   clear(:graph, RDF::URI(http://example.org/data.rdf))
+    #
+    # @example CLEAR DEFAULT
+    #   clear.default
+    #   clear(:default)
+    #
+    # @example CLEAR NAMED
+    #   clear.named
+    #   clear(:named)
+    #
+    # @example CLEAR ALL
+    #   clear.all
+    #   clear(:all)
+    #
+    # @example CLEAR SILENT ALL
+    #   clear.all.silent
+    #   clear(:all, silent: true)
+    #
+    # @param (see Clear#initialize)
     def self.clear(*arguments)
       Clear.new(*arguments)
     end
 
+    ##
+    # Create a graph
+    #
+    # @example CREATE GRAPH <http://example.org/data.rdf>
+    #   create(RDF::URI(http://example.org/data.rdf))
+    #
+    # @example CREATE SILENT GRAPH <http://example.org/data.rdf>
+    #   create(RDF::URI(http://example.org/data.rdf)).silent
+    #   create(RDF::URI(http://example.org/data.rdf), silent: true)
+    #
+    # @param (see Create#initialize)
     def self.create(*arguments)
       Create.new(*arguments)
     end
 
+    ##
+    # Drop a graph
+    #
+    # @example DROP GRAPH <http://example.org/data.rdf>
+    #   drop.graph(RDF::URI(http://example.org/data.rdf))
+    #   drop(:graph, RDF::URI(http://example.org/data.rdf))
+    #
+    # @example DROP DEFAULT
+    #   drop.default
+    #   drop(:default)
+    #
+    # @example DROP NAMED
+    #   drop.named
+    #   drop(:named)
+    #
+    # @example DROP ALL
+    #   drop.all
+    #   drop(:all)
+    #
+    # @example DROP ALL SILENT
+    #   drop.all.silent
+    #   drop(:all, silent: true)
+    #
+    # @param (see Drop#initialize)
     def self.drop(*arguments)
       Drop.new(*arguments)
     end
 
     class Operation
@@ -37,40 +139,59 @@
       end
 
       ##
       # Generic Update always returns statements
       #
-      # @return expects_statements?
+      # @return [true]
       def expects_statements?
         true
       end
 
+      ##
+      # Set `silent` option
       def silent
         self.options[:silent] = true
         self
       end
     end
 
     ##
     # @see http://www.w3.org/TR/sparql11-update/#insertData
     class InsertData < Operation
+      # @return [RDF::Enumerable]
       attr_reader :data
 
+      ##
+      # Insert statements into the graph
+      #
+      # @example INSERT DATA \{ <http://example.org/jhacker> <http://xmlns.com/foaf/0.1/name> \"J. Random Hacker\" .\}
+      #   data = RDF::Graph.new do |graph|
+      #     graph << [RDF::URI('http://example.org/jhacker'), RDF::FOAF.name, "J. Random Hacker"]
+      #   end
+      #   insert_data(data)
+      #   
+      # @param [Array<RDF::Statement>, RDF::Enumerable] data
+      # @param  [Hash{Symbol => Object}] options
       def initialize(data, options = {})
         @data = data
         super(options)
       end
 
+      ##
+      # Cause data to be inserted into the graph specified by `uri`
+      #
+      # @param [RDF::URI] uri
+      # @return [self]
       def graph(uri)
         self.options[:graph] = uri
         self
       end
 
       ##
       # InsertData always returns result set
       #
-      # @return expects_statements?
+      # @return [true]
       def expects_statements?
         false
       end
 
       def to_s
@@ -84,17 +205,34 @@
     end
 
     ##
     # @see http://www.w3.org/TR/sparql11-update/#deleteData
     class DeleteData < Operation
+      # @return [RDF::Enumerable]
       attr_reader :data
 
+      ##
+      # Delete statements from the graph
+      #
+      # @example DELETE DATA \{ <http://example.org/jhacker> <http://xmlns.com/foaf/0.1/name> \"J. Random Hacker\" .\}
+      #   data = RDF::Graph.new do |graph|
+      #     graph << [RDF::URI('http://example.org/jhacker'), RDF::FOAF.name, "J. Random Hacker"]
+      #   end
+      #   delete_data(data)
+      #   
+      # @param [Array<RDF::Statement>, RDF::Enumerable] data
+      # @param  [Hash{Symbol => Object}] options
       def initialize(data, options = {})
         @data = data
         super(options)
       end
 
+      ##
+      # Cause data to be deleted from the graph specified by `uri`
+      #
+      # @param [RDF::URI] uri
+      # @return [self]
       def graph(uri)
         self.options[:graph] = uri
         self
       end
 
@@ -120,10 +258,15 @@
         @insert_graph = _insert_graph
         @where_graph = _where_graph
         super(options)
       end
 
+      ##
+      # Cause data to be deleted and inserted from the graph specified by `uri`
+      #
+      # @param [RDF::URI] uri
+      # @return [self]
       def graph(uri)
         self.options[:graph] = uri
         self
       end
 
@@ -161,19 +304,42 @@
     # @see http://www.w3.org/TR/sparql11-update/#load
     class Load < Operation
       attr_reader :from
       attr_reader :into
 
+
+      ##
+      # Load statements into the graph
+      #
+      # @example LOAD <http://example.org/data.rdf>
+      #   load(RDF::URI(http://example.org/data.rdf))
+      #
+      # @example LOAD SILENT<http://example.org/data.rdf>
+      #   load(RDF::URI(http://example.org/data.rdf)).silent
+      #   load(RDF::URI(http://example.org/data.rdf), silent: true)
+      #
+      # @example LOAD <http://example.org/data.rdf> INTO <http://example.org/data.rdf>
+      #   load(RDF::URI(http://example.org/data.rdf)).into(RDF::URI(http://example.org/data.rdf))
+      #   load(RDF::URI(http://example.org/data.rdf), into: RDF::URI(http://example.org/data.rdf))
+      # @param [RDF::URI] from
+      # @param  [Hash{Symbol => Object}] options
+      # @option [RDF::URI] :into
+      # @option [Boolean] :silent
       def initialize(from, options = {})
         options = options.dup
         @from = RDF::URI(from)
         @into = RDF::URI(options.delete(:into)) if options[:into]
         super(options)
       end
 
-      def into(url)
-        @into = RDF::URI(url)
+      ##
+      # Cause data to be loaded into graph specified by `uri`
+      #
+      # @param [RDF::URI] uri
+      # @return [self]
+      def into(uri)
+        @into = RDF::URI(uri)
         self
       end
 
       def to_s
         query_text = 'LOAD '
@@ -187,34 +353,51 @@
     ##
     # @see http://www.w3.org/TR/sparql11-update/#clear
     class Clear < Operation
       attr_reader :uri
 
+      ##
+      # Cause data to be cleared from graph specified by `uri`
+      #
+      # @param [RDF::URI] uri
+      # @return [self]
       def graph(uri)
         @what, @uri = :graph, uri
         self
       end
 
+      ##
+      # Cause data to be cleared from the default graph
+      #
+      # @return [self]
       def default
         @what = :default
         self
       end
 
+      ##
+      # Cause data to be cleared from named graphs
+      #
+      # @return [self]
       def named
         @what = :named
         self
       end
 
+      ##
+      # Cause data to be cleared from all graphs
+      #
+      # @return [self]
       def all
         @what = :all
         self
       end
 
       ##
       # Clear always returns statements
       #
-      # @return expects_statements?
+      # @return [false]
       def expects_statements?
         false
       end
 
       def to_s
@@ -234,9 +417,10 @@
     ##
     # @see http://www.w3.org/TR/sparql11-update/#create
     class Create < Operation
       attr_reader :uri
 
+      # @param  [Hash{Symbol => Object}] options
       def initialize(uri, options = {})
         @uri = RDF::URI(uri)
         super(options)
       end
 