diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 252 |
1 files changed, 252 insertions, 0 deletions
@@ -0,0 +1,252 @@ +sirc - simple irc +================= + +A simple multi-server terminal IRC client written in C. Single source file, no runtime +dependencies beyond ncurses, OpenSSL, and pthreads. + + +LAYOUT +------ + ++------------------+--------------------------------------------------+----------------+ +| CHANNELS | Don't paste spam. Use a pastebin. Be excellent. | USERS (42) | +| +--------------------------------------------------+ | +| irc.libera.chat | 12:34 -> alice joined | @ChanServ | +| *status* | 12:34 <kky> hello everyone | @alice | +| > #python | 12:34 <alice> hey! | +bob | +| + #linux | | charlie | +| | | | +| irc.oftc.net | | | +| *status* | | | +| #debian | > _ | | ++------------------+--------------------------------------------------+----------------+ + +Header bar -- topic of the active channel. Blank if no topic is set. + Starts from the left, truncated on the right if too long. + +Channel list -- grouped by server hostname. A ~ prefix on the server name + means disconnected. Channel indicators: + > active channel + + unread messages + ! unread mention of your nick + *status* appears under each server for system/server messages. + Reachable via Ctrl+N/P like any other buffer. + +Chat area -- colour scheme: + <nick> per-nick hashed colour (bold) + message body plain white + own messages yellow bold + mentions red bold + actions (/me) magenta italic + join/part gray + URLs blue underline + IRC formatting codes (^B bold, ^C colour, etc.) are stripped + before display. + +User list -- sorted by privilege then alphabetically within each group: + ~ founder/owner (red bold) + & protected op (red bold) + @ op (red bold) + % halfop (yellow bold) + + voice (yellow bold) + regular (white) + +Input -- prompt shows "> " with a blinking cursor as you type. + + +BUILD +----- + +Dependencies: + + Library Arch Debian/Ubuntu + ------- ---- ------------- + ncurses ncurses libncurses-dev + OpenSSL openssl libssl-dev + pthreads (glibc) (glibc) + +Build: + + make + +Install to ~/.local/bin/irc: + + make install + +System-wide: + + PREFIX=/usr/local make install + + +USAGE +----- + + ./irc [options] + +CLI options configure a single server. For multiple servers use a config file. + + --host HOST server hostname (default: irc.libera.chat) + --port PORT server port (default: 6697) + --nick NICK nickname (default: circ_user) + --channel CHAN channel(s) to join, comma-separated + --tls enable TLS (default: on) + --no-tls disable TLS (plain, typically port 6667) + --sasl-user USER SASL username + --sasl-pass PASS SASL password + --config FILE path to config file + +Examples: + + # TLS with SASL + ./irc --host irc.libera.chat --nick kky --sasl-user kky --sasl-pass hunter2 + + # Plain text + ./irc --host irc.libera.chat --port 6667 --no-tls --nick kky + + # Join multiple channels + ./irc --host irc.libera.chat --nick kky --channel '#python,#linux' + + +CONFIG FILE +----------- + +Loaded from ~/.sirc or ~/.config/sirc/config (first found wins). +CLI flags override the first server in the config. + +Use [server] blocks for multiple servers. Each block is an independent +connection with its own nick, channels, and credentials. All servers +connect simultaneously on startup. + + # Global defaults (before any [server] block) + nick = kky + ignore = badbot,spammer + + [server] + host = irc.libera.chat + port = 6697 + tls = true + channel = #python,#linux + sasl_user = kky + sasl_pass = hunter2 + + [server] + host = irc.oftc.net + port = 6697 + tls = true + channel = #debian,#tor + + [server] + host = irc.rizon.net + port = 6667 + tls = false + nick = kky_rizon + channel = #rice + +Per [server] keys: + + host server hostname + port port number + nick nickname for this server + channel comma-separated channels to auto-join + tls true / false + sasl_user SASL PLAIN username + sasl_pass SASL PLAIN password + +Global keys (before any [server] block): + + nick default nick inherited by all servers + ignore comma-separated nicks to ignore globally + + +COMMANDS +-------- + +All commands act on the current server (server of the active channel). + +Messaging: + /msg <nick> <text> open a private message window + /notice <target> <text> send a NOTICE + /me <text> CTCP ACTION (* nick text) + /ctcp <nick> <cmd> send a raw CTCP request + +Channels: + /join [#chan] join a channel + /part [#chan] leave a channel (defaults to current) + /cycle [#chan] part and immediately rejoin + /names [#chan] list users in a channel + /topic [text] get the current topic, or set a new one + /invite <nick> [#chan] invite someone to a channel + /kick <nick> [reason] kick a user from the current channel + /mode [target] [modes] get or set channel/user modes + +Users: + /nick show your current nickname + /nick <n> change your nickname + /whois <nick> full whois lookup + /who [target] WHO query on a channel or nick + /away [message] set an away message + /back clear away status + /ignore [nick] ignore a nick (no arg = list ignored nicks) + /unignore <nick> stop ignoring a nick + +Server: + /list [pattern] list channels on the current server + /raw <line> send a raw IRC line (alias: /quote) + /server <host> [port] connect to an additional server at runtime + /connect reconnect the current server + /quit [message] disconnect all servers and exit + +UI: + /clear clear the current channel's scrollback + /help show command reference in *status* + + +KEYS +---- + + Tab nick completion -- cycle through matches + colon suffix (nick: ) added at start of line + Ctrl+N next channel + Ctrl+P previous channel + PgUp scroll chat up + PgDn scroll chat down + Ctrl+W delete word left + Up / Down step through input history + Left / Right move cursor + Home / End jump to start/end of input + Delete delete character under cursor + + +FEATURES +-------- + + - Multiple simultaneous servers, each with its own thread, nick, channels + - TLS via OpenSSL with certificate verification (SSL_VERIFY_PEER) + - SASL PLAIN authentication per server, before registration + - Auto-reconnect with 5-second backoff, rejoins all open channels + - Per-nick colours: djb2 hash -> 8 colours, consistent in chat and user list + - IRC formatting stripped: bold, colour, italic, underline, reset, etc. + - Topic shown in header bar, updated live on TOPIC messages + - URLs (http://, https://, www.) rendered with blue underline + - Nick tab-completion with cycling + - Ring buffer scrollback: 500 lines per channel, O(1) insert + - Global ignore list, loadable from config + + +LIMITS +------ + + Max servers 8 + Max channels (total) 128 + Users per channel 512 + Scrollback per channel 500 lines + Input line length 480 chars + Input history 256 lines + Ignore list 64 nicks + Auto-join channels/server 16 + + +LICENSE +------- + +MIT |