From c40170cb03e41bd1efe775bbd430a50da6cdeea4 Mon Sep 17 00:00:00 2001 From: Joe Date: Thu, 10 Nov 2011 11:31:23 +0000 Subject: First commit, pbot-ng already works. --- doc/ConfigChanges.txt | 17 ++ doc/bot_settings.sh.example.in | 296 +++++++++++++++++++++++++++++++ doc/coding-standards.txt | 100 +++++++++++ doc/envbot.1 | 52 ++++++ doc/factoids.sql | 15 ++ doc/karma.sql | 14 ++ doc/module_api2.txt | 383 +++++++++++++++++++++++++++++++++++++++++ doc/seen.sql | 15 ++ doc/transports_api.txt | 101 +++++++++++ 9 files changed, 993 insertions(+) create mode 100644 doc/ConfigChanges.txt create mode 100644 doc/bot_settings.sh.example.in create mode 100644 doc/coding-standards.txt create mode 100644 doc/envbot.1 create mode 100644 doc/factoids.sql create mode 100644 doc/karma.sql create mode 100644 doc/module_api2.txt create mode 100644 doc/seen.sql create mode 100644 doc/transports_api.txt (limited to 'doc') diff --git a/doc/ConfigChanges.txt b/doc/ConfigChanges.txt new file mode 100644 index 0000000..f52e894 --- /dev/null +++ b/doc/ConfigChanges.txt @@ -0,0 +1,17 @@ +Any configuration file changes and how to update should be listed here. + +Config version 17 +----------------- + * Added config_log_colors + +Config version 16 +----------------- + * Added config_commands_private_always + * Renamed config_listenregex to config_commands_listenregex + * Renamed config_unknown_commands to config_feedback_unknown_commands. + + +Config version 15 +----------------- +This file was added at this point. To convert from older versions to this +one, please read example config and add what is missing. diff --git a/doc/bot_settings.sh.example.in b/doc/bot_settings.sh.example.in new file mode 100644 index 0000000..9e8d5a9 --- /dev/null +++ b/doc/bot_settings.sh.example.in @@ -0,0 +1,296 @@ +#!/bin/bash +# -*- coding: utf-8 -*- +########################################################################### +# # +# envbot - an IRC bot in bash # +# Copyright (C) 2007-2008 Arvid Norlander # +# # +# This program is free software: you can redistribute it and/or modify # +# it under the terms of the GNU General Public License as published by # +# the Free Software Foundation, either version 3 of the License, or # +# (at your option) any later version. # +# # +# This program is distributed in the hope that it will be useful, # +# but WITHOUT ANY WARRANTY; without even the implied warranty of # +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # +# GNU General Public License for more details. # +# # +# You should have received a copy of the GNU General Public License # +# along with this program. If not, see . # +# # +########################################################################### + +# Variables marked with (*) will take effect at a rehash as well. + +# What version this config is at. This is used to check +# if your config needs updating. +config_version=17 + +#################### +# General settings # +#################### + +# Nick to use +config_firstnick="BOTNICK" +# Nick if first is in use +config_secondnick="BOTNICK_" +# Nick if second is in use +config_thirdnick="BOTNICK__" + +config_ident='rfc3092' +config_gecos='ietf.org/rfc/rfc3092' + + +################### +# Server settings # +################### + +# Server to use +config_server='irc.kuonet-ng.org' +# What port to use. Normally 6667 works for non SSL connections. +config_server_port='6667' +# If 1 use SSL, not all transport modules support this. +config_server_ssl=0 +# Accept invalid server certificates? +# Note that some SSL modules (openssl for example) just +# print any errors and continues anyway +config_server_ssl_accept_invalid=1 +# Be verbose when connecting? +# Not all SSL modules support it. The ones that doesn't +# support it will just ignore it. +# Be aware that this is mainly for debugging of SSL transport +# modules as it is possible the verbose output may confuse the bot! +config_server_ssl_verbose=0 +# If not empty try to bind to this IP when connecting, useful +# to select vhost. Not all transport modules support this. +config_server_bind="" +# If this is empty don't use a server password. +config_server_passwd="" + + +################## +# Access control # +################## + +# (*) Access regexes +# Without at least one set, the bot won't start +# "owner" is a special capab that grants all other access. +# The first access entry must be an owner. +# +# Scope is a regular expression of channels where access is effective. +# A /msg (like say to a non channel) will get the scope MSG +# Anything affecting global state will have the scope "GLOBAL" +# +# There can be several access masks matching same host (to allow +# for different scope/capab combinations). +#config_access_mask[1]='^The!owner@shellhost\.net$' +#config_access_capab[1]='owner' +#config_access_scope[1]='.*' + +# Some more access examples: + +#config_access_mask[2]='^Someone!whatever@customer-1234\.isp\.com$' +#config_access_capab[2]='say kick' +#config_access_scope[2]='#channel' + +#config_access_mask[3]='^Someone!whatever@customer-1234\.isp\.com$' +#config_access_capab[3]='facoid_admin' +#config_access_scope[3]='GLOBAL' + + +############ +# Commands # +############ + +# (*) A regular expression of prefixes we should listen to. +config_commands_listenregex="(;|${config_firstnick}[:,] )" + +# (*) Should we treat any message in /msg as a command even +# if it doesn't have the the listen prefix? +config_commands_private_always=0 + + +############ +# Feedback # +############ + +# (*) How to treat unknown commands: +# Valid values: +# 0 = Ignore them (drop command, do nothing). +# 1 = Return error to sender. +# 2 = Pass them on to modules that may handle "generic" PRIVMSG. +# Note that non-commands always get passed on to "generic" PRIVMSG handling modules. +config_feedback_unknown_commands=1 + + +########### +# Logging # +########### + +# Directory for log files +config_log_dir="@@logdir@@" +# (*) Should we log raw data or not? +# Can be 1 (log) or 0 (don't log) +config_log_raw=0 +# (*) Should we always log to STDOUT as well? +# Note that this doesn't mean it will not log at all if set to 0. +# It will still log errors and other important log messages to STDOUT. +# This is the same as --verbose. +# Can be 1 (log) or 0 (don't log) +config_log_stdout=0 +# (*) When logging to STDOUT should we use colors? +config_log_colors=1 + + +############# +# Transport # +############# + +# Transport module. You should select exactly one. +# The recommended non-SSL module is dev-tcp. +# The recommended SSL module is gnutls. +config_transport='dev-tcp' +#config_transport='netcat' # Not well tested, for Debian users and other + # with broken distros. +#config_transport='gnutls' +#config_transport='socat' # Not well tested +#config_transport='openssl' # Not well tested + +# netcat options +# MAKE SURE THEY ARE CORRECT if you use netcat. +#config_transport_netcat_path='/usr/bin/netcat' + +# socat options +# MAKE SURE THEY ARE CORRECT if you use socat. +# +# This tells if to use IPv6 or IPv4 to connect. +# socat doesn't support automatic choice of this. +# Note that socat versions below 1.5 does not +# support using IPv6 and SSL at the same time. +# This can be either "ipv4" or "ipv6". +#config_transport_socat_protocol_family=ipv4 + +# Where are transports stored, this can be a relative path from the +# main script of the bot, or an absolute path. +config_transport_dir="@@transportdir@@" + + +########### +# Modules # +########### + + +# What modules to load on startup, space separated list +# For a list of modules see the modules dir. +# Note that the order of the modules may be important +# +# The list should normally start with "modules rehash services umodes autojoin" +# Some modules should be placed last. "factoids" and "karma are such modules. +config_modules="modules rehash services umodes autojoin ctcp" + +# Where are modules stored, this can be a relative path from the +# main script of the bot, or an absolute path. +config_modules_dir="@@moddir@@" + + +############################ +# Module specific settings # +############################ + +##################################################################### +# Services module +# +# (*) NickServ password +config_module_services_nickserv_passwd='nickserv password here' +# (*) Name of NickServ +# Normally this is correct. +config_module_services_nickserv_name='NickServ' +# (*) Service style. Supported are: generic, atheme +# For the default server (irc.kuonet-ng.org) use atheme +# Otherwise try generic, that will work with atheme too but +# some features will be disabled. +config_module_services_style='atheme' +# (*) Use server side aliases +# Try 1 first, if the bot fails to identify try 0 +config_module_services_server_alias=1 + + +##################################################################### +# FAQ module +# +# (*) Location of FAQ items. +#config_module_faq_file='@@datadir@@/faq.txt' + + +#################################################################### +# Quote module +# +# (*) Location of quotes file +#config_module_quotes_file='@@datadir@@/quotes.txt' + + +##################################################################### +# AutoJoin module. +# +# Channels to autojoin on connect +config_module_autojoin_channels[1]='#channel' +# A channel can have a key as showed in the example below +config_module_autojoin_channels[2]='#otherchannel channelkey' + + +##################################################################### +# Umodes module. +# +# (*) Default umodes to set on connect. Also set these at a rehash. +config_module_umodes_default_umodes="+isB-w" + + +##################################################################### +# CTCP module +# +# (*) What to reply to VERSION requests. +config_module_ctcp_version_reply="envbot $envbot_version" + + +##################################################################### +# SQLite3 module +# +# (*) Location of SQLite3 database file +#config_module_sqlite3_database='@@datadir@@/envbot.db' + + +##################################################################### +# Factoids module +# +# (*) Table name for factoids in SQLite3 database +#config_module_factoids_table='factoids' + + +##################################################################### +# Karma module +# +# (*) Table name for karma data in SQLite3 database +#config_module_karma_table='karma' + + +##################################################################### +# Seen module +# +# (*) Table name for seen data in SQLite3 database +#config_module_seen_table='seen' + + +##################################################################### +# Vote module. +# +# (*) The channel where vote mode will work. +# Note that this is a regular expression that will be +# surronded by ^ and $ when matching. +#config_module_vote_channel='#mychannel' +# (*) How long a vote is open before it is closed (in seconds). +#config_module_vote_timeout='900' + + +##################################################################### +# For contrib modules please see the contrib module in question +# for information on what variables it uses. diff --git a/doc/coding-standards.txt b/doc/coding-standards.txt new file mode 100644 index 0000000..3e4253c --- /dev/null +++ b/doc/coding-standards.txt @@ -0,0 +1,100 @@ +Coding standards +================ +This document describe the coding standards used in envbot. + +Indention +--------- +Indention is done with tabs, one tab char for each indention level. +Do adjust the code with spaces if you need to break a long line. +Example: + thisFunctionGotLotsOfParameters foo bar quux loooooooooooooooooooooooooooongParameter + some more parameters +That is, first indent with tabs to base indention level, then use spaces +to adjust. + + +Spaces +------ +Trailing spaces + Forbidden. +Spaces around operators: + Depend on situation. + Examples: + myvar="this is a value" + if [[ "$myvar" = "something" ]]; then + As you can see it depends on where it is used. + Generally it should be used everywhere except assignment like + "=" and "=+". + + +Newlines +-------- +There should not be newlines before a { or other block separator. +For example this is correct: + if [[ $a = $b ]]; then + runStuff + fi +But this is incorrect: + if [[ $a = $b ]] + then + runStuff + fi + +Trailing newlines: There should be a single +ending newline at the end of the file, no +trailing newlines. + + +Functions +--------- +Functions should be declared without the function keyword +and with the () following the name of the function, without +space between the function name and the (). After the () there +should be one space and then the opening bracket. +Example: +myNiceFunction() { + runStuff +} + + +Functions: Returning values +--------------------------- +Return values using "printf -v" construct. Avoid subshells (for +performance reasons). One exception to this is the case of the +function only calling an external program, then just subshell +the function let the external programs output go to STDOUT of the +function. +Example of printf -v construct (first parameter for this function +is the name of the variable to return in): + myfunction() { + printf -v "$1" '%s' "something we computed" + } +Using return code should only be used when returned value is +an error code. Example: + otherfunction() { + if [[ "$1" = "foo" ]]; then + # Success! + return 0 + else + # Fail + return 1 + fi + } + + +Comments +-------- +Comments are free form inside function, function comment should +be coded in bashdoc style. +(TODO: add description of that or link to that) + +Comments should be indented to same level as surrounding code, +unless the comment is commented out code. Commented out code +should be avoided in committed code, but if it is needed, the +comment should be at the start of the line. + + +if +-- +When testing in if use the [[ ]] construct. Do NOT under ANY +circumstances use the [ ] construct. diff --git a/doc/envbot.1 b/doc/envbot.1 new file mode 100644 index 0000000..cd09d00 --- /dev/null +++ b/doc/envbot.1 @@ -0,0 +1,52 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.36. +.TH ENVBOT "1" "July 2008" "envbot" "User Commands" +.SH NAME +envbot \- An advanced modular IRC bot in bash +.SH SYNOPSIS +.B envbot +[\fIOPTION\fR]... +.SH DESCRIPTION +envbot is an advanced modular IRC bot coded in bash. +.SH OPTIONS +.TP +\fB\-c\fR, \fB\-\-config\fR file +Use file instead of the default as config file. +.TP +\fB\-l\fR, \fB\-\-libdir\fR directory +Use directory instead of the default as library directory. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Force verbose output even if config_log_stdout is 0. +.TP +\fB\-d\fR, \fB\-\-debug\fR +Enable debugging code. Most likely pointless to anyone +except envbot developers or module developers. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help and exit +.TP +\fB\-V\fR, \fB\-\-version\fR +Output version information and exit +.PP +Note that envbot can't handle short versions of options being written together like +\fB\-vv\fR currently. +.PP +Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble. +.SH EXAMPLES +.TP +envbot +Runs envbot with default options. +.TP +envbot \fB\-c\fR bot.config +Runs envbot with the config bot.config. +.SH AUTHOR +Written by Arvid Norlander and EmErgE. +.SH "REPORTING BUGS" +Report bugs to http://envbot.org/trac/simpleticket +.SH COPYRIGHT +Copyright \(co 2007-2008 Arvid Norlander +.br +Copyright \(co 2007-2008 EmErgE +.br +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. diff --git a/doc/factoids.sql b/doc/factoids.sql new file mode 100644 index 0000000..ecf2732 --- /dev/null +++ b/doc/factoids.sql @@ -0,0 +1,15 @@ +/* + * This is how to create a factoid database + * Use this file like this: + * sqlite3 -batch data/envbot.db < doc/factoids.sql + * + * If you use another table name, change below in + * both places + */ +DROP TABLE IF EXISTS factoids; +CREATE TABLE factoids ( + name TEXT UNIQUE NOT NULL PRIMARY KEY, + value TEXT NOT NULL, + who TEXT NOT NULL, + is_locked INTEGER NOT NULL DEFAULT 0 +); diff --git a/doc/karma.sql b/doc/karma.sql new file mode 100644 index 0000000..63f16f7 --- /dev/null +++ b/doc/karma.sql @@ -0,0 +1,14 @@ +/* + * This is how to create a factoid database + * Use this file like this: + * sqlite3 -batch data/envbot.db < doc/karma.sql + * + * If you use another table name, change below in + * both places + */ +DROP TABLE IF EXISTS karma; +CREATE TABLE karma ( + target TEXT UNIQUE NOT NULL PRIMARY KEY, + rating INTEGER NOT NULL, + is_locked INTEGER NOT NULL DEFAULT 0 +); diff --git a/doc/module_api2.txt b/doc/module_api2.txt new file mode 100644 index 0000000..1249a79 --- /dev/null +++ b/doc/module_api2.txt @@ -0,0 +1,383 @@ +Module API +========== + +This file contains info needed to write a module. + +File name +--------- +There are two ways to store modules: single file and directory. +Single file: + The module is a single file. + The file name should follow this pattern: + m_modulename.sh + Example: + m_faq.sh +Directory: + The module is a directory that contains several files. + The directory name should follow this pattern: + m_modulename + Example: + m_faq + This directory should contain a file called __main__.sh + that the bot will load when loading the module. This file + may then load other files from the directory as needed. + +Other than that there are no differences between the two ways to store +modules. + + +Variables +--------- +All bash variables in the module that are global MUST follow the format +module_modulename_variablename to prevent overwriting other modules, or +global bot variables. FAQ module may use: module_faq_last_query for example +as a variable. + +Variables that are local to the function (using the local directive) may have +other names. Don't forget variables created in for loops and such +(for foo in bar bash; do echo $foo; done the $foo variable is global here, + do local foo on the line before it) + + +Functions and hooks +------------------- +Hooks are functions with special names, as listed below in the section "The hooks". + +Each function or hook should start with the module_ followed by the module name. +So if the module is faq.sh the modules should start with module_faq_ like module_faq_INIT. + +All bash functions in the module MUST follow the format +module_modulename_functionname to prevent overwriting other modules, or +global bot functions. + +If not mentioned otherwise the hook is optional. +Functions marked with TODO may change, get renamed or removed and may not work +even in current code. + + +The hooks +--------- +module_modulename_INIT (REQUIRED) + Called directly after loading the module. + Parameters: + $1 = The module name. + None + Exported variables to this function: + MODULE_BASE_PATH + Useful for multifile modules, then it is the path to the base directory of + the module (without ending slash). If the module consists of a single file + it is the path to the module file. + Return status: + If return status isn't 0 the module is considered as failed to load. + Return on in variables (these will get unset after they have been processed): + modinit_HOOKS: + In this variable should be returned a space separated list of the optional functions + that the module implements. FAQ would return "before_connect on_PRIVMSG" + modinit_API: + Return 2 if you follow this module API. + Notes: + Check for dependencies (external commands and other modules) in this function, + as well as register any commands. + + +module_modulename_UNLOAD (REQUIRED) + Called to make the module unload itself. + In this function it should clean up after itself and unset all + it's functions and variables except the hook functions. + The unload function and other hook functions will be undefined + after unload finished. + The module may or may not get reloaded after this. + Parameters: + None + Return status: + 0 = Unloaded correctly + 1 = Failed to unload. On this the bot will quit. + Notes: + This function is NOT called when the bot is exiting. To check for that + use the FINALISE hook! + + +module_modulename_REHASH (REQUIRED) + Called to make the module reparse any config options. + Parameters: + None + Return status: + 0 = Rehashed correctly + 1 = Non fatal error for the bot itself. The bot will call UNLOAD on the module. + 2 = Fatal error of some kind. On this the bot will quit. + + +module_modulename_FINALISE + Called directly before the bot quits. The bot has already closed + the connection to the IRC server at this point. This is for saving + stuff. + Parameters: + None + Return status: + Not checked. + + +module_modulename_after_load + Called after all the hooks are added for the module. + Parameters: + None + Return status: + 0 = Unloaded correctly + 1 = Failed. On this the bot will call unload on the module. + Notes: + This is useful for stuff that needs to echo log messages + as that can't be done in modulename_INIT. + + +module_modulename_before_connect + Called before the bot connected. + Parameters: + None + Return status: + Not checked. + + +module_modulename_on_connect + Called for each line that the bot + receives from the server during connecting. + Parameters: + $1 = Raw line. + Return status: + Not checked. + + +module_modulename_after_connect + Called after the bot connected. + Parameters: + None + Return status: + Not checked. + + +module_modulename_on_module_UNLOAD + Called when *ANOTHER* module is got unloaded. + This is meant for a provider module that must unregister some entry + at unload. For example m_help.sh would be such a module. + Parameters: + $1 = The module that got unloaded. + Return code: + Not checked. + + +module_modulename_on_PRIVMSG + Called when bot gets a PRIVMSG + Parameters: + $1 = From who (n!u@h) + $2 = To who (channel or botnick) + $3 = The message + Return code: + 0 = pass it on to next module + 1 = I have taken care of this, and don't + consult other modules about this. + + +module_modulename_on_NOTICE + Called when bot gets a NOTICE + Parameters: + $1 = From who (n!u@h) + $2 = To who (channel or botnick) + $3 = The message + Return code: + 0 = pass it on to next module + 1 = I have taken care of this, and don't + consult other modules about this. + + +module_modulename_on_INVITE (new in 0.0.1-beta5) + Called when bot gets an INVITE + Parameters: + $1 = From who (n!u@h) + $2 = Target nick (probably our own nick). + $3 = Target channel. + Return code: + Not checked. + + +module_modulename_on_NICK + Called when someone changes nick in a channel the bot is in + Parameters: + $1 = From who (n!u@h) + $2 = New nick + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the nick change. + + +module_modulename_on_JOIN + Called when someone joins a channel the bot is in + Parameters: + $1 = Who did it (n!u@h) + $2 = What channel + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the join. + + +module_modulename_on_PART + Called when someone parts a channel the bot is in + Parameters: + $1 = Who did it (n!u@h) + $2 = What channel + $3 = A reason if one exists. + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the part. + + +module_modulename_on_KICK + Called when someone parts a channel the bot is in + Parameters: + $1 = Who did it (n!u@h). + $2 = What channel. + $3 = Who got kicked. + $4 = A reason if one exists. + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the kick. + + +module_modulename_on_QUIT + Called when someone quits + Parameters: + $1 = Who did it (n!u@h). + $2 = A reason if one exists. + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the quit. + + +module_modulename_on_TOPIC + Called when a topic is set or on channel join + Parameters: + $1 = Who did it (n!u@h). + $2 = What channel. + $3 = New topic. + Return status: + Not checked. + Reason: We don't want to get desynced modules. + + +module_modulename_on_channel_MODE + Called when someone changes a mode in the channel + Parameters: + $1 = Who did it (n!u@h). + $2 = On what channel. + $3 = The mode change with it's parameters. + Return status: + Not checked. + Reason: A module with a list of users could get desynced if it didn't + get the mode change. + + +module_modulename_on_user_MODE (new in 0.0.1-beta4) + Called when someone changes a user mode (most likely on ourself) + Parameters: + $1 = Who did it (n!u@h). + $2 = What target (nick). + $3 = The mode change with it's parameters. + Return status: + Not checked. + Reason: There is no point in checking this. + + +module_modulename_on_numeric + Called on any numeric after connect. + Parameters: + $1 = The numeric. + $2 = It's data. + Return status: + 0 = pass it on to next module + 1 = I have taken care of this, and don't + consult other modules about this. + Notes: + In most cases you DON'T want to return 1 for this. If you do be very very careful. + + +module_modulename_on_PONG + Called when bot receives a PONG from server + Parameters: + $1 = Sender + $2 = Second server. + $3 = The data. + Return status: + Not checked. + + +module_modulename_on_server_ERROR + # ERROR :Closing link (rfc3092@1.2.3.4) [Killed (AnMaster (testing a kill on inspircd))] + # ERROR :Closing Link: [1.2.3.4] (Throttled: Reconnecting too fast) -Email staff@example.com for more information. + # ERROR :Closing Link: envbot[host.name.se] Brain ([hurricane.KuoNET.org] Local kill by Brain (testing kill on unrealircd)) + # ERROR :Closing Link: envbot[host.name.se] hurricane.KuoNET.org (Killed (Brain (testing kill on unrealircd, remote one))) + Called when the bot get an ERROR from the server. + Parameters: + $1 = The ERROR message. + Return status: + Not checked. + Reason: There isn't much point in swallowing this. + + +module_modulename_on_KILL + Called when the bot get a KILL message from the server. + Parameters: + $1 = The sender of the kill. + $2 = The target of the kill. + $3 = The KILL path. + $4 = The reason. + Return status: + Not checked. + Reason: Risk for desync of modules. + + +module_modulename_before_disconnect + Called when the bot is about to disconnect from server. + The bot may or may not reconnect after this depending on what caused this. + the disconnect. + Parameters: + None + Return status: + Not checked. + Notes: + This won't be called if the disconnect wasn't planned, like + a ping timeout, getting killed, and so on. + + +module_modulename_after_disconnect + Called when the bot gets disconnected from server. + The bot may or may not reconnect after this depending on what caused + the disconnect. + Parameters: + None + Return status: + Not checked. + Reason: A module may need clean up, don't let it desync. + + +module_modulename_on_RAW + Called when the bot gets *ANY* line from the server after the initial connect. + With this a module can hook onto something not supported by a more specific hook. + The downsides: + * Potentially speed as it has to be called for any message. + * You have to parse more on your own. + * You can desync other modules! Imagine a module that keep a list of + users in the channel. If you swallow a message about a join, part, + quit, nickchange, or other ones it may get desynced! + * Even worse, you can desync the bot itself if you swallow NICK, JOIN + PART, KICK or possibly others. Or make it ping out by swallowing PING. + Parameters: + $1 = The raw line + Return status: + 0 = pass it on to next module + 1 = I have taken care of this, and don't + consult other modules about this. + For raw this means no normal hooks + will be called on the line either. diff --git a/doc/seen.sql b/doc/seen.sql new file mode 100644 index 0000000..f10e5d0 --- /dev/null +++ b/doc/seen.sql @@ -0,0 +1,15 @@ +/* + * This is how to create a factoid database + * Use this file like this: + * sqlite3 -batch data/envbot.db < doc/seen.sql + * + * If you use another table name, change below in + * both places + */ +DROP TABLE IF EXISTS seen; +CREATE TABLE seen ( + nick TEXT UNIQUE NOT NULL PRIMARY KEY, + channel TEXT NOT NULL, + timestamp TEXT NOT NULL, + message TEXT NOT NULL +); diff --git a/doc/transports_api.txt b/doc/transports_api.txt new file mode 100644 index 0000000..881ae58 --- /dev/null +++ b/doc/transports_api.txt @@ -0,0 +1,101 @@ +Transport modules +================= + +Transport modules is a feature that allows different ways to connect to the server. +They may support different systems and/or different features. + + +File descriptors +================ +If a module need to use a file descriptor it should use FD 3 and 4. +If more than two are needed, the module can try higher but that may be used +for other things in the future. + + +Configuration +============= +Additional configuration variables for a module should follow this naming scheme: +config_transport_transportname_variablename +Example: +config_transport_stunnel_path + + +Variables +========= +The module defines a variable called $transport_supports +It is a space separated list of supported features. Current ones: + * ipv4 - Supports IPv4 + * ipv6 - Supports IPv6 + * nossl - Supports making non-SSL connections + * ssl - Supports SSL + * bind - Supports using a specific IP when connecting +This variable only needs to be set after transport_check_support has run + + +Functions +========= +The function names below should not be unique for the module like with +normal modules. You can only use one transport module at a time. + + +transport_check_support() + Check if all the stuff needed to use this transport is available + on this system. + Return status: + 0 = Yes + 1 = No + + +transport_connect() + Try to connect + Return status: + 0 = Connection successful + 1 = Connection failed + Parameters: + $1 = Hostname/IP + $2 = Port + $3 = If 1 use SSL. If the module does not support it, just ignore it. + $3 = IP to bind to if any and if supported + If the module does not support it, just ignore it. + + +transport_disconnect() + Called to close connection + Parameters: + None + Return status: + Not checked. + Notes: + The module must handle this getting called even when not connected or when + partly connected (it should clean up any program the module is running in + the background on a ping time out for example). + + +transport_alive() + Called to check if connection is still alive. + Return status + 0 If connection is still alive. + 1 If it isn't alive. + Notes: + This function should be low overhead, it gets called quite often. + + + +transport_read_line() + Return a line in the variable $line. + Return status: + 0 = Success + 1 = Connection has failed (timeout or whatever) + Notes: + The transport module should remove any trailing \r and/or \n (CR and/or LF) + from the string before it returns it. + + +transport_write_line() + Send a line + Parameters: + $* = send this + Return status: + Not checked. + Notes: + The transport module should add a \n (LF) to the end of the data it get. -- cgit v1.2.3-54-g00ecf