README.md

   1 # reguloj [![Chat](https://img.shields.io/badge/matrix-%23reguloj:matrix.org-brightgreen.svg?style=social&label=Matrix)](https://matrix.to/#/#reguloj:matrix.org) [![Mailing List](https://img.shields.io/badge/email-reguloj%40metio.groups.io%20-brightgreen.svg?style=social&label=Mail)](https://metio.groups.io/g/reguloj/topics)
   2
   3 `reguloj` is a small and lightweight Java rule engine.
   4
   5 ## Usage
   6
   7 ### Creating rule engines
   8
   9 A rule engine evaluates a set of rules in a specific context. The `RuleEngine` interface offers 3 factory methods to build rule engines:
  10
  11 ```java
  12 // All rules will be evaluated indefinitely until no further rule fires.
  13 RuleEngine<CONTEXT> chained = RuleEngine.chained();
  14
  15 // All rules will be evaluated, but only a maximum number of 5 times.
  16 RuleEngine<CONTEXT> limited = RuleEngine.limited(5);
  17
  18 // Evaluates all rules, stops after the first one that fires.
  19 RuleEngine<CONTEXT> firstWins = RuleEngine.firstWins();
  20 ```
  21
  22 If custom inference behavior is required, subclass `AbstractRuleEngine` and implement the `infer()` method. The following code example shows how to work with rule engines:
  23
  24 ```java
  25 // setup - more details later
  26 RuleEngine<CONTEXT> engine = ...;
  27 Collection<Rule<CONTEXT>> rules = ...;
  28 CONTEXT context = ...;
  29
  30 // true if at least one rule can fired.
  31 engine.analyze(rules, context);
  32
  33 // perform conclusions of those rules that fired.
  34 engine.infer(rules, context);
  35 ```
  36
  37 ### Creating rules
  38
  39 A [rule](https://github.com/metio/reguloj/blob/main/src/main/java/wtf/metio/reguloj/Rule.java) has a (unique) name and runs in a given context. Additionally, it can be checked whether a rule fires in a given context.
  40
  41 Either implement the `Rule` interface yourself and or use the supplied rule implementation and builder. A standard rule is composed of a `java.util.function.Predicate` and `java.util.function.Consumer`. Both interfaces require you to implement only a single method and do not restrict you in any way. Complex rules can be created by grouping or chaining predicates/consumers together with the help of several utility methods. The following example creates a rule composed of 2 predicates and 2 consumers:
  42
  43 ```java
  44 Rule<CONTEXT> rule = Rule..called(name)
  45                 .when(predicate1.and(predicate2))
  46                 .then(consumer1.andThen(consumer2));
  47
  48 // true if the rule would fire in the given context, e.g. the above predicate is true.
  49 rule.fires(context);
  50
  51 // runs (applies) the rule in the given context
  52 rule.run(context);
  53 ```
  54
  55 Using Java 8 lambdas is possible as well:
  56
  57 ```java
  58 Rule<CONTEXT> rule = Rule.called(name)
  59                 .when(context -> context.check())
  60                 .then(context -> context.action())
  61 ```
  62
  63 ### Creating an inference context
  64
  65 An inference [context](https://github.com/metio/reguloj/blob/main/src/main/java/wtf/metio/reguloj/Context.java) contains information needed by predicates and/or consumers. This project supplies a simple implementation of the Context interface called `SimpleContext` which just wraps a given topic. The `BaseContext` abstract class can be used to create subclasses in case your rules need extra information. The API acknowledges this by using <CONTEXT extends Context<?>> as type parameter for all methods which expect a Context, thus allowing all context implementations to be used. See item 28 in Effective Java for more details.
  66
  67 ### Integration
  68
  69 ```xml
  70 <dependency>
  71   <groupId>wtf.metio.reguloj</groupId>
  72   <artifactId>reguloj</artifactId>
  73   <version>${version.reguloj}</version>
  74 </dependency>
  75 ```
  76
  77 ```kotlin
  78 dependencies {
  79     implementation("wtf.metio.reguloj:reguloj:${version.reguloj}")
  80 }
  81 ```
  82
  83 Replace `${version.reguloj}` with the [latest release](http://search.maven.org/#search%7Cga%7C1%7Cg%3Awtf.metio.reguloj%20a%3Areguloj).
  84
  85 ### Requirements
  86
  87 | regoluj    | Java |
  88 |------------|------|
  89 | 2021.4.13+ | 16+  |
  90
  91 ## Alternatives
  92
  93 In case `reguloj` is not what you are looking for, try these projects:
  94
  95 - [Dredd](https://github.com/amsterdatech/Dredd)
  96 - [SmartParam](https://github.com/smartparam/smartparam)
  97 - [ramen](https://github.com/asgarth/ramen)
  98 - [nomin](https://github.com/dobrynya/nomin)
  99 - [dvare](https://github.com/dvare/dvare-rules)
 100 - [ruli](https://github.com/mediavrog/ruli)
 101 - [MintRules](https://github.com/augusto/MintRules)
 102 - [Jare](https://github.com/uwegeercken/jare)
 103 - [tuProlog](http://alice.unibo.it/xwiki/bin/view/Tuprolog/)
 104 - [drools](https://www.drools.org/)
 105 - [Easy Rules](https://github.com/j-easy/easy-rules)
 106 - [n-cube](https://github.com/jdereg/n-cube)
 107 - [RuleBook](https://github.com/deliveredtechnologies/rulebook)
 108 - [OpenL Tablets](http://openl-tablets.org/)
 109 - [JSR 94](https://jcp.org/en/jsr/detail?id=94)
 110 - [rules](https://github.com/rlangbehn/rules)
 111
 112 ## License
 113
 114 ```
 115 To the extent possible under law, the author(s) have dedicated all copyright
 116 and related and neighboring rights to this software to the public domain
 117 worldwide. This software is distributed without any warranty.
 118
 119 You should have received a copy of the CC0 Public Domain Dedication along with
 120 this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 121 ```
 122
 123 ## Mirrors
 124
 125 - https://github.com/metio/reguloj
 126 - https://repo.or.cz/reguloj.git
 127 - https://codeberg.org/metio.wtf/reguloj
 128 - https://gitlab.com/metio.wtf/reguloj
 129 - https://bitbucket.org/metio-wtf/reguloj