OpenCores
URL https://opencores.org/ocsvn/eco32/eco32/trunk

Subversion Repositories eco32

[/] [eco32/] [trunk/] [sim/] [getline/] [README] - Blame information for rev 130

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 8 hellwig
 
2
*************************** Motivation **********************************
3
 
4
Many interactive programs read input line by line, but would like to
5
provide line editing and history functionality to the end-user that
6
runs the program.
7
 
8
The input-edit package provides that functionality.  As far as the
9
programmer is concerned, the program only asks for the next line
10
of input. However, until the user presses the RETURN key they can use
11
emacs-style line editing commands and can traverse the history of lines
12
previously typed.
13
 
14
Other packages, such as GNU's readline, have greater capability but are
15
also substantially larger.  Input-edit is small, since it uses neither
16
stdio nor any termcap features, and is also quite portable.  It only uses
17
\b to backspace and \007 to ring the bell on errors.  Since it cannot
18
edit multiple lines it scrolls long lines left and right on the same line.
19
 
20
Input edit uses classic (not ANSI) C, and should run on any Unix
21
system (BSD, SYSV or POSIX), PC's under DOS with MSC, TurboC or djgpp,
22
PC's under OS/2 with gcc (EMX), or Vax/VMS.  Porting the package to new
23
systems basicaly requires code to read a character when it is typed without
24
echoing it, everything else should be OK.
25
 
26
I have run the package on:
27
 
28
        DECstation 5000, Ultrix 4.3 with cc 2.1 and gcc 2.3.3
29
        Sun Sparc 2, SunOS 4.1.1, with cc
30
        SGI Iris, IRIX System V.3, with cc
31
        PC using DOS with MSC
32
 
33
The description below is broken into two parts, the end-user (editing)
34
interface and the programmer interface.  Send bug reports, fixes and
35
enhancements to:
36
 
37
Chris Thewalt (thewalt@ce.berkeley.edu)
38
5/3/93
39
 
40
Thanks to the following people who have provided enhancements and fixes:
41
  Ron Ueberschaer, Christoph Keller, Scott Schwartz, Steven List,
42
  DaviD W. Sanderson, Goran Bostrom, Michael Gleason, Glenn Kasten,
43
  Edin Hodzic, Eric J Bivona, Kai Uwe Rommel, Danny Quah, Ulrich Betzler
44
 
45
PS: I don't have, and don't want to add, a vi mode, sorry.
46
 
47
************************** End-User Interface ***************************
48
 
49
Entering printable keys generally inserts new text into the buffer (unless
50
in overwrite mode, see below).  Other special keys can be used to modify
51
the text in the buffer.  In the description of the keys below, ^n means
52
Control-n, or holding the CONTROL key down while pressing "n".  Errors
53
will ring the terminal bell.
54
 
55
^A/^E   : Move cursor to beginning/end of the line.
56
^F/^B   : Move cursor forward/backward one character.
57
ESC-F   : Move cursor forward one word.
58
ESC-B   : Move cursor backward one word.
59
^D      : Delete the character under the cursor.
60
^H, DEL : Delete the character to the left of the cursor.
61
^K      : Kill from the cursor to the end of line.
62
^L      : Redraw current line.
63
^O      : Toggle overwrite/insert mode. Initially in insert mode. Text
64
          added in overwrite mode (including yanks) overwrite
65
          existing text, while insert mode does not overwrite.
66
^P/^N   : Move to previous/next item on history list.
67
^R/^S   : Perform incremental reverse/forward search for string on
68
          the history list.  Typing normal characters adds to the current
69
          search string and searches for a match. Typing ^R/^S marks
70
          the start of a new search, and moves on to the next match.
71
          Typing ^H or DEL deletes the last character from the search
72
          string, and searches from the starting location of the last search.
73
          Therefore, repeated DEL's appear to unwind to the match nearest
74
          the point at which the last ^R or ^S was typed.  If DEL is
75
          repeated until the search string is empty the search location
76
          begins from the start of the history list.  Typing ESC or
77
          any other editing character accepts the current match and
78
          loads it into the buffer, terminating the search.
79
^T      : Toggle the characters under and to the left of the cursor.
80
^U      : Deletes the entire line
81
^Y      : Yank previously killed text back at current location.  Note that
82
          this will overwrite or insert, depending on the current mode.
83
TAB     : By default adds spaces to buffer to get to next TAB stop
84
          (just after every 8th column), although this may be rebound by the
85
          programmer, as described below.
86
NL, CR  : returns current buffer to the program.
87
 
88
DOS and ANSI terminal arrow key sequences are recognized, and act like:
89
 
90
  up    : same as ^P
91
  down  : same as ^N
