tinyrl.h 7.2 KB

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