((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/readline" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg") (toc)) (section 2 "Readline" (p "An interface to the GNU readline library")) (section 2 "Interface" (section 3 "Toplevel Commands" (section 4 ",!!" (p "Evaluates the previous command.") (p "This command is never added to the history list, sorry: it broke the Matrix.") (p "(j/k It caused an infinite loop when entered twice in a row, so I just made it so that the previous command can never be " (tt ",!!") ").")) (section 4 ",h-clear" (p "Clears the current session's history list.")) (section 4 ",h-save" (p "Enable/disable saving session history on exit") (p "It is enabled by default.")) (section 4 ",h-rec" (p "Enable/disable recording history for the current session") (p "It's enabled by default.")) (section 4 ",h-load" (p "Read file contents into the history list for the current session.") (p "Currently, there might be a bug (I haven't checked) where the file's name has an extra space added to it unless you enter it on a separate line:") (pre ",h-load\n~/.csi_hist")) (section 4 ",vi-mode" (p "Sets the current editing mode to Vi.") (p "The equivalent function call would be:") (pre "(readline#parse-and-bind \"set editing-mode vi\")")) (section 4 ",emacs-mode" (p "Sets the current editing mode to Emacs"))) (section 3 "Variables" (section 4 "version" (def (sig (type "string" (id string))) (p "The current version string."))) (section 4 "session" (def (sig (type "kvlist" (id kvlist))) (p "A Key-value list of settings that affect how some of the egg's functions behave for the current session.")) (section 5 "load-history-file" (def (sig (type "boolean" (id boolean))) (p "Used by " (tt "install-history-file") ".  Set to " (tt "#t") " by default; when set to " (tt "#f") ", the history file will " (b "NOT") " be loaded at start-up."))) (section 5 "save-history-on-exit" (def (sig (type "boolean" (id boolean))) (p "Used by " (tt "install-history-file") ".  Set to " (tt "#t") " by default; when set to " (tt "#f") ", the current session's history will " (b "NOT") " be saved to the history file on exit."))) (section 5 "record-history" (def (sig (type "boolean" (id boolean))) (p "Used by " (tt ",rl-rec") ".  Set to " (tt "#t") " by default; when set to " (tt "#f") " it disables recording history for the current session."))) (section 5 "verify-history-expansions" (def (sig (type "boolean" (id boolean))) (p "Settings this to true makes " (tt ",rl-!!") " wait for you to press enter instead of inserting " (tt "EOL") " automatically."))))) (section 3 "Functions" (section 4 "use-legacy-bindings" (def (sig (procedure "(use-legacy-bindings)" (id use-legacy-bindings))) (p "Exports symbols aliasing the v1.993 API to the current API.") (p "Use this function only if you have legacy code that uses the older API.") (p "Returns " (tt "(void)") " on success; will cause an error on fail.") (pre "Example:") (pre "(readline#use-legacy-bindings)\n(current-input-port (make-gnu-readline-port))"))) (section 4 "readline" (def (sig (procedure "(readline prompt1 [prompt2] )" (id readline))) (p "Reads a line using the GNU readline() function and returns a string.") (p "Both arguments must be strings; " (tt "prompt2") " is optional."))) (section 4 "%signal-cleanup" (def (sig (procedure "(%signal-cleanup)" (id %signal-cleanup))) (p "Sets the state of the underlying readline environment to a clean slate.") (p (b "NOTE") " Calls " (tt "free()") "; so using this more than once consecutively may result in undefined behavior, as in a segfault."))) (section 4 "clear-history" (def (sig (procedure "(clear-history)" (id clear-history))) (p "Clears the history buffer."))) (section 4 "read-history" (def (sig (procedure "(read-history [file])" (id read-history))) (p "Reads contents of the provided file into the history buffer.") (p "When called without file-name, reads from ~/.history.  Returns 0 on success, or errno on fail."))) (section 4 "write-history" (def (sig (procedure "(write-history [file])" (id write-history))) (p "Writes the history buffer to " (tt "file") " or ~/.history when no " (tt "file") " is provided.") (p "Returns " (tt "0") " on success; " (tt "errno") " on fail.") (p (b "USE AT YOUR OWN RISK!")) (p "Using this may clobber simultaneous sessions."))) (section 4 "append-history" (def (sig (procedure "(append-history [file])" (id append-history))) (p "Appends history buffer from the " (i "current") " session to " (tt "file") ".") (p "Returns " (tt "0") " on success; " (tt "errno") " on fail."))) (section 4 "history-newlines" (def (sig (procedure "(history-newlines)" (id history-newlines))) (p "Returns the number of entries from the " (i "current") " session."))) (section 4 "truncate-history" (def (sig (procedure "(truncate-history [file] [n])" (id truncate-history))) (p "Truncates provided history " (tt "file") " to a maximum of " (tt "n") " lines.") (p "Returns " (tt "0") " on win; " (tt "errno") " on fail."))) (section 4 "install-history-file" (def (sig (procedure "(install-history-file [homedir] [filename] [nlines])" (id install-history-file))) (p "If you also want to make the command history span sessions, add the following to your " (tt "~/.csirc") ":") (p (tt "(install-history-file)")) (p "By default this will save 1000 lines of history between sessions (it will prune the history file to 1000 lines at startup). For a different history size, pass the desired number of lines as the (optional) second argument to history-install-file-manager. If " (tt "#f") " or no second argument is passed in, no history-file-pruning will take place.") (p (b "NOTE") " Do not use this in conjunction with " (tt "rlwrap") ".  The maintainer did so and experience some very weird behavior from " (tt "csi") "."))) (section 4 "make-readline-port" (def (sig (procedure "(make-readline-port [prompt] [prompt2])" (id make-readline-port))) (p "Returns an input-port that uses the GNU readline facility. If PROMPT is not given, the value returned by (repl-prompt) is used for generating the current prompt (see the Chicken manual for more details about repl-prompt). PROMPT2 is used when there are still unclosed parenthesis; if not given, an appropriate default is generated."))) (section 4 "set-bounce-ms" (def (sig (procedure "(set-bounce-ms ms)" (id set-bounce-ms))) (p "Changes the time that the cursor spends bouncing on the matching parenthesis - the default 500ms. To turn bouncing off completely, set it to " (tt "0") "."))) (section 4 "parse-and-bind" (def (sig (procedure "(parse-and-bind string)" (id parse-and-bind))) (p "Passes " (tt "string") " straight to the readline library for parsing (see the readline manual page for details)."))) (section 4 "history-list" (def (sig (procedure "(history-list)" (id history-list))) (p "Returns the history list as a newline separated list."))) (section 4 "history-position" (def (sig (procedure "(history-position [pos])" (id history-position))) (p "Returns the current " (i "offset") " within the history list.") (p "Passing " (i "pos") " sets the current " (i "offset") "."))) (section 4 "add-history" (def (sig (procedure "(%history-add% string)" (id %history-add%))) (p "Adds " (i "string") " to the history list.") (p (b "NOTE")) (p "This function exists primarily for testing purposes.") (p "Returns " (tt "void")))) (section 4 "remove-history" (def (sig (procedure "(%remove-history% offset)" (id %remove-history%))) (p "Removes and " (b "frees") " the specified history entry and its associated memory."))) (section 4 "eval-last-history-line" (def (sig (procedure "(eval-last-history-line [script])" (id eval-last-history-line))) (p "The function behind " (tt ",rl-!!") ".") (p "This function is " (b "not") " added to the history unless " (i "script") " is true. DO " (b "NOT") " pass " (i "script") " as true, unless you know what you are doing: it makes it possible to accidentally cause an infinite loop if the previous command was also " (tt "eval-last-history-line #t") "!!") (p (b "NOTE")) (p "The line does not have to be from the current session. Also, I don't know what happens when there isn't said line, but I reckon it'd cause a segfault; I'll see about fixing that in the 3.1 release."))))) (section 2 "Building" (p "This extension supports static linking.") (section 3 "Examples" (pre "% csi -quiet\n#;1> (use readline)\n#;2> (current-input-port (make-readline-port))\n#;3>") (p "To get csi to use readline by default, and to keep a history, use the following (in your ~/.csirc file):") (pre "(use readline)\n(current-input-port (make-readline-port))\n(install-history-file #f \"/.csi.history\")") (p "To set readline to behave somewhat like vi:") (pre "(parse-and-bind \"set editing-mode vi\")"))) (section 2 "Installation problems" (p "This extension requires GNU readline.  You will receive errors if you don't have the C header files for your readline installation or if you use some versions of the BSD readline alternative, libedit.") (section 3 "Mac OS X" (section 4 "10.8/10.9 (Snow Leopard/Mavericks)" (p "Using bash...") (pre "brew install readline\nreadline_version=$(brew list readline --versions)\nreadline_version=${readline_version##* }\nexport CSC_OPTIONS=\"-I/usr/local/Cellar/readline/$readline_version/include -L/usr/local/Cellar/readline/$readline_version/lib -Wl,-flat_namespace,-undefined,suppress\"\nunset readline_version\nbrew reinstall chicken\nchicken-install readline")) (section 4 "10.6 (Snow Leopard)" (p "10.6 ships with a much older version of readline than this egg expects.  Fortunately, recent versions of " (tt "readline") " in MacPorts work.  " (tt "readline @6.0.000_2+darwin") " is confirmed to work with 10.6.2.  First install the " (tt "readline") " package from MacPorts and then do this:") (pre "export CSC_OPTIONS=\"-I/opt/local/include -L/opt/local/lib\"") (p "...before the " (tt "chicken-install") ". If this doesn't work, try an additional") (pre "export LIBRARY_PATH=/opt/local/lib")) (section 4 "Pre-10.6" (p "Mac OS X versions prior to 10.5 (Leopard) ship with an older " (tt "readline") ", causing the following error when you install this egg:") (pre "/usr/bin/ld: Undefined symbols:\n_history_truncate_file") (p "To fix this, install a copy of GNU readline in " (tt "/usr/local/lib") " or, if you're using MacPorts, symlink it:") (pre "ln -s /opt/local/lib/libreadline.dylib /usr/local/lib") (p "DO NOT modify the readline link in " (tt "/usr/lib") "."))) (section 3 "Debian GNU/Linux and derivatives (such as Ubuntu)" (p "In the case of Debian, you should probably install the package " (tt "libreadline-dev") ", which is not installed by default."))) (section 2 "About this egg" (section 3 "Author" (p "Tony Garnock-Jones") (p "Maintained by Alexej Magura")) (section 3 "Version history" (dl (dt "4.1.1") (dd "Slight changes to the toplevel commands interface.") (dt "4.1.0") (dd "Necessary updates in light of the changes in Chicken v4.10 as compared to Chicken v4.9.") (dt "4.0.0") (dd "Version bump due to v3.0b2 being considered newer than v3.1.1.") (dt "3.1.1") (dd "Removes `regex` as a dependency (patch).") (dt "3.1") (dd "Removes `current-history-line' and renames all of the history related functions.") (dt "3.0") (dd "Removes a lot of the stuff introduced by 2.0; adds toplevel-commands for convience.") (dt "3.0b2") (dd "Fixed memleaks in history-list function and str_unquotd") (dt "3.0b1") (dd "Made a few tweaks to the API to keep it in sync with the documentation I've written.") (dt "3.0b") (dd "Lots of API additions and a few changes; more efficient memory usage; removed libbsd as an optional depend") (dt "2.4") (dd "Fixed setup file and version string.") (dt "2.3") (dd "Reverted back to v1.993 setup file due to that fixes a bug with automated builds; added checks for libbsd") (dt "2.2") (dd "Fixed more bugs with the detection of unclosed expressions") (dt "2.1") (dd "Fixed a bug with legacy support where the aliases pointed to uninterned symbols.") (dt "2.0") (dd "Fixed a bug with the unclosed-exp-prompt, where " (tt "\"<NEWLINE>") " did not count as an unclosed expression.  Added more history functions and other cool stuff  (see soon-to-appear changelog for details)") (dt "1.993") (dd "fixed buggy build bugs caused by repeated build \"fixes\" (Jim Ursetto)") (dt "1.992") (dd "fixed buggy fixes made by felix (thanks to ewfalor)") (dt "1.991") (dd "fixed buggy setup script (thanks to ewfalor)") (dt "1.99") (dd "Ported to Chicken 4") (dt "1.97") (dd "Fixed an old typo that could conceivably cause errors [elf]") (dt "1.96") (dd "Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]") (dt "1.95") (dd "Fixed build process [elf]") (dt "1.94") (dd "Added backtraces to control-c breaks [elf]") (dt "1.93") (dd "Fixed history so that multiple sessions dont clobber each other. [elf]") (dt "1.92") (dd "Added proper signal handling [elf]") (dt "1.91") (dd "Added support for static linking [felix]") (dt "1.9") (dd "Ignores duplicate history entries [Thanks to Toby Butzon]") (dt "1.8") (dd "Empty lines are not added to history [Thanks to Dan Muresan]") (dt "1.7") (dd "Added parenthesis bouncing, a new auto-complete [Heath Johns]") (dt "1.6") (dd "Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]") (dt "1.5") (dd "prompt argument to make-gnu-readline-port is optional [felix]") (dt "1.4") (dd "Replaced use of (end-of-file) with #!eof") (dt "1.3") (dd "Checks more possible libraries to link with at build time [Thanks to Peter Bex]") (dt "1.2") (dd "Adapted to new setup scheme.") (dt "1.1") (dd "More features, changed license to GPL, links with either libtermcap or libncurses.") (dt "1.0") (dd "Initial release"))) (section 3 "License" (pre "Copyright (c) 2002 Tony Garnock-Jones\nCopyright (c) 2006 Heath Johns (paren bouncing and auto-completion code)") (pre "This program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 2 of the License, or\n(at your option) any later version.") (pre "This program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.") (pre "You should have received a copy of the GNU General Public License\nalong with this program; if not, write to the Free Software\nFoundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA"))))