diff -uNr a/yrc/README.txt b/yrc/README.txt --- a/yrc/README.txt a0925ad7a545437d5c9b7266d1732e3b48b9d46012b7d6315526c338d9df3778a674ec8a707306c6f76e93dfb92a6daa52075ec5d5df8772215934b03ce1666f +++ b/yrc/README.txt 53eb115d088c4523c4a703fa8c1e24cea81a0c9a96e14b8cab9e998a0dd0665953b2d4417ebcd6b98d092d9f8154d36cf5d4525aa8fb531141e70166d0b8e43f @@ -2,65 +2,65 @@ INSTALLATION - The dependencies of yrc are Python 2.6 or 2.7 (on a POSIX system) and VT100-style terminal. Python 2.5 may work as well but is presently untested. +The dependencies of yrc are Python 2.6 or 2.7 (on a POSIX system) and VT100-style terminal. Python 2.5 may work as well but is presently untested. - It can be run directly from the source tree: +It can be run directly from the source tree: - chmod +x yrc - ./yrc + chmod +x yrc + ./yrc - To install the Python modules and script to the system paths, run as root: +To install the Python modules and script to the system paths, run as root: - python2 setup.py install + python2 setup.py install QUICKSTART - At this point you are expected to read manual.txt, but here's a quick exercise: +At this point you are expected to read manual.txt, but here's a quick exercise: - 1. Configure a network and a default nick: +1. Configure a network and a default nick: - mkdir -p ~/.yrc/nets/freenode - echo chat.freenode.net > ~/.yrc/nets/freenode/addrs - whoami > ~/.yrc/nick + mkdir -p ~/.yrc/nets/freenode + echo chat.freenode.net > ~/.yrc/nets/freenode/addrs + whoami > ~/.yrc/nick - 2. Start yrc: +2. Start yrc: - yrc + yrc - 3. Connect to the configured network: +3. Connect to the configured network: - /connect freenode + /connect freenode - 4. Switch to the network's server messages window by typing Ctrl-x n. +4. Switch to the network's server messages window by typing Ctrl-x n. - 5. If your chosen nick is unavailable, you can change it temporarily: +5. If your chosen nick is unavailable, you can change it temporarily: - /nick your_nick_ + /nick your_nick_ - 6. Once your connection is registered (shows an = sign in the window list), you can join a channel: +6. Once your connection is registered (shows an = sign in the window list), you can join a channel: - /join #some-test-chan + /join #some-test-chan - 7. Try another way to switch windows: Ctrl-x w. This selects the window list; use j/k or Ctrl-n/Ctrl-p to navigate and Return to apply. +7. Try another way to switch windows: Ctrl-x w. This selects the window list; use j/k or Ctrl-n/Ctrl-p to navigate and Return to apply. - 8. Shut down with a parting message: +8. Shut down with a parting message: - /quit bye for now + /quit bye for now - 9. yrc does not advertise e.g. through your IRC name or part messages, so go tell a friend or three if you like it! +9. yrc does not advertise e.g. through your IRC name or part messages, so go tell a friend or three if you like it! BUGS - 1. When nick in use, connection gets stuck at unregistered even after /nick. (Workaround: /disconnect and change nick in /connect arguments or config.) +1. When nick in use, connection gets stuck at unregistered even after /nick. (Workaround: /disconnect and change nick in /connect arguments or config.) - 2. part/kick/disconnect doesn't clear topic from window title, causing subsequent rejoin to retain the old topic if it was meanwhile removed. +2. part/kick/disconnect doesn't clear topic from window title, causing subsequent rejoin to retain the old topic if it was meanwhile removed. - A frequent source of bugs during development was screen updates -- ensuring UI elements are redrawn when their underlying data sources change. This situation resulted from a conversion from a previous approach of "when in doubt, redraw everything and let ncurses compute the differences", and could doubtless be handled better. For now, these are easily fixed once identified (e.g. something updates only after pressing Ctrl-L). +A frequent source of bugs during development was screen updates -- ensuring UI elements are redrawn when their underlying data sources change. This situation resulted from a conversion from a previous approach of "when in doubt, redraw everything and let ncurses compute the differences", and could doubtless be handled better. For now, these are easily fixed once identified (e.g. something updates only after pressing Ctrl-L). - yrc does not go out of its way to accomodate non-standard server behavior (for example, alternate casemappings). This is not a bug, but simple compatibility workarounds can be considered if the problem server is widely used. +yrc does not go out of its way to accomodate non-standard server behavior (for example, alternate casemappings). This is not a bug, but simple compatibility workarounds can be considered if the problem server is widely used. - See the roadmap section in the manual for planned features. +See the roadmap section in the manual for planned features. HACKING - The codemap.txt file serves as a kind of index of function signatures and data structures (as there are many), and should be kept reasonably up to date. It also contains some sketchier notes-to-self. +The codemap.txt file serves as a kind of index of function signatures and data structures (as there are many), and should be kept reasonably up to date. It also contains some sketchier notes-to-self. diff -uNr a/yrc/manifest b/yrc/manifest --- a/yrc/manifest 5d217f47cc4ceb39949a9e746040db7faa78ba277bd61fe2a2695f3b05822363483866e46bc9e73836f942fd18f349ff3420d7ad0d752d4c70735604bb1d0851 +++ b/yrc/manifest a6d6ef544b68b096039990e51d0e492fc2a6e2de387d32331cdf0408a22c741b5466166b3ccb48601e921546fe1c1111f7e69dd89ffc369d868d8bcbad20b13a @@ -7,3 +7,4 @@ 768776 yrc_prompt_redraw_optimization jfw Optimize and clarify prompt drawing code; remove unneeded prompt_set_hscroll for consistency (this turned out to be needed after all; see an upcoming patch for fix and explanation). 768777 yrc_minor_command_reorder_2 jfw Reverse presentation order of back/forward prompt commands for consistency; also comment on possibly confusing differences between ctrl/meta functions. 768777 yrc_word_level_commands jfw Implement word-level motions and kills. A new global flag is needed for state tracking to coalesce multiple sequential kills into one. kill_start and kill_end are rebased on a common kill_range routine which also supports the new word-level variants. +768778 yrc_reindent_docs jfw Reindent spaces to tabs in documentation. (In README.txt, indentation levels are reduced across the board.) diff -uNr a/yrc/manual.txt b/yrc/manual.txt --- a/yrc/manual.txt 9872a8ecfe57d6523b0c0a03a8c558f9c2f5b1a89360acd85bdda21c5f4f6f8ee828bba75714dd00c40bd68be859664c8d24762a8877dc58c64b37e1071e5443 +++ b/yrc/manual.txt cef4dbb225fda495761caa82f7d7fbab8afd9af88e1dea0f59814b056780386bedea490eaeff8dc8b1733a54bba6c7873667d58e4efe2a76160bf36538974f77 @@ -4,22 +4,22 @@ Jacob Welsh Table of Contents - 1 About yrc - 2 Display - 3 Commands - 3.1 Slash commands - 3.2 Keyboard commands - 3.2.1 Anywhere - 3.2.2 In the window list - 3.2.3 At the prompt - 3.2.4 In the scrollback window - 4 Configuration - 4.1 Keys - 4.2 Logging - 4.3 Example - 5 Roadmap - 6 News and contact - Footnotes + 1 About yrc + 2 Display + 3 Commands + 3.1 Slash commands + 3.2 Keyboard commands + 3.2.1 Anywhere + 3.2.2 In the window list + 3.2.3 At the prompt + 3.2.4 In the scrollback window + 4 Configuration + 4.1 Keys + 4.2 Logging + 4.3 Example + 5 Roadmap + 6 News and contact + Footnotes 1. About yrc @@ -29,37 +29,37 @@ For yrc to achieve its goals, the following decisions were made: - 1. High-level language implementation. In a network-exposed, not performance-critical application, there's just no excuse for the possibility of invoking Undefined Behavior and the ensuing vulnerabilities. + 1. High-level language implementation. In a network-exposed, not performance-critical application, there's just no excuse for the possibility of invoking Undefined Behavior and the ensuing vulnerabilities. - 2. Simple configuration mechanism employing the filesystem as a hierarchical key-value database; no structured format to parse. [1] + 2. Simple configuration mechanism employing the filesystem as a hierarchical key-value database; no structured format to parse. [1] - 3. Support exclusively VT100-compatible terminals on Unix-like systems. + 3. Support exclusively VT100-compatible terminals on Unix-like systems. - 4. No dependencies besides POSIX. [2] + 4. No dependencies besides POSIX. [2] - 5. No superfluous features such as mIRC colors, DCC or CTCP. [3] + 5. No superfluous features such as mIRC colors, DCC or CTCP. [3] - 6. No Unicode or any other flavor of hieroglyphs. Control and 8-bit characters in any IRC string are sanitized on display, both to protect the terminal and show the operator exactly what he is receiving. [4] + 6. No Unicode or any other flavor of hieroglyphs. Control and 8-bit characters in any IRC string are sanitized on display, both to protect the terminal and show the operator exactly what he is receiving. [4] - 7. No SSL/TLS/TLS_1.3/whatever-they're-calling-it-today. [5] + 7. No SSL/TLS/TLS_1.3/whatever-they're-calling-it-today. [5] It does support several niceties: - 1. Multiple message windows (separated channels/conversations) + 1. Multiple message windows (separated channels/conversations) - 2. Maintenance of connections to multiple networks, defined either by configuration or on the fly + 2. Maintenance of connections to multiple networks, defined either by configuration or on the fly - 3. Round-robin server balancing independent of DNS + 3. Round-robin server balancing independent of DNS - 4. Unlimited scrollback [6] + 4. Unlimited scrollback [6] - 5. Basic authentication (the PASS command) + 5. Basic authentication (the PASS command) - 6. Sending raw commands to the IRC server for unsupported features + 6. Sending raw commands to the IRC server for unsupported features - 7. Communication of internal state to the operator: unread messages, connection state + 7. Communication of internal state to the operator: unread messages, connection state - 8. Chat logging + 8. Chat logging It is written in Python 2.6 (though this is an implementation detail and subject to change). Some of its more reusable terminal interface code is included as a separate "yterm" module. The yrc+yterm code weighs in around 2390 raw lines, compressing to 19KB. @@ -69,25 +69,25 @@ The yrc display is designed to maximize information and context available on a single screen, because eyes move faster than fingers. It has five parts: - Title bar: shows a description of the current window, or the channel topic. + Title bar: shows a description of the current window, or the channel topic. - Window list: an index of open windows (see below). + Window list: an index of open windows (see below). - Scrollback window: shows message history for a particular channel or private conversation, or server messages for a network, or general messages. + Scrollback window: shows message history for a particular channel or private conversation, or server messages for a network, or general messages. - Status bar: typically, shows the current nickname, network, and message target. + Status bar: typically, shows the current nickname, network, and message target. - Prompt: messages and commands are typed here. + Prompt: messages and commands are typed here. The window list is kept in alphabetical order, grouped by network, after the general messages window "yrc". An asterisk (*) in the first column indicates the currently selected window and a hyphen (-) the previous. Unread messages are indicated by a +N after the window name, where N is the number unread. A network's connection state is indicated by a symbol in front of its name, as follows: - Blank: Not connected + Blank: Not connected - Tilde (~): Connection down: awaiting TCP handshake completion, or connection lost and waiting to reconnect + Tilde (~): Connection down: awaiting TCP handshake completion, or connection lost and waiting to reconnect - Hyphen (-): TCP connection established but not registered to the server + Hyphen (-): TCP connection established but not registered to the server - Equals (=): Fully registered; clear to send messages + Equals (=): Fully registered; clear to send messages 3. Commands @@ -97,79 +97,79 @@ 3.1. Slash commands - [c]onnect NETWORK [HOST[:PORT] [NICK [PASS]]] + [c]onnect NETWORK [HOST[:PORT] [NICK [PASS]]] Connect to NETWORK, either preconfigured or with the given parameters. - [d]isconnect [NETWORK] + [d]isconnect [NETWORK] Disconnect from NETWORK or the current network, or cancel a reconnection attempt. - [j]oin CHANNEL [KEY] + [j]oin CHANNEL [KEY] Join a channel on the current network. - [k]ick USER [MESSAGE] + [k]ick USER [MESSAGE] Kick a user from the current channel. - [l]ist [CHANNEL] + [l]ist [CHANNEL] Request a list of channels and topics, or the status of a given channel, on the current network. - me MESSAGE + me MESSAGE Send MESSAGE as a CTCP ACTION (rendered by many clients in an alternate style showing the nickname as the start of a sentence). - [m]ode MODE {[CHANNEL] | NICK [CHANNEL]} + [m]ode MODE {[CHANNEL] | NICK [CHANNEL]} [TODO; uncertain...] Set a mode on CHANNEL or the current channel, or a user mode on NICK in CHANNEL or the current channel. - msg {CHANNEL | NICK} [MESSAGE] + msg {CHANNEL | NICK} [MESSAGE] Switch to the window for CHANNEL or NICK on the current network, creating one if needed, and send the given MESSAGE, if any. (This does not join a channel; messages to an unjoined channel might be rejected by the server.) - [na]mes [CHANNEL] + [na]mes [CHANNEL] Request the list of names in the given channel, or all visible channels and users on the current network. - [n]ick NICK + [n]ick NICK Temporarily change nickname on the current network (persists across reconnections but not new connections). - [p]art [PART_MESSAGE] + [p]art [PART_MESSAGE] Leave the current channel, keeping its window open. - [q]uit [QUIT_MESSAGE] + [q]uit [QUIT_MESSAGE] Disconnect from all networks and quit yrc. - [s]end COMMAND + [s]end COMMAND Send a raw IRC command to the server for the current network. - [st] set-topic TOPIC + [st] set-topic TOPIC Set the topic for the current channel to TOPIC. - [t]opic [CHANNEL] + [t]opic [CHANNEL] Get the topic for the current channel or the given channel on the current network. - [w]hois NICK + [w]hois NICK Request information on a user on the current network. - [ww] whowas NICK + [ww] whowas NICK Request cached information for a disconnected user on the current network. - [x] close + [x] close Close the current window, parting with no message if it is a channel. - [xn] close-net (TODO) + [xn] close-net (TODO) Disconnect and close all windows for the current network. @@ -183,63 +183,63 @@ 3.2.1. Anywhere - C-x n: buflist-switch-next + C-x n: buflist-switch-next Switches to the next scrollback window in the list. - C-x p: buflist-switch-prev + C-x p: buflist-switch-prev Switches to the previous scrollback window in the list. - C-x l: buflist-last-selected + C-x l: buflist-last-selected Switches to the previously active scrollback window. - C-x w: buflist-enter + C-x w: buflist-enter Moves focus to the window list (see 3.2.2). - C-l: redraw + C-l: redraw Performs a full redraw of the screen, e.g. in case of corruption from the output of another program. 3.2.2. In the window list - C-n, j, Down: buflist-next + C-n, j, Down: buflist-next Moves the cursor to the next entry in the window list. - C-p, k, Up: buflist-prev + C-p, k, Up: buflist-prev Moves the cursor to the previous entry in the window list. - h, Left: buflist-shrink + h, Left: buflist-shrink Reduces window list width. - l, Right: buflist-grow + l, Right: buflist-grow Increases window list width. - M-<, g, Home: buflist-top + M-<, g, Home: buflist-top Moves the cursor to the top of the window list. - M->, G, End: buflist-bottom + M->, G, End: buflist-bottom Moves the cursor to the bottom of the window list. - Return (C-m): buflist-submit + Return (C-m): buflist-submit Activates the selected scrollback window and returns focus to where it was. 3.2.3. At the prompt - Return (C-m): prompt-submit + Return (C-m): prompt-submit Submits the message or command given at the prompt. - Ins: prompt-exit + Ins: prompt-exit Moves focus to the scrollback window (see 3.2.4). @@ -251,11 +251,11 @@ Moves the cursor forward by one character. - C-a, Home: prompt-start + C-a, Home: prompt-start Moves the cursor to the start of the line. - C-e, End: prompt-end + C-e, End: prompt-end Moves the cursor to the end of the line. @@ -275,11 +275,11 @@ Recalls a subsequent line from input history, discarding any unsubmitted edits to a previous line. - Backspace (C-h, C-?): prompt-backspace + Backspace (C-h, C-?): prompt-backspace Deletes backward by one character. - C-d, Del: prompt-delete + C-d, Del: prompt-delete Deletes forward by one character. @@ -307,13 +307,13 @@ Following a yank, replaces the just-inserted text with the next older entry in the kill ring. - C-v, PgDn: scroll-down-page - M-v, PgUp: scroll-up-page + C-v, PgDn: scroll-down-page + M-v, PgUp: scroll-up-page Scrolls the active scrollback window. - M-<: scroll-top - M->: scroll-bottom + M-<: scroll-top + M->: scroll-bottom Scrolls the active scrollback window to the top or bottom. @@ -321,22 +321,22 @@ If the window is scrolled to the bottom (the last available message is fully visible), it will autoscroll as new messages arrive. - i, Ins: prompt-enter + i, Ins: prompt-enter Moves focus to the prompt (see 3.2.3). - C-v, C-f, f, PgDn, Space: scroll-down-page - M-v, C-b, b, PgUp: scroll-up-page + C-v, C-f, f, PgDn, Space: scroll-down-page + M-v, C-b, b, PgUp: scroll-up-page Scrolls the window down or up by a page. - C-n, j, Down: scroll-down-line - C-p, k, Up: scroll-up-line + C-n, j, Down: scroll-down-line + C-p, k, Up: scroll-up-line Scrolls the window down or up by one wrapped line. - M-<, g, Home: scroll-top - M->, G, End: scroll-bottom + M-<, g, Home: scroll-top + M->, G, End: scroll-bottom Scrolls to the top or bottom. @@ -350,9 +350,9 @@ The following keys may be defined at top level (directly in the yrc home) or per network, with network level taking precedence. - addrs -- one or more server addresses (required) - nick -- initial IRC nickname (required) - pass -- plain-text password to send on connect + addrs -- one or more server addresses (required) + nick -- initial IRC nickname (required) + pass -- plain-text password to send on connect Addresses are specified one per line as either hostname or IPv4 address optionally followed by ":" and port number. Lines starting with the "#" character are ignored. Per common practice, the default port is 6667. On initial connection to a network, a server is selected at random; subsequent reconnections by the same process rotate sequentially through the list. @@ -364,10 +364,10 @@ The log format, designed for a degree of human and machine readability, is one message per line with the following single-space-delimited fields: - timestamp -- decimal integer, centiseconds since the epoch - type -- mostly matching the IRC protocol but with some variation; consult the "message" variant type in yrc.py for details - sender -- quoted in for aesthetics - content -- running to end of line + timestamp -- decimal integer, centiseconds since the epoch + type -- mostly matching the IRC protocol but with some variation; consult the "message" variant type in yrc.py for details + sender -- quoted in for aesthetics + content -- running to end of line Note that unlike in the UI, message content is not escaped; the only characters excluded by protocol are ASCII NUL, CR and LF. Thus printing a log directly to terminal (as opposed to using an editor or "less") can cause unexpected and possibly dangerous behavior. @@ -404,26 +404,26 @@ High-priority missing features: - - Tab completion (nicks, slash commands) - - Finish mode/op and close-net commands - - Scrolling in window list if it exceeds available screen rows - - More accurate derivation of message length limit to reduce overly-conservative wrapping + - Tab completion (nicks, slash commands) + - Finish mode/op and close-net commands + - Scrolling in window list if it exceeds available screen rows + - More accurate derivation of message length limit to reduce overly-conservative wrapping Nice to have: - - Indication of nick mentions (ring bell + bold the window name?) - - Formatting for displayed messages (e.g. bold sender, highlight own nick) - - Filtering of inbound PMs (/ignore or similar) - - More efficient navigation of window list - - Search in scrollback - - Nickname fallback - - Online /help command - - Auto-connect/join or scripting - - Parse WHOIS/WHOWAS/LIST responses - - Bracketed paste [meh, not all it's cracked up to be] - - Date change messages - - Channel join status indicators - - Finish config fields [?] + - Indication of nick mentions (ring bell + bold the window name?) + - Formatting for displayed messages (e.g. bold sender, highlight own nick) + - Filtering of inbound PMs (/ignore or similar) + - More efficient navigation of window list + - Search in scrollback + - Nickname fallback + - Online /help command + - Auto-connect/join or scripting + - Parse WHOIS/WHOWAS/LIST responses + - Bracketed paste [meh, not all it's cracked up to be] + - Date change messages + - Channel join status indicators + - Finish config fields [?] 6. News and contact