rdf-n3 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1e295c958340c4c0dd8f47583cf716f65d3d2164acdddda485281cb2038c09a
-  data.tar.gz: eb2280ffe26460e5eb01e3c99cf330a47a2aa565711679f4c7ddbb4fffcc0546
+  metadata.gz: c5445c08b901dd936cdad807690c55a4b971fd1bd047b175a9b742fd7ce1bf40
+  data.tar.gz: 7fa41d9b4cf5bffe6f0e1820a9759009f7f5d2f97cfc7d8d13748a3b05e775a0
 SHA512:
-  metadata.gz: 75ca555fe8e9369e7450fd1631f484ddba0af4ba2d370bfb5710310a1c74636cc78d6f8b64358d5dfd0825707be64b489537d2a6759b91d203e00715bb7b7078
-  data.tar.gz: 2179ab00eec3d52700a4d03cfc07d63ec54e6ec84b17fe922f280181d95bac402c627bed85abfe1789e35d15e2d707b5fcb871e379fd61199fa07c99d4a1f420
+  metadata.gz: fb93395268e948bb947072899d2f492809de4d14ccf1a8a0dc23423fe977b5499f0a9e41aeca3a23f2bbe63e1f99f01d952c5470d72820ef3bc87029c16b0625
+  data.tar.gz: 48fb73cf4d731e346a0b700a657f09623723901ab9ec41c96d69cf5f64df45dcb530dbb31ab2477a8525ffe08cfdd25fb07e1fc28ff3bccd5a7df4bdce8ea2e4

data/README.md

@@ -1,11 +1,11 @@
-# RDF::N3 reader/writer
+# RDF::N3 reader/writer and reasoner
 Notation-3 reader/writer for [RDF.rb][RDF.rb] .
 
