Print this page 
12212 typos in some section 3tecla man pages
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3tecla/cpl_complete_word.3tecla
          +++ new/usr/src/man/man3tecla/cpl_complete_word.3tecla
↓ open down ↓ 16 lines elided ↑ open up ↑ 
  17   17  .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  18   18  .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  19   19  .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  20   20  .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21   21  .\"
  22   22  .\" Except as contained in this notice, the name of a copyright holder
  23   23  .\" shall not be used in advertising or otherwise to promote the sale, use
  24   24  .\" or other dealings in this Software without prior written authorization
  25   25  .\" of the copyright holder.
  26   26  .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  27      -.TH CPL_COMPLETE_WORD 3TECLA "Jun 1, 2004"
       27 +.TH CPL_COMPLETE_WORD 3TECLA "January 18, 2020"
  28   28  .SH NAME
  29   29  cpl_complete_word, cfc_file_start, cfc_literal_escapes, cfc_set_check_fn,
  30   30  cpl_add_completion, cpl_file_completions, cpl_last_error, cpl_list_completions,
  31   31  cpl_recall_matches, cpl_record_error, del_CplFileConf, cpl_check_exe,
  32   32  del_WordCompletion, new_CplFileConf, new_WordCompletion \- look up possible
  33   33  completions for a word
  34   34  .SH SYNOPSIS
  35      -.LP
  36   35  .nf
  37   36  cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
  38   37  #include <stdio.h>
  39   38  #include <libtecla.h>
  40   39  
  41   40  \fBWordCompletion *\fR\fBnew_WordCompletion\fR(\fBvoid\fR);
  42   41  .fi
  43   42  
  44   43  .LP
  45   44  .nf
↓ open down ↓ 63 lines elided ↑ open up ↑ 
 109  108  .nf
 110  109  \fBvoid\fR \fBcpl_record_error\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIerrmsg\fR);
 111  110  .fi
 112  111  
 113  112  .LP
 114  113  .nf
 115  114  \fBconst char *\fR\fBcpl_last_error\fR(\fBWordCompletion *\fR\fIcpl\fR);
 116  115  .fi
 117  116  
 118  117  .SH DESCRIPTION
 119      -.sp
 120      -.LP
 121  118  The \fBcpl_complete_word()\fR function is part of the \fBlibtecla\fR(3LIB)
 122  119  library. It is usually called behind the scenes by \fBgl_get_line\fR(3TECLA),
 123  120  but can also be called separately.
 124  121  .sp
 125  122  .LP
 126  123  Given an input line containing an incomplete word to be completed, it calls a
 127  124  user-provided callback function (or the provided file-completion callback
 128  125  function) to look up all possible completion suffixes for that word. The
 129  126  callback function is expected to look backward in the line, starting from the
 130  127  specified cursor position, to find the start of the word to be completed, then
