1c1
< .\" $NetBSD: editline.3,v 1.20 2000/02/28 17:41:05 chopps Exp $
---
> .\" $NetBSD: editline.3,v 1.48 2005/07/14 15:02:37 wiz Exp $
3c3
< .\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
---
> .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
36c36
< .\" $FreeBSD: head/lib/libedit/editline.3 141851 2005-02-13 23:45:54Z ru $
---
> .\" $FreeBSD: head/lib/libedit/editline.3 148834 2005-08-07 20:55:59Z stefanf $
38c38
< .Dd November 12, 1999
---
> .Dd July 14, 2005
58,59c58,64
< .Nm history
< .Nd line editor and history functions
---
> .Nm history ,
> .Nm tok_init ,
> .Nm tok_end ,
> .Nm tok_reset ,
> .Nm tok_line ,
> .Nm tok_str
> .Nd line editor, history and tokenization functions
77c82
< .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
---
> .Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
97a103,112
> .Ft Tokenizer *
> .Fn tok_init "const char *IFS"
> .Ft void
> .Fn tok_end "Tokenizer *t"
> .Ft void
> .Fn tok_reset "Tokenizer *t"
> .Ft int
> .Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro"
> .Ft int
> .Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]"
101c116
< library provides generic line editing and history functions,
---
> library provides generic line editing, history and tokenization functions,
157c172
< Returns the number of characters read if successful, -1 otherwise.
---
> Returns the number of characters read if successful, \-1 otherwise.
179c194
< .Dq prog:
---
> .Dq prog :
189c204
< -1 if the command is unknown,
---
> \-1 if the command is unknown,
308c323
< .Fa "unsigned char (*func)(EditLine *e, int ch)
---
> .Fa "unsigned char (*func)(EditLine *e, int ch)"
372a388,405
> .It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)"
> Define the character reading function as
> .Fa f ,
> which is to return the number of characters read and store them in
> .Fa c .
> This function is called internally by
> .Fn el_gets
> and
> .Fn el_getc .
> The builtin function can be set or restored with the special function
> name ``EL_BUILTIN_GETCFN''.
> .It Dv EL_CLIENTDATA , Fa "void *data"
> Register
> .Fa data
> to be associated with this EditLine structure.
> It can be retrieved with the corresponding
> .Fn el_get
> call.
380a414
> Returns 0 if successful, \-1 otherwise.
403a438,453
> .It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)"
> Return a pointer to the function that read characters, which is equal to
> ``EL_BUILTIN_GETCFN'' in the case of the default builtin function.
> .It Dv EL_CLIENTDATA , Fa "void **data"
> Retrieve
> .Fa data
> previously registered with the corresponding
> .Fn el_set
> call.
> .It Dv EL_UNBUFFERED, Fa "int"
> Sets or clears unbuffered mode.
> In this mode,
> .Fn el_gets
> will return immediately after processing a single character.
> .It Dv EL_PREP_TERM, Fa "int"
> Sets or clears terminal editing mode.
445a496,505
> .Pp
> .Fa buffer
> is not NUL terminated.
> This function may be called after
> .Fn el_gets
> to obtain the
> .Fa LineInfo
> structure pertaining to line returned by that function,
> and from within user defined functions added with
> .Dv EL_ADDFN .
450c510
< Returns -1 if
---
> Returns \-1 if
530c590,594
< to the current element of the history, or create an element with
---
> to the current element of the history, or perform the
> .Dv H_ENTER
> operation with argument
> .Fa str
> if there is no current element.
539a604,614
> If
> .Dv H_SETUNIQUE
> was has been called with a non-zero arguments, the element
> will not be entered into the history if its contents match
> the ones of the current history element.
> If the element is entered
> .Fn history
> returns 1, if it is ignored as a duplicate returns 0.
> Finally
> .Fn history
> returns \-1 if an error occurred.
557a633,646
> .It Dv H_SETUNIQUE , Fa "int unique"
> Set if the adjacent identical event strings should not be entered into
> the history.
> .It Dv H_GETUNIQUE
> Retrieve the current setting if if adjacent elements should be entered into
> the history.
> .It Dv H_DEL , Fa "int num"
> Delete the event numbered
> .Fa e .
> This function is only provided for
> .Xr readline 3
> compatibility.
> The caller is responsible for free'ing the string in the returned
> .Fa HistEvent .
568a658,729
> .Sh TOKENIZATION FUNCTIONS
> The tokenization functions use a common data structure,
> .Fa Tokenizer ,
> which is created by
> .Fn tok_init
> and freed by
> .Fn tok_end .
> .Pp
> The following functions are available:
> .Bl -tag -width 4n
> .It Fn tok_init
> Initialise the tokenizer, and return a data structure
> to be used by all other tokenizer functions.
> .Fa IFS
> contains the Input Field Separators, which defaults to
> .Aq space ,
> .Aq tab ,
> and
> .Aq newline
> if
> .Dv NULL .
> .It Fn tok_end
> Clean up and finish with
> .Fa t ,
> assumed to have been created with
> .Fn tok_init .
> .It Fn tok_reset
> Reset the tokenizer state.
> Use after a line has been successfully tokenized
> by
> .Fn tok_line
> or
> .Fn tok_str
> and before a new line is to be tokenized.
> .It Fn tok_line
> Tokenize
> .Fa li ,
> If successful, modify:
> .Fa argv
> to contain the words,
> .Fa argc
> to contain the number of words,
> .Fa cursorc
> (if not
> .Dv NULL )
> to contain the index of the word containing the cursor,
> and
> .Fa cursoro
> (if not
> .Dv NULL )
> to contain the offset within
> .Fa argv[cursorc]
> of the cursor.
> .Pp
> Returns
> 0 if successful,
> \-1 for an internal error,
> 1 for an unmatched single quote,
> 2 for an unmatched double quote,
> and
> 3 for a backslash quoted
> .Aq newline .
> A positive exit code indicates that another line should be read
> and tokenization attempted again.
> .
> .It Fn tok_str
> A simpler form of
> .Fn tok_line ;
> .Fa str
> is a NUL terminated string to tokenize.
> .El
> .
606,608d766
< The tokenization functions are not publically defined in
< .In histedit.h .
< .Pp
< .\" $NetBSD: editline.3,v 1.20 2000/02/28 17:41:05 chopps Exp $
---
> .\" $NetBSD: editline.3,v 1.48 2005/07/14 15:02:37 wiz Exp $
3c3
< .\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
---
> .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
36c36
< .\" $FreeBSD: head/lib/libedit/editline.3 141851 2005-02-13 23:45:54Z ru $
---
> .\" $FreeBSD: head/lib/libedit/editline.3 148834 2005-08-07 20:55:59Z stefanf $
38c38
< .Dd November 12, 1999
---
> .Dd July 14, 2005
58,59c58,64
< .Nm history
< .Nd line editor and history functions
---
> .Nm history ,
> .Nm tok_init ,
> .Nm tok_end ,
> .Nm tok_reset ,
> .Nm tok_line ,
> .Nm tok_str
> .Nd line editor, history and tokenization functions
77c82
< .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
---
> .Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
97a103,112
> .Ft Tokenizer *
> .Fn tok_init "const char *IFS"
> .Ft void
> .Fn tok_end "Tokenizer *t"
> .Ft void
> .Fn tok_reset "Tokenizer *t"
> .Ft int
> .Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro"
> .Ft int
> .Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]"
101c116
< library provides generic line editing and history functions,
---
> library provides generic line editing, history and tokenization functions,
157c172
< Returns the number of characters read if successful, -1 otherwise.
---
> Returns the number of characters read if successful, \-1 otherwise.
179c194
< .Dq prog:
---
> .Dq prog :
189c204
< -1 if the command is unknown,
---
> \-1 if the command is unknown,
308c323
< .Fa "unsigned char (*func)(EditLine *e, int ch)
---
> .Fa "unsigned char (*func)(EditLine *e, int ch)"
372a388,405
> .It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)"
> Define the character reading function as
> .Fa f ,
> which is to return the number of characters read and store them in
> .Fa c .
> This function is called internally by
> .Fn el_gets
> and
> .Fn el_getc .
> The builtin function can be set or restored with the special function
> name ``EL_BUILTIN_GETCFN''.
> .It Dv EL_CLIENTDATA , Fa "void *data"
> Register
> .Fa data
> to be associated with this EditLine structure.
> It can be retrieved with the corresponding
> .Fn el_get
> call.
380a414
> Returns 0 if successful, \-1 otherwise.
403a438,453
> .It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)"
> Return a pointer to the function that read characters, which is equal to
> ``EL_BUILTIN_GETCFN'' in the case of the default builtin function.
> .It Dv EL_CLIENTDATA , Fa "void **data"
> Retrieve
> .Fa data
> previously registered with the corresponding
> .Fn el_set
> call.
> .It Dv EL_UNBUFFERED, Fa "int"
> Sets or clears unbuffered mode.
> In this mode,
> .Fn el_gets
> will return immediately after processing a single character.
> .It Dv EL_PREP_TERM, Fa "int"
> Sets or clears terminal editing mode.
445a496,505
> .Pp
> .Fa buffer
> is not NUL terminated.
> This function may be called after
> .Fn el_gets
> to obtain the
> .Fa LineInfo
> structure pertaining to line returned by that function,
> and from within user defined functions added with
> .Dv EL_ADDFN .
450c510
< Returns -1 if
---
> Returns \-1 if
530c590,594
< to the current element of the history, or create an element with
---
> to the current element of the history, or perform the
> .Dv H_ENTER
> operation with argument
> .Fa str
> if there is no current element.
539a604,614
> If
> .Dv H_SETUNIQUE
> was has been called with a non-zero arguments, the element
> will not be entered into the history if its contents match
> the ones of the current history element.
> If the element is entered
> .Fn history
> returns 1, if it is ignored as a duplicate returns 0.
> Finally
> .Fn history
> returns \-1 if an error occurred.
557a633,646
> .It Dv H_SETUNIQUE , Fa "int unique"
> Set if the adjacent identical event strings should not be entered into
> the history.
> .It Dv H_GETUNIQUE
> Retrieve the current setting if if adjacent elements should be entered into
> the history.
> .It Dv H_DEL , Fa "int num"
> Delete the event numbered
> .Fa e .
> This function is only provided for
> .Xr readline 3
> compatibility.
> The caller is responsible for free'ing the string in the returned
> .Fa HistEvent .
568a658,729
> .Sh TOKENIZATION FUNCTIONS
> The tokenization functions use a common data structure,
> .Fa Tokenizer ,
> which is created by
> .Fn tok_init
> and freed by
> .Fn tok_end .
> .Pp
> The following functions are available:
> .Bl -tag -width 4n
> .It Fn tok_init
> Initialise the tokenizer, and return a data structure
> to be used by all other tokenizer functions.
> .Fa IFS
> contains the Input Field Separators, which defaults to
> .Aq space ,
> .Aq tab ,
> and
> .Aq newline
> if
> .Dv NULL .
> .It Fn tok_end
> Clean up and finish with
> .Fa t ,
> assumed to have been created with
> .Fn tok_init .
> .It Fn tok_reset
> Reset the tokenizer state.
> Use after a line has been successfully tokenized
> by
> .Fn tok_line
> or
> .Fn tok_str
> and before a new line is to be tokenized.
> .It Fn tok_line
> Tokenize
> .Fa li ,
> If successful, modify:
> .Fa argv
> to contain the words,
> .Fa argc
> to contain the number of words,
> .Fa cursorc
> (if not
> .Dv NULL )
> to contain the index of the word containing the cursor,
> and
> .Fa cursoro
> (if not
> .Dv NULL )
> to contain the offset within
> .Fa argv[cursorc]
> of the cursor.
> .Pp
> Returns
> 0 if successful,
> \-1 for an internal error,
> 1 for an unmatched single quote,
> 2 for an unmatched double quote,
> and
> 3 for a backslash quoted
> .Aq newline .
> A positive exit code indicates that another line should be read
> and tokenization attempted again.
> .
> .It Fn tok_str
> A simpler form of
> .Fn tok_line ;
> .Fa str
> is a NUL terminated string to tokenize.
> .El
> .
606,608d766
< The tokenization functions are not publically defined in
< .In histedit.h .
< .Pp