This repository has been archived by the owner on Oct 22, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.md.tpl
111 lines (72 loc) · 3.94 KB
/
README.md.tpl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
[](https://twitter.com/pownjs)
[](https://www.npmjs.com/package/@pown/engine)
[](https://github.com/pownjs/lobby)
[](https://secapps.com)
# Pown Engine
Pown Engine is a generic scripting and execution environment. It is used by other pown tools to provide a simle extension mechanism for task-based plugins. For example, [recon](https://github.com/pownjs/recon) is using this library to for its own template-based scripting language. SecApps is using this module as part of the RayGun Service (https://secapps.com/docs/raygun).
## Credits
This tool is part of [secapps.com](https://secapps.com) open-source initiative.
```
___ ___ ___ _ ___ ___ ___
/ __| __/ __| /_\ | _ \ _ \/ __|
\__ \ _| (__ / _ \| _/ _/\__ \
|___/___\___/_/ \_\_| |_| |___/
https://secapps.com
```
### Authors
* [@pdp](https://twitter.com/pdp) - https://pdp.im
## Quickstart
This tool is meant to be used as part of [Pown.js](https://github.com/pownjs/pown), but it can be used separately as an independent library.
### Standalone Use
Install this module locally from the root of your project:
```sh
$ npm install @pown/engine --save
```
## Programming
See `./examples` for examples how to use this library in your own projects.
## Templates
The following is a quick and dirty tutorial what templates are and how to use it.
### What is a template
A template is effectively a simplified scripting language with limited capabilities. It is based on YAML and it is meant to be used for simple task-based executions. You may already be familiar with some template scripting languages such as GitHub Actions, GitLab CI Templates and others.
Like other template languages task execution only proceeds to the next if the current one succeeds. The task execution will also fail if matcher fails. More on that later. In all other cases, execution will proceed one task at the time until it completes.
Each task is provided with an input. The current input is combination between the original input and any output from the current task. The output is what the tasks extracts or exports. More on that later.
The template language does not have the concept of loops and conditions. These types of programming privimitives are better implemented as tasks themselves.
### Matching
The template language has the concept of matching. A matcher is esentially a condition which is checked after the taks completes. If the condition is false then the execution terminates. The matcher is designed to be very versatile and expressive. You can use JavaScript expressions or a more complicated matcher object logic.
For example:
```yaml
task1:
matcher: field === 'abc'
task2:
...
```
Task `task2` will only execute if the output of task1 has a field called `field` with the string value `abc`.
The same effect can be done more verbosely with the following sytanx:
```yaml
task1:
matcher:
eq: 'abc'
part: field
task2:
...
```
## Extracting
Each task returns a result. The result is not automatically merged into the input of the next task. Instead, you need define what you want to do with the result using an extractor. In other words you need to define what parts of the task result should be merged into the input which is passed to the next task.
For example:
```yaml
task1:
extractor: ret({ niceText: text })
task2:
...
```
Here task1 will export a filed with value `abc`. If the original input for `task1` is `{ text: 'Hi' }` the input for `task2` will be `{ text: 'Hi', niceText: 'Hi' }`.
The same effect can be achieved more verbosely with the following syntax:
```yaml
task1:
extractor:
value: niceText
path: $.text
task2:
...
```