source: project/wiki/eggref/5/breadline @ 36797

Last change on this file since 36797 was 36797, checked in by wasamasa, 2 years ago

Fix example and other repo URL

File size: 4.7 KB
Line 
1== breadline
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides an incomplete set of bindings to the
8[[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
9library, suitable for augmenting {{csi}} and writing a {{csi}}-like
10application with line editing support.
11
12=== Author
13
14Vasilij Schneidermann
15
16=== Repository
17
18[[https://github.com/wasamasa/breadline]]
19
20=== Current state of the bindings
21
22* Basic interface for reading input and managing history
23* Completion interface
24* Customization of aspects crucial for Scheme programming
25
26=== Requirements
27
28You'll need to have a not too old version of GNU Readline
29installed. This egg has been tested with version 7, but version 6
30should work as well.
31
32=== API
33
34==== History
35
36<parameter>(history-file)</parameter>
37<parameter>(history-file PATH)</parameter>
38
39Specifies the location of the history file for {{make-readline-port}}.
40Defaults to {{#f}} which means to neither read nor write out the
41history.  {{PATH}} may be relative to the current working directory.
42
43<procedure>(add-history! ITEM)</procedure>
44
45Adds {{ITEM}} to the current history.
46
47<procedure>(read-history! FILE)</procedure>
48
49Reads in history items from {{FILE}} and adds them to the current
50history.
51
52<procedure>(write-history! FILE)</procedure>
53
54Writes out current history items to {{FILE}}.
55
56<procedure>(stifle-history! MAX)</procedure>
57
58Configure the current history to hold at most {{MAX}} items.
59
60<procedure>(unstifle-history!)</procedure>
61
62Undo any history stifling.  Returns the previously set maximum amount
63of history items as set by {{stifle-history!}}.  If the history was
64not stifled before, the value is negative.
65
66==== Completion
67
68<procedure>(completer-set! PROC)</procedure>
69
70Set the completion handler to {{PROC}}.  {{PROC}} is called repeatedly
71to collect completions with a fixnum state argument and a string
72prefix.  A state argument of zero means that the completion procedure
73may initialize its data, it is incremented for every subsequent call.
74The completion procedure must either return a completion matching the
75given string prefix or {{#f}} to signal that no further completions
76follow.  It is up to the completion procedure to keep track of what
77completions have been offered and whether any further completions are
78vailable.
79
80<procedure>(completer-word-break-characters-set STRING)</procedure>
81
82Sets the word-breaking characters for completion to {{STRING}}.  The
83default value of {{\t\n\"\\'`@$><=;|&{(}} is suitable for Bash's
84completion.
85
86==== Customization
87
88<procedure>(variable-bind! VARIABLE VALUE)</procedure>
89
90Sets a GNU Readline variable to a value.  Both {{VARIABLE}} and
91{{VALUE}} must be strings.
92
93<procedure>(variable-value VARIABLE)</procedure>
94
95Retrieves the current value of the given GNU Readline variable.
96{{VARIABLE}} must be a string.
97
98<procedure>(basic-quote-characters-set STRING)</procedure>
99
100Sets the quoting characters to {{STRING}}, the default value being
101{{"'}}.  This setting is used for paren blinking to determine strings.
102
103<procedure>(paren-blink-timeout-set MICROSECS)</procedure>
104
105Sets the timeout for paren blinking in microseconds, the default value
106being 500000 microseconds.  Note that typing a closing paren will not
107blink the opening paren unless {{blink-matching-paren}} has been set.
108
109==== Line editing
110
111<procedure>(readline PROMPT)</procedure>
112
113Read in a line of user input after printing {{PROMPT}}.  Returns the
114user input or {{#f}} if input has been terminated with {{C-d}}.
115
116<procedure>(make-readline-port [PROMPT])</procedure>
117
118Returns an input port using GNU Readline for line editing and history
119management.  {{PROMPT}} defaults to the value of calling
120{{(repl-prompt)}}.
121
122=== Examples
123
124<enscript highlight="scheme">
125(import breadline)
126
127(let loop ()
128  (let ((input (readline "> ")))
129    (if input
130        (begin
131          ;; processing code goes here
132          (print input)
133          (add-history! input)
134          (loop))
135        (newline))))
136</enscript>
137
138Further examples for usage in {{csi}} and writing your own completer
139can be found
140[[https://github.com/wasamasa/breadline/tree/master/examples|in the repository]].
141
142=== License
143
144 Copyright 2016 Vasilij Schneidermann
145 
146 This program is free software: you can redistribute it and/or modify
147 it under the terms of the GNU General Public License as published by
148 the Free Software Foundation, either version 3 of the License, or (at
149 your option) any later version.
150 
151 This program is distributed in the hope that it will be useful, but
152 WITHOUT ANY WARRANTY; without even the implied warranty of
153 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
154 General Public License for more details.
155 
156 A full copy of the GPL license can be found at
157 <http://www.gnu.org/licenses/>.
158
159=== Version history
160
161==== 0.1
162
163* Initial release
Note: See TracBrowser for help on using the repository browser.