linenoise.h

   1 /* linenoise.h -- guerrilla line editing library against the idea that a
   2  * line editing lib needs to be 20,000 lines of C code.
   3  *
   4  * See linenoise.c for more information.
   5  *
   6  * ------------------------------------------------------------------------
   7  *
   8  * Copyright (c) 2010, Salvatore Sanfilippo <antirez at gmail dot com>
   9  * Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
  10  *
  11  * All rights reserved.
  12  *
  13  * Redistribution and use in source and binary forms, with or without
  14  * modification, are permitted provided that the following conditions are
  15  * met:
  16  *
  17  *  *  Redistributions of source code must retain the above copyright
  18  *     notice, this list of conditions and the following disclaimer.
  19  *
  20  *  *  Redistributions in binary form must reproduce the above copyright
  21  *     notice, this list of conditions and the following disclaimer in the
  22  *     documentation and/or other materials provided with the distribution.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  27  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  28  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  29  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  30  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  31  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  32  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  33  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  34  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  35  */
  36
  37 #ifndef __LINENOISE_H
  38 #define __LINENOISE_H
  39
  40 #ifndef NO_COMPLETION
  41 typedef struct linenoiseCompletions {
  42   size_t len;
  43   char **cvec;
  44 } linenoiseCompletions;
  45
  46 /*
  47  * The callback type for tab completion handlers.
  48  */
  49 typedef void(linenoiseCompletionCallback)(const char *prefix, linenoiseCompletions *comp, void *userdata);
  50
  51 /*
  52  * Sets the current tab completion handler and returns the previous one, or NULL
  53  * if no prior one has been set.
  54  */
  55 linenoiseCompletionCallback * linenoiseSetCompletionCallback(linenoiseCompletionCallback *comp, void *userdata);
  56
  57 /*
  58  * Adds a copy of the given string to the given completion list. The copy is owned
  59  * by the linenoiseCompletions object.
  60  */
  61 void linenoiseAddCompletion(linenoiseCompletions *comp, const char *str);
  62
  63 typedef char*(linenoiseHintsCallback)(const char *, int *color, int *bold, void *userdata);
  64 typedef void(linenoiseFreeHintsCallback)(void *hint, void *userdata);
  65 void linenoiseSetHintsCallback(linenoiseHintsCallback *callback, void *userdata);
  66 void linenoiseSetFreeHintsCallback(linenoiseFreeHintsCallback *callback);
  67
  68 #endif
  69
  70 /*
  71  * Prompts for input using the given string as the input
  72  * prompt. Returns when the user has tapped ENTER or (on an empty
  73  * line) EOF (Ctrl-D on Unix, Ctrl-Z on Windows). Returns either
  74  * a copy of the entered string (for ENTER) or NULL (on EOF).  The
  75  * caller owns the returned string and must eventually free() it.
  76  */
  77 char *linenoise(const char *prompt);
  78
  79 /**
  80  * Clear the screen.
  81  */
  82 void linenoiseClearScreen(void);
  83
  84 /*
  85  * Adds a copy of the given line of the command history.
  86  */
  87 int linenoiseHistoryAdd(const char *line);
  88
  89 /*
  90  * Sets the maximum length of the command history, in lines.
  91  * If the history is currently longer, it will be trimmed,
  92  * retaining only the most recent entries. If len is 0 or less
  93  * then this function does nothing.
  94  */
  95 int linenoiseHistorySetMaxLen(int len);
  96
  97 /*
  98  * Returns the current maximum length of the history, in lines.
  99  */
 100 int linenoiseHistoryGetMaxLen(void);
 101
 102 /*
 103  * Saves the current contents of the history to the given file.
 104  * Returns 0 on success.
 105  */
 106 int linenoiseHistorySave(const char *filename);
 107
 108 /*
 109  * Replaces the current history with the contents
 110  * of the given file.  Returns 0 on success.
 111  */
 112 int linenoiseHistoryLoad(const char *filename);
 113
 114 /*
 115  * Frees all history entries, clearing the history.
 116  */
 117 void linenoiseHistoryFree(void);
 118
 119 /*
 120  * Returns a pointer to the list of history entries, writing its
 121  * length to *len if len is not NULL. The memory is owned by linenoise
 122  * and must not be freed.
 123  */
 124 char **linenoiseHistory(int *len);
 125
 126 /*
 127  * Returns the number of display columns in the current terminal.
 128  */
 129 int linenoiseColumns(void);
 130
 131 /**
 132  * Enable or disable multiline mode (disabled by default)
 133  */
 134 void linenoiseSetMultiLine(int enableml);
 135
 136 #endif /* __LINENOISE_H */