[ldpatch] some cleaning ldpatch
authorAlexandre Bertails <alexandre@bertails.org>
Sun, 27 Jul 2014 22:12:55 -0400
branchldpatch
changeset 728 b59441421b0f
parent 727 8b261730c022
child 745 4c0cabfd1189
[ldpatch] some cleaning
ldpatch.html
--- a/ldpatch.html	Sun Jul 27 17:19:03 2014 -0400
+++ b/ldpatch.html	Sun Jul 27 22:12:55 2014 -0400
@@ -418,9 +418,7 @@
         <p>
 The Bind operation is used to create a new variable by binding or assigning an RDF Term to the variable. The bound variable has a global scope. Use of a given variable name anywhere in an LD Patch document identifies the same variable, although variables can be overriden in subsequent Bound statements. Following the example above, the Bind operation creates a new variable called <code>event</code>, starting from the RDF Term <code>&lt;#&gt;</code> and following the path expression <code>/schema:attendee[/schema:url = &lt;http://conferences.ted.com/TED2009/&gt;]</code> in order to identify the RDF Term to which this variable will be bound to -- i.e. <code>_:b2</code>.
         <pre class='example'>
-...
 Bind ?event &lt;#&gt; /schema:attendee[/schema:url = &lt;http://conferences.ted.com/TED2009/&gt;] .
-...
         </pre>
         </p>
         <p>
@@ -442,11 +440,9 @@
         <p>
 The Add operation is used to add or append new RDF triples to the existing graph. To add new RDF triple, the operation requires a <tref>Subject</tref>, a <tref>Predicate</tref> and either an <tref>Object</tref> or a <tref>List</tref>.
         <pre class='example'>
-...
-Add    &lt;#&gt; profile:first_name "Timothy" .
-...
+Add &lt;#&gt; profile:first_name "Timothy" .
+
 Add ?event rdf:type schema:Event .
-...
         </pre>
 When the third component is an <tref>Object</tref>, then a single statement will be added. On the other hand, when it is a <tref>List</tref>, all the intermediate blank nodes and corresponding statements will be added to construct a well formed RDF collection (@@@ref to RDF-Schema) (in addition to the triple with the given <tref>Subject</tref>, <tref>Predicate</tref> and that collection as the object).
         </p>
@@ -457,11 +453,9 @@
         <p>
 The Delete operation is used to remove a single RDF triple from the existing graph. The syntax for the Delete operation requires a <tref>Subject</tref>, a <tref>Predicate</tref> and an <tref>Object</tref>.
         <pre class='example'>
-...
 Delete &lt;#&gt; profile:first_name "Tim" .
-...
+
 Delete ?ted schema:startDate "2009-02-04".
-...
         </pre>
         </p>
       </section>
@@ -471,17 +465,34 @@
         <p>
 The UpdateList operation is used to update the members of an RDF collection (@@@ref). That collection is supposed to be the object of a triple, specified by its <tref>Subject</tref> and <tref>Predicate</tref>. A <tref>Slice</tref> specification then describes which members (if any) of the collections are affected by the operation, and then a <tref>List</tref> of new members is provided. In the example below, UpdateList is used to replace the second member of a collection by the literal "fr-CH".
         <pre class='example'>
-...
 UpdateList &lt;#&gt; ex:preferredLanguages 1>2 ( "fr-CH" ) .
-...
         </pre>
         </p>
         <p>
 UpdateList works in a similar way to <a href="https://docs.python.org/3/reference/expressions.html#slicings">slicing in Python</a> or similar languages. In general, it replaces a part (“slice”) of a list by another list. To remove members, one can replace them by an empty list. To insert new values between two members, one can set a non empty list to the empty slice comprised between those two members.
         </p>
+
         <p>
-In LD Patch, a slice is described by two positive integers separated by ">". The second integer can be omitted, in that case it denotes the end of the list. If both integers are omitted (i.e. ">" alone), this denotes by convention the empty slice at the end of the list. @@@TODO eplain that indexes start at 0  @@@TODO give some examples here.
+In LD Patch, a slice is described by two positive integers separated by ">". The second integer can be omitted, in that case it denotes the end of the list. If both integers are omitted (i.e. ">" alone), this denotes by convention the empty slice at the end of the list. Indexes start at 0.
         </p>
+
+        <p>
+          The following example shows the syntax for appending elements to a list:
+        </p>
+
+        <pre class='example'>
+UpdateList &lt;#&gt; ex:preferredLanguages > ( "fr-CH" ) .
+        </pre>
+
+        <p>
+          In this final example, we replace all the elements after index 2 with the provided list:
+        </p>
+
+        <pre class='example'>
+UpdateList &lt;#&gt; ex:preferredLanguages 2> ( "fr-CH" ) .
+        </pre>
+
+
       </section>
 
     </section>
@@ -562,7 +573,7 @@
     <section id='abstract-syntax'>
       <h1>Abstract Syntax</h1>
       <p>
