[jboss-svn-commits] JBL Code SVN: r13575 - labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Jul 17 10:23:34 EDT 2007
Author: tirelli
Date: 2007-07-17 10:23:34 -0400 (Tue, 17 Jul 2007)
New Revision: 13575
Modified:
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml
Log:
Updating documentation to Drools 4.0
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml 2007-07-17 14:22:09 UTC (rev 13574)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml 2007-07-17 14:23:34 UTC (rev 13575)
@@ -2,8 +2,13 @@
<section>
<title>Comments</title>
+ <note>
+ <para><replaceable>(updated to Drools 4.0)</replaceable></para>
+ </note>
+
<para>Comments are sections of text that are ignored by the rule engine.
- They are effectively stripped out when they are encountered. </para>
+ They are stripped out when they are encountered, except inside semantic code
+ blocks, like the RHS of a rule.</para>
<section>
<title>Single line comment</title>
@@ -24,7 +29,20 @@
</mediaobject>
</figure>
- <para></para>
+ <para>To create single line comments, you can use either '#' or '//'. The
+ parser will ignore anything in the line after the comment symbol.
+ Example:</para>
+
+ <programlisting>rule "Testing Comments"
+when
+ # this is a single line comment
+ // this is also a single line comment
+ eval( true ) # this is a comment in the same line of a pattern
+then
+ // this is a comment inside a semantic code block
+ # this is another comment in a semantic code block
+end
+</programlisting>
</section>
<section>
@@ -46,7 +64,17 @@
</mediaobject>
</figure>
- <para></para>
+ <para>Multi-line comments are used to comment blocks of text, both in and
+ outside semantic code blocks. Example:</para>
+
+ <programlisting>rule "Test Multi-line Comments"
+when
+ /* this is a multi-line comment
+ in the left hand side of a rule */
+ eval( true )
+then
+ /* and this is a multi-line comment
+ in the right hand side of a rule */
+end </programlisting>
</section>
-
</section>
\ No newline at end of file
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml 2007-07-17 14:22:09 UTC (rev 13574)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml 2007-07-17 14:23:34 UTC (rev 13575)
@@ -2,47 +2,76 @@
<section>
<title>Overview</title>
- <para>Drools 3 has a "native" rule language that is non XML textual format.
- This format is very light in terms of punctuation, and supports natural and
- domain specific languages via "expanders" that allow the language to morph
- to your problem domain. This chapter is mostly concered with the native rule
- format. The Diagrams used are known as "rail road" diagrams, and are
- basically flow charts for the language terms. For the technically very keen,
- you can also refer to "drl.g" which is the Antlr3 grammar for the rule
- language. If you use the Rule Workbench, a lot of the rule structure is done
- for you with content assistance, for example, type "ru" and press
- ctrl+space, and it will build the rule structure for you.</para>
+ <note>
+ <para><replaceable>(updated to Drools 4.0)</replaceable></para>
+ </note>
+ <para>Drools 4.0 has a "native" rule language that is non XML textual
+ format. This format is very light in terms of punctuation, and supports
+ natural and domain specific languages via "expanders" that allow the
+ language to morph to your problem domain. This chapter is mostly concered
+ with the native rule format. The Diagrams used are known as "rail road"
+ diagrams, and are basically flow charts for the language terms. For the
+ technically very keen, you can also refer to "DRL.g" which is the Antlr3
+ grammar for the rule language. If you use the Rule Workbench, a lot of the
+ rule structure is done for you with content assistance, for example, type
+ "ru" and press ctrl+space, and it will build the rule structure for
+ you.</para>
+
<section>
<title>A rule file</title>
<para>A rule file is typically a file with a .drl extension. In a drl file
- you can have multiple rules, functions etc. However, you are also able to
+ you can have multiple rules, queries and functions, as well as some
+ resource declarations like imports, globals and attributes that are
+ assigned and used by your rules and queries. However, you are also able to
spread your rules across multiple rule files (in that case, the extension
.rule is suggested, but not required) - spreading rules across files can
help with managing large numbers of rules. A DRL file is simply a text
file.</para>
+
+ <para>The overal structure of a rule file is:</para>
+
+ <example>
+ <title>Rules file</title>
+
+ <programlisting><emphasis role="bold">package </emphasis><replaceable>package-name</replaceable>
+
+<replaceable>imports</replaceable>
+
+<replaceable>globals</replaceable>
+
+<replaceable>functions</replaceable>
+
+<replaceable>queries</replaceable>
+
+<replaceable>rules</replaceable>
+</programlisting>
+ </example>
+
+ <para>The order in which the elements are declared is not important,
+ except for the package name that, if declared, must be the first element
+ in the rules file. All elements are optional, so you will use only those
+ you need. We will discuss each of them in the following sections.</para>
</section>
<section>
<title>What makes a rule</title>
- <para>A rule has the following rough structure:<literallayout>
-rule "name"
- ATTRIBUTES
- when
- LHS
- then
- RHS
-end
-</literallayout>Its really that simple. Mostly punctuation is not needed, even
- the double quotes for "name" are optional, as are newlines. ATTRIBUTES are
- simple (always optional) hints to how the rule should behave. LHS is the
- conditional parts of the rule, which follows a certain syntax which is
- covered below. RHS is basically a block that allows Java semantic code to
- be executed (this will soon support other semantic languages, like groovy,
- and C#). The only special keywords here are for asserting, retracting or
- modifying facts. Any variables bound in the LHS are available here.</para>
+ <para>For the impatients, just as an early view, a rule has the following
+ rough structure:<programlisting><emphasis role="bold">rule</emphasis> <replaceable>"name"</replaceable>
+ <replaceable>attributes</replaceable>
+ <emphasis role="bold">when</emphasis>
+ <replaceable>LHS</replaceable>
+ <emphasis role="bold">then</emphasis>
+ <replaceable>RHS</replaceable>
+<emphasis role="bold">end</emphasis>
+</programlisting>Its really that simple. Mostly punctuation is not needed,
+ even the double quotes for "name" are optional, as are newlines.
+ Attributes are simple (always optional) hints to how the rule should
+ behave. LHS is the conditional parts of the rule, which follows a certain
+ syntax which is covered below. RHS is basically a block that allows
+ dialect specific semantic code to be executed.</para>
<para>It is important to note that whitepace is not important, EXCEPT in
thse case of domain specific languages, in which case each line is
@@ -51,60 +80,199 @@
</section>
<section>
- <title>Domain Specific Languages</title>
-
- <para>Domain specific languages are implemented as an enhancement over the
- native rule language. They use the "expander" mechanism. The expander
- mechanism is an extensible API, but by default it can work with .dsl
- files, which contain mappings from the domain or natural language to the
- rule language and your domain objects. You can think of these .dsl files
- also as a mapping to your domain model (which provides you with some
- insulation). DSLs/expanders work by processing a line in the rule source
- as it is being compiled - this is the only time that newlines are
- significant. This is done to aid readability and avoid the need for
- punctuation. It is expected that over time, alternative expanders and DSLs
- will be available/prebuilt for various domains, and provide other forms of
- natural language parsing and analysis. It is up to you if you believe a
- DSL is of benefit to your application - they certainly make for very nice
- looking rules, but for some folks, the native rule language is ideal.
- Freedom is good.</para>
- </section>
-
- <section>
<title>Reserved words</title>
<para>There are some reserved keywords that are used in the rule language.
It is wise to avoid collisions with these words when naming your domain
- objects, properties, methods, functions and so on that are used in the
- rule text. The following list are words that you should try and avoid in
- the rule contents if possible (often times it will work fine, but in some
- cases the rules may be parsed incorrectly). Of course, you can have words
- as part of a method name in camel case, like notSomething() - there are no
- issues with that scenario.</para>
+ objects, properties, methods, functions and other elements that are used
+ in the rule text. The parser is a bit smart and sometimes knows when a
+ keyword is not being used as a keyword, but avoiding the use of them might
+ prevent some headaches.</para>
- <literallayout>
-when
-then
-rule
-end
-contains
-matches
-and
-or
-modify
-retract
-assert
-salience
-function
-query
-exists
-eval
-agenda-group
-no-loop
-duration
-->
-not
-auto-focus
-</literallayout>
+ <para>The following is a list of keywords that must be avoided as
+ identifiers when writing rules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>rule</para>
+ </listitem>
+
+ <listitem>
+ <para>query</para>
+ </listitem>
+
+ <listitem>
+ <para>when</para>
+ </listitem>
+
+ <listitem>
+ <para>then</para>
+ </listitem>
+
+ <listitem>
+ <para>end</para>
+ </listitem>
+
+ <listitem>
+ <para>null</para>
+ </listitem>
+
+ <listitem>
+ <para>and</para>
+ </listitem>
+
+ <listitem>
+ <para>or</para>
+ </listitem>
+
+ <listitem>
+ <para>not</para>
+ </listitem>
+
+ <listitem>
+ <para>exists</para>
+ </listitem>
+
+ <listitem>
+ <para>collect</para>
+ </listitem>
+
+ <listitem>
+ <para>accumulate</para>
+ </listitem>
+
+ <listitem>
+ <para>from</para>
+ </listitem>
+
+ <listitem>
+ <para>forall</para>
+ </listitem>
+
+ <listitem>
+ <para>true</para>
+ </listitem>
+
+ <listitem>
+ <para>false</para>
+ </listitem>
+
+ <listitem>
+ <para>eval</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following list are keywords that you should try and avoid in the
+ rule contents if possible, but the parser usually will work fine, even if
+ you use them for something else.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>package</para>
+ </listitem>
+
+ <listitem>
+ <para>function</para>
+ </listitem>
+
+ <listitem>
+ <para>global</para>
+ </listitem>
+
+ <listitem>
+ <para>import</para>
+ </listitem>
+
+ <listitem>
+ <para>template</para>
+ </listitem>
+
+ <listitem>
+ <para>attributes</para>
+ </listitem>
+
+ <listitem>
+ <para>enabled</para>
+ </listitem>
+
+ <listitem>
+ <para>salience</para>
+ </listitem>
+
+ <listitem>
+ <para>duration</para>
+ </listitem>
+
+ <listitem>
+ <para>init</para>
+ </listitem>
+
+ <listitem>
+ <para>action</para>
+ </listitem>
+
+ <listitem>
+ <para>reverse</para>
+ </listitem>
+
+ <listitem>
+ <para>result</para>
+ </listitem>
+
+ <listitem>
+ <para>contains</para>
+ </listitem>
+
+ <listitem>
+ <para>excludes</para>
+ </listitem>
+
+ <listitem>
+ <para>memberOf</para>
+ </listitem>
+
+ <listitem>
+ <para>matches</para>
+ </listitem>
+
+ <listitem>
+ <para>in</para>
+ </listitem>
+
+ <listitem>
+ <para>date-effective</para>
+ </listitem>
+
+ <listitem>
+ <para>date-expires</para>
+ </listitem>
+
+ <listitem>
+ <para>no-loop</para>
+ </listitem>
+
+ <listitem>
+ <para>auto-focus</para>
+ </listitem>
+
+ <listitem>
+ <para>activation-group</para>
+ </listitem>
+
+ <listitem>
+ <para>agenda-group</para>
+ </listitem>
+
+ <listitem>
+ <para>dialect</para>
+ </listitem>
+
+ <listitem>
+ <para>rule-flow-group</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Of course, you can have words as part of a method name in camel
+ case, like notSomething() - there are no issues with that scenario.</para>
</section>
</section>
\ No newline at end of file
More information about the jboss-svn-commits
mailing list