mirror of
https://github.com/pragma-/pbot.git
synced 2024-11-25 13:29:29 +01:00
doc/Registry.md: update [WIP]
This commit is contained in:
Pragmatic Software
parent
692ab436e6
commit
2565a840d9
328
doc/Registry.md
328
doc/Registry.md
@ -1,182 +1,214 @@
|
|||||||
Registry
|
Registry
|
||||||
========
|
========
|
||||||
PBot's behavior can be customized via a central registry of key/value pairs segregated by sections.
|
|
||||||
|
|
||||||
|
|
||||||
<!-- md-toc-begin -->
|
<!-- md-toc-begin -->
|
||||||
* [Registry](#registry)
|
* [About](#about)
|
||||||
* [Overriding registry values per-channel](#overriding-registry-values-per-channel)
|
* [Types of values](#types-of-values)
|
||||||
* [regadd](#regadd)
|
* [Creating array values](#creating-array-values)
|
||||||
* [regrem](#regrem)
|
* [Overriding registry values per-channel](#overriding-registry-values-per-channel)
|
||||||
* [regshow](#regshow)
|
* [Overriding Registry values via command-line](#overriding-registry-values-via-command-line)
|
||||||
* [regset](#regset)
|
* [Registry commands](#registry-commands)
|
||||||
* [Registry metadata list](#registry-metadata-list)
|
* [regset](#regset)
|
||||||
* [regunset](#regunset)
|
* [regunset](#regunset)
|
||||||
* [regchange](#regchange)
|
* [regchange](#regchange)
|
||||||
* [regfind](#regfind)
|
* [regshow](#regshow)
|
||||||
* [Creating array values](#creating-array-values)
|
* [regfind](#regfind)
|
||||||
* [List of recognized registry items](#list-of-recognized-registry-items)
|
* [regsetmeta](#regsetmeta)
|
||||||
|
* [regunsetmeta](#regunsetmeta)
|
||||||
|
* [Editing Registry file](#editing-registry-file)
|
||||||
|
* [Metadata list](#metadata-list)
|
||||||
|
* [List of known registry items](#list-of-known-registry-items)
|
||||||
<!-- md-toc-end -->
|
<!-- md-toc-end -->
|
||||||
|
|
||||||
|
## About
|
||||||
|
PBot's behavior can be customized via a central registry of key/value pairs segregated by sections.
|
||||||
|
|
||||||
|
### Types of values
|
||||||
There are two types of registry values: literals and arrays. Literals can be strings, floats or integers. Arrays are comma-separated lists of literals.
|
There are two types of registry values: literals and arrays. Literals can be strings, floats or integers. Arrays are comma-separated lists of literals.
|
||||||
|
|
||||||
Overriding registry values per-channel
|
### Creating array values
|
||||||
--------------------------------------
|
Use the [regsetmeta](#regsetmeta) command to change the `type` [meta-data key](#metadata-list) to `array`, and set the registry value to a comma-separated list of values.
|
||||||
|
|
||||||
|
<pragma-> !regset foo.animals aardvark, badger, cat, dingo
|
||||||
|
<PBot> foo.animals set to aardvark, badger, cat, dingo
|
||||||
|
|
||||||
|
<pragma-> !regsetmeta foo.animals type array
|
||||||
|
<PBot> foo.animals: 'type' set to 'array'
|
||||||
|
|
||||||
|
### Overriding registry values per-channel
|
||||||
Some key/value pairs belonging to a specific section may be overridden on a per-channel basis by setting the key/value in a channel-specific section.
|
Some key/value pairs belonging to a specific section may be overridden on a per-channel basis by setting the key/value in a channel-specific section.
|
||||||
|
|
||||||
For example, the bot's trigger is defined in `general.trigger`. You may add a trigger key in `#channel` to override the trigger value for that channel: `#channel.trigger`.
|
For example, the bot's trigger is defined in `general.trigger`. You may add a `trigger` registry item in `#channel` to override the value for that channel: `#channel.trigger`.
|
||||||
|
|
||||||
For another example, the anti-flood max lines is defined in `antiflood.chat_flood_threshold`. To override this setting in `#neatchannel`, you can set `#neatchannel.chat_flood_threshold`.
|
## Overriding Registry values via command-line
|
||||||
|
You may override the Registry values via the PBot start-up command-line. Such
|
||||||
|
overrides are permanent and will be saved.
|
||||||
|
|
||||||
regadd
|
$ ./pbot data_dir=mybot irc.botnick=coolbot irc.server=freenode.net irc.port=6667
|
||||||
------
|
|
||||||
`regadd` adds a new registry value to a specific section/channel.
|
|
||||||
|
|
||||||
Usage: `regadd <section> <key> <value>`
|
## Registry commands
|
||||||
|
### regset
|
||||||
|
`regset` sets a new registry item or updates an existing item.
|
||||||
|
|
||||||
|
Usage: `regset <section>.<item> <value>`
|
||||||
|
|
||||||
For example, to override the trigger for #mychannel to be any of `,`, `!` or `%`:
|
For example, to override the trigger for #mychannel to be any of `,`, `!` or `%`:
|
||||||
|
|
||||||
<pragma> regadd #mychannel trigger [,!%]
|
<pragma> !regset #mychannel.trigger [,!%]
|
||||||
<PBot> [#mychannel] trigger set to [,!%]
|
<PBot> #mychannel.trigger set to [,!%]
|
||||||
|
|
||||||
Some registry values can be *regular expressions*, like the above trigger example. Setting `general.trigger` to the character class `[,!%]` means that it will respond to `,` `!` and `%` as trigger characters on a general basis.
|
### regunset
|
||||||
|
`regunset` removes a registry item from a specific section/channel.
|
||||||
|
|
||||||
regrem
|
Usage: `regunset <section>.<item>`
|
||||||
------
|
|
||||||
`regrem` removes a registry key from a specific section/channel.
|
|
||||||
|
|
||||||
Usage: `regrem <section> <key>`
|
### regchange
|
||||||
|
|
||||||
regshow
|
|
||||||
-------
|
|
||||||
`regshow` displays the type and value of a specific key.
|
|
||||||
|
|
||||||
Usage: `regshow <section> <key>`
|
|
||||||
|
|
||||||
<pragma> regshow antiflood chat_flood_punishment
|
|
||||||
<PBot> [antiflood] chat_flood_punishment: 60,300,3600,86400,604800,2419200 [array]
|
|
||||||
|
|
||||||
regset
|
|
||||||
------
|
|
||||||
`regset` sets the meta-data values for a specific registry key. See [registry meta-data list](#Registry_metadata_list).
|
|
||||||
|
|
||||||
If you omit the `<key>` argument, it will list all the defined keys and values for the registry item. If you specify `<key>` but omit `<value>`, it will show the value for that specific key.
|
|
||||||
|
|
||||||
Usage: `regset <section> <item> [key [value]]`
|
|
||||||
|
|
||||||
<pragma> regset irc botnick value pangloss
|
|
||||||
* PBot changed nick to pangloss
|
|
||||||
<pangloss> [irc] botnick: 'value' set to 'pangloss'
|
|
||||||
|
|
||||||
### Registry metadata list
|
|
||||||
This is a list of recognized registry meta-data keys.
|
|
||||||
|
|
||||||
* `type`: sets the type of this registry key; values can be `text` (literal) or `array`.
|
|
||||||
* `value`: the value of this registry key.
|
|
||||||
* `private`: whether the value of the registry key is displayed in regset, regshow or regfind. If set to a true value, the value of the registry key will be shown as "**\<private\>**".
|
|
||||||
|
|
||||||
regunset
|
|
||||||
--------
|
|
||||||
`regunset` deletes a meta-data key from a registry key.
|
|
||||||
|
|
||||||
Usage: `regunset <section> <item> <key>`
|
|
||||||
|
|
||||||
regchange
|
|
||||||
---------
|
|
||||||
`regchange` changes the value of a registry item using a *regular substitution expression*.
|
`regchange` changes the value of a registry item using a *regular substitution expression*.
|
||||||
|
|
||||||
Usage: `regchange <section> <item> s/<pattern>/<replacement>/`
|
Usage: `regchange <section>.<item> s/<pattern>/<replacement>/`
|
||||||
|
|
||||||
<pragma> regadd foo bar Hello, world!
|
<pragma-> regset foo.bar Hello, world!
|
||||||
<PBot> [foo] bar set to Hello, world!
|
<PBot> foo.bar set to Hello, world!
|
||||||
<pragma> regchange foo bar s/world/universe/
|
|
||||||
<PBot> [foo] bar set to Hello, universe!
|
|
||||||
|
|
||||||
regfind
|
<pragma-> regchange foo.bar s/world/universe/
|
||||||
-------
|
<PBot> foo.bar set to Hello, universe!
|
||||||
|
|
||||||
|
### regshow
|
||||||
|
`regshow` displays the type and value of a registry item.
|
||||||
|
|
||||||
|
Usage: `regshow <section>.<item>`
|
||||||
|
|
||||||
|
<pragma-> !regshow antiflood.chat_flood_punishment
|
||||||
|
<PBot> antiflood.chat_flood_punishment: 60,300,3600,86400,604800,2419200 [array]
|
||||||
|
|
||||||
|
### regfind
|
||||||
`regfind` searches for registry items, and may optionally show the values of all matching items.
|
`regfind` searches for registry items, and may optionally show the values of all matching items.
|
||||||
|
|
||||||
Usage: `regfind [-showvalues] [-section <section>] <regex>`
|
Usage: `regfind [-showvalues] [-section <section>] <regex>`
|
||||||
|
|
||||||
To limit the search to a specific section, use `-section <section>`. To dump the entire registry, use `regfind -showvalues .*`
|
To limit the search to a specific section, use `-section <section>`. To dump the entire registry, use `regfind -showvalues .*`
|
||||||
|
|
||||||
Creating array values
|
### regsetmeta
|
||||||
---------------------
|
`regsetmeta` sets the meta-data values for a specific registry key. See [registry meta-data list](#metadata-list).
|
||||||
Use the [regset](#regset) command to change the `type` meta-data value to "array", and set the registry value to a comma-separated list of values.
|
|
||||||
|
|
||||||
<pragma> regadd foo animals aardvark, badger, cat, dingo
|
If you omit the `<key>` argument, it will list all the defined keys and values for the registry item. If you specify `<key>` but omit `<value>`, it will show the value for that specific key.
|
||||||
<PBot> [foo] animals set to aardvark, badger, cat, dingo
|
|
||||||
<pragma> regset foo animals type array
|
|
||||||
<PBot> [foo] animals: 'type' set to 'array'
|
|
||||||
|
|
||||||
List of recognized registry items
|
Usage: `regsetmeta <section>.<item> [key [value]]`
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
* antiaway.bad_actions
|
For example, this directly sets the `value` meta-data key of `irc.botnick`.
|
||||||
* antiaway.bad_nicks
|
|
||||||
* antiaway.kick_msg
|
<pragma-> !regsetmeta irc.botnick value candide
|
||||||
* antiflood.chat_flood_punishment
|
* PBot changed nick to candide
|
||||||
* antiflood.chat_flood_threshold
|
<candide> irc.botnick: 'value' set to 'candide'
|
||||||
* antiflood.chat_flood_time_threshold
|
|
||||||
* antiflood.debug_checkban
|
That example is equivalent to `regset irc.botnick candide`.
|
||||||
* antiflood.dont_enforce_admins
|
|
||||||
* antiflood.enforce
|
### regunsetmeta
|
||||||
* antiflood.enter_abuse_max_offenses
|
`regunset` deletes a meta-data key from a registry item.
|
||||||
* antiflood.enter_abuse_punishment
|
|
||||||
* antiflood.enter_abuse_threshold
|
Usage: `regunset <section>.<item> <key>`
|
||||||
* antiflood.enter_abuse_time_threshold
|
|
||||||
* antiflood.join_flood_punishment
|
## Editing Registry file
|
||||||
* antiflood.join_flood_threshold
|
You may edit the Registry file manually. It is located as `$data_dir/registry`. Its
|
||||||
* antiflood.join_flood_time_threshold
|
contents are plain-text JSON.
|
||||||
* antiflood.nick_flood_punishment
|
|
||||||
* antiflood.nick_flood_threshold
|
This is a sample entry:
|
||||||
* antiflood.nick_flood_time_threshold
|
|
||||||
* antikickautorejoin.punishment
|
"irc" : {
|
||||||
* antikickautorejoin.threshold
|
"botnick" : {
|
||||||
* bantracker.chanserv_ban_timeout
|
"type" : "text",
|
||||||
* bantracker.debug
|
"value" : "PBot"
|
||||||
* bantracker.mute_timeout
|
}
|
||||||
* factoids.default_rate_limit
|
}
|
||||||
* general.compile_blocks_channels
|
|
||||||
* general.compile_blocks
|
After editing an entry in the Registry file, you may reload it with the `reload` command.
|
||||||
* general.compile_blocks_ignore_channels
|
|
||||||
* general.config_dir
|
<pragma-> !reload registry
|
||||||
* general.data_dir
|
<PBot> Registry reloaded.
|
||||||
* general.deop_timeout
|
|
||||||
* general.module_dir
|
## Metadata list
|
||||||
* general.module_repo
|
This is a list of recognized registry meta-data keys.
|
||||||
* general.paste_ratelimit
|
|
||||||
* general.show_url_titles_channels
|
Name | Description
|
||||||
* general.show_url_titles
|
--- | ---
|
||||||
* general.show_url_titles_ignore_channels
|
`type` | Sets the type of the registry item; values can be `text` (literal) or `array`.
|
||||||
* general.trigger
|
`value` | The value of the registry item.
|
||||||
* interpreter.max_recursion
|
`private` | Whether the value of the registry item is displayed in the `regset`, `regshow` or `regfind` commands. If set to a true value, the value of the registry key will be shown as `**\<private\>**`.
|
||||||
* irc.botnick
|
|
||||||
* irc.debug
|
## List of known registry items
|
||||||
* irc.identify_password
|
This is a list of recognized registry items at the time of this writing.
|
||||||
* irc.server
|
|
||||||
* irc.log_default_handler
|
Name | Description | Default value
|
||||||
* irc.max_msg_len
|
--- | --- | ---
|
||||||
* irc.port
|
antiaway.bad_actions | If a message matches against this regex, it is considered an Away action. |
|
||||||
* irc.realname
|
antiaway.bad_nicks | If a user changes their nick and the new nick matches this regex, it is considered an Away nick. |
|
||||||
* irc.show_motd
|
antiaway.kick_msg | The message to use when kicking Away offenders. |
|
||||||
* irc.SSL_ca_file
|
antiflood.chat_flood_punishment ||
|
||||||
* irc.SSL_ca_path
|
antiflood.chat_flood_threshold ||
|
||||||
* irc.SSL
|
antiflood.chat_flood_time_threshold ||
|
||||||
* irc.username
|
antiflood.debug_checkban ||
|
||||||
* lagchecker.lag_history_interval
|
antiflood.dont_enforce_admins ||
|
||||||
* lagchecker.lag_history_max
|
antiflood.enforce ||
|
||||||
* lagchecker.lag_threshold
|
antiflood.enter_abuse_max_offenses ||
|
||||||
* messagehistory.debug_aka
|
antiflood.enter_abuse_punishment ||
|
||||||
* messagehistory.debug_link
|
antiflood.enter_abuse_threshold ||
|
||||||
* messagehistory.max_messages
|
antiflood.enter_abuse_time_threshold ||
|
||||||
* messagehistory.sqlite_commit_interval
|
antiflood.join_flood_punishment ||
|
||||||
* messagehistory.sqlite_debug
|
antiflood.join_flood_threshold ||
|
||||||
* nicklist.debug
|
antiflood.join_flood_time_threshold ||
|
||||||
* [channel].dont_enforce_antiflood
|
antiflood.nick_flood_punishment ||
|
||||||
* [channel].max_newlines
|
antiflood.nick_flood_threshold ||
|
||||||
* [channel].no_url_titles
|
antiflood.nick_flood_time_threshold ||
|
||||||
* [channel].no_compile_blocks
|
antikickautorejoin.punishment ||
|
||||||
* [channel].preserve_newlines
|
antikickautorejoin.threshold ||
|
||||||
|
bantracker.chanserv_ban_timeout ||
|
||||||
|
bantracker.debug ||
|
||||||
|
bantracker.mute_timeout ||
|
||||||
|
factoids.default_rate_limit ||
|
||||||
|
general.compile_blocks_channels ||
|
||||||
|
general.compile_blocks ||
|
||||||
|
general.compile_blocks_ignore_channels ||
|
||||||
|
general.config_dir ||
|
||||||
|
general.data_dir ||
|
||||||
|
general.deop_timeout ||
|
||||||
|
general.module_dir ||
|
||||||
|
general.module_repo ||
|
||||||
|
general.paste_ratelimit ||
|
||||||
|
general.show_url_titles_channels ||
|
||||||
|
general.show_url_titles ||
|
||||||
|
general.show_url_titles_ignore_channels ||
|
||||||
|
general.trigger ||
|
||||||
|
interpreter.max_recursion ||
|
||||||
|
irc.botnick ||
|
||||||
|
irc.debug ||
|
||||||
|
irc.identify_password ||
|
||||||
|
irc.server ||
|
||||||
|
irc.log_default_handler ||
|
||||||
|
irc.max_msg_len ||
|
||||||
|
irc.port ||
|
||||||
|
irc.realname ||
|
||||||
|
irc.show_motd ||
|
||||||
|
irc.SSL_ca_file ||
|
||||||
|
irc.SSL_ca_path ||
|
||||||
|
irc.SSL ||
|
||||||
|
irc.username ||
|
||||||
|
lagchecker.lag_history_interval ||
|
||||||
|
lagchecker.lag_history_max ||
|
||||||
|
lagchecker.lag_threshold ||
|
||||||
|
messagehistory.debug_aka ||
|
||||||
|
messagehistory.debug_link ||
|
||||||
|
messagehistory.max_messages ||
|
||||||
|
messagehistory.sqlite_commit_interval ||
|
||||||
|
messagehistory.sqlite_debug ||
|
||||||
|
nicklist.debug ||
|
||||||
|
|
||||||
|
Some items only exist as a channel-specific item.
|
||||||
|
|
||||||
|
Name | Description | Default value
|
||||||
|
--- | --- | ---
|
||||||
|
[channel].dont_enforce_antiflood ||
|
||||||
|
[channel].max_newlines ||
|
||||||
|
[channel].no_url_titles ||
|
||||||
|
[channel].no_compile_blocks ||
|
||||||
|
[channel].preserve_newlines ||
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user