diff --git a/collects/readline/readline.scrbl b/collects/readline/readline.scrbl index d1e6ecc6f9..a07fdd1989 100644 --- a/collects/readline/readline.scrbl +++ b/collects/readline/readline.scrbl @@ -1,88 +1,88 @@ #lang scribble/doc @(require scribble/manual - (for-label scheme/base + (for-label racket/base readline readline/pread readline/readline - scheme/contract - (except-in scheme/foreign ->))) + racket/contract + (except-in ffi/unsafe ->))) @(define readline "Readline") @(define Readline "Readline") @title{@bold{Readline}: Terminal Interaction} -The @filepath{readline} collection (not to be confused with MzScheme's -@scheme[read-line] function) provides glue for using GNU's @|readline| -library with the MzScheme @scheme[read-eval-print-loop]. +The @filepath{readline} collection (not to be confused with Racket's +@racket[read-line] function) provides glue for using GNU's @|readline| +library with the Racket @racket[read-eval-print-loop]. @section{Normal Use of @|Readline|} @defmodule*[(readline readline/rep-start)] -The @schememodname[readline] library installs a @|readline|-based -input port, and hooks the prompt-and-read part of MzScheme's -@scheme[read-eval-print-loop] to interact with it +The @racketmodname[readline] library installs a @|readline|-based +input port, and hooks the prompt-and-read part of Racket's +@racket[read-eval-print-loop] to interact with it -You can start MzScheme with +You can start Racket with -@commandline{mzscheme -il readline} +@commandline{racket -il readline} or evaluate -@schemeblock[ +@racketblock[ (require readline) ] -in the MzScheme @scheme[read-eval-print-loop] to load @|readline| +in the Racket @racket[read-eval-print-loop] to load @|readline| manually. You can also put (require readline) in your -@filepath{~/.mzschemerc}, so that MzScheme automatically loads +@filepath{~/.racketrc}, so that Racket automatically loads @|readline| support in interactive mode. If you want to enable @|readline| support only sometimes---such as only when you use an @exec{xterm}, and not when you use an Emacs -shell---then you can use @scheme[dynamic-require], as in the following +shell---then you can use @racket[dynamic-require], as in the following example: -@schemeblock[ +@racketblock[ (when (regexp-match? #rx"xterm" (getenv "TERM")) (dynamic-require 'readline #f)) ] -The @schememodname[readline] library automatically checks whether the +The @racketmodname[readline] library automatically checks whether the current input port is a terminal, as determined by -@scheme[terminal-port?], and it installs @|readline| only to replace -terminal ports. The @schememodname[readline/rep-start] module +@racket[terminal-port?], and it installs @|readline| only to replace +terminal ports. The @racketmodname[readline/rep-start] module installs @|readline| without a terminal check. By default, @|readline|'s completion is set to use the visible bindings in the current namespace. This is far from ideal, but it's better than @|readline|'s default filename completion which is rarely useful. In addition, the @|readline| history is stored across -invocations in MzScheme's preferences file, assuming that MzScheme +invocations in Racket's preferences file, assuming that Racket exits normally. @defproc[(install-readline!) void?]{ -Adds @scheme[(require readline/rep)] to the result of -@scheme[(find-system-path 'init-file)], which is -@filepath{~/.mzschemerc} under Unix. Consequently, @|readline| will be -loaded whenever MzScheme is started in interactive mode. The +Adds @racket[(require readline/rep)] to the result of +@racket[(find-system-path 'init-file)], which is +@filepath{~/.racketrc} under Unix. Consequently, @|readline| will be +loaded whenever Racket is started in interactive mode. The declaration is added only if it is not already present, as determined -by @scheme[read]ing and checking all top-level expressions in the +by @racket[read]ing and checking all top-level expressions in the file. For more fine-grained control, such as conditionally loading @|readline| based on an environment variable, edit -@filepath{~/.mzschemerc} manually.} +@filepath{~/.racketrc} manually.} @section{Interacting with the @|Readline|-Enabled Input Port } -@defmodule[readline/pread]{ The @schememodname[readline/pread] library +@defmodule[readline/pread]{ The @racketmodname[readline/pread] library provides customization, and support for prompt-reading after -@schememodname[readline] installs the new input port.} +@racketmodname[readline] installs the new input port.} The reading facility that the new input port provides can be customized with the following parameters. @@ -91,58 +91,59 @@ customized with the following parameters. @defparam[current-prompt bstr bytes?]{ A parameter that determines the prompt that is used, as a byte string. -Defaults to @scheme[#"> "].} +Defaults to @racket[#"> "].} +@;{ @defboolparam[show-all-prompts on?]{ -A parameter. If @scheme[#f], no prompt is shown until you write input +A parameter. If @racket[#f], no prompt is shown until you write input that is completely readable. For example, when you type -@schemeblock[ +@racketblock[ (foo bar) (+ 1 2) ] you will see a single prompt in the beginning. -The problem is that the first expression can be @scheme[(read-line)], +The problem is that the first expression can be @racket[(read-line)], which normally consumes the rest of the text on the @emph{same} line. -The default value of this parameter is therefore @scheme[#t], making +The default value of this parameter is therefore @racket[#t], making it mimic plain I/O interactions.} - +} @defparam[max-history n exact-nonnegative-integer?]{ A parameter that determines the number of history entries to save, -defaults to @scheme[100].} +defaults to @racket[100].} @defparam[keep-duplicates keep? (one-of/c #f 'unconsecutive #t)]{ -A parameter. If @scheme[#f] (the default), then when a line is equal +A parameter. If @racket[#f] (the default), then when a line is equal to a previous one, the previous one is removed. If it set to -@scheme['unconsecutive] then this happens only for an line that -duplicates the previous one, and if it is @scheme[#f] then all +@racket['unconsecutive] then this happens only for an line that +duplicates the previous one, and if it is @racket[#f] then all duplicates are kept.} @defboolparam[keep-blanks keep?]{ -A parameter. If @scheme[#f] (the default), blank input lines are not +A parameter. If @racket[#f] (the default), blank input lines are not kept in history.} @defparam[readline-prompt status (or/c false/c bytes? (one-of/c 'space))]{ The new input port that you get when you require -@schememodname[readline] is a custom port that uses @|readline| for +@racketmodname[readline] is a custom port that uses @|readline| for all inputs. The problem is when you want to display a prompt and then read some input, @|readline| will get confused if it is not used when the cursor is at the beginning of the line (which is why it has a -@scheme[_prompt] argument.) To use this prompt: +@racket[_prompt] argument.) To use this prompt: -@schemeblock[ +@racketblock[ (parameterize ([readline-prompt some-byte-string]) ...code-that-reads...) ] @@ -150,20 +151,20 @@ cursor is at the beginning of the line (which is why it has a This expression makes the first call to @|readline| use the prompt, and subsequent calls will use an all-spaces prompt of the same length (for example, when you're reading an S-expression). The normal value of -@scheme[readline-prompt] is @scheme[#f] for an empty prompt (and +@racket[readline-prompt] is @racket[#f] for an empty prompt (and spaces after the prompt is used, which is why you should use -@scheme[parameterize] to restore it to @scheme[#f]). +@racket[parameterize] to restore it to @racket[#f]). A proper solution would be to install a custom output port, too, which keeps track of text that is displayed without a trailing newline. As a cheaper solution, if line-counting is enabled for the terminal's output-port, then a newline is printed before reading if the column is -not 0. (The @schememodname[readline] library enables line-counting +not 0. (The @racketmodname[readline] library enables line-counting for the output port.) @bold{Warning:} The @|readline| library uses the output port directly. -You should not use it when @scheme[current-input-port] has been -modified, or when it was not a terminal port when MzScheme was started +You should not use it when @racket[current-input-port] has been +modified, or when it was not a terminal port when Racket was started (eg, when reading input from a pipe). Expect some problems if you ignore this warning (not too bad, mostly problems with detecting an EOF).} @@ -181,7 +182,7 @@ Prints the given prompt string and reads a line.} @defproc[(readline-bytes [prompt bytes?]) bytes?]{ -Like @scheme[readline], but using raw byte-strings for the prompt and +Like @racket[readline], but using raw byte-strings for the prompt and returning a byte string.} @@ -203,16 +204,16 @@ Returns the length of the history list.} @defproc[(history-get [idx integer?]) string?]{ -Returns the history string at the @scheme[idx] position. @scheme[idx] +Returns the history string at the @racket[idx] position. @racket[idx] can be negative, which will make it count from the last (i.e, -@scheme[-1] returns the last item, @scheme[-2] returns the +@racket[-1] returns the last item, @racket[-2] returns the second-to-last, etc.)} @defproc[(history-delete [idx integer?]) string?]{ -Deletes the history string at the @scheme[idx] position. The position -is specified in the same way as the argument for @scheme[history-get].} +Deletes the history string at the @racket[idx] position. The position +is specified in the same way as the argument for @racket[history-get].} @defproc[(set-completion-function! [proc ((or/c string? bytes?) @@ -221,16 +222,16 @@ is specified in the same way as the argument for @scheme[history-get].} void?]{ Sets @|readline|'s @tt{rl_completion_entry_function} to -@scheme[proc]. The @scheme[type] argument, whose possible values are -from @schememodname[scheme/foreign], determines the type of value -supplied to the @scheme[proc].} +@racket[proc]. The @racket[type] argument, whose possible values are +from @racketmodname[ffi/unsafe], determines the type of value supplied +to the @racket[proc].} @section{License Issues} -GNU's @|readline| library is covered by the GPL, and that applies to code -that links with it. PLT Scheme is LGPL, so this code is not used by -default; you should explicitly enable it if you want to. Also, be -aware that if you write code that uses this library, it will make your -code link to the @|readline| library when invoked, with the usual GPL -implications. +GNU's @|readline| library is covered by the GPL, and that applies to +code that links with it. Racket is licensed with the LGPL, so the +@|readline| code is not used by default; you should explicitly enable +it if you want to. Also, be aware that if you write code that uses +this library, it will make your code link to the @|readline| library +when invoked, with the usual GPL implications.