↓ open down ↓ 43 lines elided ↑ open up ↑ 
 174  171  The \fBcpl_add_completion()\fR function is called zero or more times by the
 175  172  completion callback function to record each possible completion in the
 176  173  specified \fBWordCompletion\fR object. These completions are subsequently
 177  174  returned by \fBcpl_complete_word()\fR. The \fIcpl\fR, \fIline\fR, and
 178  175  \fIword_end\fR arguments should be those that were passed to the callback
 179  176  function. The \fIword_start\fR argument should be the index within the input
 180  177  line string of the start of the word that is being completed. This should equal
 181  178  \fIword_end\fR if a zero-length string is being completed. The \fIsuffix\fR
 182  179  argument is the string that would have to be appended to the incomplete word to
 183  180  complete it. If this needs any quoting (for example, the addition of
 184      -backslashes before special charaters) to be valid within the displayed input
      181 +backslashes before special characters) to be valid within the displayed input
 185  182  line, this should be included. A copy of the suffix string is allocated
 186  183  internally, so there is no need to maintain your copy of the string after
 187  184  \fBcpl_add_completion()\fR returns.
 188  185  .sp
 189  186  .LP
 190  187  In the array of possible completions that the \fBcpl_complete_word()\fR
 191  188  function returns, the suffix recorded by \fBcpl_add_completion()\fR is listed
 192      -along with the concatentation of this suffix with the word that lies between
      189 +along with the concatenation of this suffix with the word that lies between
 193  190  \fIword_start\fR and \fIword_end\fR in the input line.
 194  191  .sp
 195  192  .LP
 196  193  The \fItype_suffix\fR argument specifies an optional string to be appended to
 197  194  the completion if it is displayed as part of a list of completions by
 198      -\fIcpl_list_completions\fR. The intention is that this indicate to the user the
      195 +\fIcpl_list_completions\fR. The intention is that this indicates to the user the
 199  196  type of each completion. For example, the file completion function places a
 200  197  directory separator after completions that are directories, to indicate their
 201      -nature to the user. Similary, if the completion were a function, you could
      198 +nature to the user. Similarly, if the completion were a function, you could
 202  199  indicate this to the user by setting \fItype_suffix\fR to "()". Note that the
 203  200  \fItype_suffix\fR string is not copied, so if the argument is not a literal
 204  201  string between speech marks, be sure that the string remains valid for at least
 205  202  as long as the results of \fBcpl_complete_word()\fR are needed.
 206  203  .sp
 207  204  .LP
 208  205  The \fIcont_suffix\fR argument is a continuation suffix to append to the
 209  206  completed word in the input line if this is the only completion. This is
 210  207  something that is not part of the completion itself, but that gives the user an
 211  208  indication about how they might continue to extend the token. For example, the
 212  209  file-completion callback function adds a directory separator if the completed
 213  210  word is a directory. If the completed word were a function name, you could
 214  211  similarly aid the user by arranging for an open parenthesis to be appended.
 215  212  .sp
 216  213  .LP
 217      -The \fBcpl_complete_word()\fR is normally called behind the scenes by
      214 +The \fBcpl_complete_word()\fR function is normally called behind the scenes by
 218  215  \fBgl_get_line\fR(3TECLA), but can also be called separately if you separately
 219  216  allocate a \fBWordCompletion\fR object. It performs word completion, as
 220  217  described at the beginning of this section. Its first argument is a resource
 221  218  object previously returned by \fBnew_WordCompletion()\fR. The \fIline\fR
 222  219  argument is the input line string, containing the word to be completed. The
 223  220  \fIword_end\fR argument contains the index of the character in the input line,
 224  221  that just follows the last character of the word to be completed. When called
 225  222  by \fBgl_get_line()\fR, this is the character over which the user pressed TAB.
 226  223  The \fImatch_fn\fR argument is the function pointer of the callback function
 227  224  which will lookup possible completions of the word, as described above, and the
↓ open down ↓ 42 lines elided ↑ open up ↑ 
 270  267  .in -2
 271  268  
 272  269  .sp
 273  270  .LP
 274  271  If an error occurs during completion, \fBcpl_complete_word()\fR returns
 275  272  \fINULL\fR. A description of the error can be acquired by calling the
 276  273  \fBcpl_last_error()\fR function.
 277  274  .sp
 278  275  .LP
 279  276  The \fBcpl_last_error()\fR function returns a terse description of the error
 280      -which occurred on the last call to \fBcpl_com plete_word()\fR or
      277 +which occurred on the last call to \fBcpl_complete_word()\fR or
 281  278  \fBcpl_add_completion()\fR.
 282  279  .sp
 283  280  .LP
 284  281  As a convenience, the return value of the last call to
 285  282  \fBcpl_complete_word()\fR can be recalled at a later time by calling
 286  283  \fBcpl_recall_matches()\fR. If \fBcpl_complete_word()\fR returned \fINULL\fR,
 287  284  so will \fBcpl_recall_matches()\fR.
 288  285  .sp
 289  286  .LP
 290  287  When the \fBcpl_complete_word()\fR function returns multiple possible
 291  288  completions, the \fBcpl_list_completions()\fR function can be called upon to
 292  289  list them, suitably arranged across the available width of the terminal. It
 293  290  arranges for the displayed columns of completions to all have the same width,
 294  291  set by the longest completion. It also appends the \fItype_suffix\fR strings
 295  292  that were recorded with each completion, thus indicating their types to the
 296  293  user.
 297  294  .SS "Builtin Filename completion Callback"
 298      -.sp
 299      -.LP
 300      -By default the \fBgl_get_line()\fR function, passes the
      295 +By default the \fBgl_get_line()\fR function passes the
 301  296  \fBCPL_MATCH_FN\fR(\fBcps_file_completions\fR) completion callback function to
 302  297  \fBcpl_complete_word()\fR. This function can also be used separately, either by
 303  298  sending it to \fBcpl_complete_word()\fR, or by calling it directly from your
 304  299  own completion callback function.
 305  300  .sp
 306  301  .in +2
 307  302  .nf
 308  303  #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \e
 309  304                                void *data, const char *line, \e
 310  305                                int word_end)
