grel 0.1.0 → 0.1.1

data/lib/grel/base.rb

@@ -1,5 +1,6 @@
 module GRel
 
+  # Base class for the graph of ruby objects stored in Stardog
   class Base
 
     include Stardog
@@ -7,6 +8,15 @@ module GRel
     attr_accessor :connection, :last_query_context
     attr_reader :db_name, :schema_graph
 
+    # Builds the graph with the provided connection string and options.
+    # - endpoint : connection string. localhost:5822 by default.
+    # - options: hash of options:
+    # Valid options are:
+    # - user : user name for authentication
+    # - password : password for authentication
+    # - validate : should validate integrity constraints
+    # - db : name of the db to use
+    # Returns the newly built graph object.
     def initialize(endpoint, options) 
       @options = options
       @endpoint = endpoint
@@ -17,6 +27,12 @@ module GRel
       self
     end
 
+    # Turns on reasoning in queries.
+    # The type of reasoning must be provided as an argument.
+    # By default 'QL' is provided.
+    # Reasoning will remain turned on for all operations in the graph until it is
+    # explicitely turned off with the +without_reasoning+ message.
+    # It returns the current graph object.
     def with_reasoning(reasoning="QL")
       @reasoning = true
       @connection = stardog(@endpoint,@options.merge(:reasoning => reasoning))
@@ -26,12 +42,21 @@ module GRel
       self
     end
 
+    # Turns off reasoning in queries.
+    # Reasoning will remain turned off until enabled again with the +with_reasoning+ message.
+    # It returns the current graph object.
     def without_reasoning
       @reasoning = false
       @connection = stardog(@endpoint,@options)
       self
     end
 
+    # Sets the current Stardog database this graph is connected to.
+    # It accepts the name of the database as an argument.
+    # If an optional block is provided, operations in the block
+    # will be executed in the provided database and the old database 
+    # will be restored afterwards.
+    # It returns the current graph object.
     def with_db(db_name)
       ensure_db(db_name) do
         old_db_name = @db_name
@@ -46,6 +71,12 @@ module GRel
     end
 
 
+    # Stores a graph of ruby objects encoded as a nested collection of hashes in a database.
+    # Arguments:
+    # - data : objects to be stored.
+    # - db_name : optional database where this objects will be stored.
+    # It returns the current graph object.
+    # if a validation fails, a ValidationError will be raised.
     def store(data, db_name=nil)
       if(db_name)
         with_db(db_name) do
@@ -64,6 +95,11 @@ module GRel
     end
 
 
+    # Builds a query for the graph of objects.
+    # The query is expressed as a pattern of nested hashes that will be matched agains the data
+    # stored in the graph.
+    # Wildcard values and filters can also be added to the query.
+    # It returns the current graph object.
     def where(query)
       @last_query_context = QL::QueryContext.new(self)
       @last_query_context.register_query(query)
@@ -71,6 +107,10 @@ module GRel
       self
     end
 
+    # Adds another pattern to the current query being defined.
+    # It accepts a query pattern hash identical to the one accepted by the
+    # +where+ method.
+    # It returns the current graph object.
     def union(query)
       union_context = QL::QueryContext.new(self)
       union_context.register_query(query)
@@ -80,25 +120,44 @@ module GRel
       self
     end
 
+    # Limits how many triples will be returned from the server.
+    # The limit refers to triples, not nodes in the graph.
+    # It returns the current graph object.
     def limit(limit)
       @last_query_context.limit = limit
       self
     end
 
+    # Skip the first offset number of triples in the response returned from
+    # the server.
+    # The offset refers to triples, not nodes in the graph.
+    # It returns the current graph object.
     def offset(offset)
       @last_query_context.offset = offset
       self
     end
-
-    def order(order)
-      @last_query_context.order = order
-      self
-    end
-
+    
+#    def order(order)
+#      @last_query_context.order = order
+#      self
+#    end
+
+    # Exceutes the current query returning the raw response from the server
+    # It returns the a list of JSON-LD linked objects.
     def run
       @last_query_context.run
     end
 
+    # Defines schema meta data that will be used in the processing of queries
+    # if reasoning is activated.
+    # It accepts a list of definitions as an argument.
+    # Valid definitions are:
+    # - @subclass definitions
+    # - @subproperty definitions
+    # - @domain definitions
+    # - @range defintions
+    # - @cardinality definitions
+    # It returns the current graph object.
     def define(*args)
       unless(args.length == 3 && !args.first.is_a?(Array))
         args = args.inject([]) {|a,i| a += i; a }
