Merge branch 'release/0.0.1'

jgeldart · Dec 8, 2010 · 2852b7e · 2852b7e
2 parents b9fe67a + 6a993bb
commit 2852b7e
Show file tree

Hide file tree

Showing 5 changed files with 563 additions and 0 deletions.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,19 @@
+Copyright (C) 2010, Joe Geldart 
+
+Permission is hereby granted, free of charge, to any person obtaining a 
+copy of this software and associated documentation files (the "Software"), 
+to deal in the Software without restriction, including without limitation 
+the rights to use, copy, modify, merge, publish, distribute, sublicense, 
+and/or sell copies of the Software, and to permit persons to whom the 
+Software is furnished to do so, subject to the following conditions: 
+
+The above copyright notice and this permission notice shall be included in 
+all copies or substantial portions of the Software. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL 
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE. 
diff --git a/README.md b/README.md
@@ -0,0 +1,45 @@
+# jQuery SPARQL
+## An idiomatic DSL for SPARQL queries 
+
+[SPARQL] is to linked data as SQL is to relational databases. It is a query
+language for semi-structured, open-ended data. SPARQL is also an 
+increasingly popular way of exposing large datasets, such as those provided
+by the [UK government].
+
+jQuery SPARQL provides a DSL for programmatically constructing SPARQL queries
+against some endpoint. It uses the same 'monadic' style that is used by [jQuery],
+[Raphael], [Protovis] and other popular Javascript libraries to allow queries to 
+be manipulated as first-class objects. The main aim of the library is to
+eliminate messy string manipulations to produce and execute well-formed
+queries.
+
+Currently, the only substantial bit of jQuery used is its abstraction for
+JSON-P. This may change as we look to concrete application use-cases. Beyond
+jQuery, the library uses Yahoo!'s [YQL] service, specifically [Dave Beckett]'s 
+Triplr table, to wrap around arbitrary SPARQL endpoints (which often don't
+support either CORS or JSON-P). It is hoped that this part of the library can
+be abstracted out soon.
+
+## To Do
+
+There are many things left to do with this library, including but not limited to:
+
+- Abstracting out the execution system to support different endpoints and (maybe)
+  any local SPARQL implementations.
+- Support for more sorts of query than just SELECT (including update operators).
+- Support for automatic coercion of RDF data types to Javascript ones.
+- Integration with follow-on processing, such as DOM population, data analysis,
+  summarisation and visualisation.
+- Production of detailed documentation.
+- Lots and lots of tests.
+
+If you have any ideas about these things, or need to solve them for your work,
+please get in touch and contribute to the project!  
+
+[SPARQL]:http://www.w3.org/TR/rdf-sparql-query/
+[jQuery]:http://jquery.com/
+[Raphael]:http://raphaeljs.com/
+[Protovis]:http://vis.stanford.edu/protovis/
+[Dave Beckett]:http://www.dajobe.org/
+[YQL]:http://developer.yahoo.com/yql/
+[UK government]:http://data.gov.uk/
diff --git a/example.html b/example.html
@@ -0,0 +1,130 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Examples of usage - jQuery SPARQL</title>
+    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>
+    <script src="urlEncode.js"></script>
+    <script src="jquery.sparql.js"></script>
+    <script>
+      var cbfunc = function(results) {
+        $("#results").val(JSON.stringify(results));
+      };
+
+      $(document).ready(function() {
+        $("#run_school_list").click(function(e) {
+          $.sparql("http://gov.tso.co.uk/education/sparql")
+            .prefix("sch-ont","http://education.data.gov.uk/def/school/")
+            .select(["?name"])
+              .where("?school","a","sch-ont:School")
+                .where("sch-ont:establishmentName", "?name")
+                .where("sch-ont:districtAdministrative", "<http://statistics.data.gov.uk/id/local-authority-district/00HB>")
+            .orderby("?name")
+            .limit(10)
+            .execute(cbfunc);
+          return false;
+        });
+
+        $("#run_school_and_address_list").click(function(e) {
+          $.sparql("http://gov.tso.co.uk/education/sparql")
+             .prefix("sch-ont", "http://education.data.gov.uk/def/school/")
+             .select(["?name", "?address1", "?address2", "?postcode", "?town"])
+             .where("?school", "a", "sch-ont:School")
+               .where("sch-ont:establishmentName", "?name")
+               .where("sch-ont:districtAdministrative", "<http://statistics.data.gov.uk/id/local-authority-district/00HB>")
+               .optional()
+                 .where("?school", "sch-ont:address", "?address")
+                 .where("?address", "sch-ont:address1", "?address1")
+                   .where("sch-ont:address2", "?address2")
+                   .where("sch-ont:postcode", "?postcode")
+                   .where("sch-ont:town", "?town")
+               .end()
+             .orderby("?name")
+             .execute(cbfunc);
+            return false;
+          });
+      });
+    </script>
+  </head>
+  <body>
+    <h1>Examples of usage</h1>
+    <p>
+      These examples are drawn from the <a href="http://www.data.gov.uk">Data.gov.uk</a> education
+      dataset. They were first described in <a href="http://data.gov.uk/blog/using-sparql-our-education-datasets">a blog post</a>
+      which was chosen for the sake of familiarity and comparison.
+    </p>
+    <p>
+      Each query is shown in standard SPARQL syntax and as expressed in this DSL. The queries may be run by
+      clicking the "Run Me" link below the two blocks. The results are then shown in the text area.
+    </p>
+
+    <h2>Results</h2>
+    <textarea id="results">
+      Results will appear here.
+    </textarea>
+
+    <h2>First 10 schools in the Bristol area ordered by name</h2>
+    <h3>Original SPARQL</h3>
+    <blockquote>
+      <pre><code>PREFIX sch-ont: &lt;http://education.data.gov.uk/def/school/&gt;
+SELECT ?name WHERE {
+	?school a sch-ont:School;
+    sch-ont:establishmentName ?name;
+    sch-ont:districtAdministrative	&lt;http://statistics.data.gov.uk/id/local-authority-district/00HB&gt;;
+}
+ORDER BY ?name
+LIMIT 10</code></pre>
+    </blockquote>
+    <h3>Javascript</h3>
+    <blockquote>
+      <pre><code>$.sparql("http://gov.tso.co.uk/education/sparql")
+  .prefix("sch-ont","http://education.data.gov.uk/def/school/")
+  .select(["?name"])
+    .where("?school","a","sch-ont:School")
+      .where("sch-ont:establishmentName", "?name")
+      .where("sch-ont:districtAdministrative", "&lt;http://statistics.data.gov.uk/id/local-authority-district/00HB&gt;")
+  .orderby("?name")
+  .limit(10)
+  .execute(cbfunc);</code></pre>
+    </blockquote>
+    <p><a id="run_school_list" href="#">Run Me</a></p>
+
+    <h2>Schools in the Bristol area (with addresses) ordered by name</h2>
+    <h3>Original SPARQL</h3>
+    <blockquote>
+      <pre><code>PREFIX sch-ont: &lt;http://education.data.gov.uk/def/school/&gt;
+SELECT ?name ?address1 ?address2 ?postcode ?town WHERE {
+  ?school a sch-ont:School;
+    sch-ont:establishmentName ?name;
+    sch-ont:districtAdministrative &lt;http://statistics.data.gov.uk/id/local-authority-district/00HB&gt;; .
+  OPTIONAL {
+    ?school sch-ont:address ?address .
+
+    ?address sch-ont:address1 ?address1;
+      sch-ont:address2 ?address2 ;
+      sch-ont:postcode ?postcode ;
+      sch-ont:town ?town .
+  }
+}
+ORDER BY ?name</code></pre>
+    </blockquote>
+    <h3>Javascript</h3>
+    <blockquote>
+      <pre><code>$.sparql("http://gov.tso.co.uk/education/sparql")
+ .prefix("sch-ont", "http://education.data.gov.uk/def/school/")
+ .select(["?name", "?address1", "?address2", "?postcode", "?town"])
+ .where("?school", "a", "sch-ont:School")
+   .where("sch-ont:establishmentName", "?name")
+   .where("sch-ont:districtAdministrative", "&lt;http://statistics.data.gov.uk/id/local-authority-district/00HB&gt;")
+   .optional()
+     .where("?school", "sch-ont:address", "?address")
+     .where("?address", "sch-ont:address1", "?address1")
+       .where("sch-ont:address2", "?address2")
+       .where("sch-ont:postcode", "?postcode")
+       .where("sch-ont:town", "?town")
+   .end()
+ .orderby("?name")
+ .execute(cbfunc);</code></pre>
+    </blockquote>
+    <p><a id="run_school_and_address_list" href="#">Run Me</a></p>
+  </body>
+</html>