1#d notes_comment This function is part of the S-Lang readline interface.
2
3\function{rline_bolp}
4\synopsis{Test of the editing point is at the beginning of the line}
5\usage{Int_Type rline_bolp()}
6\description
7  The \ifun{rline_bolp} function returns a non-zero value if the
8  current editing position is at the beginning of the line.
9\notes
10 \notes_comment
11\seealso{rline_eolp, rline_get_point, rline_get_line}
12\done
13
14\function{rline_call}
15\synopsis{Invoke an internal readline function}
16\usage{rline_call (String_Type func)}
17\description
18 Not all of the readline functions are available directly from the
19 \slang interpreter.  For example, the "deleol" function, which
20 deletes through the end of the line may be executed using
21#v+
22    rline_call("deleol");
23#v-
24  See the documentation for the \ifun{rline_setkey} function for a
25  list of internal functions that may be invoked by \ifun{rline_call}.
26\notes
27 \notes_comment
28\seealso{rline_setkey, rline_del, rline_ins}
29\done
30
31\function{rline_del}
32\synopsis{Delete a specified number of characters at the current position}
33\usage{rline_del(Int_Type n)}
34\description
35 This function delete a specified number of characters at the current
36 editing position.  If the number \exmp{n} is less than zero, then the
37 previous \exmp{n} characters will be deleted.  Otherwise, the next
38 \exmp{n} characters will be deleted.
39\notes
40 \notes_comment
41\seealso{rline_ins, rline_setkey}
42\done
43
44\function{rline_eolp}
45\synopsis{Test of the editing point is at the end of the line}
46\usage{Int_Type rline_eolp()}
47\description
48  The \ifun{rline_bolp} function returns a non-zero value if the
49  current editing position is at the end of the line.
50\notes
51 \notes_comment
52\seealso{rline_bolp, rline_get_point, rline_get_line}
53\done
54
55\function{rline_getkey}
56\synopsis{Obtain the next byte in the readline input stream}
57\usage{Int_Type rline_getkey ()}
58\description
59  This function returns the next byte in the readline input stream.
60  If no byte is available, the function will wait until one is.
61\notes
62 \notes_comment
63\seealso{rline_input_pending, rline_setkey}
64\done
65
66\function{rline_get_edit_width}
67\synopsis{Get the width of the readline edit window}
68\usage{Int_Type rline_get_edit_width ()}
69\description
70  This function returns the width of the edit window.  For \slsh, this
71  number corresponds to the width of the terminal window.
72\notes
73 \notes_comment
74\seealso{rline_ins}
75\done
76
77\function{rline_get_history}
78\synopsis{Retrieve the readline history}
79\usage{Array_Type rline_get_history ()}
80\description
81  This function returns the readline edit history as an array of
82  strings.
83\notes
84 \notes_comment
85\seealso{rline_set_line}
86\done
87
88\function{rline_get_line}
89\synopsis{Get a copy of the line being edited}
90\usage{String_Type rline_get_line ()}
91\description
92  This function returns the current edit line.
93\notes
94 \notes_comment
95\seealso{rline_set_line, rline_get_history}
96\done
97
98\function{rline_get_point}
99\synopsis{Get the current editing position}
100\usage{Int_Type rline_get_point ()}
101\description
102 The \ifun{rline_get_point} function returns the byte-offset of the
103 current editing position.
104\notes
105 \notes_comment
106\seealso{rline_set_point}
107\done
108
109\function{rline_input_pending}
110\synopsis{Test to see if readline input is available for reading}
111\usage{Int_Type rline_input_pending (Int_Type tsecs)}
112\description
113  This function returns a non-zero value if readline input is
114  available to be read.  If none is immediately available, it will
115  wait for up to \exmp{tsecs} tenths of a second for input before
116  returning.
117\notes
118 \notes_comment
119\seealso{rline_getkey}
120\done
121
122\function{rline_ins}
123\synopsis{Insert a string at the current editing point}
124\usage{rline_ins (String_Type text)}
125\description
126  This function inserts the specified string into the line being edited.
127\notes
128 \notes_comment
129\seealso{rline_set_line, rline_del}
130\done
131
132\function{rline_setkey}
133\synopsis{Bind a key in the readline keymap to a function}
134\usage{rline_setkey (func, keyseq)}
135\description
136  The \ifun{rline_setkey} function binds the function \exmp{func} to
137  the specified key sequence \exmp{keyseq}.  The value of \exmp{func}
138  may be either a reference to a \slang function, or a string giving
139  the name of an internal readline function.
140
141  Functions that are internal to the readline interface include:
142#v+
143   bdel             Delete the previous character
144   bol              Move to the beginning of the line
145   complete         The command line completion function
146   del              Delete the character at the current position
147   delbol           Delete to the beginning of the line
148   deleol           Delete through the end of the line
149   down             Goto the next line in the history
150   enter            Return to the caller of the readline function
151   eol              Move to the end of the line
152   kbd_quit         Abort editing of the current line
153   left             Move left one character
154   quoted_insert    Insert the next byte into the line
155   redraw           Redraw the line
156   right            Move right one character
157   self_insert      Insert the byte that invoked the function
158   trim             Remove whitespace about the current position
159   up               Goto the previous line in the history
160#v-
161\notes
162 \notes_comment
163\seealso{rline_unsetkey}
164\done
165
166\function{rline_set_completion_callback}
167\synopsis{Set the function to be used for completion at the readline prompt}
168\usage{rline_set_completion_callback (Ref_Type func)}
169\description
170  This function sets the callback function to be used for completion at the
171  readline prompt.  The callback function must be defined to accept
172  two values, the first being a string containing the text of the line
173  being edited, and an integer giving the position of the byte-offset
174  into the string where completion was requested.
175
176  The callback function must return two values: an array giving the
177  list of possible completion strings, and an integer giving the byte
178  offset into the string of the start of the text to be completed.
179\example
180  See completion-callback function defined in the \slsh library file
181  \exmp{rline/complete.sl}.
182\notes
183 \notes_comment
184\seealso{rline_set_list_completions_callback}
185\done
186
187\function{rline_set_history}
188\synopsis{Replace the current history list with a new one}
189\usage{rline_set_history (Array_Type lines)}
190\description
191  The \ifun{rline_set_history} function replaces the current history
192  by the specified array of strings.
193\notes
194 \notes_comment
195\seealso{rline_get_history}
196\done
197
198\function{rline_set_line}
199\synopsis{Replace the current line with a new one}
200\usage{rline_set_line (String_Type line)}
201\description
202  The \ifun{rline_set_line} function replaces the line being edited by
203  the specified one.
204\notes
205 \notes_comment
206\seealso{rline_get_line}
207\done
208
209\function{rline_set_list_completions_callback}
210\synopsis{Set a callback function to display the list of completions}
211\usage{rline_set_list_completions_callback (Ref_Type func)}
212\description
213  This function sets the \slang function that is to be used to display the
214  list of possible completions for current word at the readline prompt.
215  The callback function must be defined to accept a single parameter
216  representing an array of completion strings.
217\example
218  This callback function writes the completions using the message
219  functions:
220#v+
221     private define display_completions (strings)
222     {
223        variable str;
224        vmessage ("There are %d completions:\n", length(strings));
225        foreach str (strings) vmessage ("%s\n", str);
226     }
227     rline_set_list_completions_callback (&display_completions);
228#v-
229\seealso{rline_set_completion_callback}
230\done
231
232\function{rline_set_point}
233\synopsis{Move the current editing position to another}
234\usage{rline_set_point (Int_Type ofs)}
235\description
236 The \ifun{rline_set_point} function sets the editing point to the
237 specified byte-offset from the beginning of the line.
238\notes
239 \notes_comment
240\seealso{rline_get_point}
241\done
242
243\function{rline_unsetkey}
244\synopsis{Unset a key binding from the readline keymap}
245\usage{rline_unsetkey (String_Type keyseq)}
246\description
247  The \ifun{rline_unsetkey} function unbinds the specified key sequence
248  from the readline keymap.
249\notes
250 \notes_comment
251\seealso{rline_setkey}
252\done
253
254