@@ -115,13 +174,17 @@ module GRel
       self
     end
 
+    # Drop definition statements from the schema meta data.
+    # It accepts statements equivalent to the ones provided to the +define+ method.
+    # It returns the current graph object.
     def retract_definition(*args)
       unless(args.length == 3 && !args.first.is_a?(Array))
         args = args.inject([]) {|a,i| a += i }
       end
-      additional_triples = []
 
-      triples = QL.to_turtle(args + additional_triples, true)
+      args = parse_schema_axioms(args)
+
+      triples = QL.to_turtle(args, true)
       GRel::Debugger.debug "REMOVING FROM SCHEMA #{@schema_graph}"
       GRel::Debugger.debug triples
       GRel::Debugger.debug "IN"
@@ -130,6 +193,17 @@ module GRel
       self
     end
 
+    # Adds a validation statement to the graph.
+    # Validations will be checked in every +store+ operation if validations are activated.
+    # A ValidationError exception will be raised if a validation fails.
+    # It accepts a list of definitions as an argument.
+    # Valid definitions are:
+    # - @subclass definitions
+    # - @subproperty definitions
+    # - @domain definitions
+    # - @range defintions
+    # - @cardinality definitions
+    # It returns the current graph object.
     def validate(*args)
       unless(args.detect{|e| !e.is_a?(Array)})
         args = args.inject([]) {|a,i| a += i; a }
@@ -152,6 +226,9 @@ module GRel
       self
     end
 
+    # Removes a validation from the graph.
+    # It accepts a list of validation statements equivalent to the ones accepted by the +validate+ method.
+    # It returns the current graph object.
     def retract_validation(*args)
       unless(args.length == 3 && !args.first.is_a?(Array))
         args = args.inject([]) {|a,i| a += i }
@@ -165,6 +242,11 @@ module GRel
       self
     end
 
+    # Removes data from the graph of objects.
+    # If no arguments are provided, the nodes returned from the last executed query will
+    # be removed from the graph.
+    # If a graph of objects are provided, the equivalent statements will be removed instead.
+    # It returns the current graph object.
     def remove(data = nil, options = {})
       if data
         GRel::Debugger.debug "REMMOVING"
@@ -184,6 +266,10 @@ module GRel
       self
     end
 
+    # Executes the current defined query and returns a list of matching noes from the graph.
+    # Nodes will be correctly linked in the returned list.
+    # if the option +:unlinked+ is provided with true value, only the top level nodes that has not incoming links
+    # will be returned.
     def all(options = {})
       unlinked = options[:unlinked] || false
 
@@ -219,6 +305,8 @@ module GRel
       #end
     end
 
+    # Executes the current defined query returning a list of hashes where pairs key,value
+    # are bound to the tuple variables in the query hash and retrived values for those variables.
     def tuples
       results = run_tuples(@last_query_context.to_sparql_select)
       results["results"]["bindings"].map do |h|
@@ -230,10 +318,13 @@ module GRel
       end
     end
 
+    # Returns only the first node from the list of retrieved nodes in an all query.
     def first(options = {})
       all(options).first
     end
 
+    # Executes a raw SPARQL DESCRIBE query for the current defined query.
+    # It returns the results of the query without any other processing.
     def query(query, options = {})
       GRel::Debugger.debug "QUERYING DESCRIBE..."
       GRel::Debugger.debug query
@@ -247,6 +338,8 @@ module GRel
       @connection.query(@db_name,query, args).body
     end
 
+    # Executes a raw SPARQL SELECT query for the current defined query.
+    # It returns the results of the query without any other processing.
     def run_tuples(query, options = {})
       GRel::Debugger.debug "QUERYING SELECT..."
       GRel::Debugger.debug query
@@ -260,6 +353,9 @@ module GRel
       @connection.query(@db_name,query, args).body
     end
 
+    # It turns on validations for any insertion in the graph.
+    # Validations will remain turned on until they are disabled using the +without_validations+ message.
+    # It returns the current graph.
     def with_validations(state = true)
       @validations = state
       @connection.offline_db(@db_name)
@@ -269,10 +365,34 @@ module GRel
       self
     end
 
