1 | # Hubot Factoids
|
2 |
|
3 | A factoids implementation for Hubot, inspired by [oftn-bot](https://github.com/oftn/oftn-bot).
|
4 |
|
5 | [![Build Status](https://travis-ci.org/hubot-scripts/hubot-factoids.svg)](https://travis-ci.org/hubot-scripts/hubot-factoids)
|
6 |
|
7 | ## Features
|
8 |
|
9 | * Supports [hubot-auth](https://github.com/hubot-scripts/hubot-auth).
|
10 | * @mention support: factoid value will be directed at mentioned user.
|
11 | * Customizable prefix
|
12 | * Aliases: point a factoid at the value of another factoid.
|
13 | * Substitutive editing using sed-like syntax.
|
14 | * Factoid history: any time a new value is set on a factoid, the name of the
|
15 | user, current date, previous value and new value are recorded
|
16 | * Factoid popularity: currently only visible in the raw data
|
17 | * HTTP route to view raw JSON factoid data.
|
18 |
|
19 | ## Installation
|
20 |
|
21 | `npm install hubot-factoids`
|
22 |
|
23 | ## Configuration
|
24 |
|
25 | `HUBOT_BASE_URL` _[required]_ - URL of Hubot (ex. http://myhubothost.com:5555/)
|
26 |
|
27 | `HUBOT_FACTOID_PREFIX` _[optional]_ - prefix character to use for retrieving a
|
28 | factoid (defaults to `!` if unset)
|
29 |
|
30 | ## Commands
|
31 |
|
32 | ### Create/update a factoid
|
33 |
|
34 | Creates a new factoid if it doesn't exist, or overwrites the factoid value with
|
35 | the new value. Factoids maintain a history (can be viewed via the factoid URL)
|
36 | of all past values along with who updated the value and when.
|
37 |
|
38 | > **Note:** `<factoid>` can be any string which does not contain `=` or `=~`
|
39 | (these reserved characters delimit the factoid and its value), although special
|
40 | characters should be avoided.
|
41 |
|
42 | `hubot: learn <factoid> = <details>`
|
43 |
|
44 | ### Inline editing a factoid
|
45 |
|
46 | If you prefer, you can edit a factoid value inline, using a sed-like substitution
|
47 | expression.
|
48 |
|
49 | `hubot: learn <factoid> =~ s/expression/replace/gi`
|
50 |
|
51 | `hubot: learn <factoid> =~ s/expression/replace/i`
|
52 |
|
53 | `hubot: learn <factoid> =~ s/expression/replace/g`
|
54 |
|
55 | `hubot: learn <factoid> =~ s/expression/replace/`
|
56 |
|
57 | ### Set an alias
|
58 |
|
59 | An alias will point to the specified pre-existing factoid and when invoked will
|
60 | return that factoid's value.
|
61 |
|
62 | `hubot: alias <factoid> = <factoid>`
|
63 |
|
64 | ### Forget a factoid
|
65 |
|
66 | Disables responding to a factoid. The factoid is not deleted from memory, and
|
67 | can be re-enabled by setting a new value (its complete history is retained).
|
68 |
|
69 | `hubot: forget <factoid>`
|
70 |
|
71 | ### Get URL to factoid data
|
72 |
|
73 | Serves a page with the raw JSON output of the factoid data
|
74 |
|
75 | `hubot: factoids`
|
76 |
|
77 | ### Recall a factoid value
|
78 |
|
79 | Recall the value of the given factoid.
|
80 |
|
81 | > **Note:** Hubot should not be directly addressed.
|
82 |
|
83 | `!<factoid>`
|
84 |
|
85 | Can be combined with a @mention to direct the message at another user:
|
86 |
|
87 | `!factoid @user`
|
88 |
|
89 | Hubot will respond accordingly:
|
90 |
|
91 | `Hubot> @user: factoid value`
|
92 |
|
93 | ### Search for a factoid
|
94 |
|
95 | Find a factoid containing the given string. The string can be matched in either
|
96 | the factoid key or value.
|
97 |
|
98 | `hubot: search foobar`
|
99 |
|
100 |
|
101 | ### Drop a factoid
|
102 |
|
103 | **Permanently removes a factoid—this action cannot be undone.**
|
104 | If [hubot-auth](https://github.com/hubot-scripts/hubot-auth) script is loaded,
|
105 | "admin" or "factoids-admin" role is required to perform this action. It's
|
106 | recommended you use the `forget` command instead of `drop`.
|
107 |
|
108 | `hubot: drop <factoid>`
|