[jboss-svn-commits] JBL Code SVN: r19473 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Apr 8 00:13:13 EDT 2008
Author: irooskov at redhat.com
Date: 2008-04-08 00:13:13 -0400 (Tue, 08 Apr 2008)
New Revision: 19473
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml
Log:
untinual update for reference guide revision
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml 2008-04-08 03:29:18 UTC (rev 19472)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml 2008-04-08 04:13:13 UTC (rev 19473)
@@ -145,55 +145,53 @@
</section>
<section>
- <title>Using a DSL in your rules</title>
+ <title>Using a DSL with rules</title>
- <para>A good way to get started if you are new to Rules (and DSLs) is just
- write the rules as you normally would against your object model. You can
- unit test as you go (like a good agile citizen!). Once you feel
- comfortable, you can look at extracting a domain language to express what
- you are doing in the rules. Note that once you have started using the
- "expander" keyword, you will get errors if the parser does not recognize
- expressions you have in there - you need to move everything to the DSL. As
- a way around this, you can prefix each line with ">" and it will tell
+ <para>A good way to get started with Rules (and DSLs) is to
+ write the rules normally, against the object model and unit test throughout. Once familiar with this process, a domain language can be extracted to express what is being undertaken in the rules.</para>
+
+<note>
+<para>
+ Once you have started using the
+ <emphasis>expander</emphasis> keyword, errors will occur if the parser does not recognize some of the expressions; to correct this everything will need to be moved to the DSL. As
+ a way around this, each line can be prefixed with <code>></code> and it will tell
the parser to take that line literally, and not try and expand it (this is
- handy also if you are debugging why something isn't working).</para>
+ also useful when debugging).</para>
+</note>
- <para>Also, it is better to rename the extension of your rules file from
- ".drl" to ".dslr" when you start using DSLs, as that will allow the IDE to
- correctly recognize and work with your rules file.</para>
+ <para>Also, it is better to rename the extension of the rules file from
+ <filename>.drl</filename> to <filename>.dslr</filename> when starting to use DSLs, as that will allow the IDE to
+ correctly recognize and work with the rules file.</para>
- <para>As you work through building up your DSL, you will find that the DSL
- configuration stabilizes pretty quickly, and that as you add new rules and
- edit rules you are reusing the same DSL expressions over and over. The aim
- is to make things as fluent as possible.</para>
+ <para>Working through building up the DSL, configuration will stabalize quickly. As new rules are added and edited, the same DSL expressions are reused with the aim being to make the process as fluent as possible.</para>
- <para>To use the DSL when you want to compile and run the rules, you will
- need to pass the DSL configuration source along with the rule source.
- <programlisting>PackageBuilder builder = new PackageBuilder();
+ <para>To use the DSL to compile and run the rules, the DSL configuration source along with the rule source will need to be passed.
+<screen>PackageBuilder builder = new PackageBuilder();
builder.addPackageFromDrl( source, dsl );
//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>
+</screen>
- <para>You can chain DSL expressions together on one line, as long as it is
+The expander will need to be specified by name in the
+ rule source file:
+<screen>expander your-expander.dsl </screen>
+
+Typically you keep the DSL in the same directory as the rule,
+ but this is not required if the above API is being used (only a reader needs to be passed); otherwise everything is just the same.</para>
+
+ <para>DSL expressions can be chained 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>
+ processed according to the mapping file, top to bottom in order. The resulting rule expressions can also span lines, meaning that things similar to the following can be achieved:</para>
<example>
<title>Chaining DSL Expressions</title>
- <programlisting>There is a person called Bob who is happy
+ <screen>There is a person called Bob who is happy
Or
There is a person called Mike who is sad
-</programlisting>
+</screen>
</example>
- <para>Of course this assumes that "Or" is mapped to the "or" conditional
+ <para>This assumes that <emphasis>Or</emphasis> is mapped to the <code>or</code> conditional
element (which is a sensible thing to do).</para>
</section>
@@ -206,39 +204,42 @@
come up with every combination as separate DSL statements would in many
cases not be feasible.</para>
- <para>The DSL facility allows you to achieve this however, with a simple
- convention. If your DSL expression starts with a "-", then it will be
+ <para>The DSL facility allows this to be achieved with a simple
+ convention. If the DSL expression starts with a <code>-</code>, then it will be
assumed to be a field constraint, which will be added to the declaration
that is above it (one per line).</para>
- <para>This is easier to explain with an example. Lets take look at Cheese
+ <para>This is easier to explain with an example. Lets take look at the Cheese
class, with the following fields: type, price, age, country. We can
express some LHS condition in normal DRL like the following
- <programlisting>Cheese(age < 5, price == 20, type=="stilton", country=="ch")</programlisting>
- If you know ahead of time that you will use all the fields, all the time,
- it is easy to do a mapping using the above techniques. However, chances
- are that you will have many fields, and many combinations. If this is the
- case, you can setup your mappings like so: <programlisting>[when]There is a Cheese with=Cheese()
+ <screen>Cheese(age < 5, price == 20, type=="stilton", country=="ch")</screen>
+ If it is known ahead of time if all the fields will be used, all the time, it is easy to do a mapping using the above techniques. However, chances
+ are that there will be many fields and many combinations. If this is the
+ case, the mappings can be setup like the following:
+
+<screen>[when]There is a Cheese with=Cheese()
[when]- age is less than {age}=age<{age}
[when]- type is '{type}'=type=='{type}'
-[when]- country equal to '{country}'=country=='{country}'</programlisting></para>
+[when]- country equal to '{country}'=country=='{country}'</screen></para>
- <para><emphasis role="bold">IMPORTANT:</emphasis> It is NOT possible to
- use the "-" feature after an <emphasis role="bold">accumulate</emphasis>
+<important>
+ <para>It is <emphasis>NOT</emphasis> possible to
+ use the <code>-</code> feature after an <code>accumulate</code>
statement to add constraints to the accumulate pattern. This limitation
will be removed in the future.</para>
+</important>
- <para>You can then write rules with conditions like the following:
- <programlisting>There is a Cheese with
- - age is less than 42
- - type is 'stilton'</programlisting> The parser will pick up the "-"
+ <para>Rules can then be written with conditions like the following:
+<screen>There is a Cheese with
+ - age is less than 42
+ - type is 'stilton'</screen> The parser will pick up the <code>-</code>
lines (they have to be on their own line) and add them as constraints to
the declaration above. So in this specific case, using the above mappings,
- is the equivalent to doing (in DRL): <programlisting>Cheese(age<42, type=='stilton')</programlisting>
- The parser will do all the work for you, meaning you just define mappings
- for individual constraints, and can combine them how you like (if you are
- using context assistant, if you press "-" followed by CTRL+space it will
- conveniently provide you with a filtered list of field constraints to
+ is the equivalent to doing (in DRL):
+<screen>Cheese(age<42, type=='stilton')</screen>
+ The parser will do all the work, only mappings
+ for individual constraints will need to be defined, and combined in a fashion (if context assistant is in use, press <code>-</code> followed by <keycombo>Ctrl and space</keycombo> and it will
+ conveniently provide a filtered list of field constraints to
choose from.</para>
<para>To take this further, after alter the DSL to have
@@ -247,12 +248,11 @@
<para>The extra [org.drools.Cheese] indicates that the sentence only
applies for the main constraint sentence above it (in this case "There is
- a Cheese with"). For example, if you have a class called "Cheese" - then
- if you are adding contraints to the rule (by typing "-" and waiting for
+ a Cheese with"). For example, if there is a class called "Cheese", then
+ if contraints are being added to the rule (by typing <code>-</code> and waiting for
content assistance) then it will know that only items marked as having an
- object-scope of "com.yourcompany.Something" are valid, and suggest only
- them. This is entirely optional (you can leave out that section if needed
- - OR it can be left blank).</para>
+ object-scope of <emphasis>com.yourcompany.Something</emphasis> are valid, and suggest only
+ them. This is entirely optional (this section can be left blank or out completely if necessary).</para>
</section>
<section>
More information about the jboss-svn-commits
mailing list