Improve documentation.

Author: gkellogg

.gitignore

@@ -12,3 +12,4 @@ Gemfile.lock
 benchmark/
 /.byebug_history
 /coverage/
+/doc/

README.md

@@ -1,8 +1,8 @@
 # ShEx: Shape Expression language for Ruby
 
-This is a pure-Ruby library for working with the [Shape Expressions Language][ShEx] to validate the shape of [RDF][] graphs.
+This is a pure-Ruby library for working with the [Shape Expressions Language][ShExSpec] to validate the shape of [RDF][] graphs.
 
-* <http://ruby-rdf.github.com/shex>
+<http://ruby-rdf.github.com/shex>
 
 [![Gem Version](https://badge.fury.io/rb/shex.png)](http://badge.fury.io/rb/shex)
 [![Build Status](https://travis-ci.org/ruby-rdf/shex.png?branch=master)](http://travis-ci.org/ruby-rdf/shex)
@@ -12,9 +12,41 @@ This is a pure-Ruby library for working with the [Shape Expressions Language][Sh
 ## Features
 
 * 100% pure Ruby with minimal dependencies and no bloat.
-* Fully compatible with [RDF 1.1][] specifications.
+* Fully compatible with [ShEx][ShExSpec] specifications.
 * 100% free and unencumbered [public domain](http://unlicense.org/) software.
 
+## Description
+
+The ShEx gem implements a [ShEx][ShExSpec] Shape Expression engine.
+
+* `ShEx::Parser` parses ShExC formatted documents generating executable operators which can be serialized as [S-Expressions](http://en.wikipedia.org/wiki/S-expression).
+* `ShEx::Algebra` executes operators against Any `RDF::Graph`, including compliant [RDF.rb][].
+
+## Example
+
+    require 'rubygems'
+    require 'rdf/turtle'
+    require 'shex'
+
+    shexc: %(
+      PREFIX doap:  <http://usefulinc.com/ns/doap#>
+      PREFIX dc:    <http://purl.org/dc/terms/>
+      <TestShape> EXTRA a {
+        a doap:Project;
+        (doap:name;doap:description|dc:title;dc:description)+;
+        doap:category*;
+        doap:developer IRI;
+        doap:implements    [<https://shexspec.github.io/spec/>]
+      }
+    )
+    graph = RDF::Graph.load("etc/doap.ttl")
+    schema = ShEx.parse(shexc)
+    map = {
+      "http://rubygems.org/gems/shex" => "TestShape"
+    }
+    schema.satisfies?("http://rubygems.org/gems/shex", graph, map)
+    # => true
+
 ## Documentation
 
 <http://rubydoc.info/github/ruby-rdf/shex>
@@ -30,7 +62,7 @@ This is a pure-Ruby library for working with the [Shape Expressions Language][Sh
 The recommended installation method is via [RubyGems](http://rubygems.org/).
 To install the latest official release of RDF.rb, do:
 
-    % [sudo] gem install shex             # Ruby 2+
+    % [sudo] gem install shex
 
 ## Download
 
@@ -81,5 +113,6 @@ This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange develo
 This is free and unencumbered public domain software. For more information,
 see <http://unlicense.org/> or the accompanying {file:LICENSE} file.
 
-[ShEx]:             https://shexspec.github.io/spec/
-[RDF]:              http://www.w3.org/RDF/
+[ShExSpec]:     https://shexspec.github.io/spec/
+[RDF]:          http://www.w3.org/RDF/
+[RDF.rb]:           http://rubydoc.info/github/ruby-rdf/rdf

etc/doap.shex

@@ -0,0 +1,9 @@
+PREFIX doap:  <http://usefulinc.com/ns/doap#>
+PREFIX dc:    <http://purl.org/dc/terms/>
+<TestShape> EXTRA a {
+  a doap:Project;
+  (doap:name;doap:description|dc:title;dc:description)+;
+  doap:category*;
+  doap:developer IRI;
+  doap:implements    [<https://shexspec.github.io/spec/>]
+}

etc/doap.ttl

@@ -7,27 +7,27 @@
 @prefix ex:   <http://example.org/> .
 @prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
 
-<http://rubygems.org/gems/rdf-turtle> a doap:Project, earl:TestSubject, earl:Software ;
-  doap:name          "RDF::Turtle" ;
-  doap:homepage      <http://ruby-rdf.github.com/rdf-turtle> ;
+<http://rubygems.org/gems/shex> a doap:Project, earl:TestSubject, earl:Software ;
+  doap:name          "ShEx" ;
+  doap:homepage      <http://ruby-rdf.github.com/shex> ;
   doap:license       <http://creativecommons.org/licenses/publicdomain/> ;
-  doap:shortdesc     "Turtle reader/writer for Ruby."@en ;
-  doap:description   "RDF::Turtle is an Turtle reader/writer for the RDF.rb library suite."@en ;
-  doap:created       "2011-08-29"^^xsd:date ;
+  doap:shortdesc     "ShEx is a Shape Expression engine for Ruby."@en ;
+  doap:description   "ShEx is an Shape Expression engine for the RDF.rb library suite."@en ;
+  doap:created       "2016-12-09"^^xsd:date ;
   doap:programming-language "Ruby" ;
-  doap:implements    <http://www.w3.org/TR/turtle/> ;
+  doap:implements    <https://shexspec.github.io/spec/> ;
   doap:category      <http://dbpedia.org/resource/Resource_Description_Framework>,
                      <http://dbpedia.org/resource/Ruby_(programming_language)> ;
-  doap:download-page <http://rubygems.org/gems/rdf-turtle> ;
+  doap:download-page <http://rubygems.org/gems/shex> ;
   doap:mailing-list  <http://lists.w3.org/Archives/Public/public-rdf-ruby/> ;
-  doap:bug-database  <http://github.com/ruby-rdf/rdf-turtle/issues> ;
+  doap:bug-database  <http://github.com/ruby-rdf/shex/issues> ;
   doap:blog          <http://greggkellogg.net/> ;
   doap:developer     <http://greggkellogg.net/foaf#me> ;
   doap:maintainer    <http://greggkellogg.net/foaf#me> ;
   doap:documenter    <http://greggkellogg.net/foaf#me> ;
   foaf:maker         <http://greggkellogg.net/foaf#me> ;
-  dc:title           "RDF::Turtle" ;
-  dc:description     "RDF::Turtle is an Turtle reader/writer for the RDF.rb library suite."@en ;
-  dc:date            "2011-08-29"^^xsd:date ;
+  dc:title           "ShEx" ;
+  dc:description     "ShEx is an Shape Expression engine for the RDF.rb library suite."@en ;
+  dc:date            "2016-12-09"^^xsd:date ;
   dc:creator         <http://greggkellogg.net/foaf#me> ;
   dc:isPartOf        <http://rubygems.org/gems/rdf> .

lib/shex.rb

@@ -14,14 +14,17 @@ module ShEx
   ##
   # Parse the given ShEx `query` string.
   #
-  # @example
-  #   query = ShEx.parse("...")
+  # @example parsing a ShExC schema
+  #   schema = ShEx.parse(%(
+  #     PREFIX ex: <http://schema.example/> ex:IssueShape {ex:state IRI}
+  #   ).parse
   #
   # @param  [IO, StringIO, String, #to_s]  expression (ShExC or ShExJ)
   # @param  ['shexc', 'shexj', 'sse']  format ('shexc')
   # @param  [Hash{Symbol => Object}] options
   # @return [ShEx::Algebra::Schema] The executable parsed expression.
-  # @raise  [Parser::Error] on invalid input
+  # @raise [ShEx::ParseError] when a syntax error is detected
+  # @raise [ShEx::StructureError, ShEx::OperandError] on structural problems with schema
   def self.parse(expression, format: 'shexc', **options)
     case format
     when 'shexc' then Parser.new(expression, options).parse
@@ -34,32 +37,46 @@ def self.parse(expression, format: 'shexc', **options)
   ##
   # Parses input from the given file name or URL.
   #
+  # @example parsing a ShExC schema
+  #   schema = ShEx.parse('foo.shex').parse
+  #
   # @param  [String, #to_s] filename
   # @param  ['shexc', 'shexj', 'sse']  format ('shexc')
   # @param  [Hash{Symbol => Object}] options
   #   any additional options (see `RDF::Reader#initialize` and `RDF::Format.for`)
   # @yield  [ShEx::Algebra::Schema]
   # @yieldparam  [RDF::Reader] reader
   # @yieldreturn [void] ignored
-  # @raise  [RDF::FormatError] if no reader found for the specified format
+  # @return [ShEx::Algebra::Schema] The executable parsed expression.
+  # @raise [ShEx::ParseError] when a syntax error is detected
+  # @raise [ShEx::StructureError, ShEx::OperandError] on structural problems with schema
   def self.open(filename, format: 'shexc', **options, &block)
     RDF::Util::File.open_file(filename, options) do |file|
       self.parse(file, options)
     end
   end
 
   ##
-  # Parse and execute the given ShEx `expression` string against `queriable`.
-  # @param  [IO, StringIO, String, #to_s]  expression (ShExC or ShExJ)
-  # @param  ['shexc', 'shexj', 'sse']  format ('shexc')
-  # @param  [Hash{Symbol => Object}] options
-  def self.execute(expression, queryable, format: 'shexc', **options, &block)
+  # Parse and validate the given ShEx `expression` string against `queriable`.
+  #
+  # @example executing a ShExC schema
+  #   graph = RDF::Graph.load("etc/doap.ttl")
+  #   ShEx.execute('etc/doap.shex', graph, "http://rubygems.org/gems/shex", "")
+  #
+  # @param [IO, StringIO, String, #to_s]  expression (ShExC or ShExJ)
+  # @param [RDF::Resource] focus
+  # @param [RDF::Resource] shape
+  # @param ['shexc', 'shexj', 'sse']  format ('shexc')
+  # @param [Hash{Symbol => Object}] options
+  # @return [Boolean] `true` if satisfied, `false` if it does not apply
+  # @raise [ShEx::NotSatisfied] if not satisfied
+  # @raise [ShEx::ParseError] when a syntax error is detected
+  # @raise [ShEx::StructureError, ShEx::OperandError] on structural problems with schema
+  def self.execute(expression, queryable, focus, shape, format: 'shexc', **options, &block)
     shex = self.parse(expression, options)
     queryable = queryable || RDF::Graph.new
 
-    shex.execute(queryable, options)
-  rescue Parser::Error => e
-    raise MalformedQuery, e.message
+    shex.satisfies?(focus, queryable, {focus => shape}, options)
   end
 
   class Error < StandardError

lib/shex/algebra.rb

@@ -1,7 +1,6 @@
 $:.unshift(File.expand_path("../..", __FILE__))
 require 'sparql/algebra'
 require 'sxp'
-require 'shex/algebra/extensions'
 
 module ShEx
   # Based on the SPARQL Algebra, operators for executing a patch

lib/shex/algebra/extensions.rb

@@ -8,8 +8,6 @@ class OneOf < Operator
     # `expr` is a OneOf and there is some shape expression `se2` in shapeExprs such that a `matches(T, se2, m)`...
     #
     # @param [Array<RDF::Statement>] t
-    # @param [RDF::Queryable] g
-    # @param [Hash{RDF::Resource => RDF::Resource}] m
     # @return [Array<RDF::Statement]
     def matches(t)
       results = []

lib/shex/algebra/one_of.rb

@@ -341,8 +341,6 @@ class Unary < Operator
       ##
       # @param  [RDF::Term] arg1
       #   the first operand
-      # @param  [RDF::Term] arg2
-      #   the second operand
       # @param  [Hash{Symbol => Object}] options
       #   any additional options (see {Operator#initialize})
       def initialize(arg1, options = {})

lib/shex/algebra/operator.rb

@@ -15,8 +15,6 @@ class Schema < Operator
     ##
     # Match on schema. Finds appropriate shape for node, and matches that shape.
     #
-    # FIXME: startActs and start
-    #
     # @param [RDF::Resource] n
     # @param [RDF::Queryable] g
     # @param [Hash{RDF::Resource => RDF::Resource}] m