<commit_before><?xml version="1.0" encoding="UTF-8"?>
	<section version="5.0" xmlns="http://docbook.org/ns/docbook"
                    xmlns:xlink="http://www.w3.org/1999/xlink"
                    xmlns:xi="http://www.w3.org/2001/XInclude"
                    xmlns:svg="http://www.w3.org/2000/svg"
                    xmlns:m="http://www.w3.org/1998/Math/MathML"
                    xmlns:html="http://www.w3.org/1999/xhtml"
                    xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
  <title>Domain Specific Languages</title>

  <para>As mentioned previously, <indexterm>
      <primary>Domain Specific Languages</primary>
    </indexterm>(or DSLs) are a way of extending the rule language to your
  problem domain. They are wired in to the rule language for you, and can make
  use of all the underlying rule language and engine features.</para>

  <para>DSLs are used both in the IDE, as well as the web based BRMS. Of
  course as rules are text, you can use them even without this tooling.</para>

  <section>
    <title>When to use a DSL</title>

    <para>DSLs can serve as a layer of separation between rule authoring (and
    rule authors) and the domain objects that the engine operates on. DSLs can
    also act as "templates" of conditions or actions that are used over and
    over in your rules, perhaps only with parameters changing each time. If
    your rules need to be read and validated by less technical folk, (such as
    Business Analysts) the DSLs are definitely for you. If the conditions or
    consequences of your rules follow similar patterns which you can express
    in a template. You wish to hide away your implementation details, and
    focus on the business rule. You want to provide a controlled means of
    editing rules based on pre-defined templates.</para>

    <para>DSLs have no impact on the rules at runtime, they are just a
    parse/compile time feature.</para>

    <para>Note that Drools 4 DSLs are quite different from Drools 2 XML based
    DSLs. It is still possible to do Drools 2 style XML languages - if you
    require this, then take a look at the Drools 4 XML rule language, and
    consider using XSLT to map from your XML language to the Drools 4 XML
    language.</para>
  </section>

  <section>
    <title>Editing and managing a DSL</title>

    <para>A DSL's configuration like most things is stored in plain text. If
    you use the IDE, you get a nice graphical editor (with some validation),
    but the format of the file is quite simple, and is basically a properties
    file.</para>

    <para>Note that since Drools 4.0, DSLs have become more powerful in
    allowing you to customise almost any part of the language, including
    keywords. Regular expressions can also be used to match words/sentences if
    needed (this is provided for enhanced localisation). However, not all
    features are supported by all the tools (although you can use them, the
    content assistance just may not be 100% accurate in certain cases).</para>

    <example>
      <title>Example <indexterm>
          <primary>DSL</primary>
        </indexterm> mapping</title>

      <programlisting>[when]This is {something}=Something(something=={something})</programlisting>
    </example>

    <para>Referring to the above example, the [when] refers to the scope of
    the expression: ie does it belong on the LHS or the RHS of a rule. The
    part after the [scope] is the expression that you use in the rule
    (typically a natural language expression, but it doesn't have to be). The
    part on the right of the "=" is the mapping into the rule language (of
    course the form of this depends on if you are talking about the RHS or the
    LHS - if its the LHS, then its the normal LHS syntax, if its the RHS then
    its fragments of Java code for instance).</para>

    <para>The parser will take the expression you specify, and extract the
    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 that the rule engine actually uses).</para>

    <para>Note also that the "sentences" above can be regular expressions.
    This means the parser will match the sentence fragements that match the
    expressions. This means you can use (for instance) the '?' to indicate the
    character before it is optional (think of each sentence as a regular
    expression pattern - this means if you want to use regex characters - you
    will need to escape them with a '\' of course.</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
    "This 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
    double-quotes). 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
    sure you enclose the data you want to capture (see other example).</para>

    <example>
      <title>Example with quotes</title>

      <programlisting>[when]This is "{something}" and "{another}"=Something(something=="{something}", another=="{another}")