-The LD Patch data model makes use of the commonly defined <a href="http://en.wikipedia.org/wiki/Abstract_data_type">Abstract Data Types</a> <a href="http://en.wikipedia.org/wiki/Set_(computer_science)">Set</a>, <a href="http://en.wikipedia.org/wiki/List_(computer_science)">List</a> and <a href="http://en.wikipedia.org/wiki/Option_type">Option</a>, used here as type constructors. For example, <code>Set(A)</code> denotes the type for the sets of elements of type <code>A</code>. We assume that they come with their common operations, such as the function <code>size&nbsp;:&nbsp;Set&nbsp;→&nbsp;Int</code>.					
+The LD Patch data model makes use of the commonly defined <a href="http://en.wikipedia.org/wiki/Abstract_data_type">Abstract Data Types</a> <a href="http://en.wikipedia.org/wiki/Set_(computer_science)">Set</a>, <a href="http://en.wikipedia.org/wiki/List_(computer_science)">List</a> and <a href="http://en.wikipedia.org/wiki/Option_type">Option</a>, used here as type constructors. For example, <code>Set(A)</code> denotes the type for the sets of elements of type <code>A</code>. <!--We assume that they come with their common operations, such as the function <code>size&nbsp;:&nbsp;Set&nbsp;→&nbsp;Int</code>.-->				
       </p>
       <pre>
 <tref>LDPatch</tref> ::= <tref>List</tref>(<tref>Statement</tref>)
@@ -603,126 +614,32 @@
     
     <section id='operational-semantics'>
       <h1>Operational Semantics</h1>
-      <p>
-The denotational RDF semantics makes use of the <a href="http://en.wikipedia.org/wiki/Set-builder_notation">set-builder notation</a> for building the RDF sets.
-      </p>
-      <p>@@[email protected]@</p>
-      <p>
-LD Patch abides to the semantics of the <a href="http://tools.ietf.org/html/rfc5789" target="_blank">HTTP PATCH method</a>, in that the server MUST apply the entire set of changes atomically and never provide (e.g., in response to a GET during this operation) a partially modified representation. If the entire patch document cannot be successfully applied (e.g., one of the instructions has failed), then the server MUST NOT apply any of the changes.
-      </p>
-<!--pre>An Env(ironment) is a Map from Var-s to Node-s
-Env      ::= Map(Var, Set(Node))
-
-TBD
----
-
-env[x]
-env[x -> nodes]
-
-matchTriples: Graph -> Option(Node) -> Uri -> Option(Node) -> Set((Node, Uri, Node))
-matchTriples: (g: Graph) -> (s: Option(Node)) -> (p: Uri) -> (o: Option(Node)) -> { matchingTriples: Set((Node, Uri, Node)) | triple matches the pattern (s, p, o) in g -> triple ∈ matchingNodes }
-
-+: Graph -> Set(Triple) -> Graph
-
--: Graph -> Set(Triple) -> Graph
-
-sem functions
--------------
-
-sem_varOrConcreteNode is a function that maps a Var to a Node or a ConcreteNode to itself
-sem_varOrConcreteNode: Env -> VarOrConcreteNode -> Set(Node)
-sem_varOrConcreteNode(env, v: Var) = env[v]
-sem_varOrConcreteNode(env, uri: Uri) = Set(uri)
-sem_varOrConcreteNode(env, literal: Literal) = Set(literal)
-
-sem_matchingNodes: Graph -> Set(Node) -> Path -> Set(Node)
-sem_matchingNodes(graph, nodes, List()) = nodes
-sem_matchingNodes(graph, nodes, (Forward, uri, mode) :: restPath) =
-  let triples = { matchTriples(graph, node, uri, ANY) | node ∈ nodes } in
-  let matchingNodes = { o | (s, p, o) ∈ triples } in
-  if mode is Single and size(matchingNodes) is not 1 then throw error
-  sem_matchingNodes(graph, matchingNodes, restPath)
-sem_matchingNodes(graph, nodes, (Backward, uri, mode) :: restPath) =
-  let triples = { matchTriples(graph, ANY, uri, node) | node ∈ nodes } in
-  let matchingNodes = { s | (s, p, o) ∈ triples } in
-  if mode is Single and size(matchingNodes) is not 1 then throw error
-  sem_matchingNodes(graph, matchingNodes, restPath)
-
-makeTriples: Set(Node) -> OrientedPredicate -> Node -> Set(Triple)
-makeTriples(nodes, (Forward, uri), node) =
-  { (n, uri, node) | n ∈ nodes }
-makeTriples(nodes, (Backward, uri), node) =
-  { (node, uri, n) | n ∈ nodes }
-
-
-sem_bind: (Env, Graph) -> Bind -> (Env, Graph)
-sem_bind((env, graph), Bind(start, path, v)) =
-  let nodes = sem_matchingNodes(sem_varOrConcreteNode(graph, env, start), path) in
-  (env[v -> nodes], graph)
 
