1
0

tinyrl.h 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  1. /**
  2. \ingroup tinyrl
  3. \defgroup tinyrl_class tinyrl
  4. @{
  5. \brief This class provides instances which are capable of handling user input
  6. from a CLI in a "readline" like fashion.
  7. */
  8. #ifndef _tinyrl_tinyrl_h
  9. #define _tinyrl_tinyrl_h
  10. #include <stdio.h>
  11. #include "lub/types.h"
  12. #include "lub/c_decl.h"
  13. #include "tinyrl/history.h"
  14. #define UTF8_MASK 0xC0
  15. #define UTF8_11 0xC0
  16. #define UTF8_10 0x80
  17. _BEGIN_C_DECL typedef struct _tinyrl tinyrl_t;
  18. typedef enum {
  19. /**
  20. * no possible completions were found
  21. */
  22. TINYRL_NO_MATCH = 0,
  23. /**
  24. * the provided string was already an exact match
  25. */
  26. TINYRL_MATCH,
  27. /**
  28. * the provided string was ambiguous and produced
  29. * more than one possible completion
  30. */
  31. TINYRL_AMBIGUOUS,
  32. /**
  33. * the provided string was unambiguous and a
  34. * completion was performed
  35. */
  36. TINYRL_COMPLETED_MATCH,
  37. /**
  38. * the provided string was ambiguous but a partial
  39. * completion was performed.
  40. */
  41. TINYRL_COMPLETED_AMBIGUOUS,
  42. /**
  43. * the provided string was an exact match for one
  44. * possible value but there are other exetensions
  45. * of the string available.
  46. */
  47. TINYRL_MATCH_WITH_EXTENSIONS
  48. } tinyrl_match_e;
  49. /* virtual methods */
  50. typedef char *tinyrl_compentry_func_t(tinyrl_t * instance,
  51. const char *text,
  52. unsigned offset, unsigned state);
  53. typedef int tinyrl_hook_func_t(tinyrl_t * instance);
  54. typedef char **tinyrl_completion_func_t(tinyrl_t * instance,
  55. const char *text,
  56. unsigned start, unsigned end);
  57. /**
  58. * \return
  59. * - BOOL_TRUE if the action associated with the key has
  60. * been performed successfully
  61. * - BOOL_FALSE if the action was not successful
  62. */
  63. typedef bool_t tinyrl_key_func_t(tinyrl_t * instance, int key);
  64. /* exported functions */
  65. extern tinyrl_t *tinyrl_new(FILE * instream,
  66. FILE * outstream,
  67. unsigned stifle,
  68. tinyrl_completion_func_t * complete_fn);
  69. /*lint -esym(534,tinyrl_printf) Ignoring return value of function */
  70. extern int tinyrl_printf(const tinyrl_t * instance, const char *fmt, ...);
  71. extern void tinyrl_delete(tinyrl_t * instance);
  72. extern tinyrl_history_t *tinyrl__get_history(const tinyrl_t * instance);
  73. extern const char *tinyrl__get_prompt(const tinyrl_t * instance);
  74. extern void tinyrl_done(tinyrl_t * instance);
  75. extern void tinyrl_completion_over(tinyrl_t * instance);
  76. extern void tinyrl_completion_error_over(tinyrl_t * instance);
  77. extern bool_t tinyrl_is_completion_error_over(const tinyrl_t * instance);
  78. extern void *tinyrl__get_context(const tinyrl_t * instance);
  79. /**
  80. * This operation returns the current line in use by the tinyrl instance
  81. * NB. the pointer will become invalid after any further operation on the
  82. * instance.
  83. */
  84. extern const char *tinyrl__get_line(const tinyrl_t * instance);
  85. extern void tinyrl__set_istream(tinyrl_t * instance, FILE * istream);
  86. extern bool_t tinyrl__get_isatty(const tinyrl_t * instance);
  87. extern FILE *tinyrl__get_istream(const tinyrl_t * instance);
  88. extern FILE *tinyrl__get_ostream(const tinyrl_t * instance);
  89. extern bool_t tinyrl__get_utf8(const tinyrl_t * instance);
  90. extern void tinyrl__set_utf8(tinyrl_t * instance, bool_t utf8);
  91. extern char *tinyrl_readline(tinyrl_t * instance,
  92. const char *prompt, void *context);
  93. extern char *tinyrl_forceline(tinyrl_t * instance,
  94. const char *prompt,
  95. void *context, const char *line);
  96. extern bool_t
  97. tinyrl_bind_key(tinyrl_t * instance, int key, tinyrl_key_func_t * fn);
  98. extern void tinyrl_delete_matches(char **instance);
  99. extern char **tinyrl_completion(tinyrl_t * instance,
  100. const char *line,
  101. unsigned start,
  102. unsigned end,
  103. tinyrl_compentry_func_t * generator);
  104. extern void tinyrl_crlf(const tinyrl_t * instance);
  105. extern void tinyrl_ding(const tinyrl_t * instance);
  106. extern void tinyrl_reset_line_state(tinyrl_t * instance);
  107. extern bool_t tinyrl_insert_text(tinyrl_t * instance, const char *text);
  108. extern void
  109. tinyrl_delete_text(tinyrl_t * instance, unsigned start, unsigned end);
  110. extern void tinyrl_redisplay(tinyrl_t * instance);
  111. extern void
  112. tinyrl_replace_line(tinyrl_t * instance, const char *text, int clear_undo);
  113. /**
  114. * Complete the current word in the input buffer, displaying
  115. * a prompt to clarify any abiguity if necessary.
  116. *
  117. * \return
  118. * - the type of match performed.
  119. * \post
  120. * - If the current word is ambiguous then a list of
  121. * possible completions will be displayed.
  122. */
  123. extern tinyrl_match_e tinyrl_complete(tinyrl_t * instance);
  124. /**
  125. * Complete the current word in the input buffer, displaying
  126. * a prompt to clarify any abiguity or extra extensions if necessary.
  127. *
  128. * \return
  129. * - the type of match performed.
  130. * \post
  131. * - If the current word is ambiguous then a list of
  132. * possible completions will be displayed.
  133. * - If the current word is complete but there are extra
  134. * completions which are an extension of that word then
  135. * a list of these will be displayed.
  136. */
  137. extern tinyrl_match_e tinyrl_complete_with_extensions(tinyrl_t * instance);
  138. /**
  139. * Disable echoing of input characters when a line in input.
  140. *
  141. */
  142. extern void tinyrl_disable_echo(
  143. /**
  144. * The instance on which to operate
  145. */
  146. tinyrl_t * instance,
  147. /**
  148. * The character to display instead of a key press.
  149. *
  150. * If this has the special value '/0' then the insertion point will not
  151. * be moved when keys are pressed.
  152. */
  153. char echo_char);
  154. /**
  155. * Enable key echoing for this instance. (This is the default behaviour)
  156. */
  157. extern void tinyrl_enable_echo(
  158. /**
  159. * The instance on which to operate
  160. */
  161. tinyrl_t * instance);
  162. /**
  163. * Indicate whether the current insertion point is quoting or not
  164. */
  165. extern bool_t tinyrl_is_quoting(
  166. /**
  167. * The instance on which to operate
  168. */
  169. const tinyrl_t * instance);
  170. /**
  171. * Limit maximum line length
  172. */
  173. extern void tinyrl_limit_line_length(
  174. /**
  175. * The instance on which to operate
  176. */
  177. tinyrl_t * instance,
  178. /**
  179. * The length to limit to (0) is unlimited
  180. */
  181. unsigned length);
  182. _END_C_DECL
  183. #endif /* _tinyrl_tinyrl_h */
  184. /** @} tinyrl_tinyrl */