Menu
▾
▴
[Jboss-svn-commits] JBL Code SVN: r3880 - labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language
|
From: <jbo...@li...> - 2006-04-21 10:20:19
|
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 > {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" ---> Person(name="kitty")
+Person is at least 42 years old and lives in "atlanta" ---> Person(age > 42, location="atlanta")
+Log "boo" ---> System.out.println("boo");
+There is a Person with name of "bob" and Person is at least 30 years old and lives in "atlanta"
+ ---> Person(name="kitty") and Person(age > 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
|