[when]This is {also} valid=Another(something=="{also}")</programlisting>
    </example>

    <para>It is a good idea to try and avoid punctuation in your DSL
    expressions where possible, other then quotes and the like - keep it
    simple and 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 (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 <programlisting>if (foo) {
    doSomething(); }</programlisting> 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, as the result of the mapping must be a valid expression in
    the rule language.</para>

    <example>
      <title>Some more examples</title>
<commit_msg>JBRULES-1953 corrected escaping of curlies<commit_after><?xml version="1.0" encoding="UTF-8"?>
	<section version="5.0" xmlns="http://docbook.org/ns/docbook"
                    xmlns:xlink="http://www.w3.org/1999/xlink"
                    xmlns:xi="http://www.w3.org/2001/XInclude"
                    xmlns:svg="http://www.w3.org/2000/svg"
                    xmlns:m="http://www.w3.org/1998/Math/MathML"
                    xmlns:html="http://www.w3.org/1999/xhtml"
                    xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
  <title>Domain Specific Languages</title>

  <para>As mentioned previously, <indexterm>
      <primary>Domain Specific Languages</primary>
    </indexterm>(or DSLs) are a way of extending the rule language to your
  problem domain. They are wired in to the rule language for you, and can make
  use of all the underlying rule language and engine features.</para>

  <para>DSLs are used both in the IDE, as well as the web based BRMS. Of
  course as rules are text, you can use them even without this tooling.</para>

  <section>
    <title>When to use a DSL</title>

    <para>DSLs can serve as a layer of separation between rule authoring (and
    rule authors) and the domain objects that the engine operates on. DSLs can
    also act as "templates" of conditions or actions that are used over and
    over in your rules, perhaps only with parameters changing each time. If
    your rules need to be read and validated by less technical folk, (such as
    Business Analysts) the DSLs are definitely for you. If the conditions or
    consequences of your rules follow similar patterns which you can express
    in a template. You wish to hide away your implementation details, and
    focus on the business rule. You want to provide a controlled means of
    editing rules based on pre-defined templates.</para>

    <para>DSLs have no impact on the rules at runtime, they are just a
    parse/compile time feature.</para>

    <para>Note that Drools 4 DSLs are quite different from Drools 2 XML based
    DSLs. It is still possible to do Drools 2 style XML languages - if you
    require this, then take a look at the Drools 4 XML rule language, and
    consider using XSLT to map from your XML language to the Drools 4 XML
    language.</para>
  </section>

  <section>
    <title>Editing and managing a DSL</title>

    <para>A DSL's configuration like most things is stored in plain text. If
    you use the IDE, you get a nice graphical editor (with some validation),
    but the format of the file is quite simple, and is basically a properties
    file.</para>

    <para>Note that since Drools 4.0, DSLs have become more powerful in
    allowing you to customise almost any part of the language, including
    keywords. Regular expressions can also be used to match words/sentences if
    needed (this is provided for enhanced localisation). However, not all
    features are supported by all the tools (although you can use them, the
    content assistance just may not be 100% accurate in certain cases).</para>

    <example>
      <title>Example <indexterm>
          <primary>DSL</primary>
        </indexterm> mapping</title>

      <programlisting>[when]This is {something}=Something(something=={something})</programlisting>
    </example>

    <para>Referring to the above example, the [when] refers to the scope of
    the expression: ie does it belong on the LHS or the RHS of a rule. The
    part after the [scope] is the expression that you use in the rule
    (typically a natural language expression, but it doesn't have to be). The
    part on the right of the "=" is the mapping into the rule language (of
    course the form of this depends on if you are talking about the RHS or the
    LHS - if its the LHS, then its the normal LHS syntax, if its the RHS then
    its fragments of Java code for instance).</para>

    <para>The parser will take the expression you specify, and extract the
    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 that the rule engine actually uses).</para>

    <para>Note also that the "sentences" above can be regular expressions.
    This means the parser will match the sentence fragements that match the
    expressions. This means you can use (for instance) the '?' to indicate the
    character before it is optional (think of each sentence as a regular
    expression pattern - this means if you want to use regex characters - you
    will need to escape them with a '\' of course.</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
    "This 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
    double-quotes). 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
    sure you enclose the data you want to capture (see other example).</para>

    <example>
      <title>Example with quotes</title>

      <programlisting>[when]This is "{something}" and "{another}"=Something(something=="{something}", another=="{another}")
[when]This is {also} valid=Another(something=="{also}")</programlisting>
    </example>

    <para>It is a good idea to try and avoid punctuation in your DSL
    expressions where possible, other then quotes and the like - keep it
    simple and 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 (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 <programlisting>if (foo) \{
    doSomething();\ }</programlisting> as well as with the token names as shown
    above.</para><para>PLEASE NOTE that if you want curly braces to appear literally as curly braces, then escape them with a backslack (\). Otherwise it may think it is a token to be replaced.
  </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, as the result of the mapping must be a valid expression in
    the rule language.</para>

    <example>
      <title>Some more examples</title>

{'fraction_non_alphanumeric': 0.06876037631433315, 'fraction_numerical': 0.005810736026563365, 'mean_word_length': 3.1989544002323553, 'pattern_counts': {'":': 0, '<': 137, '<?xml version=': 2, '>': 137, 'https://': 0, 'lorem ipsum': 0, 'www.': 10, 'xml': 18}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7254551', 'n_tokens_mistral': 3884, 'n_tokens_neox': 3694, 'n_words': 2037}