The cl-rules Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-rules Reference Manual

This is the cl-rules Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:31:34 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-rules

Build Status

Simple DSL for rules that can be configured without code. If part of your program logic is set of rules, this package will help you. You can create custom rules and conditions, bind actions to rules, load and save your rules from/in yaml format.

Usage

Consider a simple example: system of different tariffs, which defines in declarative style. Each tariff contains a set of limits from which the cost is calculated.

1. Define your set of parameters

Parameters represent basic variables of your system. They may contain absolutely any information and arbitrary strusture. For creating them, specify the name and initial value. Any parameter can change own value over time, for this purpose is intended setparam.

In our example, parameters - this is basic characteristics of tariff. Define them:

(in-package :cl-user)
(defpackage my-package
  (:use :cl)
  (:import-from :cl-rules
                :defparam
                :defaction
                :defcond
                :defrule
                :eval-rule
                :fire-rule)))
(in-package :my-package)


(defparam ram 0)
(defparam cpu 0)
(defparam disk 0)

(defvar *user-balance* 1000) ;; Starting value of user balance. Only for illustration.

2. Define your conditons

Condition represent predicate, which may be only a true or false. In the base case, conditions is a function of previosly defined parameters. With help of param-val you can get a parameter value within the condition or specify it in arguments.

All values of the tariff characteristics are in a certain range, therefore it is sufficient for us to define only one condition:

(defcond between (low-limit high-limit value)
  (and (>= value low-limit) (<= value high-limit value)))

3. Define your actions

Action - arbitrary kind of code. Any actions may be linked with rule. Action called only if rule is true.

Define two actions: first - withdraw money from user account, second - print a user account balance.

(defaction pay (amount)
  (decf *user-balance* amount))
  
(defaction report ()
  (print (format nil "The balance is ~d" *user-balance*)))

4. Define your rules!!!

The rules - heart of our system. They consist of several conditions and optional actions. Conditions specified with concrete values of arguments and can be specified in arbitrary order. Only if all conditions are true, rule is true.

Now we can define the rules for our tariff system. On this stage exists two ways:

define your rules in code

(defrule mini-tariff
  :actions
  ((pay 100)
   (report))
   
  (between 0 512 ram)
  (between 1 1 cpu)
  (between 0 20 disk))
  
(defrule base-tariff
  :actions
  ((pay 200)
   (report))
   
  (between 513 1024 ram)
  (between 1 1 cpu)
  (between 21 30 disk))

(defrule super-tariff
  :actions
  ((pay 300)
   (report))
   
  (between 1025 2048 ram)
  (between 2 2 cpu)
  (between 31 50 disk))

or load them from file using function (loads "/path/to/your/file")

rules:
  mini-tariff:
    conditions:
      - [between, 0, 512, "{{ram}}"]
      - [between, 1, 1, "{{cpu}}"]
      - [between, 0, 20, "{{disk}}"]
    actions:
      - [pay, 100]
      - [report]
  base-tariff:
    conditions:
      - [between, 513, 1024, "{{ram}}"]
      - [between, 1, 1, "{{cpu}}"]
      - [between, 21, 30, "{{disk}}"]
    actions:
      - [pay, 200]
      - [report]
  super-tariff:
    conditions:
      - [between, 1025, 2048, "{{ram}}"]
      - [between, 2, 2, "{{cpu}}"]
      - [between, 31, 50, "{{disk}}"]
    actions:
      - [pay, 300]
      - [report]

For storage is used yaml format.

Time for run your rules