+    # It disables validations for any insertion in the graph.
+    # Validations will remain turned off until they are enabled again using the +with_validations+ message.
+    # It returns the current graph.
     def without_validations
       with_validations(false)
     end
 
+    # Removes connection to a node in the graph.
+    # It accepts a list of node IDs that will be unlinked.
+    def unlink(ids)
+      ids = [ids] if(ids.is_a?(String))
+      query = QL.unlink_sparql_query(ids)
+      results = @connection.query(@db_name, query,{}).body
+      triples = results["results"]["bindings"].map do |h|
+        "<#{h['S']['value']}> <#{h['P']['value']}> <#{h['O']['value']}>"
+      end
+
+      if(triples.length > 0)
+        triples = "#{triples.join('.')} ."
+        GRel::Debugger.debug "REMMOVING"
+        GRel::Debugger.debug triples
+        GRel::Debugger.debug "IN"
+        GRel::Debugger.debug @db_name
+        @connection.remove(@db_name, triples, nil, "text/turtle")
+      end
+      self
+    end
+
     private
 
     def ensure_db(db_name)

data/lib/grel/ql.rb

@@ -1,5 +1,15 @@
 module GRel
   module QL
+
+    def self.unlink_sparql_query(ids)
+      conditions = ids.map do |id|
+        id = "@id(#{id})" if id && id.is_a?(String) && id.index("@id(").nil?        
+        id = QL.to_query(id)
+        "(?S = #{id} && isIRI(?O) && ?P != <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>) || ?O = #{id}"
+      end
+      "SELECT ?S ?P ?O WHERE { ?S ?P ?O . FILTER (#{conditions.join(' || ')}) } "
+    end
+
     def self.to_id(obj)
       if(obj =~ ID_REGEX)
         "<http://grel.org/ids/id/#{URI.encode(ID_REGEX.match(obj)[1])}>"

data/lib/grel.rb

@@ -4,6 +4,8 @@ require 'uri'
 require 'securerandom'
 
 class Array
+  # When using an array of arrays to hold list of triples,
+  # returns the first triple subject.
   def triples_id
     self.first.first
   end
@@ -11,6 +13,8 @@ end
 
 module GRel
 
+  # Exception raised to signal a validation error due to a
+  # Stardog ICV.
   class ValidationError < Stardog::ICVException
     attr_accessor :icv_exception
     def initialize(msg, exception)
@@ -21,19 +25,25 @@ module GRel
 
   DEBUG = ENV["GREL_DEBUG"] || false
 
+  # Wrapper for the debugging logger method.
   class Debugger
     def self.debug(msg)
       puts msg if DEBUG
     end
   end
 
+  # Common namespace for all URIs generated by GRel.
   NAMESPACE = "http://grel.org/vocabulary#"
+  # Used to match valid ID strings
   ID_REGEX = /^\@id\((\w+)\)$/
+  # A URI denoting a ruby nil value
   NIL = "\"http://www.w3.org/1999/02/22-rdf-syntax-ns#nil\""
   BNODE = "BNODE"
 
+  # XML Scheam NonNegativeInteger type
   class NonNegativeInteger
 
+    # Just wraps a numeric type
     def initialize(number)
       @number = number
     end
@@ -49,25 +59,40 @@ module GRel
 
   end
 
+  # RDF Blank nodes
   class BlankId 
 
+    # The ID of the blank node.
     attr_reader :blank_id
 
+    # Creates a new BlankId object with an unique ID for
+    # this execution.
     def initialize
       @blank_id = BlankId.next_id
     end
 
+    # Unique IDs generator.
     def self.next_id
       next_id = (@counter ||= 0)
       @counter += 1
       next_id
     end
 
+    # Turtle represenation of the blank node.
     def to_s
       "_:#{@blank_id}"
     end
   end
 
+  # Creates a new graph object connected to the provided Stardog server.
+  # Arguments:
+  # - name : connection string. localhost:5822 by default.
+  # - options: hash of options:
+  #    + user : user name for authentication
+  #    + password : password for authentication
+  #    + validate : should validate integrity constraints
+  #    + db : name of the db to use
+  # Returns the newly built graph object.
   def graph(name='http://localhost:5822/',options = {})
     options[:user] ||= "admin"
     options[:password] ||= "admin"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-22 00:00:00.000000000 Z
+date: 2013-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: stardog-rb