290 mode, and returned early to avoid blocking the process
291 while waiting for terminal I/O. The gl_pending_io()
292 function can be used to see what type of I/O
293 gl_get_line() was waiting for. See the
294 gl_io_mode(3TECLA).
295
296
297 GLR_SIGNAL
298 A signal was caught by gl_get_line() that had an after-
299 signal disposition of GLS_ABORT. See gl_trap_signal().
300
301
302 GLR_TIMEOUT
303 The inactivity timer expired while gl_get_line() was
304 waiting for input, and the timeout callback function
305 returned GLTO_ABORT. See gl_inactivity_timeout() for
306 information about timeouts.
307
308
309 GLR_FDABORT
310 An application I/O callback returned GLFD_ABORT. Ssee
311 gl_watch_fd().
312
313
314 GLR_EOF
315 End of file reached. This can happen when input is
316 coming from a file or a pipe, instead of the terminal.
317 It also occurs if the user invokes the list-or-eof or
318 del-char-or-list-or-eof actions at the start of a new
319 line.
320
321
322 GLR_ERROR
323 An unexpected error caused gl_get_line() to abort
324 (consult errno and/or gl_error_message() for details.
325
326
327
328 When gl_return_status() returns GLR_ERROR and the value of errno is not
329 sufficient to explain what happened, you can use the gl_error_message()
330 function to request a description of the last error that occurred.
460 If app_string != NULL, then it is interpreted as a string containing
461 one or more configuration commands, separated from each other in the
462 string by embedded newline characters. If app_file != NULL then it is
463 interpreted as the full pathname of an application-specific
464 configuration file. If user_file != NULL then it is interpreted as the
465 full path name of a user-specific configuration file, such as
466 ~/.teclarc. For example, in the call
467
468 gl_configure_getline(gl, "edit-mode vi \n nobeep",
469 "/usr/share/myapp/teclarc", "~/.teclarc");
470
471
472
473 The app_string argument causes the calling application to start in
474 vi(1) edit-mode, instead of the default emacs mode, and turns off the
475 use of the terminal bell by the library. It then attempts to read
476 system-wide configuration commands from an optional file called
477 /usr/share/myapp/teclarc, then finally reads user-specific
478 configuration commands from an optional .teclarc file in the user's
479 home directory. Note that the arguments are listed in ascending order
480 of priority, with the contents of app_string being potentially over
481 riden by commands in app_file, and commands in app_file potentially
482 being overridden by commands in user_file.
483
484
485 You can call this function as many times as needed, the results being
486 cumulative, but note that copies of any file names specified with the
487 app_file and user_file arguments are recorded internally for subsequent
488 use by the read-init-files key-binding function, so if you plan to call
489 this function multiple times, be sure that the last call specifies the
490 filenames that you want re-read when the user requests that the
491 configuration files be re-read.
492
493
494 Individual key sequences can also be bound and unbound using the
495 gl_bind_keyseq() function. The origin argument specifies the priority
496 of the binding, according to whom it is being established for, and must
497 be one of the following two values.
498
499 GL_USER_KEY
500 The user requested this key-binding.
501
502
527
528 The data argument provides a way for your application to pass
529 arbitrary, application-specific information to the callback function.
530 This is passed to the callback every time that it is called. It might
531 for example point to the symbol table from which possible completions
532 are to be sought. The match_fn argument specifies the callback function
533 to be called. The CplMatchFn function type is defined in <libtecla.h>,
534 as is a CPL_MATCH_FN() macro that you can use to declare and prototype
535 callback functions. The declaration and responsibilities of callback
536 functions are described in depth on the cpl_complete_word(3TECLA)
537 manual page.
538
539
540 The callback function is responsible for looking backwards in the input
541 line from the point at which the user pressed TAB, to find the start of
542 the word being completed. It then must lookup possible completions of
543 this word, and record them one by one in the WordCompletion object that
544 is passed to it as an argument, by calling the cpl_add_completion()
545 function. If the callback function wants to provide filename completion
546 in addition to its own specific completions, it has the option of
547 itself calling the builtin filename completion callback. This also is
548 documented on the cpl_complete_word(3TECLA) manual page.
549
550
551 If you would like gl_get_line() to return the current input line when a
552 successful completion is been made, you can arrange this when you call
553 cpl_add_completion() by making the last character of the continuation
554 suffix a newline character. The input line will be updated to display
555 the completion, together with any contiuation suffix up to the newline
556 character, and gl_get_line() will return this input line.
557
558
559 If your callback function needs to write something to the terminal, it
560 must call gl_normal_io() before doing so. This will start a new line
561 after the input line that is currently being edited, reinstate normal
562 terminal I/O, and notify gl_get_line() that the input line will need to
563 be redrawn when the callback returns.
564
565 Adding Completion Actions
566 In the previous section the ability to customize the behavior of the
567 only default completion action, complete-word, was described. In this
568 section the ability to install additional action functions, so that
569 different types of word completion can be bound to different key
570 sequences, is described. This is achieved by using the
571 gl_completion_action() function.
572
573
574 The data and match_fn arguments are as described on the
575 cpl_complete_word(3TECLA) manual page, and specify the callback
576 function that should be invoked to identify possible completions. The
577 list_only argument determines whether the action that is being defined
578 should attempt to complete the word as far as possible in the input
579 line before displaying any possible ambiguous completions, or whether
580 it should simply display the list of possible completions without
581 touching the input line. The former option is selected by specifying a
582 value of 0, and the latter by specifying a value of 1. The name
583 argument specifies the name by which configuration files and future
584 invocations of this function should refer to the action. This must
585 either be the name of an existing completion action to be changed, or
586 be a new unused name for a new action. Finally, the keyseq argument
587 specifies the default key sequence to bind the action to. If this is
588 NULL, no new key sequence will be bound to the action.
589
590
591 Beware that in order for the user to be able to change the key sequence
592 that is bound to actions that are installed in this manner, you
593 shouldcall gl_completion_action() to install a given action for the
594 first time between calling new_GetLine() and the first call to
595 gl_get_line(). Otherwise, when the user's configuration file is read
596 on the first call to gl_get_line(), the name of the your additional
597 action will not be known, and any reference to it in the configuration
598 file will generate an error.
599
600
601 As discussed for gl_customize_completion(), if your callback function
602 needs to write anything to the terminal, it must call gl_normal_io()
603 before doing so.
604
605 Defining Custom Actions
606 Although the built-in key-binding actions are sufficient for the needs
607 of most applications, occasionally a specialized application may need
608 to define one or more custom actions, bound to application-specific key
609 sequences. For example, a sales application would benefit from having a
610 key sequence that displayed the part name that corresponded to a part
611 number preceding the cursor. Such a feature is clearly beyond the scope
612 of the built-in action functions. So for such special cases, the
613 gl_register_action() function is provided.
614
615
616 The gl_register_action() function lets the application register an
617 external function, fn, that will thereafter be called whenever either
618 the specified key sequence, keyseq, is entered by the user, or the user
723
724
725 Along with each history line, additional information about it, such as
726 its nesting level and when it was entered by the user, is recorded as a
727 comment preceding the line in the history file. Writing this as a
728 comment allows the history file to double as a command file, just in
729 case you wish to replay a whole session using it. Since comment
730 prefixes differ in different languages, the comment argument is
731 provided for specifying the comment prefix. For example, if your
732 application were a UNIX shell, such as the Bourne shell, you would
733 specify "#" here. Whatever you choose for the comment character, you
734 must specify the same prefix to gl_load_history() that you used when
735 you called gl_save_history() to write the history file.
736
737
738 The max_lines argument must be either -1 to specify that all lines in
739 the history list be saved, or a positive number specifying a ceiling on
740 how many of the most recent lines should be saved.
741
742
743 Both fuctions return non-zero on error, after writing an error message
744 to stderr. Note that gl_load_history() does not consider the non-
745 existence of a file to be an error.
746
747 Multiple History Lists
748 If your application uses a single GetLine object for entering many
749 different types of input lines, you might want gl_get_line() to
750 distinguish the different types of lines in the history list, and only
751 recall lines that match the current type of line. To support this
752 requirement, gl_get_line() marks lines being recorded in the history
753 list with an integer identifier chosen by the application. Initially
754 this identifier is set to 0 by new_GetLine(), but it can be changed
755 subsequently by calling gl_group_history().
756
757
758 The integer identifier ID can be any number chosen by the application,
759 but note that gl_save_history() and gl_load_history() preserve the
760 association between identifiers and historical input lines between
761 program invocations, so you should choose fixed identifiers for the
762 different types of input line used by your application.
763
1419 o So that you do not need to end each output line with \r\n,
1420 instead of just \n.
1421
1422
1423 The GL_RESTORE_ENV combination is the same as GL_SUSPEND_INPUT, except
1424 that it does not move the cursor. If your signal handler does not read
1425 or write anything to the terminal, the user will not see any visible
1426 indication that a signal was caught. This can be useful if you have a
1427 signal handler that only occasionally writes to the terminal, where
1428 using GL_SUSPEND_LINE would cause the input line to be unnecessarily
1429 duplicated when nothing had been written to the terminal. Such a signal
1430 handler, when it does write to the terminal, should be sure to start a
1431 new line at the start of its first write, by writing a new line before
1432 returning. If the signal arrives while the user is entering a line that
1433 only occupies a signal terminal line, or if the cursor is on the last
1434 terminal line of a longer input line, this will have the same effect as
1435 GL_SUSPEND_INPUT. Otherwise it will start writing on a line that
1436 already contains part of the displayed input line. This does not do any
1437 harm, but it looks a bit ugly, which is why the GL_SUSPEND_INPUT
1438 combination is better if you know that you are always going to be
1439 writting to the terminal.
1440
1441
1442 The after argument, which determines what gl_get_line() does after the
1443 application's signal handler returns (if it returns), can take any one
1444 of the following values:
1445
1446 GLS_RETURN
1447 Return the completed input line, just as though the
1448 user had pressed the return key.
1449
1450
1451 GLS_ABORT
1452 Cause gl_get_line() to abort. When this happens,
1453 gl_get_line() returns NULL, and a following call to
1454 gl_return_status() will return GLR_SIGNAL. Note that if
1455 the application needs errno always to have a meaningful
1456 value when gl_get_line() returns NULL, the callback
1457 function should set errno appropriately.
1458
1459
1892 ATTRIBUTES
1893 See attributes(5) for descriptions of the following attributes:
1894
1895
1896
1897
1898 +--------------------+-----------------+
1899 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1900 +--------------------+-----------------+
1901 |Interface Stability | Committed |
1902 +--------------------+-----------------+
1903 |MT-Level | MT-Safe |
1904 +--------------------+-----------------+
1905
1906 SEE ALSO
1907 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_io_mode(3TECLA),
1908 libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)
1909
1910
1911
1912 April 9, 2016 GL_GET_LINE(3TECLA)
|
290 mode, and returned early to avoid blocking the process
291 while waiting for terminal I/O. The gl_pending_io()
292 function can be used to see what type of I/O
293 gl_get_line() was waiting for. See the
294 gl_io_mode(3TECLA).
295
296
297 GLR_SIGNAL
298 A signal was caught by gl_get_line() that had an after-
299 signal disposition of GLS_ABORT. See gl_trap_signal().
300
301
302 GLR_TIMEOUT
303 The inactivity timer expired while gl_get_line() was
304 waiting for input, and the timeout callback function
305 returned GLTO_ABORT. See gl_inactivity_timeout() for
306 information about timeouts.
307
308
309 GLR_FDABORT
310 An application I/O callback returned GLFD_ABORT. See
311 gl_watch_fd().
312
313
314 GLR_EOF
315 End of file reached. This can happen when input is
316 coming from a file or a pipe, instead of the terminal.
317 It also occurs if the user invokes the list-or-eof or
318 del-char-or-list-or-eof actions at the start of a new
319 line.
320
321
322 GLR_ERROR
323 An unexpected error caused gl_get_line() to abort
324 (consult errno and/or gl_error_message() for details.
325
326
327
328 When gl_return_status() returns GLR_ERROR and the value of errno is not
329 sufficient to explain what happened, you can use the gl_error_message()
330 function to request a description of the last error that occurred.
460 If app_string != NULL, then it is interpreted as a string containing
461 one or more configuration commands, separated from each other in the
462 string by embedded newline characters. If app_file != NULL then it is
463 interpreted as the full pathname of an application-specific
464 configuration file. If user_file != NULL then it is interpreted as the
465 full path name of a user-specific configuration file, such as
466 ~/.teclarc. For example, in the call
467
468 gl_configure_getline(gl, "edit-mode vi \n nobeep",
469 "/usr/share/myapp/teclarc", "~/.teclarc");
470
471
472
473 The app_string argument causes the calling application to start in
474 vi(1) edit-mode, instead of the default emacs mode, and turns off the
475 use of the terminal bell by the library. It then attempts to read
476 system-wide configuration commands from an optional file called
477 /usr/share/myapp/teclarc, then finally reads user-specific
478 configuration commands from an optional .teclarc file in the user's
479 home directory. Note that the arguments are listed in ascending order
480 of priority, with the contents of app_string being potentially
481 overridden by commands in app_file, and commands in app_file
482 potentially being overridden by commands in user_file.
483
484
485 You can call this function as many times as needed, the results being
486 cumulative, but note that copies of any file names specified with the
487 app_file and user_file arguments are recorded internally for subsequent
488 use by the read-init-files key-binding function, so if you plan to call
489 this function multiple times, be sure that the last call specifies the
490 filenames that you want re-read when the user requests that the
491 configuration files be re-read.
492
493
494 Individual key sequences can also be bound and unbound using the
495 gl_bind_keyseq() function. The origin argument specifies the priority
496 of the binding, according to whom it is being established for, and must
497 be one of the following two values.
498
499 GL_USER_KEY
500 The user requested this key-binding.
501
502
527
528 The data argument provides a way for your application to pass
529 arbitrary, application-specific information to the callback function.
530 This is passed to the callback every time that it is called. It might
531 for example point to the symbol table from which possible completions
532 are to be sought. The match_fn argument specifies the callback function
533 to be called. The CplMatchFn function type is defined in <libtecla.h>,
534 as is a CPL_MATCH_FN() macro that you can use to declare and prototype
535 callback functions. The declaration and responsibilities of callback
536 functions are described in depth on the cpl_complete_word(3TECLA)
537 manual page.
538
539
540 The callback function is responsible for looking backwards in the input
541 line from the point at which the user pressed TAB, to find the start of
542 the word being completed. It then must lookup possible completions of
543 this word, and record them one by one in the WordCompletion object that
544 is passed to it as an argument, by calling the cpl_add_completion()
545 function. If the callback function wants to provide filename completion
546 in addition to its own specific completions, it has the option of
547 itself calling the builtin filename completion callback. This is also
548 documented in the cpl_complete_word(3TECLA) manual page.
549
550
551 If you would like gl_get_line() to return the current input line when a
552 successful completion has been made, you can arrange this when you call
553 cpl_add_completion() by making the last character of the continuation
554 suffix a newline character. The input line will be updated to display
555 the completion, together with any continuation suffix up to the newline
556 character, and gl_get_line() will return this input line.
557
558
559 If your callback function needs to write something to the terminal, it
560 must call gl_normal_io() before doing so. This will start a new line
561 after the input line that is currently being edited, reinstate normal
562 terminal I/O, and notify gl_get_line() that the input line will need to
563 be redrawn when the callback returns.
564
565 Adding Completion Actions
566 In the previous section the ability to customize the behavior of the
567 only default completion action, complete-word, was described. In this
568 section the ability to install additional action functions, so that
569 different types of word completion can be bound to different key
570 sequences, is described. This is achieved by using the
571 gl_completion_action() function.
572
573
574 The data and match_fn arguments are as described on the
575 cpl_complete_word(3TECLA) manual page, and specify the callback
576 function that should be invoked to identify possible completions. The
577 list_only argument determines whether the action that is being defined
578 should attempt to complete the word as far as possible in the input
579 line before displaying any possible ambiguous completions, or whether
580 it should simply display the list of possible completions without
581 touching the input line. The former option is selected by specifying a
582 value of 0, and the latter by specifying a value of 1. The name
583 argument specifies the name by which configuration files and future
584 invocations of this function should refer to the action. This must
585 either be the name of an existing completion action to be changed, or
586 be a new unused name for a new action. Finally, the keyseq argument
587 specifies the default key sequence to bind the action to. If this is
588 NULL, no new key sequence will be bound to the action.
589
590
591 Beware that in order for the user to be able to change the key sequence
592 that is bound to actions that are installed in this manner, you should
593 call gl_completion_action() to install a given action for the first
594 time between calling new_GetLine() and the first call to gl_get_line().
595 Otherwise, when the user's configuration file is read on the first call
596 to gl_get_line(), the name of the your additional action will not be
597 known, and any reference to it in the configuration file will generate
598 an error.
599
600
601 As discussed for gl_customize_completion(), if your callback function
602 needs to write anything to the terminal, it must call gl_normal_io()
603 before doing so.
604
605 Defining Custom Actions
606 Although the built-in key-binding actions are sufficient for the needs
607 of most applications, occasionally a specialized application may need
608 to define one or more custom actions, bound to application-specific key
609 sequences. For example, a sales application would benefit from having a
610 key sequence that displayed the part name that corresponded to a part
611 number preceding the cursor. Such a feature is clearly beyond the scope
612 of the built-in action functions. So for such special cases, the
613 gl_register_action() function is provided.
614
615
616 The gl_register_action() function lets the application register an
617 external function, fn, that will thereafter be called whenever either
618 the specified key sequence, keyseq, is entered by the user, or the user
723
724
725 Along with each history line, additional information about it, such as
726 its nesting level and when it was entered by the user, is recorded as a
727 comment preceding the line in the history file. Writing this as a
728 comment allows the history file to double as a command file, just in
729 case you wish to replay a whole session using it. Since comment
730 prefixes differ in different languages, the comment argument is
731 provided for specifying the comment prefix. For example, if your
732 application were a UNIX shell, such as the Bourne shell, you would
733 specify "#" here. Whatever you choose for the comment character, you
734 must specify the same prefix to gl_load_history() that you used when
735 you called gl_save_history() to write the history file.
736
737
738 The max_lines argument must be either -1 to specify that all lines in
739 the history list be saved, or a positive number specifying a ceiling on
740 how many of the most recent lines should be saved.
741
742
743 Both functions return non-zero on error, after writing an error message
744 to stderr. Note that gl_load_history() does not consider the non-
745 existence of a file to be an error.
746
747 Multiple History Lists
748 If your application uses a single GetLine object for entering many
749 different types of input lines, you might want gl_get_line() to
750 distinguish the different types of lines in the history list, and only
751 recall lines that match the current type of line. To support this
752 requirement, gl_get_line() marks lines being recorded in the history
753 list with an integer identifier chosen by the application. Initially
754 this identifier is set to 0 by new_GetLine(), but it can be changed
755 subsequently by calling gl_group_history().
756
757
758 The integer identifier ID can be any number chosen by the application,
759 but note that gl_save_history() and gl_load_history() preserve the
760 association between identifiers and historical input lines between
761 program invocations, so you should choose fixed identifiers for the
762 different types of input line used by your application.
763
1419 o So that you do not need to end each output line with \r\n,
1420 instead of just \n.
1421
1422
1423 The GL_RESTORE_ENV combination is the same as GL_SUSPEND_INPUT, except
1424 that it does not move the cursor. If your signal handler does not read
1425 or write anything to the terminal, the user will not see any visible
1426 indication that a signal was caught. This can be useful if you have a
1427 signal handler that only occasionally writes to the terminal, where
1428 using GL_SUSPEND_LINE would cause the input line to be unnecessarily
1429 duplicated when nothing had been written to the terminal. Such a signal
1430 handler, when it does write to the terminal, should be sure to start a
1431 new line at the start of its first write, by writing a new line before
1432 returning. If the signal arrives while the user is entering a line that
1433 only occupies a signal terminal line, or if the cursor is on the last
1434 terminal line of a longer input line, this will have the same effect as
1435 GL_SUSPEND_INPUT. Otherwise it will start writing on a line that
1436 already contains part of the displayed input line. This does not do any
1437 harm, but it looks a bit ugly, which is why the GL_SUSPEND_INPUT
1438 combination is better if you know that you are always going to be
1439 writing to the terminal.
1440
1441
1442 The after argument, which determines what gl_get_line() does after the
1443 application's signal handler returns (if it returns), can take any one
1444 of the following values:
1445
1446 GLS_RETURN
1447 Return the completed input line, just as though the
1448 user had pressed the return key.
1449
1450
1451 GLS_ABORT
1452 Cause gl_get_line() to abort. When this happens,
1453 gl_get_line() returns NULL, and a following call to
1454 gl_return_status() will return GLR_SIGNAL. Note that if
1455 the application needs errno always to have a meaningful
1456 value when gl_get_line() returns NULL, the callback
1457 function should set errno appropriately.
1458
1459
1892 ATTRIBUTES
1893 See attributes(5) for descriptions of the following attributes:
1894
1895
1896
1897
1898 +--------------------+-----------------+
1899 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1900 +--------------------+-----------------+
1901 |Interface Stability | Committed |
1902 +--------------------+-----------------+
1903 |MT-Level | MT-Safe |
1904 +--------------------+-----------------+
1905
1906 SEE ALSO
1907 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_io_mode(3TECLA),
1908 libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5), tecla(5)
1909
1910
1911
1912 January 18, 2020 GL_GET_LINE(3TECLA)
|