92
  left  : same as ^B
93
  right : same as ^F
94
 
95
************************** Programmer Interface ***************************
96
 
97
The programmer accesses input-edit through these functions, and optionally
98
through three additional function pointer hooks.  The four functions are:
99
 
100
char *gl_getline(char *prompt)
101
 
102
        Prints the prompt and allows the user to edit the current line. A
103
        pointer to the line is returned when the user finishes by
104
        typing a newline or a return.  Unlike GNU readline, the returned
105
        pointer points to a static buffer, so it should not be free'd, and
106
        the buffer contains the newline character.  The user enters an
107
        end-of-file by typing ^D on an empty line, in which case the
108
        first character of the returned buffer is '\0'.  Getline never
109
        returns a NULL pointer.  The getline functions sets terminal modes
110
        needed to make it work, and resets them before returning to the
111
        caller.  The getline function also looks for characters that would
112
        generate a signal, and resets the terminal modes before raising the
113
        signal condition.  If the signal handler returns to getline,
114
        the screen is automatically redrawn and editing can continue.
115
        Getline now requires both the input and output stream be connected
116
        to the terminal (not redirected) so the main program should check
117
        to make sure this is true.  If input or output have been redirected
118
        the main program should use buffered IO (stdio) rather than
119
        the slow 1 character read()s that getline uses.
120
 
121
void gl_setwidth(int width)
122
 
123
        Set the width of the terminal to the specified width. The default
124
        width is 80 characters, so this function need only be called if the
125
        width of the terminal is not 80.  Since horizontal scrolling is
126
        controlled by this parameter it is important to get it right.
127
 
128
void gl_histadd(char *buf)
129
 
130
        The gl_histadd function checks to see if the buf is not empty or
131
        whitespace, and also checks to make sure it is different than
132
        the last saved buffer to avoid repeats on the history list.
133
        If the buf is a new non-blank string a copy is made and saved on
134
        the history list, so the caller can re-use the specified buf.
135
 
136
void gl_strwidth(size_t (*func)())
137
        The gl_strwidth function allows the caller to supply a pointer to
138
        a prompt width calculation function (strlen by default). This
139
        allows the caller to embed escape sequences in the prompt and then
140
        tell getline how many screen spaces the prompt will take up.
141
 
142
The main loop in testgl.c, included in this directory, shows how the
143
input-edit package can be used:
144
 
145
extern char *gl_getline();
146
extern void  gl_histadd();
147
main()
148
{
149
    char *p;
150
    do {
151
        p = gl_getline("PROMPT>>>> ");
152
        gl_histadd(p);
153
        fputs(p, stdout);
154
    } while (*p != 0);
155
}
156
 
157
In order to allow the main program to have additional access to the buffer,
158
to implement things such as completion or auto-indent modes, three
159
function pointers can be bound to user functions to modify the buffer as
160
described below.  By default gl_in_hook and gl_out_hook are set to NULL,
161
and gl_tab_hook is bound to a function that inserts spaces until the next
162
logical tab stop is reached.  The user can reassign any of these pointers
163
to other functions.  Each of the functions bound to these hooks receives
164
the current buffer as the first argument, and must return the location of
165
the leftmost change made in the buffer.  If the buffer isn't modified the
166
functions should return -1.  When the hook function returns the screen is
167
updated to reflect any changes made by the user function.
168
 
169
int (*gl_in_hook)(char *buf)
170
 
171
        If gl_in_hook is non-NULL the function is called each time a new
172
        buffer is loaded. It is called when getline is entered, with an
173
        empty buffer, it is called each time a new buffer is loaded from
174
        the history with ^P or ^N, and it is called when an incremental
175
        search string is accepted (when the search is terminated). The
176
        buffer can be modified and will be redrawn upon return to getline().
177
 
178
int (*gl_out_hook)(char *buf)
179
 
180
        If gl_out_hook is non-NULL it is called when a line has been
181
        completed by the user entering a newline or return. The buffer
182
        handed to the hook does not yet have the newline appended. If the
183
        buffer is modified the screen is redrawn before getline returns the
184
        buffer to the caller.
185
 
186
int (*gl_tab_hook)(char *buf, int prompt_width, int *cursor_loc)
187
 
188
        If gl_tab_hook is non-NULL, it is called whenever a tab is typed.
189
        In addition to receiving the buffer, the current prompt width is
190
        given (needed to do tabbing right) and a pointer to the cursor
191
        offset is given, where a 0 offset means the first character in the
192
        line.  Not only does the cursor_loc tell the programmer where the
193
        TAB was received, but it can be reset so that the cursor will end
194
        up at the specified location after the screen is redrawn.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.