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 Note that the order of the collection dictates the evaluation order of your rules - if order does matter, use `List` rather than `Set`.
  38
  39 ### Creating rules
  40
  41 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.
  42
  43 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:
  44
  45 ```java
  46 Rule<CONTEXT> rule = Rule.called(name)
  47                 .when(predicate1.and(predicate2))
  48                 .then(consumer1.andThen(consumer2));
  49
  50 // true if the rule would fire in the given context, e.g. the above predicate is true.
  51 rule.fires(context);
  52
  53 // runs (applies) the rule in the given context
  54 rule.run(context);
  55 ```
  56
  57 Using Java 8 lambdas is possible as well:
  58
  59 ```java
  60 Rule<CONTEXT> rule = Rule.called(name)
  61                 .when(context -> context.check())
  62                 .then(context -> context.action())
  63 ```
  64
  65 ### Creating an inference context
  66
  67 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.
  68
  69 ```java
  70 CONTEXT context = Context.of("some object");
  71 ```
  72
  73 ### Integration
  74
  75 ```xml
  76 <dependency>
  77   <groupId>wtf.metio.reguloj</groupId>
  78   <artifactId>reguloj</artifactId>
  79   <version>${version.reguloj}</version>
  80 </dependency>
  81 ```
  82
  83 ```kotlin
  84 dependencies {
  85     implementation("wtf.metio.reguloj:reguloj:${version.reguloj}")
  86 }
  87 ```
  88
  89 Replace `${version.reguloj}` with the [latest release](http://search.maven.org/#search%7Cga%7C1%7Cg%3Awtf.metio.reguloj%20a%3Areguloj).
  90
  91 ### Requirements
  92
  93 | regoluj    | Java |
  94 |------------|------|
  95 | 2021.4.13+ | 16+  |
  96
  97 ## Alternatives
  98
  99 In case `reguloj` is not what you are looking for, try these projects:
 100
 101 - [Dredd](https://github.com/amsterdatech/Dredd)
 102 - [SmartParam](https://github.com/smartparam/smartparam)
 103 - [ramen](https://github.com/asgarth/ramen)
 104 - [nomin](https://github.com/dobrynya/nomin)
 105 - [dvare](https://github.com/dvare/dvare-rules)
 106 - [ruli](https://github.com/mediavrog/ruli)
 107 - [MintRules](https://github.com/augusto/MintRules)
 108 - [Jare](https://github.com/uwegeercken/jare)
 109 - [tuProlog](http://alice.unibo.it/xwiki/bin/view/Tuprolog/)
 110 - [drools](https://www.drools.org/)
 111 - [Easy Rules](https://github.com/j-easy/easy-rules)
 112 - [n-cube](https://github.com/jdereg/n-cube)
 113 - [RuleBook](https://github.com/deliveredtechnologies/rulebook)
 114 - [OpenL Tablets](http://openl-tablets.org/)
 115 - [JSR 94](https://jcp.org/en/jsr/detail?id=94)
 116 - [rules](https://github.com/rlangbehn/rules)
 117
 118 ## License
 119
 120 ```
 121 To the extent possible under law, the author(s) have dedicated all copyright
 122 and related and neighboring rights to this software to the public domain
 123 worldwide. This software is distributed without any warranty.
 124
 125 You should have received a copy of the CC0 Public Domain Dedication along with
 126 this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 127 ```
 128
 129 ## Mirrors
 130
 131 - https://github.com/metio/reguloj
 132 - https://repo.or.cz/reguloj.git
 133 - https://codeberg.org/metio.wtf/reguloj
 134 - https://gitlab.com/metio.wtf/reguloj
 135 - https://bitbucket.org/metio-wtf/reguloj