-sem_add: (Env, Graph) -> Add -> (Env, Graph)
-sem_add((env, graph), Add(start, path, orientedPredicate, (node, pgTriples))) =
-  let nodes = sem_matchingNodes(sem_varOrConcreteNode(graph, env, start), path) in  
-  let triples = makeTriples(nodes, orientedPredicate, node) in
-  (env, graph + triples + pgTriples)
-
-
-sem_delete: (Env, Graph) -> Delete -> (Env, Graph)
-sem_delete((env, graph), Delete(start, path, orientedPredicate, None)) =
-  let nodes = sem_matchingNodes(sem_varOrConcreteNode(graph, env, start), path) in
-  let triples = { matchTriples(graph, node, orientedPredicate, None) | node ∈ nodes } in
-  (env, graph - triples)
-sem_delete((env, graph), Delete(start, path, orientedPredicate, Some((node, pgTriples)))) =
-  let nodes = sem_matchingNodes(sem_varOrConcreteNode(graph, env, start), path) in
-  let triples = { matchTriples(graph, node, orientedPredicate, Some(node)) | node ∈ nodes } in
-  (env, graph - triples - pgTriples)
-
-sem_cut: (Env, Graph) -> Cut -> (Env, Graph)
-sem_cut((env, graph), Cut(varOrConcreteNode)) =
-  let nodes = sem_varOrConcreteNode(graph, env, varConcreteNode) in
-  let triples = connectedGraph(nodes) in
-  (env, graph = triples)
-
-
-connectedGraph: Graph -> Set(Node) -> Set(Triple)
-connectedGraph(graph, nodes) =
-  let f(triples) = { matchingTriples(o, None, None)  | (s, p, o) ∈ triples } in
-  fixpoint f
-
+      <p>
+        LD Patch abides to the semantics of the <a href="http://tools.ietf.org/html/rfc5789" target="_blank">HTTP PATCH method</a>, in that the server MUST apply the entire set of changes atomically and never provide (e.g., in response to a GET during this operation) a partially modified representation. If the entire patch document cannot be successfully applied (e.g., one of the instructions has failed), then the server MUST NOT apply any of the changes.
+      </p>
 
-sem_update: (Env, Graph) -> Update -> (Env, Graph)
-sem_update((env, graph), Update(varOrConcreteNode, (pgNode, pgTriples))) =
-  let nodes = sem_varOrConcreteNode(graph, env, varOrConcreteNode) in
-  let incomingTriples = { matchingTriples(None, None, node) | node ∈ nodes } in
-  let newIncomingTriples = { (s, p, pgNode) | (s, p, _) ∈ incomingTriples } in
-  let connectedTriples = connectedGraph(nodes) in
-  (env, graph - incomingTriples - connectedTriples + newIncomingTriples + pgTriples)
-
-sem_patch: Graph -> List(Statement) -> Graph
-sem_patch(g, statements) = sem_patch_state(({}, g), statements)
+      <p>
+      </p>
 
-sem_statement: (Env, Graph) -> Statement -> (Env, Graph)
-sem_statement(state, bind: Bind) = sem_bind(state, bind)
-sem_statement(state, add: Add) = sem_bind(state, add)
-sem_statement(state, delete: Delete) = sem_bind(state, delete)
-sem_statement(state, update: Update) = sem_bind(state, update)
+      <h2></h2>
 
-sem_patch_state: (Env, Graph) -> List(Statement) -> Graph
-sem_patch_state((env, graph), List()) = graph
-sem_patch_state(state, statement :: restStatements) =
-  let newState = sem_statement(state, statement) in
-  sem_patch_state(newState, restStatements)
-
-
+      <!-- p>The formal semantics of a statement is a function from state to state. That state carries the current graph and a map from variables to RDF nodes. The semantics of an LD Patch document is defined by applying its statements in order while carrying the state. The initial state is made of the original graph and of an empty mapping. If no runtime errors occurs, the final state has the final value of the graph.</p>
 
+      <p>The semantics of a Subject, an Object and Value a ground RDF node ie. it is itself if it is a RDF node, or its value in the map if it is a variable. The semantics of all the statements, including Bind, is defined on ground terms.</p>
 
-TODO:
-* runtime error
-* parsing error
-* grammar
-* lists
-* examples
-* best practices
+      <p>The semantics of Bind is defined by evaluating the path on the starting node, and adding a binding from the variable to the result.</p>
+
+      <p>The semantics of Add is defined by adding the triple made of the (Subject, Predicate, Object) to the current graph.</p>
+
+      <p>The semantics of AddList is defined by adding the triple made of the (Subject, Predicate, Object) to the current graph.</p>
+
+      <p>The semantics of Delete is defined by removing the triple made of the (Subject, Predicate, Object) from the current graph.</p>
+
+      <p></p-->
+
+      <p>TODO</p>
+
 
         </pre-->
     </section>