diff --git a/README.md b/README.md index a68983eb..ce7050e1 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,46 @@ GLIRC - Advanced Console IRC Client ============= -* **glirc** [![Hackage](https://img.shields.io/hackage/v/glirc.svg)](https://hackage.haskell.org/package/glirc) [![Build Status](https://secure.travis-ci.org/glguy/irc-core.svg)](http://travis-ci.org/glguy/irc-core) + + Packaging status + + +* **glirc** [![Hackage](https://img.shields.io/hackage/v/glirc.svg)](https://hackage.haskell.org/package/glirc) * **irc-core** [![Hackage](https://img.shields.io/hackage/v/irc-core.svg)](https://hackage.haskell.org/package/irc-core) * **hookup** [![Hackage](https://img.shields.io/hackage/v/hookup.svg)](https://hackage.haskell.org/package/hookup) -[Wiki Documentation](https://github.com/glguy/irc-core/wiki) +Client Features +--------------- + +* Support for [a wide variety of IRCv3 capabilities](https://ircv3.net/software/clients#desktop-clients). +* Joins, parts, and quits fold into one line to save space without sacrificing context. +Detailed view (F2) shows additional info, such as part/quit messages. +* Ignore support that folds ignored messages into the joins and parts. Detailed view shows the messages. +* Searchable channel list, who and names list, and list modes (beqI) views separate from chat messages. +* Dynamic, in-place message and list view searching using `/grep`. +* View and open long URLs with `/url`. +* Context-sensitive tab completion and command hints. +* WYSIWYG mIRC formatting input. +* Multi-line editing; Enter sends one line at a time. +* Atheme-flavored-ChanServ integration. +* Nicknames in chat messages are colored to match messages from that nickname. +* Correct handling of [STATUSMSG](https://modern.ircdocs.horse/#statusmsg-parameter), including CTCP ACTIONs. +* Command macros. +* Support for a wide variety of SASL authentication mechanisms, including `ECDSA-NIST256P-CHALLENGE`. +* Split-screen view. +* Configurable color palette. +* Desktop notifications on important messages while unfocused. Can run arbitrary commands instead (or turn them off). +* Extensions, a Lua plugin system, and trivial piping of IRC messages to arbitrary commands with `/exec`. +* Plenty more, but this list is getting a bit long. ![](https://raw.githubusercontent.com/wiki/glguy/irc-core/images/screenshot.png) Building ======== -glirc uses recent versions of packages, make sure you package databases are +[![Build Status](https://github.com/glguy/irc-core/actions/workflows/haskell-ci.yml/badge.svg)](https://github.com/glguy/irc-core/actions/workflows/haskell-ci.yml) + +glirc uses recent versions of packages, make sure your package databases are up-to-date: ``` @@ -32,37 +60,17 @@ $ cabal install --dep $ cabal build ``` -Client Features -=============== - -* All views and transformation are dynamic and don't change the underlying model. -* Subsequent joins and parts fold into one line and do not scroll chat messages off the screen -* Ignore support that folds ignored messages into the joins and parts. Toggle it off to see previously hidden messages -* Detailed view to see all the messages in a channel in full detail with hostmask and timestamp (F2) -* Context sensitive tab completion -* Searchable ban, quiet, invex, and exception view separate from chat messages -* Searchable user list, detailed view shows full hostmasks -* WYSIWYG mIRC formatting input -* Multi-line editing -* Dynamic, in-place message searching -* Chanserv integration -* Nicknames in chat messages are colored to match messages from that nickname -* Support for /STATUSMSG/ messages (messages only voice or op users can see) -* Run commands upon connection -* Command macros -* CERTFP and SASL authentication -* Split-screen view -* Configurable color palette - Startup ======= ``` glirc [FLAGS] INITIAL_NETWORKS... - -c PATH --config=PATH Configuration file path - -! --noconnect Disable autoconnecting - -h --help Show help - -v --version Show version + -c PATH --config=PATH Configuration file path + -! --noconnect Disable autoconnecting + -h --help Show help + --config-format Show configuration file format + -v --version Show version + --full-version Show version and versions of all linked Haskell libraries ``` Environment variables @@ -74,52 +82,50 @@ IRCPASSWORD= Configuration file ================= -A configuration file can currently be used to provide some default values instead of -using command line arguments. If any value is missing the default will be used. - -The default configuration file path is `~/.config/glirc/config` +Most of glirc's settings are specified using a configuration file. +The file format is [config-value](http://hackage.haskell.org/package/config-value), +an indentation-sensitive format that resembles YAML. +It has macros which are documented +[here](https://hackage.haskell.org/package/config-value/docs/Config-Macro.html). +The default configuration file path is `~/.config/glirc/config`. Relative paths are relative to the home directory. -Learn more about this file format at [config-value](http://hackage.haskell.org/package/config-value) +To view the full list of configuration variables, +run `glirc --config-format | less`. +If any variable is unspecified, a default value will be used instead. ``` -- vim: filetype=config-value -- Grab the Vim syntax highlighting file from the config-value package --- Learn more about these settings with `glirc --config-format` - -- Defaults used when not specified on command line defaults: nick: "yournick" username: "yourusername" realname: "Your real name" - password: "IRC server password" tls: yes -- or: no, or: starttls -- enabling tls automatically uses port 6697 - tls-verify: yes -- or: no -- Override the defaults when connecting to specific servers servers: * name: "libera" - hostname: "irc.libera.chat" + hostname: "irc.libera.chat" sasl: username: "someuser" password: "somepass" - socks-host: "socks5.example.com" - socks-port: 8080 -- defaults to 1080 - log-dir: "/home/myuser/ircLogs" - - * name: "example" - hostname: "example.com" - port: 7000 -- override the default port + log-dir: "/home/myuser/ircLogs" connect-cmds: - * "join #favoritechannel,#otherchannel" - * "msg mybot another command" + * "join #glirc,#someotherchannel" - -- Specify additional certificates beyond the system CAs - -- relative to home directory - tls-server-cert: "extra/certificate.pem" + * name: "znc" + hostname: "znc.example.com" + port: 7000 -- Override the default port + password: "IRC server password" + tls-verify: no + message-hooks: ["buffextras"] -- Use this when using ZNC's "buffextra" module to get correct playback + flood-penalty: -1 -- Disable flood controls + flood-threshold: -1 macros: * name: "wipe" @@ -129,20 +135,20 @@ macros: * name: "mysplits" commands: - * "splits fn:#haskell fn:#haskell-offtopic" + * "splits libera:#haskell libera:#haskell-offtopic" -- Example use of macro in combination with an extension * name: "extra" commands: - * "extension Lua some-parameter $network $channel" + * "extension Lua somecommand $network $channel" -extra-highlights: ["glirc", "lens"] +extra-highlights: ["glirc", "hello"] nick-padding: - side: left -- try right if you don't like left padding + side: left -- Try "right" if you don't like left padding width: 13 -url-opener: "open" -- This works on macOS, "xdg-open" for most Linuxes +url-opener: "open" -- This works on macOS; use "xdg-open" for most Linuxes key-bindings: * bind: "C-M-b" @@ -153,7 +159,7 @@ palette: time: fg: [10,10,10] -- RGB values for color for timestamps bg: blue - nick-colors: + identifier-colors: -- Used for nicknames and channel names [ cyan, magenta, green, yellow, blue , bright-cyan, bright-magenta, bright-green, bright-blue , 218, 88, 89, 124, 160, 205, 212, 224 -- reds @@ -163,206 +169,72 @@ palette: , 25, 27, 33, 39, 51, 80, 81, 75 -- blues , 69, 61, 56, 54, 129, 93, 99, 147 -- purples ] -``` - -Configuration sections: --------- - -| setting | type | description | -|------------------------|---------------------|--------------------------------------------------------------------------------------------| -| `defaults` | server | These settings are used for all connections | -| `servers` | list of servers | These settings are used to override defaults when the hostname matches | -| `palette` | palette | Client color overrides | -| `window-names` | text | Names of windows (typically overridden on non QWERTY layouts) | -| `nick-padding` | nonnegative integer | Nicks are padded until they have the specified length | -| `indent-wrapped-lines` | nonnegative integer | How far to indent lines when they are wrapped | -| `extra-highlights` | list of text | Extra words/nicks to highlight | -| `extensions` | list of text | Filenames of extension to load | -| `url-opener` | text | Command to execute with URL parameter for `/url` e.g. xdg-open on most Linuxes or open on macOS | -| `ignores` | list of text | Initial list of nicknames to ignore | -| `activity-bar` | yes or no | Initial setting for visibility of activity bar (default no) | -| `bell-on-mention` | yes or no | Sound terminal bell on transition from not mentioned to mentioned (default no) | -| `macros` | list of macros | User-configurable client commands | - -Server Settings ---------------- - -| setting | type | description | -|-----------------------|----------------------|----------------------------------------------------------------| -| `name` | text | name of server entry, defaults to `hostname` | -| `hostname` | text | hostname used to connect and to specify the server | -| `port` | number | port number, defaults to 6667 without TLS and 6697 with TLS | -| `nick` | text or list of text | nicknames to try in order | -| `username` | text | server username | -| `realname` | text | real name / GECOS | -| `password` | text | server password | -| `sasl` | sasl-settings | SASL authentication settings | -| `tls` | yes/no/starttls | use TLS to connect | -| `tls-verify` | yes/no | enable/ disable TLS certificate checks | -| `tls-client-cert` | text | path to TLS client certificate | -| `tls-client-key` | text | path to TLS client key | -| `tls-server-cert` | text | CA certificate to use when validating certificates | -| `tls-ciphers` | text | OpenSSL cipher suite description string | -| `connect-cmds` | list of text | client commands to send upon connection | -| `socks-host` | text | hostname of SOCKS proxy to connect through | -| `socks-port` | number | port number of SOCKS proxy to connect through | -| `chanserv-channels` | list of text | list of channels with chanserv op permission | -| `flood-penalty` | number | cost in seconds per message | -| `flood-threshold` | number | threshold in seconds for burst | -| `message-hooks` | list of text | names of hooks to enable | -| `reconnect-attempts` | int | number of reconnections to attempt on error | -| `autoconnect` | yes or no | automatically connect at client startup | -| `nick-completion` | default or slack | set this to slack to use `@` sigils when completing nicks | - -SASL Settings -------------- - -By default SASL will use PLAIN mode, but you can specify one of: `plain`, `external`, or `ecdsa-nist256p-challenge`. - -| setting | type | description | -|-----------------------|----------------------|----------------------------------------------------------------| -| `mechanism` | optional mechanism | SASL mechanism (defaults to PLAIN) | -| `username` | text | SASL username (PLAIN and ECDSA-NIST256P-CHALLENGE mode) | -| `password` | text | SASL password (PLAIN mode) | -| `private-key` | text | Path to ECDSA private key file (ECDSA-NIST256P-CHALLENGE mode) | -| `authzid` | text | Authorization identity (very rarely needed) | - -Palette -------- - -| entry | type | description | -|-----------------------|--------------|------------------------------------------| -| `nick-colors` | list of attr | Use for nick highlights | -| `self` | attr | our own nickname(s) outside of mentions | -| `self-highlight` | attr | our own nickname(s) in mentions | -| `time` | attr | timestamp on messages | -| `meta` | attr | metadata (joins/parts/etc.) | -| `sigil` | attr | sigils (+@) | -| `label` | attr | information labels | -| `latency` | attr | latency time | -| `error` | attr | error messages | -| `textbox` | attr | textbox edges (^$) | -| `window-name` | attr | current window name | -| `activity` | attr | activity notification | -| `mention` | attr | mention notification | -| `command` | attr | recognized command | -| `command-prefix` | attr | prefix of known command | -| `command-ready` | attr | recognized command with arguments filled | -| `command-placeholder` | attr | command argument placeholder | -| `window-divider` | attr | the dividing line between split windows | -| `line-marker` | attr | the dividing line for new messages | - -Text Attributes ---------------- - -Text attributes can be specified either as a single foreground color or section of attributes. - -* `` - Maps to a terminal color -* `` - Direct selection of standard 16 terminal colors -* `[red-number, blue-number, green-number]` - List of 3 numbers in range 0-255 map to an approximation of the RGB color. - -Attributes -* `fg` - foreground color -* `bg` - background color -* `style` - single style or list of styles - -Styles - -* `blink` -* `bold` -* `dim` -* `standout` -* `reverse-video` -* `underline` +notifications: terminal-notifier -- Use terminal-notifier for nicer notifications (macOS only) +``` Commands ======== -Client commands +glirc has built-in documentation for all of its commands. +To view the full list of commands and what they do, use `/help`. +To view help on a specific command, use `/help `. + +Unlike some other clients, glirc does not send unknown commands to the server. +Use `/quote` to send arbitrary IRC commands. + +The following is a curated list of commands for basic use: * `/help [command]` - Show in-client help * `/exit` - Terminate the client -* `/quit` - Gracefully terminate connection to the current server -* `/connect ` - Connect to the given server -* `/disconnect` - Forcefully terminate connection to the current server -* `/reconnect` - Reconnect to the current server * `/reload [path]` - Load a new configuration file (optional path) * `/palette` - Show the client palette -* `/digraphs` - Show the table of digraphs -* `/mentions` - Show all the highlighted lines across all windows -* `/extension ` - Send the given params to the named extension -* `/exec [-n network] [-c channel] ` - Execute a command, If no network or channel are provided send output to client window, if network and channel are provided send output as messages, if network is provided send output as raw IRC messages. * `/url [n]` - Execute url-opener on the nth URL in the current window (defaults to first) - -View toggles -* `/toggle-detail` - toggle full detail view of messages * `/toggle-activity-bar` - toggle channel names in activity bar -* `/toggle-metadata` - toggle visibility of channel metadata -* `/toggle-layout` - toggle split-screen layout between 1 and 2 column view +* `/toggle-detail` - toggle full detail view of messages +* `/toggle-metadata` - toggle visibility of channel metadata (joins, parts, quits, nick changes, etc) -Connection commands +Connection +* `/connect ` - Connect to the given server +* `/quit [message]` - Gracefully terminate connection to the current server +* `/reconnect` - Reconnect to the current server * `/nick ` - Change nickname -* `/away ` - Set away status +* `/away [message]` - Set away status; no message removes away status Window management * `/windows [filter]` - List all open windows (filters: networks, channels, users) -* `/focus ` - Change focus to server window -* `/focus ` - Change focus to channel window +* `/setname [letter]` - Assign a one-letter name to the given window. +* `/channel ` - Change focus to channel/user on current network (alias: `/c`) +* `/channel :[channel]` - Change focus to channel/user on the specified network (alias: `/c`) * `/clear [network] [channel]` - Clear contents of current or specified window -* `/ignore` - Show all ignore masks -* `/ignore ...` - Toggle ignore status on a list of masks -* `/channel ` - Change focus to channel on current network (alias: `/c`) * `/splits [focuses...]` - Enable split-screen view. Focuses should be space delimited list of NETWORK:CHANNEL * `/splits+ [focuses...]` - Incremental addition to splits * `/splits- [focuses...]` - Incremental removal from splits - -Channel membership - -* `/join ` - Join a channel (alias: `/j`) -* `/part` - Part from current channel +* `/toggle-layout` - toggle split-screen layout between 1 and 2 column view Chat commands -* `/query []` - Switch focus to target window on current server, optionally send message +* `/join ` - Join a channel (alias: `/j`) +* `/part [msg]` - Part from current channel +* `/query [msg]` - Switch focus to target window on current server, optionally send message (alias: `/q`) * `/msg ` - Send a message on the current server to target -* `/notice ` - Send a notice message on the current server to target -* `/ctcp ` - Send a ctcp command on the current server to target * `/me ` - Send action message to channel -* `/say ` - Send normal message to channel - -Channel management - -* `/mode ` - Change modes on the current channel (advanced tab completion) -* `/kick ` - Kick a user -* `/kickban ` - Kick and ban a user -* `/remove` - Gracefully kick a user -* `/topic ` - Change the topic (tab completion for topic) -* `/invite ` - Invite a user to the current channel - -Queries - -* `/who ` - Perform WHO query (use detailed view to see output) -* `/whois ` - Perform WHOIS query -* `/whowas ` - Perform WHOWAS query -* `/ison ` - Perform ISON query -* `/userhost ` - Perform USERHOST query -* `/links ` - Perform LINKS query -* `/time` - Perform TIME query -* `/stats ` - Perform STATS query +* `/say ` - Send normal message to channel; useful for macros and messages starting with a slash +* `/ignore ...` - Toggle ignore status on a list of masks +* `/topic [msg]` - Display or set the current topic of a channel -Channel information +Views -* `/users` - Show channel user list -* `/masks ` - Show channel bans(b), quiets(q), exempts(e), or invex(I) * `/channelinfo` - Show channel topic, creation, url - -Window filters - -* `/grep` - Filter chat messages using a regular expression -* `/grepi` - Filter chat messages using a case-insensitive regular expression on the message +* `/grep [flags] ` - Filter using a regular expression +* `/ignore` - Show all ignore masks +* `/list` - View the list of public channels on the network +* `/masks ` - Show channel bans(b), quiets(q), exempts(e), or invex(I) +* `/mentions` - Show all the highlighted lines across all windows +* `/names` - Show the user list for the current channel +* `/who [channel] [options]` - Perform WHO query, sending options to the server, or show the results of the previous query. ZNC-specific @@ -371,8 +243,11 @@ ZNC-specific * `/znc-playback