From d951340fb311b6b231430820c52074edcf9f52b2 Mon Sep 17 00:00:00 2001 From: Roland Olbricht Date: Sun, 3 May 2009 21:24:45 +0000 Subject: [PATCH] =?UTF-8?q?Use=20cases=20in=20der=20Dokumentation=20vervol?= =?UTF-8?q?lst=C3=A4ndigt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- add_rule.c | 4 +- html/index.html | 516 +++++++++++++++++++++++++++++++++++++++++++++++- some_rules.xml | 4 +- update_rule.c | 6 +- 4 files changed, 522 insertions(+), 8 deletions(-) diff --git a/add_rule.c b/add_rule.c index dc731d05a..061383e68 100644 --- a/add_rule.c +++ b/add_rule.c @@ -143,8 +143,10 @@ int main(int argc, char *argv[]) temp<<"')"; mysql_query(mysql, temp.str().c_str()); + set_debug_mode(VERBOSE); temp.str(""); - temp<<"Rule '"<OSM Server Side Script     union
Concepts
    Data structures
+    Scripts and Rules
    Control Flow
    Variables
    Other Sets in Scripts
@@ -84,7 +85,7 @@

Use Cases

The following examples are some sample use cases to give you an idea what you can do with the system. Of course, there are many more useful -use cases, and you are kindly invited to add other use cases.

+use cases, and you are kindly invited to add other use cases in the wiki.

@@ -118,7 +119,7 @@

Download an entire city

  • An area based on a way has the the id of the way plus 2,400,000,000.
  • An area based on a relation has the id of the relation plus 3,600,000,000.
    • -For example, the area representing the German city "Wuppertal" has id 3,600,062,478 because its pivot element is the relation 62,478 describing the borders of Wuppertal. In particular this means that area ids are as stable as the ids in the OSM database. +For example, the area representing the German city "Wuppertal" has id 3,600,062,478 because its pivot element is the relation 62,478 describing the borders of Wuppertal. In particular this means that area ids are as stable as the ids in the OSM database. If you don't know the id of the OSM entity in question, then can simply     query it.

    @@ -138,7 +139,7 @@

    Download an entire city

    -If you prefer to receive additionally all nodes any way refers to, you can change the script to: This script also will take some time before it gives a response depending on server load.
    +If you prefer to receive additionally all nodes any way refers to, you can change the script to: This script also will take some time depending on server load before it gives a response.

    + +

    +The server will return a human readable HTML document that lists the conflicts related to this relation; these are generated by user editable rules and should be self-explanatory. The result can be empty (and probably will be empty for Wuppertal because the respective area has successfully been created), but we simply can't leave an area in permanently broken state to show how the conflict feedback system works. +

    + +

    +If you get an empty result from the first query, check whether there exists a relation at all: +

    + + +

    +This searches the data for all relations that match the given criteria, i.e. that have a tag with key "name" and value "Wuppertal". +

    + +

    +If you already know the id of your relation, you can use instead the following to find conflicts: +

    + + +

    +

    + +

    +We give a short overview of the used statement: the query <query type="relation"><has-kv k="name" v="Wuppertal, Stadt"/></query> searches for relations (this is specified by the parameter type) that have a tag with key "name" and value "Wuppertal, Stadt" (this condition is specified by the tag <has-kv k="name" v="Wuppertal, Stadt"/>. A full explanation of the quite versatile syntax of the query statement can be found in its documentation. The <id-query type="relation" ref="62478"/> by contrast finds the single relation with id 62478 as specified by the parameter ref. Both store their result into the default set because there is no other set specified. Then, the statement <report/> prints to the user all conflicts that are related to an item in its input, again the default set. It doesn't change any values in the script. Alternatively, the <print mode="body"/> simply prints the entire content of the default set. +

    +

    Declare a new type of area

    +

    +Not all relations that refer to ways give automatically rise to a relation. The server recognizes a certain relation (or any other designated set of ways) as an area if a rule matches this relation or set of ways. The amazing thing is that you (or anybody else) can add rules or change the existing ones. Now assume that you want to designate all relations with a tag with key "foo" and value "bar" to represent areas. +

    + +

    +You can retrieve an existing rule to get a blueprint for our new rule. For example, the following query will return the rule that creates areas from administrative units: +

    + + +

    +This will give you a result like the following: +
    +<osm-script name="Area::Create_from_admin_level" version="1">
+
+<query type="relation">
+  <has-kv k="admin_level"/>
+  <has-kv k="name"/>
+</query>
+<foreach into="rel">
+  <union>
+    <recurse type="relation-way" from="rel"/>
+    <recurse type="way-node"/>
+  </union>
+  <make-area pivot="rel" into="odd"/>
+  <detect-odd-nodes into="odd"/>
+  <foreach from="odd" into="i">
+    <union><item set="i"/><item set="rel"/></union>
+    <conflict>In <item set="rel"/>, the <item set="i"/> is contained in an odd number of segments.</conflict>
+  </foreach>
+</foreach>
+
+</osm-script>
+
     +

    + +

    +We take the following modifications: In the first line, we replace the name of the rule by a new, descriptive name because we are adding a new rule. We remove the version tag because this will be chosen by the server. Then, we replace the two lines starting with has-kv by a single line that describes the designation for the relations in question. Then we post the new rule to add_rule: +

    + + +

    +You should recieve a message that the rule has successfully been added along with its new version number. If you recieve a the error that a rule with this name already exists, you have probably not changed the name in the above rule (and another guy already has left this example in the rule base). +

    + +

    +To avoid cluttering the server, please complete this tutorial with removing your rule. Just call update_rule with the empty rule and the parameter replace set to the version number just recieved: +

    + + +

    +You should recieve a message that the rule has successfully been updated. If you recieve the error that you should provide the last version-id, then call again get_rule on you rule: +
    + + +

    +The result contains the correct version number. +

    + +

    +We conclude by explaining the statements in the rule "Area::Create_from_admin_level": The first line <osm-script name="Area::Create_from_admin_level" version="1"> is an explicit statement of the root element because a rule needs always a name and the name is provided as parameter of the root element. The version tag is added by the server to indicate which version of the rule it has returned - in our example the most recent version which is by incidence 1. +

    + +

    +The first executable statement in the rule is the query-block <query type="relation"><has-kv k="admin_level"/><has-kv k="name"/></query>. This query-block searches for relations as specified by the parameter "type". It returns only relations that have a tag with key "admin_level" and a tag with key "name". For both tags, any values match the search criteria as there are no values specified in the has-kv tags. The results of the query are stored into the default set. A detailed description of the query syntax can be found in its documentation. +

    + +

    +The <foreach into="rel"> statement regulates the control flow: The body is executed once for each element in the input set. As there is no input set specified, the input is taken from the default set. The output set "rel" contains during each loop solely the respective element from the input set. +

    + +

    +The foreach-body starts with an union-block, containing the two statements <recurse type="relation-way" from="rel"/> and <recurse type="way-node"/>. The first one sets the default set to the set of all ways that are members of the relation in the input set "rel". The second sets the default set to the set of all nodes that are referred by ways from the default set. Because of the union-block wrapped around, the default set contains afterwards the ways that are members of the relation and their associated nodes. +

    + +

    +The statement <make-area pivot="rel" into="odd"/> now creates the area: It takes input from two different sets. The first one not specified, thus being the default set, contains the ways and nodes that decribe the spatial extent of the area; it contains any point that is separated from the south pole by an odd number of way segments. The second input set is specified by the pivot parameter. It should contain exactly one element, and the set "rel", set by foreach, does so. The area's id and tags are derived from this element. The output of make-area is the created area if any. It is simultanenously written to the output set as well as the database. The set is in our case redirected to the set "odd" as we don't need the area anymore. +

    + +

    +The <detect-odd-nodes into="odd"/> statement detects nodes that appear an odd times as starting or end points of a way. These nodes are exactly the nodes that prevent make-area from making an area. The detect-odd-nodes statement takes its input from the default set because there is no other set specified. The default set still contains the ways and nodes to produce an area from. The odd nodes are returned into the specified output set "odd". +

    + +

    +The <foreach from="odd" into="i"> statement loops over these nodes, which are stored in the input set "odd". Each node is during one loop available as content of the set "i". In the loop, the line <union><item set="i"/><item set="rel"/></union> sets the default set to the node of the inner loop and the relation from the outer loop: The <item set="i"/> statement returns the content of the set "i" as output, hence the node of the current inner loop. The <item set="rel"/> returns the set "rel" that contains the relation of the current outer loop. +

    + +

    +Finally, the line <conflict>In <item set="rel"/>, the <item set="i"/> is contained in an odd number of segments.</conflict> writes the conflict message into the database for the elements of the current inner and current outer loop. It obtains these elements from its input set, the default set. In the conflict message, the subtags <item set="rel"/> and <item set="i"/> are replaced by their contents. The conflict statement does not return anything. Then the script continues with another inner loop or outer loop respectively. +

    + +

    Interface Calls

    @@ -243,71 +397,421 @@

    Statements

    area-query

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    conflict

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    coord-query

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    detect-odd-nodes

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    foreach

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    id-query

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    item

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    make-area

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    osm-script

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    print

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    query

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    recurse

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    report

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +

    union

    +
    + +

    Mandatory parameters

    +
    + +
    + +

    Optional parameters

    +
    + +
    + +

    Description

    +
    + +
    + +

    Properties

    +
    + +
    + +

    Examples

    +
    +
    @@ -316,6 +820,7 @@

    Concepts

    Data structures
    +Scripts and Rules
    Control Flow
    Variables
    Other Sets in Scripts
    @@ -329,6 +834,11 @@

    Concepts

    Data structures

    +
    + +

    Scripts and Rules

    +
    +

    Control Flow

    diff --git a/some_rules.xml b/some_rules.xml index 7812ff1a5..f1c9e477e 100644 --- a/some_rules.xml +++ b/some_rules.xml @@ -12,7 +12,7 @@ - + @@ -33,7 +33,7 @@ - + diff --git a/update_rule.c b/update_rule.c index 76cd2630b..8191dea4a 100644 --- a/update_rule.c +++ b/update_rule.c @@ -88,7 +88,7 @@ int main(int argc, char *argv[]) if (!rule_replace) add_static_error("Updating a rule requires providing its last version-id."); if (rule_version) - add_static_error("Providing a version-id while updating a rule is not allowed."); + add_static_error("Providing an arbitrary version-id while updating a rule is not allowed."); xml_raw = xml_raw.substr(xml_raw.find("') + 1); @@ -150,8 +150,10 @@ int main(int argc, char *argv[]) temp<<"')"; mysql_query(mysql, temp.str().c_str()); + set_debug_mode(VERBOSE); temp.str(""); - temp<<"Rule '"<