From 299389c12b7d0ac8dc4fdaa25a2cde0a2765166f Mon Sep 17 00:00:00 2001 From: user Date: Fri, 11 Oct 2024 23:24:35 +0300 Subject: [PATCH] Regenerate PLUGINS.md --- PLUGINS.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 91 insertions(+), 7 deletions(-) diff --git a/PLUGINS.md b/PLUGINS.md index 6e2213b..5c96271 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -1,5 +1,5 @@ - + ## Description and configuration of available plugins @@ -49,6 +49,7 @@ section of the README. * [filter.type - Filter for records of specific type](#filtertype---filter-for-records-of-specific-type) * [filter.json - Format record as JSON](#filterjson---format-record-as-json) * [filter.format - Format record as text](#filterformat---format-record-as-text) + * [filter.format.event - Generate Event from record text](#filterformatevent---generate-event-from-record-text) * [filter.deduplicate - Drop already seen records](#filterdeduplicate---drop-already-seen-records) * [filter.nitter.pick - Pick NitterRecord with specified properties](#filternitterpick---pick-nitterrecord-with-specified-properties) * [filter.nitter.drop - Drop NitterRecord without specified properties.](#filternitterdrop---drop-nitterrecord-without-specified-properties) @@ -981,6 +982,9 @@ multiple chains and process them in a single place. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. +##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. --- @@ -992,6 +996,9 @@ Can be used to stuff multiple chains in one if the need ever arises. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. +##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. --- @@ -1005,6 +1012,8 @@ defined by `patterns` list found in any (or specified) field of the record. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `patterns`: list of strings to search for in the record. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `fields`: field names to search the patterns in. If not specified, all fields are checked. Not required. --- @@ -1019,6 +1028,8 @@ defined by `patterns` list found in any (or specified) field of the record. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `patterns`: list of strings to search for in the record. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `fields`: field names to search the patterns in. If not specified, all fields are checked. Not required. --- @@ -1034,6 +1045,8 @@ them from regular records. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `event_types`: list of event types. See descriptions of plugins producing events for possible values. Not required. @@ -1065,6 +1078,9 @@ Regular records (not Events) are passed through unchanged. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. +##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. --- @@ -1077,6 +1093,8 @@ Only lets through records of specified types, such as `Event` or `YoutubeVideoRe * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `types`: list of records class names, such as "Record" and "Event" . Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `exact_match`: whether match should check for exact record type or look in entire records hierarchy up to Record. Default value is `false`. --- @@ -1090,6 +1108,8 @@ original record in JSON format, with option for pretty-print. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `prettify`: whether output should be multiline and indented or a single line. Default value is `false`. @@ -1126,6 +1146,8 @@ parameter is provided to allow formatting these fields in desired timezone. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `template`: template string with placeholders that will be filled with corresponding values from current record. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `missing`: if specified, will be used to fill template placeholders that do not have corresponding fields in current record. Not required. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. @@ -1145,6 +1167,47 @@ Simplest record, containing only a single text field --- +### `filter.format.event` - Generate Event from record text + +Takes a record and produces a new `Event` with the `event_type` and +`text` values evaluated by filling placeholders in `type_template` +and `text_template`. + +Just like with the `filter.format`, missing placeholders are filled with +value from the `missing` parameter if it is specified, otherwise they are +left unchanged. + +Specifying timezone offset for the output text is also +supported, though original record might be retrieved with `filter.event.cause`. + + +#### Entity configuration options: +* `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. +* `type_template`: template string with placeholders that will be filled with corresponding values from current record. Required. +* `text_template`: template string with placeholders that will be filled with corresponding values from current record. Required. +##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. +* `missing`: if specified, will be used to fill template placeholders that do not have corresponding fields in current record. Not required. +* `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. + + +#### Produced records types: + + +
+ Event + +Record produced by an internal event (usually error) inside the plugin + + +* `event_type`: text describing the nature of event, can be used to filter classes of events, such as errors. +* `text`: text describing specific even details. + +
+ +--- + ### `filter.deduplicate` - Drop already seen records Checks if the `field` field value of the current record has already been @@ -1167,6 +1230,8 @@ restarts. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `field`: field name to use for comparison. Default value is `hash`. * `history_size`: how many old records should be kept in memory. Default value is `10000`. @@ -1181,6 +1246,8 @@ All records from other sources pass through without filtering. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `retweet`: match retweets. Default value is `false`. * `reply`: match replies. Default value is `false`. * `quote`: match quotes. Default value is `false`. @@ -1225,6 +1292,8 @@ All records from other sources pass through without filtering. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `retweet`: match retweets. Default value is `false`. * `reply`: match replies. Default value is `false`. * `quote`: match quotes. Default value is `false`. @@ -1272,6 +1341,8 @@ entities if picking records with any of multiple properties is required. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `upcoming`: to pass the filter a record should be either upcoming livestream or scheduled premiere. Default value is `false`. * `live`: to pass the filter a record should be an ongoing livestream. Default value is `false`. * `member_only`: to pass the filter a record should be marked as member-only. Default value is `false`. @@ -1321,6 +1392,8 @@ If the record is not an upcoming Youtube livestream, it gets silently dropped. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `prior`: output a record this many minutes before the scheduled start of a live broadcast. Default value is `10`. * `include_ongoing`: whether currently live streams should be included. Default value is `false`. @@ -1389,6 +1462,8 @@ All records from other sources pass through without filtering. #### Entity configuration options: * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `retweet`: match retweets. Default value is `false`. * `reply`: match replies. Default value is `false`. * `quote`: match quotes. Default value is `false`. @@ -1421,6 +1496,8 @@ will be dropped with a warning. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `url`: webhook url. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. @@ -1428,7 +1505,7 @@ will be dropped with a warning. ### `execute` - Run pre-defined shell command -Take `command` string, replace keywords provided in `placeholders` with corresponding fields +Take `command` string, replace keywords wrapped in curly braces with corresponding fields of currently processed record. For example, if `command` is set to "yt-dlp {url}"` @@ -1439,10 +1516,8 @@ resulting command will be yt-dlp https://www.youtube.com/watch?v=L692Sxz3thw -Note that placeholders do not have to be wrapped in `{}` and can, in fact, be any -arbitrary text strings. However, placeholders are replaced by corresponding values -one after another, so using piece of text that might come up in record field might -produce unexpected results. +See `Formatting templates` section of README.md for more detailed description +of the formatting options. `command` string is not treated as raw shell command. Instead, it is split into list of elements, where first element specifies the program executable, and the rest @@ -1471,12 +1546,13 @@ it happens to fail due to video link not being a livestream. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `command`: shell command to be executed on every received record. Supports placeholders that will be replaced with currently processed record fields values. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. * `working_dir`: path to the directory where command will be executed. If not set current working directory is used. Supports templating with {...}. Not required. * `log_dir`: write executed process output to a file in this directory if set. If it is not set, output will not be redirected to file. Not required. * `log_filename`: filename to write executed process output to. If not defined, it is generated automatically based on command and entity name. Not required. -* `placeholders`: parts of `command` string that should be replaced with processed record fields, defined as mapping `'placeholder': 'record field name'`. Default value is `"{url}": "url", "{title}": "title", "{text}": "text"`. * `static_placeholders`: parts of `command` string that will be replaced with provided values, defined as mapping `'placeholder': 'replacement string'`. Intended to allow reusing same `command` template for multiple entities. Not required. * `forward_failed`: emit currently processed record down the chain if the subprocess returned non-zero exit code. Can be used to define fallback command in case this one fails. Default value is `false`. * `report_failed`: emit Event with type "error" if the subprocess returned non-zero exit code or raised exception. Default value is `true`. @@ -1529,6 +1605,8 @@ using system-wide encoding. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `filename`: name of the output file. Supports templating with {...}. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. * `path`: directory where output file should be created. Default is current directory. Supports templating with {...}. Not required. @@ -1593,6 +1671,8 @@ sharing the base name, the new file will be deleted, giving preference to the ex * `url_field`: field in the incoming record containing url of file to be downloaded. Required. * `path`: directory where downloaded file should be created. Supports templating with {...}. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. * `cookies_file`: path to a text file containing cookies in Netscape format. Not required. @@ -1622,6 +1702,8 @@ it to server side. * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `jid`: JID to send message to. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. @@ -1655,6 +1737,8 @@ database is kept in memory and not stored on disk at all, providing a clean data * `name`: name of a specific entity. Used to reference it in `chains` section. Must be unique within a plugin. Required. * `cookies_file`: path to a text file containing cookies in Netscape format. Required. ##### +* `reset_origin`: treat throughput records as if they have originated from this entity, +emitting them in every Chain this entity is used. Default value is `false`. * `consume_record`: whether record should be consumed or passed down the chain after processing. Disabling it allows chaining multiple Actions. Default value is `true`. * `timezone`: takes timezone name from (or local time if omitted), converts record fields containing date and time to this timezone. Not required. * `url`: Twitter domain name. Default value is `https://twitter.com`.