1
0

tinyrl.h 6.9 KB

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