Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/el_init.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 .TH EDITLINE 3 "August 15, 2021" ""
jpayne@68 2 .SH NAME
jpayne@68 3 \fBeditline\fP,
jpayne@68 4 \fBel_init\fP,
jpayne@68 5 \fBel_init_fd\fP,
jpayne@68 6 \fBel_end\fP,
jpayne@68 7 \fBel_reset\fP,
jpayne@68 8 \fBel_gets\fP,
jpayne@68 9 \fBel_wgets\fP,
jpayne@68 10 \fBel_getc\fP,
jpayne@68 11 \fBel_wgetc\fP,
jpayne@68 12 \fBel_push\fP,
jpayne@68 13 \fBel_wpush\fP,
jpayne@68 14 \fBel_parse\fP,
jpayne@68 15 \fBel_wparse\fP,
jpayne@68 16 \fBel_set\fP,
jpayne@68 17 \fBel_wset\fP,
jpayne@68 18 \fBel_get\fP,
jpayne@68 19 \fBel_wget\fP,
jpayne@68 20 \fBel_source\fP,
jpayne@68 21 \fBel_resize\fP,
jpayne@68 22 \fBel_cursor\fP,
jpayne@68 23 \fBel_line\fP,
jpayne@68 24 \fBel_wline\fP,
jpayne@68 25 \fBel_insertstr\fP,
jpayne@68 26 \fBel_winsertstr\fP,
jpayne@68 27 \fBel_deletestr\fP,
jpayne@68 28 \fBel_wdeletestr\fP,
jpayne@68 29 \fBhistory_init\fP,
jpayne@68 30 \fBhistory_winit\fP,
jpayne@68 31 \fBhistory_end\fP,
jpayne@68 32 \fBhistory_wend\fP,
jpayne@68 33 \fBhistory\fP,
jpayne@68 34 \fBhistory_w\fP,
jpayne@68 35 \fBtok_init\fP,
jpayne@68 36 \fBtok_winit\fP,
jpayne@68 37 \fBtok_end\fP,
jpayne@68 38 \fBtok_wend\fP,
jpayne@68 39 \fBtok_reset\fP,
jpayne@68 40 \fBtok_wreset\fP,
jpayne@68 41 \fBtok_line\fP,
jpayne@68 42 \fBtok_wline\fP,
jpayne@68 43 \fBtok_str\fP,
jpayne@68 44 \fBtok_wstr\fP
jpayne@68 45 \- line editor, history and tokenization functions
jpayne@68 46 .SH LIBRARY
jpayne@68 47 Command Line Editor Library (libedit, -ledit)
jpayne@68 48 .SH SYNOPSIS
jpayne@68 49 .PP
jpayne@68 50 \fB#include <histedit.h>\fP
jpayne@68 51 .PP
jpayne@68 52 \fIEditLine *\fP
jpayne@68 53 .br
jpayne@68 54 \fBel_init\fP(\fIconst char *prog\fP, \fIFILE *fin\fP, \fIFILE *fout\fP, \fIFILE *ferr\fP);
jpayne@68 55 .PP
jpayne@68 56 \fIEditLine *\fP
jpayne@68 57 .br
jpayne@68 58 \fBel_init_fd\fP(\fIconst char *prog\fP, \fIFILE *fin\fP, \fIFILE *fout\fP, \fIFILE *ferr\fP, \fIint fdin\fP, \fIint fdout\fP, \fIint fderr\fP);
jpayne@68 59 .PP
jpayne@68 60 \fIvoid\fP
jpayne@68 61 .br
jpayne@68 62 \fBel_end\fP(\fIEditLine *e\fP);
jpayne@68 63 .PP
jpayne@68 64 \fIvoid\fP
jpayne@68 65 .br
jpayne@68 66 \fBel_reset\fP(\fIEditLine *e\fP);
jpayne@68 67 .PP
jpayne@68 68 \fIconst char *\fP
jpayne@68 69 .br
jpayne@68 70 \fBel_gets\fP(\fIEditLine *e\fP, \fIint *count\fP);
jpayne@68 71 .PP
jpayne@68 72 \fIconst wchar_t *\fP
jpayne@68 73 .br
jpayne@68 74 \fBel_wgets\fP(\fIEditLine *e\fP, \fIint *count\fP);
jpayne@68 75 .PP
jpayne@68 76 \fIint\fP
jpayne@68 77 .br
jpayne@68 78 \fBel_getc\fP(\fIEditLine *e\fP, \fIchar *ch\fP);
jpayne@68 79 .PP
jpayne@68 80 \fIint\fP
jpayne@68 81 .br
jpayne@68 82 \fBel_wgetc\fP(\fIEditLine *e\fP, \fIwchar_t *wc\fP);
jpayne@68 83 .PP
jpayne@68 84 \fIvoid\fP
jpayne@68 85 .br
jpayne@68 86 \fBel_push\fP(\fIEditLine *e\fP, \fIconst char *mbs\fP);
jpayne@68 87 .PP
jpayne@68 88 \fIvoid\fP
jpayne@68 89 .br
jpayne@68 90 \fBel_wpush\fP(\fIEditLine *e\fP, \fIconst wchar_t *wcs\fP);
jpayne@68 91 .PP
jpayne@68 92 \fIint\fP
jpayne@68 93 .br
jpayne@68 94 \fBel_parse\fP(\fIEditLine *e\fP, \fIint argc\fP, \fIconst char *argv[]\fP);
jpayne@68 95 .PP
jpayne@68 96 \fIint\fP
jpayne@68 97 .br
jpayne@68 98 \fBel_wparse\fP(\fIEditLine *e\fP, \fIint argc\fP, \fIconst wchar_t *argv[]\fP);
jpayne@68 99 .PP
jpayne@68 100 \fIint\fP
jpayne@68 101 .br
jpayne@68 102 \fBel_set\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
jpayne@68 103 .PP
jpayne@68 104 \fIint\fP
jpayne@68 105 .br
jpayne@68 106 \fBel_wset\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
jpayne@68 107 .PP
jpayne@68 108 \fIint\fP
jpayne@68 109 .br
jpayne@68 110 \fBel_get\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
jpayne@68 111 .PP
jpayne@68 112 \fIint\fP
jpayne@68 113 .br
jpayne@68 114 \fBel_wget\fP(\fIEditLine *e\fP, \fIint op\fP, \fI...\fP);
jpayne@68 115 .PP
jpayne@68 116 \fIint\fP
jpayne@68 117 .br
jpayne@68 118 \fBel_source\fP(\fIEditLine *e\fP, \fIconst char *file\fP);
jpayne@68 119 .PP
jpayne@68 120 \fIvoid\fP
jpayne@68 121 .br
jpayne@68 122 \fBel_resize\fP(\fIEditLine *e\fP);
jpayne@68 123 .PP
jpayne@68 124 \fIint\fP
jpayne@68 125 .br
jpayne@68 126 \fBel_cursor\fP(\fIEditLine *e\fP, \fIint count\fP);
jpayne@68 127 .PP
jpayne@68 128 \fIconst LineInfo *\fP
jpayne@68 129 .br
jpayne@68 130 \fBel_line\fP(\fIEditLine *e\fP);
jpayne@68 131 .PP
jpayne@68 132 \fIconst LineInfoW *\fP
jpayne@68 133 .br
jpayne@68 134 \fBel_wline\fP(\fIEditLine *e\fP);
jpayne@68 135 .PP
jpayne@68 136 \fIint\fP
jpayne@68 137 .br
jpayne@68 138 \fBel_insertstr\fP(\fIEditLine *e\fP, \fIconst char *str\fP);
jpayne@68 139 .PP
jpayne@68 140 \fIint\fP
jpayne@68 141 .br
jpayne@68 142 \fBel_winsertstr\fP(\fIEditLine *e\fP, \fIconst wchar_t *str\fP);
jpayne@68 143 .PP
jpayne@68 144 \fIvoid\fP
jpayne@68 145 .br
jpayne@68 146 \fBel_deletestr\fP(\fIEditLine *e\fP, \fIint count\fP);
jpayne@68 147 .PP
jpayne@68 148 \fIvoid\fP
jpayne@68 149 .br
jpayne@68 150 \fBel_wdeletestr\fP(\fIEditLine *e\fP, \fIint count\fP);
jpayne@68 151 .PP
jpayne@68 152 \fIHistory *\fP
jpayne@68 153 .br
jpayne@68 154 \fBhistory_init\fP(void );
jpayne@68 155 .PP
jpayne@68 156 \fIHistoryW *\fP
jpayne@68 157 .br
jpayne@68 158 \fBhistory_winit\fP(void );
jpayne@68 159 .PP
jpayne@68 160 \fIvoid\fP
jpayne@68 161 .br
jpayne@68 162 \fBhistory_end\fP(\fIHistory *h\fP);
jpayne@68 163 .PP
jpayne@68 164 \fIvoid\fP
jpayne@68 165 .br
jpayne@68 166 \fBhistory_wend\fP(\fIHistoryW *h\fP);
jpayne@68 167 .PP
jpayne@68 168 \fIint\fP
jpayne@68 169 .br
jpayne@68 170 \fBhistory\fP(\fIHistory *h\fP, \fIHistEvent *ev\fP, \fIint op\fP, \fI...\fP);
jpayne@68 171 .PP
jpayne@68 172 \fIint\fP
jpayne@68 173 .br
jpayne@68 174 \fBhistory_w\fP(\fIHistoryW *h\fP, \fIHistEventW *ev\fP, \fIint op\fP, \fI...\fP);
jpayne@68 175 .PP
jpayne@68 176 \fITokenizer *\fP
jpayne@68 177 .br
jpayne@68 178 \fBtok_init\fP(\fIconst char *IFS\fP);
jpayne@68 179 .PP
jpayne@68 180 \fITokenizerW *\fP
jpayne@68 181 .br
jpayne@68 182 \fBtok_winit\fP(\fIconst wchar_t *IFS\fP);
jpayne@68 183 .PP
jpayne@68 184 \fIvoid\fP
jpayne@68 185 .br
jpayne@68 186 \fBtok_end\fP(\fITokenizer *t\fP);
jpayne@68 187 .PP
jpayne@68 188 \fIvoid\fP
jpayne@68 189 .br
jpayne@68 190 \fBtok_wend\fP(\fITokenizerW *t\fP);
jpayne@68 191 .PP
jpayne@68 192 \fIvoid\fP
jpayne@68 193 .br
jpayne@68 194 \fBtok_reset\fP(\fITokenizer *t\fP);
jpayne@68 195 .PP
jpayne@68 196 \fIvoid\fP
jpayne@68 197 .br
jpayne@68 198 \fBtok_wreset\fP(\fITokenizerW *t\fP);
jpayne@68 199 .PP
jpayne@68 200 \fIint\fP
jpayne@68 201 .br
jpayne@68 202 \fBtok_line\fP(\fITokenizer *t\fP, \fIconst LineInfo *li\fP, \fIint *argc\fP, \fIconst char **argv[]\fP, \fIint *cursorc\fP, \fIint *cursoro\fP);
jpayne@68 203 .PP
jpayne@68 204 \fIint\fP
jpayne@68 205 .br
jpayne@68 206 \fBtok_wline\fP(\fITokenizerW *t\fP, \fIconst LineInfoW *li\fP, \fIint *argc\fP, \fIconst wchar_t **argv[]\fP, \fIint *cursorc\fP, \fIint *cursoro\fP);
jpayne@68 207 .PP
jpayne@68 208 \fIint\fP
jpayne@68 209 .br
jpayne@68 210 \fBtok_str\fP(\fITokenizer *t\fP, \fIconst char *str\fP, \fIint *argc\fP, \fIconst char **argv[]\fP);
jpayne@68 211 .PP
jpayne@68 212 \fIint\fP
jpayne@68 213 .br
jpayne@68 214 \fBtok_wstr\fP(\fITokenizerW *t\fP, \fIconst wchar_t *str\fP, \fIint *argc\fP, \fIconst wchar_t **argv[]\fP);
jpayne@68 215 .SH DESCRIPTION
jpayne@68 216 The
jpayne@68 217 \fBeditline\fP
jpayne@68 218 library provides generic line editing, history and tokenization functions,
jpayne@68 219 similar to those found in
jpayne@68 220 \fBsh\fP(1).
jpayne@68 221
jpayne@68 222 These functions are available in the
jpayne@68 223 \fBlibedit\fP
jpayne@68 224 library (which needs the
jpayne@68 225 \fBlibtermcap\fP
jpayne@68 226 library).
jpayne@68 227 Programs should be linked with
jpayne@68 228 \fB\-ledit\fP ltermcap .
jpayne@68 229
jpayne@68 230 The
jpayne@68 231 \fBeditline\fP
jpayne@68 232 library respects the
jpayne@68 233 .IR LC_CTYPE
jpayne@68 234 locale set by the application program and never uses
jpayne@68 235 \fBsetlocale\fP(3)
jpayne@68 236 to change the locale.
jpayne@68 237 .SH LINE EDITING FUNCTIONS
jpayne@68 238 The line editing functions use a common data structure,
jpayne@68 239 \fIEditLine\fP,
jpayne@68 240 which is created by
jpayne@68 241 \fBel_init\fP()
jpayne@68 242 or
jpayne@68 243 \fBel_init_fd\fP()
jpayne@68 244 and freed by
jpayne@68 245 \fBel_end\fP().
jpayne@68 246
jpayne@68 247 The wide-character functions behave the same way as their narrow
jpayne@68 248 counterparts.
jpayne@68 249
jpayne@68 250 The following functions are available:
jpayne@68 251 .TP
jpayne@68 252 \fBel_init\fP()
jpayne@68 253 Initialize the line editor, and return a data structure
jpayne@68 254 to be used by all other line editing functions, or
jpayne@68 255 NULL
jpayne@68 256 on failure.
jpayne@68 257 \fIprog \fP
jpayne@68 258 is the name of the invoking program, used when reading the
jpayne@68 259 \fBeditrc\fP(5)
jpayne@68 260 file to determine which settings to use.
jpayne@68 261 \fIfin\fP,
jpayne@68 262 \fIfout \fP
jpayne@68 263 and
jpayne@68 264 \fIferr \fP
jpayne@68 265 are the input, output, and error streams (respectively) to use.
jpayne@68 266 In this documentation, references to
jpayne@68 267 ``the tty''
jpayne@68 268 are actually to this input/output stream combination.
jpayne@68 269 .TP
jpayne@68 270 \fBel_init_fd\fP()
jpayne@68 271 Like
jpayne@68 272 \fBel_init\fP()
jpayne@68 273 but allows specifying file descriptors for the
jpayne@68 274 \fBstdio\fP(3)
jpayne@68 275 corresponding streams, in case those were created with
jpayne@68 276 \fBfunopen\fP(3).
jpayne@68 277 .TP
jpayne@68 278 \fBel_end\fP()
jpayne@68 279 Clean up and finish with
jpayne@68 280 \fIe\fP,
jpayne@68 281 assumed to have been created with
jpayne@68 282 \fBel_init\fP()
jpayne@68 283 or
jpayne@68 284 \fBel_init_fd\fP().
jpayne@68 285 .TP
jpayne@68 286 \fBel_reset\fP()
jpayne@68 287 Reset the tty and the parser.
jpayne@68 288 This should be called after an error which may have upset the tty's
jpayne@68 289 state.
jpayne@68 290 .TP
jpayne@68 291 \fBel_gets\fP()
jpayne@68 292 Read a line from the tty.
jpayne@68 293 \fIcount \fP
jpayne@68 294 is modified to contain the number of characters read.
jpayne@68 295 Returns the line read if successful, or
jpayne@68 296 NULL
jpayne@68 297 if no characters were read or if an error occurred.
jpayne@68 298 If an error occurred,
jpayne@68 299 \fIcount \fP
jpayne@68 300 is set to \-1 and
jpayne@68 301 errno
jpayne@68 302 contains the error code that caused it.
jpayne@68 303 The return value may not remain valid across calls to
jpayne@68 304 \fBel_gets\fP()
jpayne@68 305 and must be copied if the data is to be retained.
jpayne@68 306 .TP
jpayne@68 307 \fBel_wgetc\fP()
jpayne@68 308 Read a wide character from the tty, respecting the current locale,
jpayne@68 309 or from the input queue described in
jpayne@68 310 \fBeditline\fP(7)
jpayne@68 311 if that is not empty, and store it in
jpayne@68 312 \fIwc\fP.
jpayne@68 313 If an invalid or incomplete character is found, it is discarded,
jpayne@68 314 \fIerrno\fP
jpayne@68 315 is set to
jpayne@68 316 Er EILSEQ ,
jpayne@68 317 and the next character is read and stored in
jpayne@68 318 \fIwc\fP.
jpayne@68 319 Returns 1 if a valid character was read, 0 on end of file, or \-1 on
jpayne@68 320 \fBread\fP(2)
jpayne@68 321 failure.
jpayne@68 322 In the latter case,
jpayne@68 323 \fIerrno\fP
jpayne@68 324 is set to indicate the error.
jpayne@68 325 .TP
jpayne@68 326 \fBel_getc\fP()
jpayne@68 327 Read a wide character as described for
jpayne@68 328 \fBel_wgetc\fP()
jpayne@68 329 and return 0 on end of file or \-1 on failure.
jpayne@68 330 If the wide character can be represented as a single-byte character,
jpayne@68 331 convert it with
jpayne@68 332 \fBwctob\fP(3),
jpayne@68 333 store the result in
jpayne@68 334 \fIch\fP,
jpayne@68 335 and return 1; otherwise, set
jpayne@68 336 \fIerrno\fP
jpayne@68 337 to
jpayne@68 338 Er ERANGE
jpayne@68 339 and return \-1.
jpayne@68 340 In the C or POSIX locale, this simply reads a byte, but for any other
jpayne@68 341 locale, including UTF-8, this is rarely useful.
jpayne@68 342 .TP
jpayne@68 343 \fBel_wpush\fP()
jpayne@68 344 Push the wide character string
jpayne@68 345 \fIwcs \fP
jpayne@68 346 back onto the input queue described in
jpayne@68 347 \fBeditline\fP(7).
jpayne@68 348 If the queue overflows, for example due to a recursive macro,
jpayne@68 349 or if an error occurs, for example because
jpayne@68 350 \fIwcs \fP
jpayne@68 351 is
jpayne@68 352 NULL
jpayne@68 353 or memory allocation fails, the function beeps at the user,
jpayne@68 354 but does not report the problem to the caller.
jpayne@68 355 .TP
jpayne@68 356 \fBel_push\fP()
jpayne@68 357 Use the current locale to convert the multibyte string
jpayne@68 358 \fImbs \fP
jpayne@68 359 to a wide character string, and pass the result to
jpayne@68 360 \fBel_wpush\fP().
jpayne@68 361 .TP
jpayne@68 362 \fBel_parse\fP()
jpayne@68 363 Parses the
jpayne@68 364 \fIargv \fP
jpayne@68 365 array (which is
jpayne@68 366 \fIargc \fP
jpayne@68 367 elements in size)
jpayne@68 368 to execute builtin
jpayne@68 369 \fBeditline\fP
jpayne@68 370 commands.
jpayne@68 371 If the command is prefixed with
jpayne@68 372 ``prog :''
jpayne@68 373 then
jpayne@68 374 \fBel_parse\fP()
jpayne@68 375 will only execute the command if
jpayne@68 376 ``prog''
jpayne@68 377 matches the
jpayne@68 378 \fIprog \fP
jpayne@68 379 argument supplied to
jpayne@68 380 \fBel_init\fP().
jpayne@68 381 The return value is
jpayne@68 382 \-1 if the command is unknown,
jpayne@68 383 0 if there was no error or
jpayne@68 384 ``prog''
jpayne@68 385 didn't match, or
jpayne@68 386 1 if the command returned an error.
jpayne@68 387 Refer to
jpayne@68 388 \fBeditrc\fP(5)
jpayne@68 389 for more information.
jpayne@68 390 .TP
jpayne@68 391 \fBel_set\fP()
jpayne@68 392 Set
jpayne@68 393 \fBeditline\fP
jpayne@68 394 parameters.
jpayne@68 395 \fIop \fP
jpayne@68 396 determines which parameter to set, and each operation has its
jpayne@68 397 own parameter list.
jpayne@68 398 Returns 0 on success, \-1 on failure.
jpayne@68 399
jpayne@68 400 The following values for
jpayne@68 401 \fIop \fP
jpayne@68 402 are supported, along with the required argument list:
jpayne@68 403 .RS
jpayne@68 404 .TP
jpayne@68 405 EL_PROMPT , \fIchar *(*f)(EditLine *)\fP
jpayne@68 406 Define prompt printing function as
jpayne@68 407 \fIf\fP,
jpayne@68 408 which is to return a string that contains the prompt.
jpayne@68 409 .TP
jpayne@68 410 EL_PROMPT_ESC , \fIchar *(*f)(EditLine *), Fa char c\fP
jpayne@68 411 Same as
jpayne@68 412 EL_PROMPT ,
jpayne@68 413 but the
jpayne@68 414 \fIc \fP
jpayne@68 415 argument indicates the start/stop literal prompt character.
jpayne@68 416
jpayne@68 417 If a start/stop literal character is found in the prompt, the
jpayne@68 418 character itself
jpayne@68 419 is not printed, but characters after it are printed directly to the
jpayne@68 420 terminal without affecting the state of the current line.
jpayne@68 421 A subsequent second start/stop literal character ends this behavior.
jpayne@68 422 This is typically used to embed literal escape sequences that change the
jpayne@68 423 color/style of the terminal in the prompt.
jpayne@68 424 Note that the literal escape character cannot be the last character in the
jpayne@68 425 prompt, as the escape sequence is attached to the next character in the prompt.
jpayne@68 426 0
jpayne@68 427 unsets it.
jpayne@68 428 .TP
jpayne@68 429 EL_REFRESH
jpayne@68 430 Re-display the current line on the next terminal line.
jpayne@68 431 .TP
jpayne@68 432 EL_RPROMPT , \fIchar *(*f)(EditLine *)\fP
jpayne@68 433 Define right side prompt printing function as
jpayne@68 434 \fIf\fP,
jpayne@68 435 which is to return a string that contains the prompt.
jpayne@68 436 .TP
jpayne@68 437 EL_RPROMPT_ESC , \fIchar *(*f)(EditLine *), Fa char c\fP
jpayne@68 438 Define the right prompt printing function but with a literal escape character.
jpayne@68 439 .TP
jpayne@68 440 EL_TERMINAL , \fIconst char *type\fP
jpayne@68 441 Define terminal type of the tty to be
jpayne@68 442 \fItype\fP,
jpayne@68 443 or to
jpayne@68 444 .IR TERM
jpayne@68 445 if
jpayne@68 446 \fItype \fP
jpayne@68 447 is
jpayne@68 448 NULL .
jpayne@68 449 .TP
jpayne@68 450 EL_EDITOR , \fIconst char *mode\fP
jpayne@68 451 Set editing mode to
jpayne@68 452 \fImode\fP,
jpayne@68 453 which must be one of
jpayne@68 454 ``emacs''
jpayne@68 455 or
jpayne@68 456 ``vi''.
jpayne@68 457 .TP
jpayne@68 458 EL_SIGNAL , \fIint flag\fP
jpayne@68 459 If
jpayne@68 460 \fIflag \fP
jpayne@68 461 is non-zero,
jpayne@68 462 \fBeditline\fP
jpayne@68 463 will install its own signal handler for the following signals when
jpayne@68 464 reading command input:
jpayne@68 465 SIGCONT ,
jpayne@68 466 SIGHUP ,
jpayne@68 467 SIGINT ,
jpayne@68 468 SIGQUIT ,
jpayne@68 469 SIGSTOP ,
jpayne@68 470 SIGTERM ,
jpayne@68 471 SIGTSTP ,
jpayne@68 472 and
jpayne@68 473 SIGWINCH .
jpayne@68 474 Otherwise, the current signal handlers will be used.
jpayne@68 475 .TP
jpayne@68 476 EL_BIND , \fIconst char *, Fa ..., Dv NULL \fP
jpayne@68 477 Perform the
jpayne@68 478 \fBbind\fP
jpayne@68 479 builtin command.
jpayne@68 480 Refer to
jpayne@68 481 \fBeditrc\fP(5)
jpayne@68 482 for more information.
jpayne@68 483 .TP
jpayne@68 484 EL_ECHOTC , \fIconst char *, Fa ..., Dv NULL \fP
jpayne@68 485 Perform the
jpayne@68 486 \fBechotc\fP
jpayne@68 487 builtin command.
jpayne@68 488 Refer to
jpayne@68 489 \fBeditrc\fP(5)
jpayne@68 490 for more information.
jpayne@68 491 .TP
jpayne@68 492 EL_SETTC , \fIconst char *, Fa ..., Dv NULL \fP
jpayne@68 493 Perform the
jpayne@68 494 \fBsettc\fP
jpayne@68 495 builtin command.
jpayne@68 496 Refer to
jpayne@68 497 \fBeditrc\fP(5)
jpayne@68 498 for more information.
jpayne@68 499 .TP
jpayne@68 500 EL_SETTY , \fIconst char *, Fa ..., Dv NULL \fP
jpayne@68 501 Perform the
jpayne@68 502 \fBsetty\fP
jpayne@68 503 builtin command.
jpayne@68 504 Refer to
jpayne@68 505 \fBeditrc\fP(5)
jpayne@68 506 for more information.
jpayne@68 507 .TP
jpayne@68 508 EL_TELLTC , \fIconst char *, Fa ..., Dv NULL \fP
jpayne@68 509 Perform the
jpayne@68 510 \fBtelltc\fP
jpayne@68 511 builtin command.
jpayne@68 512 Refer to
jpayne@68 513 \fBeditrc\fP(5)
jpayne@68 514 for more information.
jpayne@68 515 .TP
jpayne@68 516 EL_ADDFN , \fIconst char *name, Fa const char *help, \ \fP
jpayne@68 517 Fa "unsigned char (*func)(EditLine *e, int ch)"
jpayne@68 518 Add a user defined function,
jpayne@68 519 \fBfunc\fP(),
jpayne@68 520 referred to as
jpayne@68 521 \fIname \fP
jpayne@68 522 which is invoked when a key which is bound to
jpayne@68 523 \fIname \fP
jpayne@68 524 is entered.
jpayne@68 525 \fIhelp \fP
jpayne@68 526 is a description of
jpayne@68 527 \fIname\fP.
jpayne@68 528 At invocation time,
jpayne@68 529 \fIch \fP
jpayne@68 530 is the key which caused the invocation.
jpayne@68 531 The return value of
jpayne@68 532 \fBfunc\fP()
jpayne@68 533 should be one of:
jpayne@68 534 .RS
jpayne@68 535 .TP
jpayne@68 536 CC_NORM
jpayne@68 537 Add a normal character.
jpayne@68 538 .TP
jpayne@68 539 CC_NEWLINE
jpayne@68 540 End of line was entered.
jpayne@68 541 .TP
jpayne@68 542 CC_EOF
jpayne@68 543 EOF was entered.
jpayne@68 544 .TP
jpayne@68 545 CC_ARGHACK
jpayne@68 546 Expecting further command input as arguments, do nothing visually.
jpayne@68 547 .TP
jpayne@68 548 CC_REFRESH
jpayne@68 549 Refresh display.
jpayne@68 550 .TP
jpayne@68 551 CC_REFRESH_BEEP
jpayne@68 552 Refresh display, and beep.
jpayne@68 553 .TP
jpayne@68 554 CC_CURSOR
jpayne@68 555 Cursor moved, so update and perform
jpayne@68 556 CC_REFRESH .
jpayne@68 557 .TP
jpayne@68 558 CC_REDISPLAY
jpayne@68 559 Redisplay entire input line.
jpayne@68 560 This is useful if a key binding outputs extra information.
jpayne@68 561 .TP
jpayne@68 562 CC_ERROR
jpayne@68 563 An error occurred.
jpayne@68 564 Beep, and flush tty.
jpayne@68 565 .TP
jpayne@68 566 CC_FATAL
jpayne@68 567 Fatal error, reset tty to known state.
jpayne@68 568 .RE
jpayne@68 569 .TP
jpayne@68 570 EL_HIST , \fIHistory *(*func)(History *, int op, ...), \ \fP
jpayne@68 571 Fa "const char *ptr"
jpayne@68 572 Defines which history function to use, which is usually
jpayne@68 573 \fBhistory\fP().
jpayne@68 574 \fIptr \fP
jpayne@68 575 should be the value returned by
jpayne@68 576 \fBhistory_init\fP().
jpayne@68 577 .TP
jpayne@68 578 EL_EDITMODE , \fIint flag\fP
jpayne@68 579 If
jpayne@68 580 \fIflag \fP
jpayne@68 581 is non-zero,
jpayne@68 582 editing is enabled (the default).
jpayne@68 583 Note that this is only an indication, and does not
jpayne@68 584 affect the operation of
jpayne@68 585 \fB.\fP
jpayne@68 586 At this time, it is the caller's responsibility to
jpayne@68 587 check this
jpayne@68 588 (using
jpayne@68 589 \fBel_get\fP() )
jpayne@68 590 to determine if editing should be enabled or not.
jpayne@68 591 .TP
jpayne@68 592 EL_UNBUFFERED , \fIint flag\fP
jpayne@68 593 If
jpayne@68 594 \fIflag \fP
jpayne@68 595 is zero,
jpayne@68 596 unbuffered mode is disabled (the default).
jpayne@68 597 In unbuffered mode,
jpayne@68 598 \fBel_gets\fP()
jpayne@68 599 will return immediately after processing a single character.
jpayne@68 600 .TP
jpayne@68 601 EL_SAFEREAD , \fIint flag\fP
jpayne@68 602 If the
jpayne@68 603 \fIflag \fP
jpayne@68 604 argument is non-zero, then
jpayne@68 605 \fBeditline\fP
jpayne@68 606 attempts to recover from read errors, ignoring the first interrupted
jpayne@68 607 error, and trying to reset the input file descriptor to reset non-blocking I/O.
jpayne@68 608 This is disabled by default, and desirable only when
jpayne@68 609 \fBeditline\fP
jpayne@68 610 is used in shell-like applications.
jpayne@68 611 .TP
jpayne@68 612 EL_GETCFN , \fIel_rfunc_t f\fP
jpayne@68 613 Whenever reading a character, use the function
jpayne@68 614 -ragged -offset indent -compact
jpayne@68 615 .PP
jpayne@68 616 \fIint\fP
jpayne@68 617 .br
jpayne@68 618 Fo f
jpayne@68 619 \fIEditLine *e\fP
jpayne@68 620 \fIwchar_t *wc\fP
jpayne@68 621 Fc
jpayne@68 622 which stores the character in
jpayne@68 623 \fIwc \fP
jpayne@68 624 and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding
jpayne@68 625 errors.
jpayne@68 626 Functions internally using it include
jpayne@68 627 \fBel_wgets\fP(),
jpayne@68 628 \fBel_wgetc\fP(),
jpayne@68 629 \fBel_gets\fP(),
jpayne@68 630 and
jpayne@68 631 \fBel_getc\fP().
jpayne@68 632 Initially, a builtin function is installed, and replacing it
jpayne@68 633 is discouraged because writing such a function is very error prone.
jpayne@68 634 The builtin function can be restored at any time by passing the
jpayne@68 635 special value
jpayne@68 636 EL_BUILTIN_GETCFN
jpayne@68 637 instead of a function pointer.
jpayne@68 638 .TP
jpayne@68 639 EL_CLIENTDATA , \fIvoid *data\fP
jpayne@68 640 Register
jpayne@68 641 \fIdata \fP
jpayne@68 642 to be associated with this EditLine structure.
jpayne@68 643 It can be retrieved with the corresponding
jpayne@68 644 \fBel_get\fP();
jpayne@68 645 call.
jpayne@68 646 .TP
jpayne@68 647 EL_SETFP , \fIint fd, Fa FILE *fp\fP
jpayne@68 648 Set the current
jpayne@68 649 \fBeditline\fP
jpayne@68 650 file pointer for
jpayne@68 651 ``input''
jpayne@68 652 \fIfd \fP
jpayne@68 653 =
jpayne@68 654 0 ,
jpayne@68 655 ``output''
jpayne@68 656 \fIfd \fP
jpayne@68 657 =
jpayne@68 658 1 ,
jpayne@68 659 or
jpayne@68 660 ``error''
jpayne@68 661 \fIfd \fP
jpayne@68 662 =
jpayne@68 663 2
jpayne@68 664 from
jpayne@68 665 \fIfp\fP.
jpayne@68 666 .RE
jpayne@68 667 .TP
jpayne@68 668 \fBel_get\fP()
jpayne@68 669 Get
jpayne@68 670 \fBeditline\fP
jpayne@68 671 parameters.
jpayne@68 672 \fIop \fP
jpayne@68 673 determines which parameter to retrieve into
jpayne@68 674 \fIresult\fP.
jpayne@68 675 Returns 0 if successful, \-1 otherwise.
jpayne@68 676
jpayne@68 677 The following values for
jpayne@68 678 \fIop \fP
jpayne@68 679 are supported, along with actual type of
jpayne@68 680 \fIresult : \fP
jpayne@68 681 .RS
jpayne@68 682 .TP
jpayne@68 683 EL_PROMPT , \fIchar *(*f)(EditLine *), Fa char *c\fP
jpayne@68 684 Set
jpayne@68 685 \fIf \fP
jpayne@68 686 to a pointer to the function that displays the prompt.
jpayne@68 687 If
jpayne@68 688 \fIc \fP
jpayne@68 689 is not
jpayne@68 690 NULL ,
jpayne@68 691 set it to the start/stop literal prompt character.
jpayne@68 692 .TP
jpayne@68 693 EL_RPROMPT , \fIchar *(*f)(EditLine *), Fa char *c\fP
jpayne@68 694 Set
jpayne@68 695 \fIf \fP
jpayne@68 696 to a pointer to the function that displays the prompt.
jpayne@68 697 If
jpayne@68 698 \fIc \fP
jpayne@68 699 is not
jpayne@68 700 NULL ,
jpayne@68 701 set it to the start/stop literal prompt character.
jpayne@68 702 .TP
jpayne@68 703 EL_EDITOR , \fIconst char **n\fP
jpayne@68 704 Set the name of the editor in
jpayne@68 705 \fIn\fP,
jpayne@68 706 which will be one of
jpayne@68 707 ``emacs''
jpayne@68 708 or
jpayne@68 709 ``vi''.
jpayne@68 710 .TP
jpayne@68 711 EL_GETTC , \fIconst char *name, Fa void *value\fP
jpayne@68 712 If
jpayne@68 713 \fIname \fP
jpayne@68 714 is a valid
jpayne@68 715 \fBtermcap\fP(5)
jpayne@68 716 capability set
jpayne@68 717 \fIvalue \fP
jpayne@68 718 to the current value of that capability.
jpayne@68 719 .TP
jpayne@68 720 EL_SIGNAL , \fIint *s\fP
jpayne@68 721 Set
jpayne@68 722 \fIs \fP
jpayne@68 723 to non-zero if
jpayne@68 724 \fBeditline\fP
jpayne@68 725 has installed private signal handlers (see
jpayne@68 726 \fBel_get\fP()
jpayne@68 727 above).
jpayne@68 728 .TP
jpayne@68 729 EL_EDITMODE , \fIint *c\fP
jpayne@68 730 Set
jpayne@68 731 \fIc \fP
jpayne@68 732 to non-zero if editing is enabled.
jpayne@68 733 .TP
jpayne@68 734 EL_GETCFN , \fIel_rfunc_t *f\fP
jpayne@68 735 Set
jpayne@68 736 \fIf \fP
jpayne@68 737 to a pointer to the function that reads characters, or to
jpayne@68 738 EL_BUILTIN_GETCFN
jpayne@68 739 if the builtin function is in use.
jpayne@68 740 .TP
jpayne@68 741 EL_CLIENTDATA , \fIvoid **data\fP
jpayne@68 742 Set
jpayne@68 743 \fIdata \fP
jpayne@68 744 to the previously registered client data set by an
jpayne@68 745 \fBel_set\fP()
jpayne@68 746 call.
jpayne@68 747 .TP
jpayne@68 748 EL_UNBUFFERED , \fIint *c\fP
jpayne@68 749 Set
jpayne@68 750 \fIc \fP
jpayne@68 751 to non-zero if unbuffered mode is enabled.
jpayne@68 752 .TP
jpayne@68 753 EL_SAFEREAD , \fIint *c\fP
jpayne@68 754 Set
jpayne@68 755 \fIc \fP
jpayne@68 756 to non-zero if safe read is set.
jpayne@68 757 .TP
jpayne@68 758 EL_GETFP , \fIint fd", Fa FILE **fp\fP
jpayne@68 759 Set
jpayne@68 760 \fIfp \fP
jpayne@68 761 to the current
jpayne@68 762 \fBeditline\fP
jpayne@68 763 file pointer for
jpayne@68 764 ``input''
jpayne@68 765 \fIfd \fP
jpayne@68 766 =
jpayne@68 767 0 ,
jpayne@68 768 ``output''
jpayne@68 769 \fIfd \fP
jpayne@68 770 =
jpayne@68 771 1 ,
jpayne@68 772 or
jpayne@68 773 ``error''
jpayne@68 774 \fIfd \fP
jpayne@68 775 =
jpayne@68 776 2 .
jpayne@68 777 .RE
jpayne@68 778 .TP
jpayne@68 779 \fBel_source\fP()
jpayne@68 780 Initialize
jpayne@68 781 \fBeditline\fP
jpayne@68 782 by reading the contents of
jpayne@68 783 \fIfile\fP.
jpayne@68 784 \fBel_parse\fP()
jpayne@68 785 is called for each line in
jpayne@68 786 \fIfile\fP.
jpayne@68 787 If
jpayne@68 788 \fIfile \fP
jpayne@68 789 is
jpayne@68 790 NULL ,
jpayne@68 791 try
jpayne@68 792 \fI$EDITRC\fP
jpayne@68 793 and if that is not set
jpayne@68 794 \fI$HOME/.editrc\fP.
jpayne@68 795 Refer to
jpayne@68 796 \fBeditrc\fP(5)
jpayne@68 797 for details on the format of
jpayne@68 798 \fIfile\fP.
jpayne@68 799 \fBel_source\fP()
jpayne@68 800 returns 0 on success and \-1 on error.
jpayne@68 801 .TP
jpayne@68 802 \fBel_resize\fP()
jpayne@68 803 Must be called if the terminal size changes.
jpayne@68 804 If
jpayne@68 805 EL_SIGNAL
jpayne@68 806 has been set with
jpayne@68 807 \fBel_set\fP(),
jpayne@68 808 then this is done automatically.
jpayne@68 809 Otherwise, it's the responsibility of the application to call
jpayne@68 810 \fBel_resize\fP()
jpayne@68 811 on the appropriate occasions.
jpayne@68 812 .TP
jpayne@68 813 \fBel_cursor\fP()
jpayne@68 814 Move the cursor to the right (if positive) or to the left (if negative)
jpayne@68 815 \fIcount \fP
jpayne@68 816 characters.
jpayne@68 817 Returns the resulting offset of the cursor from the beginning of the line.
jpayne@68 818 .TP
jpayne@68 819 \fBel_line\fP()
jpayne@68 820 Return the editing information for the current line in a
jpayne@68 821 \fILineInfo \fP
jpayne@68 822 structure, which is defined as follows:
jpayne@68 823
jpayne@68 824 typedef struct lineinfo {
jpayne@68 825 .br
jpayne@68 826 const char *buffer; /* address of buffer */
jpayne@68 827 .br
jpayne@68 828 const char *cursor; /* address of cursor */
jpayne@68 829 .br
jpayne@68 830 const char *lastchar; /* address of last character */
jpayne@68 831 .br
jpayne@68 832 } LineInfo;
jpayne@68 833 .br
jpayne@68 834
jpayne@68 835 \fIbuffer \fP
jpayne@68 836 is not NUL terminated.
jpayne@68 837 This function may be called after
jpayne@68 838 \fBel_gets\fP()
jpayne@68 839 to obtain the
jpayne@68 840 \fILineInfo \fP
jpayne@68 841 structure pertaining to line returned by that function,
jpayne@68 842 and from within user defined functions added with
jpayne@68 843 EL_ADDFN .
jpayne@68 844 .TP
jpayne@68 845 \fBel_insertstr\fP()
jpayne@68 846 Insert
jpayne@68 847 \fIstr \fP
jpayne@68 848 into the line at the cursor.
jpayne@68 849 Returns \-1 if
jpayne@68 850 \fIstr \fP
jpayne@68 851 is empty or won't fit, and 0 otherwise.
jpayne@68 852 .TP
jpayne@68 853 \fBel_deletestr\fP()
jpayne@68 854 Delete
jpayne@68 855 \fIcount \fP
jpayne@68 856 characters before the cursor.
jpayne@68 857 .SH HISTORY LIST FUNCTIONS
jpayne@68 858 The history functions use a common data structure,
jpayne@68 859 \fIHistory\fP,
jpayne@68 860 which is created by
jpayne@68 861 \fBhistory_init\fP()
jpayne@68 862 and freed by
jpayne@68 863 \fBhistory_end\fP().
jpayne@68 864
jpayne@68 865 The following functions are available:
jpayne@68 866 .TP
jpayne@68 867 \fBhistory_init\fP()
jpayne@68 868 Initialize the history list, and return a data structure
jpayne@68 869 to be used by all other history list functions, or
jpayne@68 870 NULL
jpayne@68 871 on failure.
jpayne@68 872 .TP
jpayne@68 873 \fBhistory_end\fP()
jpayne@68 874 Clean up and finish with
jpayne@68 875 \fIh\fP,
jpayne@68 876 assumed to have been created with
jpayne@68 877 \fBhistory_init\fP().
jpayne@68 878 .TP
jpayne@68 879 \fBhistory\fP()
jpayne@68 880 Perform operation
jpayne@68 881 \fIop \fP
jpayne@68 882 on the history list, with optional arguments as needed by the
jpayne@68 883 operation.
jpayne@68 884 \fIev \fP
jpayne@68 885 is changed accordingly to operation.
jpayne@68 886 The following values for
jpayne@68 887 \fIop \fP
jpayne@68 888 are supported, along with the required argument list:
jpayne@68 889 .RS
jpayne@68 890 .TP
jpayne@68 891 H_SETSIZE , \fIint size\fP
jpayne@68 892 Set size of history to
jpayne@68 893 \fIsize \fP
jpayne@68 894 elements.
jpayne@68 895 .TP
jpayne@68 896 H_GETSIZE
jpayne@68 897 Get number of events currently in history.
jpayne@68 898 .TP
jpayne@68 899 H_END
jpayne@68 900 Cleans up and finishes with
jpayne@68 901 \fIh\fP,
jpayne@68 902 assumed to be created with
jpayne@68 903 \fBhistory_init\fP().
jpayne@68 904 .TP
jpayne@68 905 H_CLEAR
jpayne@68 906 Clear the history.
jpayne@68 907 .TP
jpayne@68 908 H_FUNC , \fIvoid *ptr, Fa history_gfun_t first, \ \fP
jpayne@68 909 Fa "history_gfun_t next" , Fa "history_gfun_t last" , \
jpayne@68 910 Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \
jpayne@68 911 Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \
jpayne@68 912 Fa "history_efun_t enter" , Fa "history_efun_t add"
jpayne@68 913 Define functions to perform various history operations.
jpayne@68 914 \fIptr \fP
jpayne@68 915 is the argument given to a function when it's invoked.
jpayne@68 916 .TP
jpayne@68 917 H_FIRST
jpayne@68 918 Return the first element in the history.
jpayne@68 919 .TP
jpayne@68 920 H_LAST
jpayne@68 921 Return the last element in the history.
jpayne@68 922 .TP
jpayne@68 923 H_PREV
jpayne@68 924 Return the previous element in the history.
jpayne@68 925 It is newer than the current one.
jpayne@68 926 .TP
jpayne@68 927 H_NEXT
jpayne@68 928 Return the next element in the history.
jpayne@68 929 It is older than the current one.
jpayne@68 930 .TP
jpayne@68 931 H_CURR
jpayne@68 932 Return the current element in the history.
jpayne@68 933 .TP
jpayne@68 934 H_SET , \fIint position\fP
jpayne@68 935 Set the cursor to point to the requested element.
jpayne@68 936 .TP
jpayne@68 937 H_ADD , \fIconst char *str\fP
jpayne@68 938 Append
jpayne@68 939 \fIstr \fP
jpayne@68 940 to the current element of the history, or perform the
jpayne@68 941 H_ENTER
jpayne@68 942 operation with argument
jpayne@68 943 \fIstr \fP
jpayne@68 944 if there is no current element.
jpayne@68 945 .TP
jpayne@68 946 H_APPEND , \fIconst char *str\fP
jpayne@68 947 Append
jpayne@68 948 \fIstr \fP
jpayne@68 949 to the last new element of the history.
jpayne@68 950 .TP
jpayne@68 951 H_ENTER , \fIconst char *str\fP
jpayne@68 952 Add
jpayne@68 953 \fIstr \fP
jpayne@68 954 as a new element to the history and, if necessary,
jpayne@68 955 removing the oldest entry to keep the list to the created size.
jpayne@68 956 If
jpayne@68 957 H_SETUNIQUE
jpayne@68 958 has been called with a non-zero argument, the element
jpayne@68 959 will not be entered into the history if its contents match
jpayne@68 960 the ones of the current history element.
jpayne@68 961 If the element is entered
jpayne@68 962 \fBhistory\fP()
jpayne@68 963 returns 1; if it is ignored as a duplicate returns 0.
jpayne@68 964 Finally
jpayne@68 965 \fBhistory\fP()
jpayne@68 966 returns \-1 if an error occurred.
jpayne@68 967 .TP
jpayne@68 968 H_PREV_STR , \fIconst char *str\fP
jpayne@68 969 Return the closest previous event that starts with
jpayne@68 970 \fIstr\fP.
jpayne@68 971 .TP
jpayne@68 972 H_NEXT_STR , \fIconst char *str\fP
jpayne@68 973 Return the closest next event that starts with
jpayne@68 974 \fIstr\fP.
jpayne@68 975 .TP
jpayne@68 976 H_PREV_EVENT , \fIint e\fP
jpayne@68 977 Return the previous event numbered
jpayne@68 978 \fIe\fP.
jpayne@68 979 .TP
jpayne@68 980 H_NEXT_EVENT , \fIint e\fP
jpayne@68 981 Return the next event numbered
jpayne@68 982 \fIe\fP.
jpayne@68 983 .TP
jpayne@68 984 H_LOAD , \fIconst char *file\fP
jpayne@68 985 Load the history list stored in
jpayne@68 986 \fIfile\fP.
jpayne@68 987 .TP
jpayne@68 988 H_SAVE , \fIconst char *file\fP
jpayne@68 989 Save the history list to
jpayne@68 990 \fIfile\fP.
jpayne@68 991 .TP
jpayne@68 992 H_SAVE_FP , \fIFILE *fp\fP
jpayne@68 993 Save the history list to the opened
jpayne@68 994 .PP
jpayne@68 995 \fIFILE\fP
jpayne@68 996 .br
jpayne@68 997 pointer
jpayne@68 998 \fIfp\fP.
jpayne@68 999 .TP
jpayne@68 1000 H_NSAVE_FP , \fIsize_t n, Fa FILE *fp\fP
jpayne@68 1001 Save the last
jpayne@68 1002 .PP
jpayne@68 1003 \fIn\fP
jpayne@68 1004 .br
jpayne@68 1005 history entries to the opened
jpayne@68 1006 .PP
jpayne@68 1007 \fIFILE\fP
jpayne@68 1008 .br
jpayne@68 1009 pointer
jpayne@68 1010 \fIfp\fP.
jpayne@68 1011 .TP
jpayne@68 1012 H_SETUNIQUE , \fIint unique\fP
jpayne@68 1013 Set flag that adjacent identical event strings should not be entered
jpayne@68 1014 into the history.
jpayne@68 1015 .TP
jpayne@68 1016 H_GETUNIQUE
jpayne@68 1017 Retrieve the current setting if adjacent identical elements should
jpayne@68 1018 be entered into the history.
jpayne@68 1019 .TP
jpayne@68 1020 H_DEL , \fIint e\fP
jpayne@68 1021 Delete the event numbered
jpayne@68 1022 \fIe\fP.
jpayne@68 1023 This function is only provided for
jpayne@68 1024 \fBreadline\fP
jpayne@68 1025 compatibility.
jpayne@68 1026 The caller is responsible for free'ing the string in the returned
jpayne@68 1027 \fIHistEvent\fP.
jpayne@68 1028 .RE
jpayne@68 1029
jpayne@68 1030 \fBhistory\fP();
jpayne@68 1031 returns >= 0 if the operation
jpayne@68 1032 \fIop \fP
jpayne@68 1033 succeeds.
jpayne@68 1034 Otherwise, \-1 is returned and
jpayne@68 1035 \fIev \fP
jpayne@68 1036 is updated to contain more details about the error.
jpayne@68 1037 .SH TOKENIZATION FUNCTIONS
jpayne@68 1038 The tokenization functions use a common data structure,
jpayne@68 1039 \fITokenizer\fP,
jpayne@68 1040 which is created by
jpayne@68 1041 \fBtok_init\fP()
jpayne@68 1042 and freed by
jpayne@68 1043 \fBtok_end\fP().
jpayne@68 1044
jpayne@68 1045 The following functions are available:
jpayne@68 1046 .TP
jpayne@68 1047 \fBtok_init\fP()
jpayne@68 1048 Initialize the tokenizer, and return a data structure
jpayne@68 1049 to be used by all other tokenizer functions.
jpayne@68 1050 \fIIFS \fP
jpayne@68 1051 contains the Input Field Separators, which defaults to
jpayne@68 1052 <space ,>
jpayne@68 1053 <tab ,>
jpayne@68 1054 and
jpayne@68 1055 <newline>
jpayne@68 1056 if
jpayne@68 1057 NULL .
jpayne@68 1058 .TP
jpayne@68 1059 \fBtok_end\fP()
jpayne@68 1060 Clean up and finish with
jpayne@68 1061 \fIt\fP,
jpayne@68 1062 assumed to have been created with
jpayne@68 1063 \fBtok_init\fP().
jpayne@68 1064 .TP
jpayne@68 1065 \fBtok_reset\fP()
jpayne@68 1066 Reset the tokenizer state.
jpayne@68 1067 Use after a line has been successfully tokenized
jpayne@68 1068 by
jpayne@68 1069 \fBtok_line\fP()
jpayne@68 1070 or
jpayne@68 1071 \fBtok_str\fP()
jpayne@68 1072 and before a new line is to be tokenized.
jpayne@68 1073 .TP
jpayne@68 1074 \fBtok_line\fP()
jpayne@68 1075 Tokenize
jpayne@68 1076 \fIli\fP,
jpayne@68 1077 If successful, modify:
jpayne@68 1078 \fIargv \fP
jpayne@68 1079 to contain the words,
jpayne@68 1080 \fIargc \fP
jpayne@68 1081 to contain the number of words,
jpayne@68 1082 \fIcursorc \fP
jpayne@68 1083 (if not
jpayne@68 1084 NULL )
jpayne@68 1085 to contain the index of the word containing the cursor,
jpayne@68 1086 and
jpayne@68 1087 \fIcursoro \fP
jpayne@68 1088 (if not
jpayne@68 1089 NULL )
jpayne@68 1090 to contain the offset within
jpayne@68 1091 \fIargv[cursorc] \fP
jpayne@68 1092 of the cursor.
jpayne@68 1093
jpayne@68 1094 Returns
jpayne@68 1095 0 if successful,
jpayne@68 1096 \-1 for an internal error,
jpayne@68 1097 1 for an unmatched single quote,
jpayne@68 1098 2 for an unmatched double quote,
jpayne@68 1099 and
jpayne@68 1100 3 for a backslash quoted
jpayne@68 1101 <newline .>
jpayne@68 1102 A positive exit code indicates that another line should be read
jpayne@68 1103 and tokenization attempted again.
jpayne@68 1104 .TP
jpayne@68 1105 \fBtok_str\fP()
jpayne@68 1106 A simpler form of
jpayne@68 1107 \fBtok_line\fP(; )
jpayne@68 1108 \fIstr \fP
jpayne@68 1109 is a NUL terminated string to tokenize.
jpayne@68 1110 .SH SEE ALSO
jpayne@68 1111 \fBsh\fP(1),
jpayne@68 1112 \fBsignal\fP(3),
jpayne@68 1113 \fBtermcap\fP(3),
jpayne@68 1114 \fBeditrc\fP(5),
jpayne@68 1115 \fBtermcap\fP(5),
jpayne@68 1116 \fBeditline\fP(7)
jpayne@68 1117 .SH HISTORY
jpayne@68 1118 The
jpayne@68 1119 \fBeditline\fP
jpayne@68 1120 library first appeared in
jpayne@68 1121 Bx 4.4 .
jpayne@68 1122 CC_REDISPLAY
jpayne@68 1123 appeared in
jpayne@68 1124 Nx 1.3 .
jpayne@68 1125 CC_REFRESH_BEEP ,
jpayne@68 1126 EL_EDITMODE
jpayne@68 1127 and the readline emulation appeared in
jpayne@68 1128 Nx 1.4 .
jpayne@68 1129 EL_RPROMPT
jpayne@68 1130 appeared in
jpayne@68 1131 Nx 1.5 .
jpayne@68 1132 .SH AUTHORS
jpayne@68 1133
jpayne@68 1134 -nosplit
jpayne@68 1135 The
jpayne@68 1136 \fBeditline\fP
jpayne@68 1137 library was written by
jpayne@68 1138
jpayne@68 1139 Christos Zoulas .
jpayne@68 1140
jpayne@68 1141 Luke Mewburn
jpayne@68 1142 wrote this manual and implemented
jpayne@68 1143 CC_REDISPLAY ,
jpayne@68 1144 CC_REFRESH_BEEP ,
jpayne@68 1145 EL_EDITMODE ,
jpayne@68 1146 and
jpayne@68 1147 EL_RPROMPT .
jpayne@68 1148
jpayne@68 1149 Jaromir Dolecek
jpayne@68 1150 implemented the readline emulation.
jpayne@68 1151
jpayne@68 1152 Johny Mattsson
jpayne@68 1153 implemented wide-character support.
jpayne@68 1154 .SH BUGS
jpayne@68 1155 At this time, it is the responsibility of the caller to
jpayne@68 1156 check the result of the
jpayne@68 1157 EL_EDITMODE
jpayne@68 1158 operation of
jpayne@68 1159 \fBel_get\fP()
jpayne@68 1160 (after an
jpayne@68 1161 \fBel_source\fP()
jpayne@68 1162 or
jpayne@68 1163 \fBel_parse\fP() )
jpayne@68 1164 to determine if
jpayne@68 1165 \fBeditline\fP
jpayne@68 1166 should be used for further input.
jpayne@68 1167 I.e.,
jpayne@68 1168 EL_EDITMODE
jpayne@68 1169 is purely an indication of the result of the most recent
jpayne@68 1170 \fBeditrc\fP(5)
jpayne@68 1171 \fBedit\fP
jpayne@68 1172 command.