-[![Gem Version](https://badge.fury.io/rb/rdf-n3.png)](http://badge.fury.io/rb/rdf-n3)
-[![Build Status](https://travis-ci.org/ruby-rdf/rdf-n3.png?branch=master)](http://travis-ci.org/ruby-rdf/rdf-n3)
+[![Gem Version](https://badge.fury.io/rb/rdf-n3.png)](https://badge.fury.io/rb/rdf-n3)
+[![Build Status](https://travis-ci.org/ruby-rdf/rdf-n3.png?branch=master)](https://travis-ci.org/ruby-rdf/rdf-n3)
 
 ## Description
-RDF::N3 is an Notation-3 parser for Ruby using the [RDF.rb][RDF.rb]  library suite.
+RDF::N3 is an Notation-3 parser for Ruby using the [RDF.rb][RDF.rb]  library suite. Also implements N3 Entailment.
 
 Reader inspired from TimBL predictiveParser and Python librdf implementation.
 
@@ -14,14 +14,12 @@ Support for Turtle mime-types and specific format support has been deprecated fr
 as Turtle is now implemented using [RDF::Turtle][RDF::Turtle].
 
 ## Features
-RDF::N3 parses [Notation-3][N3], [Turtle][Turtle] and [N-Triples][N-Triples] into statements or triples. It also serializes to Turtle.
+RDF::N3 parses [Notation-3][N3], [Turtle][Turtle] and [N-Triples][N-Triples] into statements or quads. It also performs reasoning and serializes to N3.
 
 Install with `gem install rdf-n3`
 
 ## Limitations
-* Full support of Unicode input requires Ruby version 2.0 or greater.
-* Support for Variables in Formulae dependent on underlying repository. Existential variables are quantified to RDF::Node instances, Universals to RDF::Query::Variable, with the URI of the variable target used as the variable name.
-* No support for N3 Reification. If there were, it would be through a :reify option to the reader.
+* Support for Variables in Formulae. Existential variables are quantified to RDF::Node instances, Universals to RDF::Query::Variable, with the URI of the variable target used as the variable name.
 
 ## Usage
 Instantiate a reader from a local file:
@@ -40,23 +38,53 @@ Write a graph to a file:
        writer << graph
     end
 
-### Formulae
+### Reasoning
+Experimental N3 reasoning is supported. Instantiate a reasoner from a dataset:
+
+    RDF::N3::Reasoner.new do |reasoner|
+      RDF::N3::Reader.open("etc/foaf.n3") {|reader| reasoner << reader}
+
+       reader.each_statement do |statement|
+         puts statement.inspect
+       end
+    end
+
+Reasoning is performed by turning a repository containing formula and predicate operators into an executable set of operators (similar to the executable SPARQL Algebra). Reasoning adds statements to the base dataset, marked with `:inferred` (e.g. `statement.inferred?`). Predicate operators are defined from the following vocabularies:
+
+* RDF List vocabulary <http://www.w3.org/2000/10/swap/list#>
+  * list:append (not implemented yet - See {RDF::N3::Algebra::ListAppend})
+  * list:in (not implemented yet - See {RDF::N3::Algebra::ListIn})
+  * list:last (not implemented yet - See {RDF::N3::Algebra::ListLast})
+  * list:member (not implemented yet - See {RDF::N3::Algebra::ListMember})
+* RDF Log vocabulary <http://www.w3.org/2000/10/swap/log#>
+  * log:conclusion (not implemented yet - See {RDF::N3::Algebra::LogConclusion})
+  * log:conjunction (not implemented yet - See {RDF::N3::Algebra::LogConjunction})
+  * log:equalTo (See {not implemented yet - RDF::N3::Algebra::LogEqualTo})
+  * log:implies (See {RDF::N3::Algebra::LogImplies})
+  * log:includes (not implemented yet - See {RDF::N3::Algebra::LogIncludes})
+  * log:notEqualTo (not implemented yet - See {RDF::N3::Algebra::LogNotEqualTo})
+  * log:notIncludes (not implemented yet - See {RDF::N3::Algebra::LogNotIncludes})
+  * log:outputString (not implemented yet - See {RDF::N3::Algebra::LogOutputString})
+
 N3 Formulae are introduced with the { statement-list } syntax. A given formula is assigned an RDF::Node instance, which is also used as the graph_name for RDF::Statement instances provided to RDF::N3::Reader#each_statement. For example, the following N3 generates the associated statements:
 
-    { [ x:firstname  "Ora" ] dc:wrote [ dc:title  "Moby Dick" ] } a n3:falsehood .
+    @prefix x: <http://example.org/x-ns/#> .
+    @prefix log: <http://www.w3.org/2000/10/swap/log#> .
+    @prefix dc: <http://purl.org/dc/elements/1.1/#> .
+
+    { [ x:firstname  "Ora" ] dc:wrote [ dc:title  "Moby Dick" ] } a log:falsehood .
   
-results in
+when turned into an RDF Repository results in the following quads
+
+    _:form <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2000/10/swap/log#falsehood> .
+    _:moby <http://purl.org/dc/elements/1.1/#title> "Moby Dick" _:form .
+    _:ora <http://purl.org/dc/elements/1.1/#wrote> _:moby _:form .
+    _:ora <http://example.org/x-ns/#firstname> "Ora" _:form .
 
-    f = RDF::Node.new
-    s = RDF::Node.new
-    o = RDF::Node.new
-    RDF::Statement(f, rdf:type n3:falsehood)
-    RDF::Statement(s, x:firstname, "Ora", graph_name: f)
-    RDF::Statement(s, dc:wrote, o, graph_name: f)
-    RDF::Statement(o, dc:title, "Moby Dick", graph_name: f)
+Reasoning uses a Notation3 Algebra, similar to [SPARQL S-Expressions](). This implementation considers formulae to be patterns, which may be asserted on statements made in the default graph, possibly loaded from a separate file. The logical relationships are reduced to algebraic operators. 
 
 ### Variables
-N3 Variables are introduced with @forAll, @forEach, or ?x. Variables reference URIs described in formulae, typically defined in the default vocabulary (e.g., ":x"). Existential variables are replaced with an allocated RDF::Node instance. Universal variables are replaced with a RDF::Query::Variable instance. For example, the following N3 generates the associated statements:
+N3 Variables are introduced with @forAll, @forSome, or ?x. Variables reference URIs described in formulae, typically defined in the default vocabulary (e.g., ":x"). Existential variables are replaced with an allocated RDF::Node instance. Universal variables are replaced with a RDF::Query::Variable instance. For example, the following N3 generates the associated statements:
 
     @forAll <#h>. @forSome <#g>. <#g> <#loves> <#h> .
 
@@ -66,6 +94,8 @@ results in:
     g = RDF::Node.new()
     RDF::Statement(f, <#loves>, h)
 
+Note that the behavior of both existential and universal variables is not entirely in keeping with the [Team Submission][], and neither work quite like SPARQL variables. When used in the antecedent part of an implication, universal variables should behave much like SPARQL variables. This area is subject to a fair amount of change.
+
 ## Implementation Notes
 The parser is driven through a rules table contained in lib/rdf/n3/reader/meta.rb. This includes
 branch rules to indicate productions to be taken based on a current production. Terminals are denoted
@@ -79,48 +109,60 @@ http://www.w3.org/2000/10/swap/grammar/n3.n3 (along with bnf-rules.n3) using cwm
 
 [n3-selectors.n3][file:lib/rdf/n3/reader/n3-selectors.rb] is itself used to generate meta.rb using script/build_meta.
 
-## TODO
-* Generate Formulae and solutions using BGP and SPARQL CONSTRUCT mechanisms
-* Create equivalent to `--think` to iterate on solutions.
-
 ## Dependencies
-* [RDF.rb](http://rubygems.org/gems/rdf) (>= 3.0)
+* [RDF.rb](https://rubygems.org/gems/rdf) (~> 3.0, >= 3.0.10)
 
 ## Documentation
-Full documentation available on [RubyDoc.info](http://rubydoc.info/github/ruby-rdf/rdf-n3/frames)
+Full documentation available on [RubyDoc.info](https://rubydoc.info/github/ruby-rdf/rdf-n3)
 
 ### Principle Classes
 * {RDF::N3}
 * {RDF::N3::Format}
 * {RDF::N3::Reader}
+* {RDF::N3::Reasoner}
 * {RDF::N3::Writer}
+* {RDF::N3::Algebra}
+  * {RDF::N3::Algebra::Formula}
+  * {RDF::N3::Algebra::ListAppend}
+  * {RDF::N3::Algebra::ListIn}
+  * {RDF::N3::Algebra::ListLast}
+  * {RDF::N3::Algebra::ListMember}
+  * {RDF::N3::Algebra::LogConclusion}
+  * {RDF::N3::Algebra::LogConjunction}
+  * {RDF::N3::Algebra::LogEqualTo}
+  * {RDF::N3::Algebra::LogImplies}
+  * {RDF::N3::Algebra::LogIncludes}
+  * {RDF::N3::Algebra::LogNotEqualTo}
+  * {RDF::N3::Algebra::LogNotIncludes}
+  * {RDF::N3::Algebra::LogOutputString}
 
 ### Additional vocabularies
-* {RDF::LOG}
-* {RDF::REI}
-
-### Patches
-* `Array`
-* `RDF::List`
+* {RDF::N3::Log}
+* {RDF::N3::Rei}
+* {RDF::N3::Crypto}
+* {RDF::N3::List}
+* {RDF::N3::Math}
+* {RDF::N3::Str}
+* {RDF::N3::Time}
 
 ## Resources
 * [RDF.rb][RDF.rb]
 * [Distiller](http://rdf.greggkellogg.net/distiller)
-* [Documentation](http://rubydoc.info/github/ruby-rdf/rdf-n3/master/frames)
+* [Documentation](https://rubydoc.info/github/ruby-rdf/rdf-n3/)
 * [History](file:file.History.html)
 * [Notation-3][N3]
-* [N3 Primer](http://www.w3.org/2000/10/swap/Primer.html)
-* [N3 Reification](http://www.w3.org/DesignIssues/Reify.html)
+* [N3 Primer](https://www.w3.org/2000/10/swap/Primer.html)
+* [N3 Reification](https://www.w3.org/DesignIssues/Reify.html)
 * [Turtle][Turtle]
-* [W3C SWAP Test suite](http://www.w3.org/2000/10/swap/test/README.html)
-* [W3C Turtle Test suite](http://www.w3.org/2001/sw/DataAccess/df1/tests/README.txt)
+* [W3C SWAP Test suite](https://www.w3.org/2000/10/swap/test/README.html)
+* [W3C Turtle Test suite](https://www.w3.org/2001/sw/DataAccess/df1/tests/README.txt)
 * [N-Triples][N-Triples]
 
 ## Author
-* [Gregg Kellogg](http://github.com/gkellogg) - <http://greggkellogg.net/>
+* [Gregg Kellogg](https://github.com/gkellogg) - <https://greggkellogg.net/>
 
 ## Contributors
-* [Nicholas Humfrey](http://github.com/njh) - <http://njh.me/>
+* [Nicholas Humfrey](https://github.com/njh) - <https://njh.me/>
 
 ## Contributing
 This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
@@ -140,19 +182,21 @@ This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange develo
 ## License
 
 This is free and unencumbered public domain software. For more information,
-see <http://unlicense.org/> or the accompanying {file:UNLICENSE} file.
+see <https://unlicense.org/> or the accompanying {file:UNLICENSE} file.
 
 ## Feedback
 * <gregg@greggkellogg.net>
-* <http://rubygems.org/gem/rdf-n3>
-* <http://github.com/ruby-rdf/rdf-n3>
-* <http://lists.w3.org/Archives/Public/public-rdf-ruby/>
-
-[RDF.rb]:       http://ruby-rdf.github.com/rdf
-[RDF::Turtle]:  http://ruby-rdf.github.com/rdf-turtle/
-[N3]:           http://www.w3.org/DesignIssues/Notation3.html "Notation-3"
-[Turtle]:       http://www.w3.org/TR/turtle/
-[N-Triples]:    http://www.w3.org/TR/n-triples/
-[YARD]:         http://yardoc.org/
-[YARD-GS]:      http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
-[PDD]:          http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+* <https://rubygems.org/gem/rdf-n3>
+* <https://github.com/ruby-rdf/rdf-n3>
+* <https://lists.w3.org/Archives/Public/public-rdf-ruby/>
+
+[RDF.rb]:       https://ruby-rdf.github.com/rdf
+[RDF::Turtle]:  https://ruby-rdf.github.com/rdf-turtle/
+[N3]:           https://www.w3.org/DesignIssues/Notation3.html "Notation-3"
+[Team Submission]: https://www.w3.org/TeamSubmission/n3/
+[Turtle]:       https://www.w3.org/TR/turtle/
+[N-Triples]:    https://www.w3.org/TR/n-triples/
+[YARD]:         https://yardoc.org/
+[YARD-GS]:      https://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:          https://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+[SPARQL S-Expressions]: https://jena.apache.org/documentation/notes/sse.html

data/VERSION

@@ -1 +1 @@
-3.0.1
+3.1.0

data/lib/rdf/n3.rb

@@ -16,17 +16,20 @@ module RDF
   #   end
   #
   # @see http://www.rubydoc.info/github/ruby-rdf/rdf/
-  # @see http://www.w3.org/TR/REC-rdf-syntax/
+  # @see https://www.w3.org/TR/REC-rdf-syntax/
   #
   # @author [Gregg Kellogg](http://greggkellogg.net/)
   module N3
+    require 'rdf/n3/algebra'
     require 'rdf/n3/format'
     require 'rdf/n3/vocab'
+    require 'rdf/n3/extensions'
     require 'rdf/n3/patches/array_hacks'
-    autoload :Meta,    'rdf/n3/reader/meta'
-    autoload :Parser,  'rdf/n3/reader/parser'
-    autoload :Reader,  'rdf/n3/reader'
-    autoload :VERSION, 'rdf/n3/version'
-    autoload :Writer,  'rdf/n3/writer'
+    autoload :Meta,     'rdf/n3/reader/meta'
+    autoload :Parser,   'rdf/n3/reader/parser'
+    autoload :Reader,   'rdf/n3/reader'
+    autoload :Reasoner, 'rdf/n3/reasoner'
+    autoload :VERSION,  'rdf/n3/version'
+    autoload :Writer,   'rdf/n3/writer'
   end
 end

data/lib/rdf/n3/algebra.rb

@@ -0,0 +1,125 @@
+$:.unshift(File.expand_path("../..", __FILE__))
+require 'sparql/algebra'
+require 'sxp'
+
+module RDF::N3
+  # Based on the SPARQL Algebra, operators for executing a patch
+  #
+  # @author [Gregg Kellogg](http://greggkellogg.net/)
+  module Algebra
+    autoload :Formula,                'rdf/n3/algebra/formula'
+
+    module List
+      autoload :Append,               'rdf/n3/algebra/list/append'
+      autoload :In,                   'rdf/n3/algebra/list/in'
+      autoload :Last,                 'rdf/n3/algebra/list/last'
+      autoload :Member,               'rdf/n3/algebra/list/member'
+    end
+
+    module Log
+      autoload :Conclusion,           'rdf/n3/algebra/log/conclusion'
+      autoload :Conjunction,          'rdf/n3/algebra/log/conjunction'
+      autoload :EqualTo,              'rdf/n3/algebra/log/equalTo'
+      autoload :Implies,              'rdf/n3/algebra/log/implies'
+      autoload :Includes,             'rdf/n3/algebra/log/includes'
+      autoload :NotEqualTo,           'rdf/n3/algebra/log/notEqualTo'
+      autoload :NotIncludes,          'rdf/n3/algebra/log/notIncludes'
+      autoload :OutputString,         'rdf/n3/algebra/log/outputString'
+    end
+
+    module Math
+      autoload :AbsoluteValue,        'rdf/n3/algebra/math/absoluteValue'
+      autoload :Difference,           'rdf/n3/algebra/math/difference'
+      autoload :EqualTo,              'rdf/n3/algebra/math/equalTo'
+      autoload :Exponentiation,       'rdf/n3/algebra/math/exponentiation'
+      autoload :GreaterThan,          'rdf/n3/algebra/math/greaterThan'
+      autoload :IntegerQuotient,      'rdf/n3/algebra/math/integerQuotient'
+      autoload :LessThan,             'rdf/n3/algebra/math/lessThan'
+      autoload :MemberCount,          'rdf/n3/algebra/math/memberCount'
+      autoload :Negation,             'rdf/n3/algebra/math/negation'
+      autoload :NotEqualTo,           'rdf/n3/algebra/math/notEqualTo'
+      autoload :NotGreaterThan,       'rdf/n3/algebra/math/notGreaterThan'
+      autoload :NotLessThan,          'rdf/n3/algebra/math/notLessThan'
+      autoload :Product,              'rdf/n3/algebra/math/product'
+      autoload :Quotient,             'rdf/n3/algebra/math/quotient'
+      autoload :Remainder,            'rdf/n3/algebra/math/remainder'
+      autoload :Rounded,              'rdf/n3/algebra/math/rounded'
+      autoload :Sum,                  'rdf/n3/algebra/math/sum'
+    end
+
+    module Str
+      autoload :Concatenation,        'rdf/n3/algebra/str/concatenation'
+      autoload :Contains,             'rdf/n3/algebra/str/contains'
+      autoload :ContainsIgnoringCase, 'rdf/n3/algebra/str/containsIgnoringCase'
+      autoload :EndsWith,             'rdf/n3/algebra/str/endsWith'
+      autoload :EqualIgnoringCase,    'rdf/n3/algebra/str/equalIgnoringCase'
+      autoload :Format,               'rdf/n3/algebra/str/format'
+      autoload :GreaterThan,          'rdf/n3/algebra/str/greaterThan'
+      autoload :LessThan,             'rdf/n3/algebra/str/lessThan'
+      autoload :Matches,              'rdf/n3/algebra/str/matches'
+      autoload :NotEqualIgnoringCase, 'rdf/n3/algebra/str/notEqualIgnoringCase'
+      autoload :NotGreaterThan,       'rdf/n3/algebra/str/notGreaterThan'
+      autoload :NotLessThan,          'rdf/n3/algebra/str/notLessThan'
+      autoload :NotMatches,           'rdf/n3/algebra/str/notMatches'
+      autoload :Replace,              'rdf/n3/algebra/str/replace'
+      autoload :Scrape,               'rdf/n3/algebra/str/scrape'
+      autoload :StartsWith,           'rdf/n3/algebra/str/startsWith'
+    end
+
+    def for(uri)
+      {
+        RDF::N3::List.append              => List::Append,
+        RDF::N3::List.in                  => List::In,
+        RDF::N3::List.last                => List::Last,
+        RDF::N3::List.member              => List::Member,
+
+        RDF::N3::Log.conclusion           => Log::Conclusion,
+        RDF::N3::Log.conjunction          => Log::Conjunction,
+        RDF::N3::Log.equalTo              => Log::EqualTo,
+        RDF::N3::Log.implies              => Log::Implies,
+        RDF::N3::Log.includes             => Log::Includes,
+        RDF::N3::Log.notEqualTo           => Log::NotEqualTo,
+        RDF::N3::Log.notIncludes          => Log::NotIncludes,
+        RDF::N3::Log.outputString         => Log::OutputString,
+
+        RDF::N3::Math.absoluteValue       => Math::AbsoluteValue,
+        RDF::N3::Math.difference          => Math::Difference,
+        RDF::N3::Math.equalTo             => Math::EqualTo,
+        RDF::N3::Math.exponentiation      => Math::Exponentiation,
+        RDF::N3::Math.greaterThan         => Math::GreaterThan,
+        RDF::N3::Math.integerQuotient     => Math::IntegerQuotient,
+        RDF::N3::Math.lessThan            => Math::LessThan,
+        RDF::N3::Math.memberCount         => Math::MemberCount,
+        RDF::N3::Math.negation            => Math::Negation,
+        RDF::N3::Math.notEqualTo          => Math::NotEqualTo,
+        RDF::N3::Math.notGreaterThan      => Math::NotGreaterThan,
+        RDF::N3::Math.notLessThan         => Math::NotLessThan,
+        RDF::N3::Math.product             => Math::Product,
+        RDF::N3::Math.quotient            => Math::Quotient,
+        RDF::N3::Math.remainder           => Math::Remainder,
+        RDF::N3::Math.rounded             => Math::Rounded,
+        RDF::N3::Math.sum                 => Math::Sum,
+
+        RDF::N3::Str.concatenation        => Str::Concatenation,
+        RDF::N3::Str.contains             => Str::Contains,
+        RDF::N3::Str.containsIgnoringCase => Str::ContainsIgnoringCase,
+        RDF::N3::Str.endsWith             => Str::EndsWith,
+        RDF::N3::Str.equalIgnoringCase    => Str::EqualIgnoringCase,
+        RDF::N3::Str.format               => Str::Format,
+        RDF::N3::Str.greaterThan          => Str::GreaterThan,
+        RDF::N3::Str.lessThan             => Str::LessThan,
+        RDF::N3::Str.matches              => Str::Matches,
+        RDF::N3::Str.notEqualIgnoringCase => Str::NotEqualIgnoringCase,
+        RDF::N3::Str.notGreaterThan       => Str::NotGreaterThan,
+        RDF::N3::Str.notLessThan          => Str::NotLessThan,
+        RDF::N3::Str.notMatches           => Str::NotMatches,
+        RDF::N3::Str.replace              => Str::Replace,
+        RDF::N3::Str.scrape               => Str::Scrape,
+        RDF::N3::Str.startsWith           => Str::StartsWith,
+      }[uri]
+    end
+    module_function :for
+  end
+end
+
+

data/lib/rdf/n3/algebra/formula.rb

@@ -0,0 +1,185 @@
+require 'rdf'
+
+module RDF::N3::Algebra
+  #
+  # A Notation3 Formula combines a graph with a BGP query.
+  class Formula < SPARQL::Algebra::Operator
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Update
+    include RDF::Enumerable
+    include RDF::Util::Logger
+
+    attr_accessor :query
+
+    NAME = [:formula]
+
+    ##
+    # Yields solutions from patterns and other operands. Solutions are created by evaluating each pattern and other sub-operand against `queryable`.
+    #
+    # When executing, blank nodes are turned into non-distinguished existential variables, noted with `$$`. These variables are removed from the returned solutions, as they can't be bound outside of the formula.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @option options [RDF::Query::Solutions] solutions
+    #   optional initial solutions for chained queries
+    # @return [RDF::Solutions] distinct solutions
+    def execute(queryable, solutions: RDF::Query::Solutions(RDF::Query::Solution.new), **options)
+      log_debug {"formula #{graph_name} #{operands.to_sxp}"}
+
+      # If we were passed solutions in options, extract bindings to use for query
+      bindings = solutions.bindings
+      log_debug {"(formula bindings) #{bindings.map {|k,v| RDF::Query::Variable.new(k,v)}.to_sxp}"}
+
+      # Only query as patterns if this is an embedded formula
+      @query ||= RDF::Query.new(patterns).optimize!
+      @solutions = @query.patterns.empty? ? solutions : queryable.query(@query, solutions: solutions, bindings: bindings, **options)
+
+      # Merge solution sets
+      # Reject solutions which include variables as values
+      @solutions = @solutions
+        .merge(options[:solutions])
+        .filter {|s| s.enum_value.none?(&:variable?)}
+
+      # Use our solutions for sub-ops
+      # Join solutions from other operands
+      log_depth do
+        sub_ops.each do |op|
+          @solutions = op.execute(queryable, solutions: @solutions)
+        end
+      end
+      log_debug {"(formula solutions) #{@solutions.to_sxp}"}
+
+      # Only return solutions with distinguished variables
+      variable_names = @solutions.variable_names.reject {|v| v.to_s.start_with?('$$')}
+      variable_names.empty? ? @solutions : @solutions.dup.project(*variable_names)
+    end
+
+    ##
+    # Yields each statement from this formula bound to previously determined solutions.
+    #
+    # @yield  [statement]
+    #   each matching statement
+    # @yieldparam  [RDF::Statement] solution
+    # @yieldreturn [void] ignored
+    def each(&block)
+      @solutions ||= begin
+        # If there are no solutions, create a single solution
+        RDF::Query::Solutions(RDF::Query::Solution.new)
+      end
+      log_debug {"formula #{graph_name} each #{@solutions.to_sxp}"}
+
+      # Yield constant statements/patterns
+      constants.each do |pattern|
+        log_debug {"(formula constant) #{pattern.to_sxp}"}
+        block.call(RDF::Statement.from(pattern, graph_name: graph_name))
+      end
+
+      # Yield patterns by binding variables
+      # FIXME: do we need to do something with non-bound non-distinguished extistential variables?
+      @solutions.each do |solution|
+        # Bind blank nodes to the solution when it doesn't contain a solution for an existential variable
+        existential_vars.each do |var|
+          solution[var.name] ||= RDF::Node.intern(var.name.to_s.sub(/^\$+/, ''))
+        end
+
+        log_debug {"(formula apply) #{solution.to_sxp} to BGP"}
+        # Yield each variable statement which is constant after applying solution
+        patterns.each do |pattern|
+          terms = {}
+          [:subject, :predicate, :object].each do |r|
+            terms[r] = case o = pattern.send(r)
+            when RDF::Query::Variable then solution[o]
+            else                           o
+            end
+          end
+
+          statement = RDF::Statement.from(terms)
+
+          # Sanity checking on statement
+          if statement.variable? ||
+             statement.predicate.literal? ||
+             statement.subject.is_a?(SPARQL::Algebra::Operator) ||
+             statement.object.is_a?(SPARQL::Algebra::Operator)
+            log_debug {"(formula skip) #{statement.to_sxp}"}
+            next
+          end
+
+          log_debug {"(formula add) #{statement.to_sxp}"}
+          block.call(statement)
+        end
+      end
+
+      # statements from sub-operands
+      log_depth {sub_ops.each {|op| op.each(&block)}}
+    end
+
+    # Set solutions
+    # @param [RDF::Query::Solutions] solutions
+    def solutions=(solutions)
+      @solutions = solutions
+    end
+
+    # Graph name associated with this formula
+    # @return [RDF::Resource]
+    def graph_name; @options[:graph_name]; end
+
+    ##
+    # Statements memoizer
+    def statements
+      # BNodes in statements are non-distinguished existential variables
+      @statements ||= operands.
+        select {|op| op.is_a?(RDF::Statement)}.
+        map do |pattern|
+
+        # Map nodes to non-distinguished existential variables (except when in top-level formula)
+        if graph_name
+          terms = {}
+          [:subject, :predicate, :object].each do |r|
+            terms[r] = case o = pattern.send(r)
+            when RDF::Node then RDF::Query::Variable.new(o.id, existential: true, distinguished: false)
+            else                o
+            end
+          end
+
+          RDF::Query::Pattern.from(terms)
+        else
+          RDF::Query::Pattern.from(pattern)
+        end
+      end
+    end
+
+    ##
+    # Constants memoizer
+    def constants
+      # BNodes in statements are existential variables
+      @constants ||= statements.select(&:constant?)
+    end
+
+    ##
+    # Patterns memoizer
+    def patterns
+      # BNodes in statements are existential variables
+      @patterns ||= statements.reject(&:constant?)
+    end
+
+    ##
+    # Non-statement operands memoizer
+    def sub_ops
+      # operands that aren't statements, ordered by their graph_name
+      @sub_ops ||= operands.reject {|op| op.is_a?(RDF::Statement)}
+    end
+
+    ##
+    # Existential vars in this formula
+    def existential_vars
+      @existentials ||= patterns.vars.select(&:existential?)
+    end
+
+    def to_sxp_bin
+      [:formula, graph_name].compact +
+      operands.map(&:to_sxp_bin)
+    end
+  end
+end