Rules running with this command: (fire-rule 'mini-tariff 'base-tariff 'super-tariff), but in this case, actions not called. fire-rule - only return a logic value, true - if all rules is true and false - otherwise.

If you want call actions, using this: (eval-rule 'mini-tariff 'base-tariff 'super-tariff). After this command *user-balance* will be less.

More examples in tests.

Installation

(ql:quickload :cl-rules)

Author

Copyright

Copyright (c) 2017 Ito Dimercel (xolcman@gmail.com)

License

Licensed under the GPL-3.0 License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-rules

Author

Ito Dimercel

License

GPL-3.0

Description

Simple DSL for rules that can be configured without code

Long Description

# cl-rules

[![Build Status](https://travis-ci.org/Dimercel/cl-rules.svg?branch=master)](https://travis-ci.org/Dimercel/cl-rules)

Simple DSL for rules that can be configured without code. If part of your program logic is set of rules, this package will help you. You can create custom rules and conditions, bind actions to rules, load and save your rules from/in yaml format.

## Usage

Consider a simple example: system of different tariffs, which defines in declarative style. Each tariff contains a set of limits from which the cost is calculated.

### 1. Define your set of parameters

Parameters represent basic variables of your system. They may contain absolutely any information and arbitrary strusture. For creating them, specify the name and initial value. Any parameter can change own value over time, for this purpose is intended ‘setparam‘.
In our example, parameters - this is basic characteristics of tariff. Define them:

“‘common-lisp
(in-package :cl-user)
(defpackage my-package
(:use :cl)
(:import-from :cl-rules
:defparam
:defaction
:defcond
:defrule
:eval-rule
:fire-rule)))
(in-package :my-package)

(defparam ram 0)
(defparam cpu 0)
(defparam disk 0)

(defvar *user-balance* 1000) ;; Starting value of user balance. Only for illustration.
“‘

### 2. Define your conditons

Condition represent predicate, which may be only a true or false. In the base case, conditions is a function of previosly defined parameters. With help of ‘param-val‘ you can get a parameter value within the condition or specify it in arguments.

All values of the tariff characteristics are in a certain range, therefore it is sufficient for us to define only one condition:

“‘common-lisp
(defcond between (low-limit high-limit value)
(and (>= value low-limit) (<= value high-limit value)))
“‘

### 3. Define your actions

Action - arbitrary kind of code. Any actions may be linked with rule. Action called only if rule is true.

Define two actions: first - withdraw money from user account, second - print a user account balance.

“‘common-lisp
(defaction pay (amount)
(decf *user-balance* amount))

(defaction report ()
(print (format nil "The balance is ~d" *user-balance*)))
“‘

### 4. Define your rules!!!

The rules - heart of our system. They consist of several conditions and optional actions. Conditions specified with concrete values of arguments and can be specified in arbitrary order. Only if all conditions are true, rule is true.

Now we can define the rules for our tariff system. On this stage exists two ways:

define your rules in code

“‘common-lisp
(defrule mini-tariff
:actions
((pay 100)
(report))

(between 0 512 ram)
(between 1 1 cpu)
(between 0 20 disk))

(defrule base-tariff
:actions
((pay 200)
(report))

(between 513 1024 ram)
(between 1 1 cpu)
(between 21 30 disk))

(defrule super-tariff
:actions
((pay 300)
(report))

(between 1025 2048 ram)
(between 2 2 cpu)
(between 31 50 disk))
“‘
or load them from file using function ‘(loads "/path/to/your/file")‘

“‘yml
rules:
mini-tariff:
conditions:
- [between, 0, 512, "{{ram}}"]
- [between, 1, 1, "{{cpu}}"]
- [between, 0, 20, "{{disk}}"]
actions:
- [pay, 100]
- [report]
base-tariff:
conditions:
- [between, 513, 1024, "{{ram}}"]
- [between, 1, 1, "{{cpu}}"]
- [between, 21, 30, "{{disk}}"]
actions:
- [pay, 200]
- [report]
super-tariff:
conditions:
- [between, 1025, 2048, "{{ram}}"]
- [between, 2, 2, "{{cpu}}"]
- [between, 31, 50, "{{disk}}"]
actions:
- [pay, 300]
- [report]
“‘
For storage is used [yaml](http://yaml.org/) format.

### Time for run your rules

Rules running with this command: ‘(fire-rule ’mini-tariff ’base-tariff ’super-tariff)‘, but in this case, actions not called. ‘fire-rule‘ - only return a logic value, true - if all rules is true and false - otherwise.

If you want call actions, using this: ‘(eval-rule ’mini-tariff ’base-tariff ’super-tariff)‘. After this command ‘*user-balance*‘ will be less.

More examples in [tests](https://github.com/Dimercel/cl-rules/tree/master/t).

## Installation

“‘common-lisp
(ql:quickload :cl-rules)
“‘

## Author

* Ito Dimercel (xolcman@gmail.com)

## Copyright

Copyright (c) 2017 Ito Dimercel (xolcman@gmail.com)

## License

Licensed under the GPL-3.0 License.

Version

0.1

Dependencies
Source

cl-rules.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 cl-rules/src

Parent

cl-rules (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-rules.asd

Location

cl-rules.asd

Systems

cl-rules (system)

Packages

cl-rules-asd


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-rules/src/core.lisp

Parent

src (module)

Location

src/core.lisp

Packages

cl-rules.core

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cl-rules/src/serialization.lisp

Dependency

core.lisp (file)

Parent

src (module)

Location

src/serialization.lisp

Packages

cl-rules.serialization

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cl-rules/src/cl-rules.lisp

Dependencies
Parent

src (module)

Location

src/cl-rules.lisp

Packages

cl-rules


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 cl-rules-asd

Source

cl-rules.asd

Use List

Next: , Previous: , Up: Packages   [Contents][Index]

5.2 cl-rules.core

Source

core.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

5.3 cl-rules.serialization

Source

serialization.lisp (file)

Use List
Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.4 cl-rules

Source

cl-rules.lisp (file)

Use List

common-lisp


Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: defaction NAME ARGS &body FORMS
Package

cl-rules.core

Source

core.lisp (file)

Macro: defcond NAME ARGS &body FORMS

Define new condition with NAME. Represents arbitrary predicate

Package

cl-rules.core

Source

core.lisp (file)

Macro: defparam NAME FORM

Defines a new parameter

Package

cl-rules.core

Source

core.lisp (file)

Macro: defrule NAME &body FORMS
Package

cl-rules.core

Source

core.lisp (file)

Macro: with-rules SYM &body FORMS

Allow traversing by all registered rules. In SYM stored name of rule

Package

cl-rules.core

Source

core.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: action-args ACTION
Package

cl-rules.core

Source

core.lisp (file)

Function: action-name ACTION
Package

cl-rules.core

Source

core.lisp (file)

Function: action-reg-p NAME

Action with NAME is registered?

Package

cl-rules.core

Source

core.lisp (file)

Function: cond-args CONDITION

Return list contains condition arguments

Package

cl-rules.core

Source

core.lisp (file)

Function: cond-name CONDITION

Will return name of condition as string

Package

cl-rules.core

Source

core.lisp (file)

Function: cond-reg-p NAME

Condition with NAME id registered?

Package

cl-rules.core

Source

core.lisp (file)

Function: cond-val NAME ARGS &optional BAD-VAL

Return value of condition for specified arguments

Package

cl-rules.core

Source

core.lisp (file)

Function: eval-rule &rest RULE-NAMES

Is similar fire-rule, but evaluate actions. Actions will be evaluate only if the value of rule is true

Package

cl-rules.core

Source

core.lisp (file)

Function: fire-rule &rest RULE-NAMES

Will return true if all conditions is true. Linked actions not execute.

Package

cl-rules.core

Source

core.lisp (file)

Function: loads STR-OR-PATH
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: make-action NAME ARGS

Action consists of name and arguments for the function. ARGS - list of arguments, which will be link with function

Package

cl-rules.core

Source

core.lisp (file)

Function: make-cond NAME ARGS

Create condition from itself name and list of arguments ARGS. NAME is symbol or string

Package

cl-rules.core

Source

core.lisp (file)

Function: make-rule NAME CONDITIONS &optional ACTIONS

Create new rule with NAME and list of conditions. Rule is true, only if all conditions is true

Package

cl-rules.core

Source

core.lisp (file)

Function: param-reg-p NAME

Parameter with NAME is registered?

Package

cl-rules.core

Source

core.lisp (file)

Function: param-val NAME &optional BAD-VAL

Will return value of parameter, if he is exists. If parameter with NAME not exists, returns BAD-VAL. NAME is symbol or string

Package

cl-rules.core

Source

core.lisp (file)

Function: register-rule RULE

Registers new rule. Names of rules must be unique

Package

cl-rules.core

Source

core.lisp (file)

Function: rule-by-name NAME

NAME is symbol or string

Package

cl-rules.core

Source

core.lisp (file)

Function: rule-conditions RULE

Condition stored with static values of arguments

Package

cl-rules.core

Source

core.lisp (file)

Function: rule-name RULE
Package

cl-rules.core

Source

core.lisp (file)

Function: rule-reg-p NAME

Rule with NAME is registered?

Package

cl-rules.core

Source

core.lisp (file)

Function: save-to-file PATH &rest RULE-NAMES
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: save-to-str &rest RULE-NAMES
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: setparam NAME VAL

Set a new value for parameter

Package

cl-rules.core

Source

core.lisp (file)

Function: unregister-rule NAME-OF-RULE
Package

cl-rules.core

Source

core.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Constants

Constant: +root-key+
Package

cl-rules.serialization

Source

serialization.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Special variables

Special Variable: *actions*
Package

cl-rules.core

Source

core.lisp (file)

Special Variable: *conditions*
Package

cl-rules.core

Source

core.lisp (file)

Special Variable: *parameters*
Package

cl-rules.core

Source

core.lisp (file)

Special Variable: *rules*
Package

cl-rules.core

Source

core.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: action-by-name NAME

Return action by specified name. Name must be a symbol or string

Package

cl-rules.core

Source

core.lisp (file)

Function: actions-specified-p RULE-ARGS
Package

cl-rules.core

Source

core.lisp (file)

Function: cond-by-name NAME

Will return condiiton by specified name. NAME is symbol or string

Package

cl-rules.core

Source

core.lisp (file)

Function: eval-action ACTION

Each action linked with function. Function called with arguments of action

Package

cl-rules.core

Source

core.lisp (file)

Function: eval-params ARGS

If a parameter is specified among the arguments, its value is replacement

Package

cl-rules.core

Source

core.lisp (file)

Function: fire-condition CONDITION

Evaluate predicate. Will return true or false

Package

cl-rules.core

Source

core.lisp (file)

Function: is-param-p ITEM

Does the string contain a parameter? Example: ’{{param-name}}’

Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: rule-actions RULE

List of actions, linked with rule. If value of rule is true, the actions evaluates

Package

cl-rules.core

Source

core.lisp (file)

Function: rule-value NAME

Rule is true?

Package

cl-rules.core

Source

core.lisp (file)

Function: serialize-action ACTION
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: serialize-cond CONDITION
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: serialize-param NAME
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: serialize-rule RULE RULESET
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: unserialize-action RAW-ACTION
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: unserialize-cond RAW-CONDITION
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: unserialize-param RAW-PARAM
Package

cl-rules.serialization

Source

serialization.lisp (file)

Function: unserialize-rule NAME RULES
Package

cl-rules.serialization

Source

serialization.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-rules.asd: The cl-rules<dot>asd file
cl-rules/src: The cl-rules/src module
cl-rules/src/cl-rules.lisp: The cl-rules/src/cl-rules<dot>lisp file
cl-rules/src/core.lisp: The cl-rules/src/core<dot>lisp file
cl-rules/src/serialization.lisp: The cl-rules/src/serialization<dot>lisp file

F
File, Lisp, cl-rules.asd: The cl-rules<dot>asd file
File, Lisp, cl-rules/src/cl-rules.lisp: The cl-rules/src/cl-rules<dot>lisp file
File, Lisp, cl-rules/src/core.lisp: The cl-rules/src/core<dot>lisp file
File, Lisp, cl-rules/src/serialization.lisp: The cl-rules/src/serialization<dot>lisp file

L
Lisp File, cl-rules.asd: The cl-rules<dot>asd file
Lisp File, cl-rules/src/cl-rules.lisp: The cl-rules/src/cl-rules<dot>lisp file
Lisp File, cl-rules/src/core.lisp: The cl-rules/src/core<dot>lisp file
Lisp File, cl-rules/src/serialization.lisp: The cl-rules/src/serialization<dot>lisp file

M
Module, cl-rules/src: The cl-rules/src module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   E   F   I   L   M   P   R   S   U   W  
Index Entry  Section

A
action-args: Exported functions
action-by-name: Internal functions
action-name: Exported functions
action-reg-p: Exported functions
actions-specified-p: Internal functions

C
cond-args: Exported functions
cond-by-name: Internal functions
cond-name: Exported functions
cond-reg-p: Exported functions
cond-val: Exported functions

D
defaction: Exported macros
defcond: Exported macros
defparam: Exported macros
defrule: Exported macros

E
eval-action: Internal functions
eval-params: Internal functions
eval-rule: Exported functions

F
fire-condition: Internal functions
fire-rule: Exported functions
Function, action-args: Exported functions
Function, action-by-name: Internal functions
Function, action-name: Exported functions
Function, action-reg-p: Exported functions
Function, actions-specified-p: Internal functions
Function, cond-args: Exported functions
Function, cond-by-name: Internal functions
Function, cond-name: Exported functions
Function, cond-reg-p: Exported functions
Function, cond-val: Exported functions
Function, eval-action: Internal functions
Function, eval-params: Internal functions
Function, eval-rule: Exported functions
Function, fire-condition: Internal functions
Function, fire-rule: Exported functions
Function, is-param-p: Internal functions
Function, loads: Exported functions
Function, make-action: Exported functions
Function, make-cond: Exported functions
Function, make-rule: Exported functions
Function, param-reg-p: Exported functions
Function, param-val: Exported functions
Function, register-rule: Exported functions
Function, rule-actions: Internal functions
Function, rule-by-name: Exported functions
Function, rule-conditions: Exported functions
Function, rule-name: Exported functions
Function, rule-reg-p: Exported functions
Function, rule-value: Internal functions
Function, save-to-file: Exported functions
Function, save-to-str: Exported functions
Function, serialize-action: Internal functions
Function, serialize-cond: Internal functions
Function, serialize-param: Internal functions
Function, serialize-rule: Internal functions
Function, setparam: Exported functions
Function, unregister-rule: Exported functions
Function, unserialize-action: Internal functions
Function, unserialize-cond: Internal functions
Function, unserialize-param: Internal functions
Function, unserialize-rule: Internal functions

I
is-param-p: Internal functions

L
loads: Exported functions

M
Macro, defaction: Exported macros
Macro, defcond: Exported macros
Macro, defparam: Exported macros
Macro, defrule: Exported macros
Macro, with-rules: Exported macros
make-action: Exported functions
make-cond: Exported functions
make-rule: Exported functions

P
param-reg-p: Exported functions
param-val: Exported functions

R
register-rule: Exported functions
rule-actions: Internal functions
rule-by-name: Exported functions
rule-conditions: Exported functions
rule-name: Exported functions
rule-reg-p: Exported functions
rule-value: Internal functions

S
save-to-file: Exported functions
save-to-str: Exported functions
serialize-action: Internal functions
serialize-cond: Internal functions
serialize-param: Internal functions
serialize-rule: Internal functions
setparam: Exported functions

U
unregister-rule: Exported functions
unserialize-action: Internal functions
unserialize-cond: Internal functions
unserialize-param: Internal functions
unserialize-rule: Internal functions

W
with-rules: Exported macros

Jump to:   A   C   D   E   F   I   L   M   P   R   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   S  
Index Entry  Section

*
*actions*: Internal special variables
*conditions*: Internal special variables
*parameters*: Internal special variables
*rules*: Internal special variables

+
+root-key+: Internal constants

C
Constant, +root-key+: Internal constants

S
Special Variable, *actions*: Internal special variables
Special Variable, *conditions*: Internal special variables
Special Variable, *parameters*: Internal special variables
Special Variable, *rules*: Internal special variables

Jump to:   *   +  
C   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-rules: The cl-rules system
cl-rules: The cl-rules package
cl-rules-asd: The cl-rules-asd package
cl-rules.core: The cl-rules<dot>core package
cl-rules.serialization: The cl-rules<dot>serialization package

P
Package, cl-rules: The cl-rules package
Package, cl-rules-asd: The cl-rules-asd package
Package, cl-rules.core: The cl-rules<dot>core package
Package, cl-rules.serialization: The cl-rules<dot>serialization package

S
System, cl-rules: The cl-rules system

Jump to:   C   P   S