Changeset 32235 in project


Ignore:
Timestamp:
02/03/15 01:18:58 (5 years ago)
Author:
Alexej Magura
Message:

updates the readline docs

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/readline

    r32226 r32235  
    44== readline
    55
    6 Bindings for the GNU readline library.
     6An interface to the GNU readline library
    77
    88== Requirements
     
    1010* [[regex]]
    1111
    12 == API
     12== Interface
     13
     14=== Toplevel Commands
     15==== ,rl-!!
     16<procedure>,rl-!!</procedure>
     17Evaluates the previous command.
     18
     19This command is never added to the history list, sorry: <s>it broke the Matrix<s> it caused an infinite loop when entered twice in a row, so I just made it so that the previous command can never be {{,rl-!!}}.
     20
     21==== ,rl-clh
     22<procedure>,rl-clh</procedure>
     23Clears the current session's history list.
     24
     25==== ,rl-savhist
     26<procedure>,rl-savhist</procedure>
     27Enable/disable saving session history on exit
     28
     29It is enabled by default.
     30
     31==== ,rl-rec
     32<procedure>,rl-rec</procedure>
     33Enable/disable recording history for the current session
     34
     35It's enabled by default.
     36
     37==== ,rl-rd
     38<procedure>,rl-rd file</procedure>
     39Read file contents into the history list for the current session.
     40
     41Currently, there might be a bug (I haven't checked) where the file's name has an extra space added to it unless you enter it on a separate line:
     42 ,rl-rd
     43 ~/.csi_hist
     44
     45==== ,rl-vi
     46<procedure>,rl-vi</procedure>
     47Sets the current editing mode to Vi.
     48
     49The equivalent function call would be:
     50 (readline#parse-and-bind "set editing-mode vi")
     51
     52==== ,rl-emacs
     53<procedure>,rl-emacs</procedure>
     54Sets the current editing mode to Emacs
     55
     56=== Variables
     57==== Session
     58<procedure>session</procedure>
     59A Key-value list of settings that affect how some of the egg's functions behave.
     60
     61===== load-history-file
     62<type>boolean</type>
     63Used by {{install-history-file}}.  Set to {{#t}} by default; when set to {{#f}}, the history file will '''NOT''' be loaded at start-up.
     64
     65===== save-history-on-exit
     66<type>boolean</type>
     67Used by {{install-history-file}}.  Set to {{#t}} by default; when set to {{#f}}, the current session's history will '''NOT''' be saved to the history file on exit.
     68
     69===== record-history
     70Used by {{,rl-rec}}.  Set to {{#t}} by default; when set to {{#f}} it disables recording history for the current session.
     71
     72===== verify-history-expansions
     73Settings this to true makes {{,rl-!!}} wait for you to press enter instead of inserting {{EOL}} automatically.
    1374
    1475=== Functions
     
    2990
    3091==== readline
    31 <procedure>(readline prompt1 [prompt2])</procedure>
     92<procedure>(readline prompt1 [prompt2] )</procedure>
    3293
    3394Reads a line using the GNU readline() function and returns a string.
     
    41102Sets the state of the underlying readline environment to a clean slate.
    42103
    43 '''NOTE''' Calls {{free()}}; so using this more than once consecutively may cause problems, such as a {{segfault}}.
     104'''NOTE''' Calls {{free()}}; so using this more than once consecutively may result in undefined behavior, as in a segfault.
    44105
    45106==== clear-history
     
    113174
    114175Passes {{string}} straight to the readline library for parsing (see the readline manual page for details).
    115 
    116 ==== history-stifle
    117 <procedure>(history-stifle [max])</procedure>
    118 Limit the current history file/session (might be either or: this detail has not been tested) remembering only the last ''max'' entries.
    119 
    120 Call without args to unstifle the current history file/session.
    121 
    122 ==== history-stifled
    123 <procedure>(history-stifled)</procedure>
    124 Returns true or false depending on whether the current history file/session is being stifled.
    125 
    126 ==== history-search
    127 <procedure>(history-search string direction)</procedure>
    128 Search the history for ''string'' in ''direction'' starting at the current history position.
    129 
    130 ''Direction'' should be either ''-1'' for backwards, or ''>= 0'' for forwards.
    131 
    132 ==== history-search-backward
    133 <procedure>(history-search-backward string)</procedure>
    134 Search the history for ''string'' starting at the current history position and progressing backwards.
    135 
    136 ==== history-search-forward
    137 <procedure>(history-search-forward string)</procedure>
    138 Search the history for ''string'' starting at the current history position and progressing forwards.
    139 
    140 
    141 ==== history-search-backward-starts-with
    142 <procedure>(history-search-backward-starts-with string)</procedure>
    143 Search the history backwards for ''string'' starting at the current history position.  The search is anchored: matching lines must being with ''string''.
    144 
    145 ==== history-search-forward-starts-with
    146 <procedure>(history-search-forward-starts-with string)</procedure>
    147 Search the history forwards for ''string'' starting at the current history position.  The search is anchored: matching lines must being with ''string''.
    148 
    149 ==== history-search-from-position
    150 <procedure>(history-search-from-position string direction position)</procedure>
    151 Search the history in ''direction'' for ''string'' starting at the absolute index ''position''.
    152176
    153177==== history-list
     
    155179Returns the history list as a newline separated list.
    156180
    157 ==== history-list-length
    158 <procedure>(history-list-length)</procedure>
    159 Returns the current length of the history list.
    160 
    161 ==== history-list-max-entries
    162 <procedure>(history-list-max-entries)</procedure>
    163 Returns the maximum number of supported history entries.
    164 
    165 It is the maintainer's opinion that ''0'', as a return value, means unlimited.
    166 
    167 ==== history-list-size
    168 <procedure>(history-list-size)</procedure>
    169 Returns the ''sizeof'' all of the lines in the history list's entries.
    170 
    171181==== history-position
    172182<procedure>(history-position [pos])</procedure>
     
    175185Passing ''pos'' sets the current ''offset''.
    176186
    177 ==== history-use-timestamps
    178 <procedure>(history-write-timestamps yes-no)</procedure>
    179 If passed ''#t'', timestamps are written to the history file, so they can be preserved between sessions.  Timestamps are disabled by default.
    180 
    181 ==== history-get-entry
    182 <procedure>(history-get-entry index [time])</procedure>
    183 Returns the history entry at position ''index'' starting from ''history_base''.  Pass ''time'' as ''#t'' to have said entry's timestamp included in the return value.
    184 
    185 ==== history-current-entry
    186 <procedure>(history-current-entry [time])</procedure>
    187 Returns the current history entry as determined by the current history position; the return value is a string.
    188 
    189 ==== history-previous-entry
    190 <procedure>(history-previous-entry [time])</procedure>
    191 Returns the previous history entry as determined by the current history position; returns a string.
    192 
    193 ==== history-next-entry
    194 <procedure>(history-next-entry [time])</procedure>
    195 Returns the next history entry as determined by the current history position; returns a string.
     187==== add-history
     188<procedure>(%history-add% string)</procedure>
     189Adds ''string'' to the history list.
     190
     191'''NOTE'''
     192
     193This function exists primarily for testing purposes.
     194
     195Returns {{void}}
     196
     197
     198==== remove-history
     199<procedure>(%remove-history% offset)</procedure>
     200Removes and '''frees''' the specified history entry and its associated memory.
     201
     202==== eval-last-history-line
     203<procedure>(eval-last-history-line [script])</procedure>
     204The function behind {{,rl-!!}}.
     205
     206This function is '''not''' added to the history unless ''script'' is true.
     207DO '''NOT''' pass ''script'' as true, unless you know what you are doing: it makes it possible to accidentally cause an infinite loop if the previous command was also {{eval-last-history-line #t}}!!
     208
     209'''NOTE'''
     210
     211The line does not have to be from the current session.
     212Also, I don't know what happens when there isn't said line, but I reckon it'd cause a segfault; I'll see about fixing that in the 3.1 release.
    196213
    197214== Building
     
    267284
    268285=== Version history
     286; 3.0 : Removes a lot of the stuff introduced by 2.0; adds toplevel-commands for convience.
    269287; 3.0b2 : Fixed memleaks in history-list function and str_unquotd
    270288; 3.0b1 : Made a few tweaks to the API to keep it in sync with the documentation I've written.
Note: See TracChangeset for help on using the changeset viewer.