↓ open down ↓ 25 lines elided ↑ open up ↑ 
 336  331  filename starts in the input line. Passing \fIstart_index\fR=-1 reenables the
 337  332  default behavior.
 338  333  .sp
 339  334  .LP
 340  335  By default, when \fBcpl_file_completions()\fR looks at a filename in the input
 341  336  line, each lone backslash in the input line is interpreted as being a special
 342  337  character which removes any special significance of the character which follows
 343  338  it, such as a space which should be taken as part of the filename rather than
 344  339  delimiting the start of the filename. These backslashes are thus ignored while
 345  340  looking for completions, and subsequently added before spaces, tabs and literal
 346      -back slashes in the list of completions. To have unescaped back slashes treated
      341 +backslashes in the list of completions. To have unescaped backslashes treated
 347  342  as normal characters, call \fBcfc_literal_escapes()\fR with a non-zero value in
 348  343  its \fIliteral\fR argument.
 349  344  .sp
 350  345  .LP
 351  346  By default, \fBcpl_file_completions()\fR reports all files whose names start
 352  347  with the prefix that is being completed. If you only want a selected subset of
 353  348  these files to be reported in the list of completions, you can arrange this by
 354  349  providing a callback function which takes the full pathname of a file, and
 355  350  returns 0 if the file should be ignored, or 1 if the file should be included in
 356  351  the list of completions. To register such a function for use by
↓ open down ↓ 13 lines elided ↑ open up ↑ 
 370  365  
 371  366  void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \e
 372  367                                               void *chk_data);
 373  368  .fi
 374  369  .in -2
 375  370  
 376  371  .sp
 377  372  .LP
 378  373  The \fBcpl_check_exe()\fR function is a provided callback of the above type,
 379  374  for use with \fBcpl_file_completions()\fR. It returns non-zero if the filename
 380      -that it is given represents a normal file that the user has execute permission
 381      -to. You could use this to have \fBcpl_file_completions()\fR only list
      375 +that it is given represents a normal file that the user has permission to
      376 +execute. You could use this to have \fBcpl_file_completions()\fR only list
 382  377  completions of executable files.
 383  378  .sp
 384  379  .LP
 385  380  When you have finished with a \fBCplFileConf\fR variable, you can pass it to
 386  381  the \fBdel_CplFileConf()\fR destructor function to reclaim its memory.
 387  382  .SS "Thread Safety"
 388      -.sp
 389      -.LP
 390  383  It is safe to use the facilities of this module in multiple threads, provided
 391  384  that each thread uses a separately allocated \fBWordCompletion\fR object. In
 392  385  other words, if two threads want to do word completion, they should each call
 393  386  \fBnew_WordCompletion()\fR to allocate their own completion objects.
 394  387  .SH ATTRIBUTES
 395      -.sp
 396      -.LP
 397  388  See \fBattributes\fR(5) for descriptions of the following attributes:
 398  389  .sp
 399  390  
 400  391  .sp
 401  392  .TS
 402  393  box;
 403  394  c | c
 404  395  l | l .
 405  396  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 406  397  _
 407  398  Interface Stability     Evolving
 408  399  _
 409  400  MT-Level        MT-Safe
 410  401  .TE
 411  402  
 412  403  .SH SEE ALSO
 413      -.sp
 414      -.LP
 415  404  \fBef_expand_file\fR(3TECLA), \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB),
 416  405  \fBpca_lookup_file\fR(3TECLA), \fBattributes\fR(5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX