jboss-svn-commits Mailing List for JBoss Community (Page 54)

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Author: mic...@jb...
Date: 2006-04-21 06:19:58 -0400 (Fri, 21 Apr 2006)
New Revision: 3880

Modified:
   labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml
Log:
more documentation goodness

Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml
===================================================================

--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml	2006-04-21 03:22:59 UTC (rev 3879)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml	2006-04-21 10:19:58 UTC (rev 3880)
@@ -55,20 +55,20 @@
     values that match where the {something} (named Tokens) appear in the
     input. The values that match the tokens are then interpolated with the
     corresponding {something} (named Tokens) on the right hand side of the
-    mapping (the target expression).</para>
+    mapping (the target expression that the rule engine actually uses).</para>
 
     <para>It is important to note that the DSL expressions are processed one
     line at a time. This means that in the above example, all the text after
-    "There is " will be included as the value for "{something}" when it is
-    interpolated into the target string. This may not be exactly what you
-    want, as you may want to "chain" together different DSL expressions to
-    generate a target expression. The best way around this is to make sure
-    that the {tokens} are enclosed with characters or words. This means that
-    the parser will scan along the sentence, and pluck out the value BETWEEN
-    the characters (in the example below they are doublequotes). Note that the
-    characters that surrount the token are not included in when interpolating,
-    just the contents between them (rather then all the way to the end of the
-    line, as would otherwise be the case).</para>
+    "There is " to the end of the line will be included as the value for
+    "{something}" when it is interpolated into the target string. This may not
+    be exactly what you want, as you may want to "chain" together different
+    DSL expressions to generate a target expression. The best way around this
+    is to make sure that the {tokens} are enclosed with characters or words.
+    This means that the parser will scan along the sentence, and pluck out the
+    value BETWEEN the characters (in the example below they are doublequotes).
+    Note that the characters that surround the token are not included in when
+    interpolating, just the contents between them (rather then all the way to
+    the end of the line, as would otherwise be the case).</para>
 
     <para>As a rule of thumb, use quotes for textual data that a rule editor
     may want to enter. You can also wrap words around the {tokens} to make
@@ -85,11 +85,17 @@
     expressions where possible, other then quotes and the like - keep it
     simple it things will be easier. Using a DSL can make debugging slightly
     harder when you are first building rules, but it can make the maintenance
-    easier.</para>
+    easier (and of course the readability of the rules).</para>
 
+    <para>The "{" and "}" characters should only be used on the left hand side
+    of the mapping (the expression) to mark tokens. On the right hand side you
+    can use "{" and "}" on their own if needed (such as if (foo) {
+    doSomething(); } ) as well as with the token names as shown above.</para>
+
     <para>Don't forget that if you are capturing strings from users, you will
     also need the quotes on the right hand side of the mapping, just like a
-    normal rule.</para>
+    normal rule, as the result of the mapping must be a valid expression in
+    the rule language.</para>
 
     <example>
       <title>Some more examples</title>
@@ -98,8 +104,19 @@
 [when]There is a Person with name of "{name}"=Person(name=="{name}")
 [when]Person is at least {age} years old and lives in "{location}"=Person(age &gt; {age}, location=="{location}")
 [then]Log "{message}"=System.out.println("{message}");
-</programlisting>
+[when]And = and</programlisting>
     </example>
+
+    <para>Referring to the above examples, this would render the following
+    input as shown below: <example>
+        <title>Some examples as processed</title>
+
+        <programlisting>There is a Person with name of "kitty" ---&gt; Person(name="kitty")
+Person is at least 42 years old and lives in "atlanta" ---&gt; Person(age &gt; 42, location="atlanta")
+Log "boo" ---&gt; System.out.println("boo");
+There is a Person with name of "bob" and Person is at least 30 years old and lives in "atlanta" 
+          ---&gt; Person(name="kitty") and Person(age &gt; 30, location="atlanta")</programlisting>
+      </example></para>
   </section>
 
   <section>
@@ -128,14 +145,57 @@
 //source is a reader for the rule source, dsl is a reader for the DSL configuration
 </programlisting> You will also need to specify the expander by name in the
     rule source file: <programlisting>expander your-expander.dsl
-</programlisting> Typically you keep the DSL in the same directory as the
-    rule, but this is not required if you are using the above API (you only
-    need to pass a reader). Otherwise everything is just the same.</para>
+</programlisting>Typically you keep the DSL in the same directory as the rule,
+    but this is not required if you are using the above API (you only need to
+    pass a reader). Otherwise everything is just the same.</para>
+
+    <para>You can chain DSL expressions together on one line, as long as it is
+    clear to the parser what the {tokens} are (otherwise you risk reading in
+    too much text until the end of the line). The DSL expressions are
+    processed according to the mapping file, top to bottom in order. You can
+    also have the resulting rule expressions span lines - this means that you
+    can do things like:</para>
+
+    <example>
+      <programlisting>There is a person called Bob who is happy
+  Or
+There is a person called Mike who is sad
+</programlisting>
+    </example>
+
+    <para>Of course this assumes that "Or" is mapped to the "or" conditional
+    element (which is a sensible thing to do).</para>
   </section>
 
   <section>
     <title>How it works</title>
 
-    <para></para>
+    <para>DSLs kick in when the rule is parsed. The DSL configuration is read
+    and supplied to the parser, so the parser can "expand" the DSL expressions
+    into the real rule language expressions.</para>
+
+    <para>When the parser is processing the rules, it will check if an
+    "expander" representing a DSL is enabled, if it is, it will try to expand
+    the expression based on the context of where it is the rule. If an
+    expression can not be expanded, then an error will be added to the
+    results, and the line number recorded (this insures against typos when
+    editing the rules with a DSL). At present, the DSL expander is fairly
+    space sensitive, but this will be made more tolerant in future releases
+    (including tolerance for a wide range of punctuation).</para>
+
+    <para>The expansion itself works by trying to match a line against the
+    expression in the DSL configuration. The values that correspond to the
+    token place holders are stored in a map based on the name of the token,
+    and then interpolated to the target mapping. The values that match the
+    token placeholders are extracted by either searching until the end of the
+    line, or until a character or word after the token place holder is
+    matched. The "{" and "}" are not included in the values that are
+    extracted, they are only used to demarcate the tokens - you should not use
+    these characters in the DSL expression (but you can in the target).</para>
+
+    <para>Refer to the ExpanderResolver, Expander and DefaultExpander classes
+    for more indepth information if required. As the parser works off the
+    Expander and ExpanderResolver interfaces, it is possible to plug in your
+    own advanced expanders if required.</para>
   </section>
 </section>
\ No newline at end of file





2005	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug (233)	Sep (199)	Oct (206)	Nov (185)	Dec (270)
2006	Jan (232)	Feb (426)	Mar (623)	Apr (592)	May (506)	Jun (389)	Jul (160)	Aug (3)	Sep (1)	Oct (1)	Nov (2)	Dec (5)
2007	Jan (1)	Feb (1)	Mar (2)	Apr (2)	May (4)	Jun (2)	Jul	Aug (3)	Sep (5)	Oct (9)	Nov (6)	Dec (6)
2008	Jan (3)	Feb	Mar (1)	Apr (3)	May (3)	Jun (5)	Jul (10)	Aug (2)	Sep (12)	Oct (10)	Nov (54)	Dec (49)
2009	Jan (19)	Feb (13)	Mar (20)	Apr (24)	May (44)	Jun (29)	Jul (32)	Aug (10)	Sep (7)	Oct (10)	Nov (4)	Dec (17)
2010	Jan (14)	Feb (5)	Mar (23)	Apr (50)	May (31)	Jun (9)	Jul (5)	Aug (4)	Sep (7)	Oct (5)	Nov (2)	Dec (3)
2011	Jan (12)	Feb (5)	Mar (5)	Apr (3)	May (4)	Jun (3)	Jul (2)	Aug	Sep	Oct	Nov (1)	Dec
2012	Jan (1)	Feb (2)	Mar	Apr (1)	May (1)	Jun (2)	Jul (4)	Aug (1)	Sep	Oct (1)	Nov	Dec
2013	Jan	Feb	Mar	Apr	May	Jun	Jul (2)	Aug (1)	Sep	Oct	Nov	Dec
2014	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug (3)	Sep	Oct	Nov	Dec (1)
2015	Jan	Feb	Mar (2)	Apr	May	Jun (1)	Jul	Aug	Sep	Oct	Nov	Dec
2016	Jan	Feb	Mar	Apr	May	Jun (1)	Jul (1)	Aug	Sep	Oct	Nov	Dec

jboss-svn-commits Mailing List for JBoss Community (Page 54)

jboss-svn-commits — JBoss SVN commit notifications