diff options
Diffstat (limited to 'lib/readline/doc')
| -rw-r--r-- | lib/readline/doc/Makefile | 159 | ||||
| -rw-r--r-- | lib/readline/doc/fdl.texi | 506 | ||||
| -rw-r--r-- | lib/readline/doc/history.texi | 85 | ||||
| -rw-r--r-- | lib/readline/doc/hstech.texi | 602 | ||||
| -rw-r--r-- | lib/readline/doc/hsuser.texi | 533 | ||||
| -rw-r--r-- | lib/readline/doc/rlman.texi | 84 | ||||
| -rw-r--r-- | lib/readline/doc/rltech.texi | 2815 | ||||
| -rw-r--r-- | lib/readline/doc/rluser.texi | 2488 | ||||
| -rw-r--r-- | lib/readline/doc/rluserman.texi | 70 | ||||
| -rw-r--r-- | lib/readline/doc/version.texi | 11 |
10 files changed, 7353 insertions, 0 deletions
diff --git a/lib/readline/doc/Makefile b/lib/readline/doc/Makefile new file mode 100644 index 0000000..2ad833a --- /dev/null +++ b/lib/readline/doc/Makefile @@ -0,0 +1,159 @@ +# Derived by hand from the generated readline-src/doc/Makefile +# This makefile for Readline library documentation is in -*- text -*- mode. +# Emacs likes it that way. + +# Copyright (C) 1996-2002 Free Software Foundation, Inc. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. +# + +topdir = . +srcdir = . +VPATH = . + +prefix = /usr/local +infodir = ${prefix}/info + +mandir = ${prefix}/man +manpfx = man + +man1ext = 1 +man1dir = $(mandir)/$(manpfx)$(man1ext) +man3ext = 3 +man3dir = $(mandir)/$(manpfx)$(man3ext) + +SHELL = /bin/sh +RM = rm -f + +INSTALL = /usr/bin/install -c +INSTALL_DATA = ${INSTALL} -m 644 + +BUILD_DIR = . +TEXINPUTDIR = $(srcdir) + +MAKEINFO = LANGUAGE= makeinfo +TEXI2DVI = $(srcdir)/texi2dvi +TEXI2HTML = $(srcdir)/texi2html +QUIETPS = #set this to -q to shut up dvips +PSDPI = 300 # I don't have any 600-dpi printers +DVIPS = dvips -D ${PSDPI} $(QUIETPS) -o $@ # tricky +DVIPDF = dvipdfm -o $@ -p ${PAPERSIZE} +PSPDF = gs -sPAPERSIZE=${PAPERSIZE} -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=$@ + +RLSRC = $(srcdir)/rlman.texi $(srcdir)/rluser.texi \ + $(srcdir)/rltech.texi $(srcdir)/version.texi \ + $(srcdir)/rluserman.texi +HISTSRC = $(srcdir)/history.texi $(srcdir)/hsuser.texi \ + $(srcdir)/hstech.texi $(srcdir)/version.texi + +# This should be a program that converts troff to an ascii-readable format +NROFF = groff -Tascii + +# This should be a program that converts troff to postscript +GROFF = groff + +DVIOBJ = readline.dvi history.dvi rluserman.dvi +INFOOBJ = readline.info history.info rluserman.info +PSOBJ = readline.ps history.ps rluserman.ps +HTMLOBJ = readline.html history.html rluserman.html +PDFOBJ = readline.pdf history.pdf rluserman.pdf + +INTERMEDIATE_OBJ = rlman.dvi + +CREATED_DOCS = $(DVIOBJ) $(INFOOBJ) $(PSOBJ) $(HTMLOBJ) $(PDFOBJ) + +.SUFFIXES: .ps .txt .dvi .html .pdf + +.ps.pdf: + $(RM) $@ + -${PSPDF} $< + +.dvi.pdf: + $(RM) $@ + -${DVIPDF} $< + +all: info dvi html ps +nodvi: info html +pdf: $(PDFOBJ) + +readline.dvi: $(RLSRC) + TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rlman.texi + mv rlman.dvi readline.dvi + +readline.info: $(RLSRC) + $(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texi + +rluserman.dvi: $(RLSRC) + TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rluserman.texi + +rluserman.info: $(RLSRC) + $(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rluserman.texi + +history.dvi: ${HISTSRC} + TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/history.texi + +history.info: ${HISTSRC} + $(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/history.texi + +readline.ps: readline.dvi + $(RM) $@ + $(DVIPS) readline.dvi + +rluserman.ps: rluserman.dvi + $(RM) $@ + $(DVIPS) rluserman.dvi + +history.ps: history.dvi + $(RM) $@ + $(DVIPS) history.dvi + +readline.html: ${RLSRC} + $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rlman.texi + sed -e 's:rlman.html:readline.html:' rlman.html > readline.html + $(RM) rlman.html + +rluserman.html: ${RLSRC} + $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rluserman.texi + +history.html: ${HISTSRC} + $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/history.texi + +info: $(INFOOBJ) +dvi: $(DVIOBJ) +ps: $(PSOBJ) +html: $(HTMLOBJ) + +readline.pdf: readline.dvi +history.pdf: history.dvi +rluserman.pdf: rluserman.dvi + +clean: + $(RM) *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps *.pgs \ + *.fns *.kys *.tps *.vrs *.bt *.bts *.o core *.core + +distclean: clean + $(RM) $(CREATED_DOCS) + $(RM) $(INTERMEDIATE_OBJ) + +mostlyclean: clean + +maintainer-clean: clean + $(RM) $(CREATED_DOCS) + $(RM) $(INTERMEDIATE_OBJ) + $(RM) Makefile + +install: + @echo "This documentation should not be installed." + +uninstall: diff --git a/lib/readline/doc/fdl.texi b/lib/readline/doc/fdl.texi new file mode 100644 index 0000000..8805f1a --- /dev/null +++ b/lib/readline/doc/fdl.texi @@ -0,0 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/lib/readline/doc/history.texi b/lib/readline/doc/history.texi new file mode 100644 index 0000000..721118b --- /dev/null +++ b/lib/readline/doc/history.texi @@ -0,0 +1,85 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header (This is for running Texinfo on a region.) +@setfilename history.info +@settitle GNU History Library +@include version.texi + +@c %**end of header (This is for running Texinfo on a region.) + +@copying +This document describes the GNU History library +(version @value{VERSION}, @value{UPDATED}), +a programming tool that provides a consistent user interface for +recalling lines of previously typed input. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* History: (history). The GNU history library API. +@end direntry + +@titlepage +@title GNU History Library +@subtitle Edition @value{EDITION}, for @code{History Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page + +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU History Library + +This document describes the GNU History library, a programming tool that +provides a consistent user interface for recalling lines of previously +typed input. + +@menu +* Using History Interactively:: GNU History User's Manual. +* Programming with GNU History:: GNU History Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. +@end menu +@end ifnottex + +@syncodeindex fn vr + +@include hsuser.texi +@include hstech.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@node Concept Index +@appendix Concept Index +@printindex cp + +@node Function and Variable Index +@appendix Function and Variable Index +@printindex vr + +@bye diff --git a/lib/readline/doc/hstech.texi b/lib/readline/doc/hstech.texi new file mode 100644 index 0000000..da6417b --- /dev/null +++ b/lib/readline/doc/hstech.texi @@ -0,0 +1,602 @@ +@ignore +This file documents the user interface to the GNU History library. + +Copyright (C) 1988-2022 Free Software Foundation, Inc. +Authored by Brian Fox and Chet Ramey. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Programming with GNU History +@chapter Programming with GNU History + +This chapter describes how to interface programs that you write +with the @sc{gnu} History Library. +It should be considered a technical guide. +For information on the interactive use of @sc{gnu} History, @pxref{Using +History Interactively}. + +@menu +* Introduction to History:: What is the GNU History library for? +* History Storage:: How information is stored. +* History Functions:: Functions that you can use. +* History Variables:: Variables that control behaviour. +* History Programming Example:: Example of using the GNU History Library. +@end menu + +@node Introduction to History +@section Introduction to History + +Many programs read input from the user a line at a time. The @sc{gnu} +History library is able to keep track of those lines, associate arbitrary +data with each line, and utilize information from previous lines in +composing new ones. + +A programmer using the History library has available functions +for remembering lines on a history list, associating arbitrary data +with a line, removing lines from the list, searching through the list +for a line containing an arbitrary text string, and referencing any line +in the list directly. In addition, a history @dfn{expansion} function +is available which provides for a consistent user interface across +different programs. + +The user using programs written with the History library has the +benefit of a consistent user interface with a set of well-known +commands for manipulating the text of previous lines and using that text +in new commands. The basic history manipulation commands are similar to +the history substitution provided by @code{csh}. + +The programmer can also use the Readline library, which +includes some history manipulation by default, and has the added +advantage of command line editing. + +Before declaring any functions using any functionality the History +library provides in other code, an application writer should include +the file @code{<readline/history.h>} in any file that uses the +History library's features. It supplies extern declarations for all +of the library's public functions and variables, and declares all of +the public data structures. + +@node History Storage +@section History Storage + +The history list is an array of history entries. A history entry is +declared as follows: + +@example +typedef void *histdata_t; + +typedef struct _hist_entry @{ + char *line; + char *timestamp; + histdata_t data; +@} HIST_ENTRY; +@end example + +The history list itself might therefore be declared as + +@example +HIST_ENTRY **the_history_list; +@end example + +The state of the History library is encapsulated into a single structure: + +@example +/* + * A structure used to pass around the current state of the history. + */ +typedef struct _hist_state @{ + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; +@} HISTORY_STATE; +@end example + +If the flags member includes @code{HS_STIFLED}, the history has been +stifled. + +@node History Functions +@section History Functions + +This section describes the calling sequence for the various functions +exported by the @sc{gnu} History library. + +@menu +* Initializing History and State Management:: Functions to call when you + want to use history in a + program. +* History List Management:: Functions used to manage the list + of history entries. +* Information About the History List:: Functions returning information about + the history list. +* Moving Around the History List:: Functions used to change the position + in the history list. +* Searching the History List:: Functions to search the history list + for entries containing a string. +* Managing the History File:: Functions that read and write a file + containing the history list. +* History Expansion:: Functions to perform csh-like history + expansion. +@end menu + +@node Initializing History and State Management +@subsection Initializing History and State Management + +This section describes functions used to initialize and manage +the state of the History library when you want to use the history +functions in your program. + +@deftypefun void using_history (void) +Begin a session in which the history functions might be used. This +initializes the interactive variables. +@end deftypefun + +@deftypefun {HISTORY_STATE *} history_get_history_state (void) +Return a structure describing the current state of the input history. +@end deftypefun + +@deftypefun void history_set_history_state (HISTORY_STATE *state) +Set the state of the history list according to @var{state}. +@end deftypefun + +@node History List Management +@subsection History List Management + +These functions manage individual entries on the history list, or set +parameters managing the list itself. + +@deftypefun void add_history (const char *string) +Place @var{string} at the end of the history list. The associated data +field (if any) is set to @code{NULL}. +If the maximum number of history entries has been set using +@code{stifle_history()}, and the new number of history entries would exceed +that maximum, the oldest history entry is removed. +@end deftypefun + +@deftypefun void add_history_time (const char *string) +Change the time stamp associated with the most recent history entry to +@var{string}. +@end deftypefun + +@deftypefun {HIST_ENTRY *} remove_history (int which) +Remove history entry at offset @var{which} from the history. The +removed element is returned so you can free the line, data, +and containing structure. +@end deftypefun + +@deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent) +Free the history entry @var{histent} and any history library private +data associated with it. Returns the application-specific data +so the caller can dispose of it. +@end deftypefun + +@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data) +Make the history entry at offset @var{which} have @var{line} and @var{data}. +This returns the old entry so the caller can dispose of any +application-specific data. In the case +of an invalid @var{which}, a @code{NULL} pointer is returned. +@end deftypefun + +@deftypefun void clear_history (void) +Clear the history list by deleting all the entries. +@end deftypefun + +@deftypefun void stifle_history (int max) +Stifle the history list, remembering only the last @var{max} entries. +The history list will contain only @var{max} entries at a time. +@end deftypefun + +@deftypefun int unstifle_history (void) +Stop stifling the history. This returns the previously-set +maximum number of history entries (as set by @code{stifle_history()}). +The value is positive if the history was +stifled, negative if it wasn't. +@end deftypefun + +@deftypefun int history_is_stifled (void) +Returns non-zero if the history is stifled, zero if it is not. +@end deftypefun + +@node Information About the History List +@subsection Information About the History List + +These functions return information about the entire history list or +individual list entries. + +@deftypefun {HIST_ENTRY **} history_list (void) +Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the +current input history. Element 0 of this list is the beginning of time. +If there is no history, return @code{NULL}. +@end deftypefun + +@deftypefun int where_history (void) +Returns the offset of the current history element. +@end deftypefun + +@deftypefun {HIST_ENTRY *} current_history (void) +Return the history entry at the current position, as determined by +@code{where_history()}. If there is no entry there, return a @code{NULL} +pointer. +@end deftypefun + +@deftypefun {HIST_ENTRY *} history_get (int offset) +Return the history entry at position @var{offset}. +The range of valid +values of @var{offset} starts at @code{history_base} and ends at +@var{history_length} - 1 (@pxref{History Variables}). +If there is no entry there, or if @var{offset} is outside the valid +range, return a @code{NULL} pointer. +@end deftypefun + +@deftypefun time_t history_get_time (HIST_ENTRY *entry) +Return the time stamp associated with the history entry @var{entry}. +If the timestamp is missing or invalid, return 0. +@end deftypefun + +@deftypefun int history_total_bytes (void) +Return the number of bytes that the primary history entries are using. +This function returns the sum of the lengths of all the lines in the +history. +@end deftypefun + +@node Moving Around the History List +@subsection Moving Around the History List + +These functions allow the current index into the history list to be +set or changed. + +@deftypefun int history_set_pos (int pos) +Set the current history offset to @var{pos}, an absolute index +into the list. +Returns 1 on success, 0 if @var{pos} is less than zero or greater +than the number of history entries. +@end deftypefun + +@deftypefun {HIST_ENTRY *} previous_history (void) +Back up the current history offset to the previous history entry, and +return a pointer to that entry. If there is no previous entry, return +a @code{NULL} pointer. +@end deftypefun + +@deftypefun {HIST_ENTRY *} next_history (void) +If the current history offset refers to a valid history entry, +increment the current history offset. +If the possibly-incremented history offset refers to a valid history +entry, return a pointer to that entry; +otherwise, return a @code{BNULL} pointer. +@end deftypefun + +@node Searching the History List +@subsection Searching the History List +@cindex History Searching + +These functions allow searching of the history list for entries containing +a specific string. Searching may be performed both forward and backward +from the current history position. The search may be @dfn{anchored}, +meaning that the string must match at the beginning of the history entry. +@cindex anchored search + +@deftypefun int history_search (const char *string, int direction) +Search the history for @var{string}, starting at the current history offset. +If @var{direction} is less than 0, then the search is through +previous entries, otherwise through subsequent entries. +If @var{string} is found, then +the current history index is set to that history entry, and the value +returned is the offset in the line of the entry where +@var{string} was found. Otherwise, nothing is changed, and a -1 is +returned. +@end deftypefun + +@deftypefun int history_search_prefix (const char *string, int direction) +Search the history for @var{string}, starting at the current history +offset. The search is anchored: matching lines must begin with +@var{string}. If @var{direction} is less than 0, then the search is +through previous entries, otherwise through subsequent entries. +If @var{string} is found, then the +current history index is set to that entry, and the return value is 0. +Otherwise, nothing is changed, and a -1 is returned. +@end deftypefun + +@deftypefun int history_search_pos (const char *string, int direction, int pos) +Search for @var{string} in the history list, starting at @var{pos}, an +absolute index into the list. If @var{direction} is negative, the search +proceeds backward from @var{pos}, otherwise forward. Returns the absolute +index of the history element where @var{string} was found, or -1 otherwise. +@end deftypefun + +@node Managing the History File +@subsection Managing the History File + +The History library can read the history from and write it to a file. +This section documents the functions for managing a history file. + +@deftypefun int read_history (const char *filename) +Add the contents of @var{filename} to the history list, a line at a time. +If @var{filename} is @code{NULL}, then read from @file{~/.history}. +Returns 0 if successful, or @code{errno} if not. +@end deftypefun + +@deftypefun int read_history_range (const char *filename, int from, int to) +Read a range of lines from @var{filename}, adding them to the history list. +Start reading at line @var{from} and end at @var{to}. +If @var{from} is zero, start at the beginning. If @var{to} is less than +@var{from}, then read until the end of the file. If @var{filename} is +@code{NULL}, then read from @file{~/.history}. Returns 0 if successful, +or @code{errno} if not. +@end deftypefun + +@deftypefun int write_history (const char *filename) +Write the current history to @var{filename}, overwriting @var{filename} +if necessary. +If @var{filename} is @code{NULL}, then write the history list to +@file{~/.history}. +Returns 0 on success, or @code{errno} on a read or write error. +@end deftypefun + +@deftypefun int append_history (int nelements, const char *filename) +Append the last @var{nelements} of the history list to @var{filename}. +If @var{filename} is @code{NULL}, then append to @file{~/.history}. +Returns 0 on success, or @code{errno} on a read or write error. +@end deftypefun + +@deftypefun int history_truncate_file (const char *filename, int nlines) +Truncate the history file @var{filename}, leaving only the last +@var{nlines} lines. +If @var{filename} is @code{NULL}, then @file{~/.history} is truncated. +Returns 0 on success, or @code{errno} on failure. +@end deftypefun + +@node History Expansion +@subsection History Expansion + +These functions implement history expansion. + +@deftypefun int history_expand (char *string, char **output) +Expand @var{string}, placing the result into @var{output}, a pointer +to a string (@pxref{History Interaction}). Returns: +@table @code +@item 0 +If no expansions took place (or, if the only change in +the text was the removal of escape characters preceding the history expansion +character); +@item 1 +if expansions did take place; +@item -1 +if there was an error in expansion; +@item 2 +if the returned line should be displayed, but not executed, +as with the @code{:p} modifier (@pxref{Modifiers}). +@end table + +If an error occurred in expansion, then @var{output} contains a descriptive +error message. +@end deftypefun + +@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar) +Returns the text of the history event beginning at @var{string} + +@var{*cindex}. @var{*cindex} is modified to point to after the event +specifier. At function entry, @var{cindex} points to the index into +@var{string} where the history event specification begins. @var{qchar} +is a character that is allowed to end the event specification in addition +to the ``normal'' terminating characters. +@end deftypefun + +@deftypefun {char **} history_tokenize (const char *string) +Return an array of tokens parsed out of @var{string}, much as the +shell might. The tokens are split on the characters in the +@var{history_word_delimiters} variable, +and shell quoting conventions are obeyed as described below. +@end deftypefun + +@deftypefun {char *} history_arg_extract (int first, int last, const char *string) +Extract a string segment consisting of the @var{first} through @var{last} +arguments present in @var{string}. Arguments are split using +@code{history_tokenize}. +@end deftypefun + +@node History Variables +@section History Variables + +This section describes the externally-visible variables exported by +the @sc{gnu} History Library. + +@deftypevar int history_base +The logical offset of the first entry in the history list. +@end deftypevar + +@deftypevar int history_length +The number of entries currently stored in the history list. +@end deftypevar + +@deftypevar int history_max_entries +The maximum number of history entries. This must be changed using +@code{stifle_history()}. +@end deftypevar + +@deftypevar int history_write_timestamps +If non-zero, timestamps are written to the history file, so they can be +preserved between sessions. The default value is 0, meaning that +timestamps are not saved. + +The current timestamp format uses the value of @var{history_comment_char} +to delimit timestamp entries in the history file. If that variable does +not have a value (the default), timestamps will not be written. +@end deftypevar + +@deftypevar char history_expansion_char +The character that introduces a history event. The default is @samp{!}. +Setting this to 0 inhibits history expansion. +@end deftypevar + +@deftypevar char history_subst_char +The character that invokes word substitution if found at the start of +a line. The default is @samp{^}. +@end deftypevar + +@deftypevar char history_comment_char +During tokenization, if this character is seen as the first character +of a word, then it and all subsequent characters up to a newline are +ignored, suppressing history expansion for the remainder of the line. +This is disabled by default. +@end deftypevar + +@deftypevar {char *} history_word_delimiters +The characters that separate tokens for @code{history_tokenize()}. +The default value is @code{" \t\n()<>;&|"}. +@end deftypevar + +@deftypevar {char *} history_search_delimiter_chars +The list of additional characters which can delimit a history search +string, in addition to space, TAB, @samp{:} and @samp{?} in the case of +a substring search. The default is empty. +@end deftypevar + +@deftypevar {char *} history_no_expand_chars +The list of characters which inhibit history expansion if found immediately +following @var{history_expansion_char}. The default is space, tab, newline, +carriage return, and @samp{=}. +@end deftypevar + +@deftypevar int history_quotes_inhibit_expansion +If non-zero, the history expansion code implements shell-like quoting: +single-quoted words are not scanned for the history expansion +character or the history comment character, and double-quoted words may +have history expansion performed, since single quotes are not special +within double quotes. +The default value is 0. +@end deftypevar + +@deftypevar int history_quoting_state +An application may set this variable to indicate that the current line +being expanded is subject to existing quoting. If set to @samp{'}, the +history expansion function will assume that the line is single-quoted and +inhibit expansion until it reads an unquoted closing single quote; if set +to @samp{"}, history expansion will assume the line is double quoted until +it reads an unquoted closing double quote. If set to zero, the default, +the history expansion function will assume the line is not quoted and +treat quote characters within the line as described above. +This is only effective if @var{history_quotes_inhibit_expansion} is set. +@end deftypevar + +@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function +This should be set to the address of a function that takes two arguments: +a @code{char *} (@var{string}) +and an @code{int} index into that string (@var{i}). +It should return a non-zero value if the history expansion starting at +@var{string[i]} should not be performed; zero if the expansion should +be done. +It is intended for use by applications like Bash that use the history +expansion character for additional purposes. +By default, this variable is set to @code{NULL}. +@end deftypevar + +@node History Programming Example +@section History Programming Example + +The following program demonstrates simple use of the @sc{gnu} History Library. + +@smallexample +#include <stdio.h> +#include <readline/history.h> + +main (argc, argv) + int argc; + char **argv; +@{ + char line[1024], *t; + int len, done = 0; + + line[0] = 0; + + using_history (); + while (!done) + @{ + printf ("history$ "); + fflush (stdout); + t = fgets (line, sizeof (line) - 1, stdin); + if (t && *t) + @{ + len = strlen (t); + if (t[len - 1] == '\n') + t[len - 1] = '\0'; + @} + + if (!t) + strcpy (line, "quit"); + + if (line[0]) + @{ + char *expansion; + int result; + + result = history_expand (line, &expansion); + if (result) + fprintf (stderr, "%s\n", expansion); + + if (result < 0 || result == 2) + @{ + free (expansion); + continue; + @} + + add_history (expansion); + strncpy (line, expansion, sizeof (line) - 1); + free (expansion); + @} + + if (strcmp (line, "quit") == 0) + done = 1; + else if (strcmp (line, "save") == 0) + write_history ("history_file"); + else if (strcmp (line, "read") == 0) + read_history ("history_file"); + else if (strcmp (line, "list") == 0) + @{ + register HIST_ENTRY **the_list; + register int i; + + the_list = history_list (); + if (the_list) + for (i = 0; the_list[i]; i++) + printf ("%d: %s\n", i + history_base, the_list[i]->line); + @} + else if (strncmp (line, "delete", 6) == 0) + @{ + int which; + if ((sscanf (line + 6, "%d", &which)) == 1) + @{ + HIST_ENTRY *entry = remove_history (which); + if (!entry) + fprintf (stderr, "No such entry %d\n", which); + else + @{ + free (entry->line); + free (entry); + @} + @} + else + @{ + fprintf (stderr, "non-numeric arg given to `delete'\n"); + @} + @} + @} +@} +@end smallexample diff --git a/lib/readline/doc/hsuser.texi b/lib/readline/doc/hsuser.texi new file mode 100644 index 0000000..9081baf --- /dev/null +++ b/lib/readline/doc/hsuser.texi @@ -0,0 +1,533 @@ +@ignore +This file documents the user interface to the GNU History library. + +Copyright (C) 1988--2022 Free Software Foundation, Inc. +Authored by Brian Fox and Chet Ramey. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Using History Interactively +@chapter Using History Interactively + +@ifclear BashFeatures +@defcodeindex bt +@end ifclear + +@ifset BashFeatures +This chapter describes how to use the @sc{gnu} History Library +interactively, from a user's standpoint. +It should be considered a user's guide. +For information on using the @sc{gnu} History Library in other programs, +see the @sc{gnu} Readline Library Manual. +@end ifset +@ifclear BashFeatures +This chapter describes how to use the @sc{gnu} History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the @sc{gnu} History Library in your own programs, +@pxref{Programming with GNU History}. +@end ifclear + +@ifset BashFeatures +@menu +* Bash History Facilities:: How Bash lets you manipulate your command + history. +* Bash History Builtins:: The Bash builtin commands that manipulate + the command history. +* History Interaction:: What it feels like using History as a user. +@end menu +@end ifset +@ifclear BashFeatures +@menu +* History Interaction:: What it feels like using History as a user. +@end menu +@end ifclear + +@ifset BashFeatures +@node Bash History Facilities +@section Bash History Facilities +@cindex command history +@cindex history list + +When the @option{-o history} option to the @code{set} builtin +is enabled (@pxref{The Set Builtin}), +the shell provides access to the @dfn{command history}, +the list of commands previously typed. +The value of the @env{HISTSIZE} shell variable is used as the +number of commands to save in a history list. +The text of the last @env{$HISTSIZE} +commands (default 500) is saved. +The shell stores each command in the history list prior to +parameter and variable expansion +but after history expansion is performed, subject to the +values of the shell variables +@env{HISTIGNORE} and @env{HISTCONTROL}. + +When the shell starts up, the history is initialized from the +file named by the @env{HISTFILE} variable (default @file{~/.bash_history}). +The file named by the value of @env{HISTFILE} is truncated, if +necessary, to contain no more than the number of lines specified by +the value of the @env{HISTFILESIZE} variable. +When a shell with history enabled exits, the last +@env{$HISTSIZE} lines are copied from the history list to the file +named by @env{$HISTFILE}. +If the @code{histappend} shell option is set (@pxref{Bash Builtins}), +the lines are appended to the history file, +otherwise the history file is overwritten. +If @env{HISTFILE} +is unset, or if the history file is unwritable, the history is not saved. +After saving the history, the history file is truncated +to contain no more than @env{$HISTFILESIZE} lines. +If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or +a numeric value less than zero, the history file is not truncated. + +If the @env{HISTTIMEFORMAT} is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. +When the history file is read, lines beginning with the history +comment character followed immediately by a digit are interpreted +as timestamps for the following history entry. + +The builtin command @code{fc} may be used to list or edit and re-execute +a portion of the history list. +The @code{history} builtin may be used to display or modify the history +list and manipulate the history file. +When using command-line editing, search commands +are available in each editing mode that provide access to the +history list (@pxref{Commands For History}). + +The shell allows control over which commands are saved on the history +list. The @env{HISTCONTROL} and @env{HISTIGNORE} +variables may be set to cause the shell to save only a subset of the +commands entered. +The @code{cmdhist} +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The @code{lithist} +shell option causes the shell to save the command with embedded newlines +instead of semicolons. +The @code{shopt} builtin is used to set these options. +@xref{The Shopt Builtin}, for a description of @code{shopt}. + +@node Bash History Builtins +@section Bash History Builtins +@cindex history builtins + +Bash provides two builtin commands which manipulate the +history list and history file. + +@table @code + +@item fc +@btindex fc +@example +@code{fc [-e @var{ename}] [-lnr] [@var{first}] [@var{last}]} +@code{fc -s [@var{pat}=@var{rep}] [@var{command}]} +@end example + +The first form selects a range of commands from @var{first} to +@var{last} from the history list and displays or edits and re-executes +them. +Both @var{first} and +@var{last} may be specified as a string (to locate the most recent +command beginning with that string) or as a number (an index into the +history list, where a negative number is used as an offset from the +current command number). + +When listing, a @var{first} or @var{last} of 0 is equivalent to -1 +and -0 is equivalent to the current command (usually the @code{fc} +command); +otherwise 0 is equivalent to -1 and -0 is invalid. + +If @var{last} is not specified, it is set to +@var{first}. If @var{first} is not specified, it is set to the previous +command for editing and @minus{}16 for listing. If the @option{-l} flag is +given, the commands are listed on standard output. The @option{-n} flag +suppresses the command numbers when listing. The @option{-r} flag +reverses the order of the listing. Otherwise, the editor given by +@var{ename} is invoked on a file containing those commands. If +@var{ename} is not given, the value of the following variable expansion +is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the +value of the @env{FCEDIT} variable if set, or the value of the +@env{EDITOR} variable if that is set, or @code{vi} if neither is set. +When editing is complete, the edited commands are echoed and executed. + +In the second form, @var{command} is re-executed after each instance +of @var{pat} in the selected command is replaced by @var{rep}. +@var{command} is interpreted the same as @var{first} above. + +A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so +that typing @samp{r cc} runs the last command beginning with @code{cc} +and typing @samp{r} re-executes the last command (@pxref{Aliases}). + +@item history +@btindex history +@example +history [@var{n}] +history -c +history -d @var{offset} +history -d @var{start}-@var{end} +history [-anrw] [@var{filename}] +history -ps @var{arg} +@end example + +With no options, display the history list with line numbers. +Lines prefixed with a @samp{*} have been modified. +An argument of @var{n} lists only the last @var{n} lines. +If the shell variable @env{HISTTIMEFORMAT} is set and not null, +it is used as a format string for @var{strftime} to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. + +Options, if supplied, have the following meanings: + +@table @code +@item -c +Clear the history list. This may be combined +with the other options to replace the history list completely. + +@item -d @var{offset} +Delete the history entry at position @var{offset}. +If @var{offset} is positive, it should be specified as it appears when +the history is displayed. +If @var{offset} is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of @samp{-1} refers to the current +@code{history -d} command. + +@item -d @var{start}-@var{end} +Delete the range of history entries between positions @var{start} and +@var{end}, inclusive. +Positive and negative values for @var{start} and @var{end} +are interpreted as described above. + +@item -a +Append the new history lines to the history file. +These are history lines entered since the beginning of the current +Bash session, but not already appended to the history file. + +@item -n +Append the history lines not already read from the history file +to the current history list. These are lines appended to the history +file since the beginning of the current Bash session. + +@item -r +Read the history file and append its contents to +the history list. + +@item -w +Write out the current history list to the history file. + +@item -p +Perform history substitution on the @var{arg}s and display the result +on the standard output, without storing the results in the history list. + +@item -s +The @var{arg}s are added to the end of +the history list as a single entry. + +@end table + +If a @var{filename} argument is supplied +when any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options +is used, Bash uses @var{filename} as the history file. +If not, then the value of the @env{HISTFILE} variable is used. + +The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +@var{offset} or range is supplied as an argument to @option{-d}, or the +history expansion supplied as an argument to @option{-p} fails. + +@end table +@end ifset + +@node History Interaction +@section History Expansion +@cindex history expansion + +The History library provides a history expansion feature that is similar +to the history expansion provided by @code{csh}. This section +describes the syntax used to manipulate the history information. + +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. + +@ifset BashFeatures +History expansion is performed immediately after a complete line +is read, before the shell breaks it into words, and is performed +on each line individually. Bash attempts to inform the history +expansion functions about quoting still in effect from previous lines. +@end ifset + +History expansion takes place in two parts. The first is to determine +which line from the history list should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the history is called the +@dfn{event}, and the portions of that line that are acted upon are +called @dfn{words}. Various @dfn{modifiers} are available to manipulate +the selected words. The line is broken into words in the same fashion +that Bash does, so that several words +surrounded by quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is @samp{!} by default. + +History expansion implements shell-like quoting conventions: +a backslash can be used to remove the special handling for the next character; +single quotes enclose verbatim sequences of characters, and can be used to +inhibit history expansion; +and characters enclosed within double quotes may be subject to history +expansion, since backslash can escape the history expansion character, +but single quotes may not, since they are not treated specially within +double quotes. + +@ifset BashFeatures +When using the shell, only @samp{\} and @samp{'} may be used to escape the +history expansion character, but the history expansion character is +also treated as quoted if it immediately precedes the closing double quote +in a double-quoted string. +@end ifset + +@ifset BashFeatures +Several shell options settable with the @code{shopt} +builtin (@pxref{The Shopt Builtin}) may be used to tailor +the behavior of history expansion. If the +@code{histverify} shell option is enabled, and Readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the Readline +editing buffer for further modification. +If Readline is being used, and the @code{histreedit} +shell option is enabled, a failed history expansion will be +reloaded into the Readline editing buffer for correction. +The @option{-p} option to the @code{history} builtin command +may be used to see what a history expansion will do before using it. +The @option{-s} option to the @code{history} builtin may be used to +add commands to the end of the history list without actually executing +them, so that they are available for subsequent recall. +This is most useful in conjunction with Readline. + +The shell allows control of the various characters used by the +history expansion mechanism with the @code{histchars} variable, +as explained above (@pxref{Bash Variables}). The shell uses +the history comment character to mark history timestamps when +writing the history file. +@end ifset + +@menu +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. +@end menu + +@node Event Designators +@subsection Event Designators +@cindex event designators + +An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +@cindex history events + +@table @asis + +@item @code{!} +@ifset BashFeatures +Start a history substitution, except when followed by a space, tab, +the end of the line, @samp{=} or @samp{(} (when the +@code{extglob} shell option is enabled using the @code{shopt} builtin). +@end ifset +@ifclear BashFeatures +Start a history substitution, except when followed by a space, tab, +the end of the line, or @samp{=}. +@end ifclear + +@item @code{!@var{n}} +Refer to command line @var{n}. + +@item @code{!-@var{n}} +Refer to the command @var{n} lines back. + +@item @code{!!} +Refer to the previous command. This is a synonym for @samp{!-1}. + +@item @code{!@var{string}} +Refer to the most recent command +preceding the current position in the history list +starting with @var{string}. + +@item @code{!?@var{string}[?]} +Refer to the most recent command +preceding the current position in the history list +containing @var{string}. +The trailing +@samp{?} may be omitted if the @var{string} is followed immediately by +a newline. +If @var{string} is missing, the string from the most recent search is used; +it is an error if there is no previous search string. + +@item @code{^@var{string1}^@var{string2}^} +Quick Substitution. Repeat the last command, replacing @var{string1} +with @var{string2}. Equivalent to +@code{!!:s^@var{string1}^@var{string2}^}. + +@item @code{!#} +The entire command line typed so far. + +@end table + +@node Word Designators +@subsection Word Designators + +Word designators are used to select desired words from the event. +A @samp{:} separates the event specification from the word designator. It +may be omitted if the word designator begins with a @samp{^}, @samp{$}, +@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning +of the line, with the first word being denoted by 0 (zero). Words are +inserted into the current line separated by single spaces. + +@need 0.75 +For example, + +@table @code +@item !! +designates the preceding command. When you type this, the preceding +command is repeated in toto. + +@item !!:$ +designates the last argument of the preceding command. This may be +shortened to @code{!$}. + +@item !fi:2 +designates the second argument of the most recent command starting with +the letters @code{fi}. +@end table + +@need 0.75 +Here are the word designators: + +@table @code + +@item 0 (zero) +The @code{0}th word. For many applications, this is the command word. + +@item @var{n} +The @var{n}th word. + +@item ^ +The first argument; that is, word 1. + +@item $ +The last argument. + +@item % +The first word matched by the most recent @samp{?@var{string}?} search, +if the search string begins with a character that is part of a word. + +@item @var{x}-@var{y} +A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}. + +@item * +All of the words, except the @code{0}th. This is a synonym for @samp{1-$}. +It is not an error to use @samp{*} if there is just one word in the event; +the empty string is returned in that case. + +@item @var{x}* +Abbreviates @samp{@var{x}-$} + +@item @var{x}- +Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word. +If @samp{x} is missing, it defaults to 0. + +@end table + +If a word designator is supplied without an event specification, the +previous command is used as the event. + +@node Modifiers +@subsection Modifiers + +After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a @samp{:}. +These modify, or edit, the word or words selected from the history event. + +@table @code + +@item h +Remove a trailing pathname component, leaving only the head. + +@item t +Remove all leading pathname components, leaving the tail. + +@item r +Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving +the basename. + +@item e +Remove all but the trailing suffix. + +@item p +Print the new command but do not execute it. + +@ifset BashFeatures +@item q +Quote the substituted words, escaping further substitutions. + +@item x +Quote the substituted words as with @samp{q}, +but break into words at spaces, tabs, and newlines. +The @samp{q} and @samp{x} modifiers are mutually exclusive; the last one +supplied is used. +@end ifset + +@item s/@var{old}/@var{new}/ +Substitute @var{new} for the first occurrence of @var{old} in the +event line. +Any character may be used as the delimiter in place of @samp{/}. +The delimiter may be quoted in @var{old} and @var{new} +with a single backslash. If @samp{&} appears in @var{new}, +it is replaced by @var{old}. A single backslash will quote +the @samp{&}. +If @var{old} is null, it is set to the last @var{old} +substituted, or, if no previous history substitutions took place, +the last @var{string} +in a !?@var{string}@code{[?]} +search. +If @var{new} is null, each matching @var{old} is deleted. +The final delimiter is optional if it is the last +character on the input line. + +@item & +Repeat the previous substitution. + +@item g +@itemx a +Cause changes to be applied over the entire event line. Used in +conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/}, +or with @samp{&}. + +@item G +Apply the following @samp{s} or @samp{&} modifier once to each word +in the event. + +@end table diff --git a/lib/readline/doc/rlman.texi b/lib/readline/doc/rlman.texi new file mode 100644 index 0000000..d046b87 --- /dev/null +++ b/lib/readline/doc/rlman.texi @@ -0,0 +1,84 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename readline.info +@settitle GNU Readline Library +@include version.texi + +@comment %**end of header (This is for running Texinfo on a region.) +@synindex vr fn + +@copying +This manual describes the GNU Readline Library +(version @value{VERSION}, @value{UPDATED}), a library which aids in the +consistency of user interface across discrete programs which provide +a command line interface. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* Readline: (readline). The GNU readline library API. +@end direntry + +@titlepage +@title GNU Readline Library +@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Readline Library + +This document describes the GNU Readline Library, a utility which aids +in the consistency of user interface across discrete programs which +provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. + +@menu +* Command Line Editing:: GNU Readline User's Manual. +* Programming with GNU Readline:: GNU Readline Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. +@end menu +@end ifnottex + +@include rluser.texi +@include rltech.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@node Concept Index +@unnumbered Concept Index +@printindex cp + +@node Function and Variable Index +@unnumbered Function and Variable Index +@printindex fn + +@bye diff --git a/lib/readline/doc/rltech.texi b/lib/readline/doc/rltech.texi new file mode 100644 index 0000000..a93f77d --- /dev/null +++ b/lib/readline/doc/rltech.texi @@ -0,0 +1,2815 @@ +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rltech.info +@comment %**end of header (This is for running Texinfo on a region.) + +@ifinfo +This document describes the GNU Readline Library, a utility for aiding +in the consistency of user interface across discrete programs that need +to provide a command line interface. + +Copyright (C) 1988--2022 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +pare preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@node Programming with GNU Readline +@chapter Programming with GNU Readline + +This chapter describes the interface between the @sc{gnu} Readline Library and +other programs. If you are a programmer, and you wish to include the +features found in @sc{gnu} Readline +such as completion, line editing, and interactive history manipulation +in your own programs, this section is for you. + +@menu +* Basic Behavior:: Using the default behavior of Readline. +* Custom Functions:: Adding your own functions to Readline. +* Readline Variables:: Variables accessible to custom + functions. +* Readline Convenience Functions:: Functions which Readline supplies to + aid in writing your own custom + functions. +* Readline Signal Handling:: How Readline behaves when it receives signals. +* Custom Completers:: Supplanting or supplementing Readline's + completion functions. +@end menu + +@node Basic Behavior +@section Basic Behavior + +Many programs provide a command line interface, such as @code{mail}, +@code{ftp}, and @code{sh}. For such programs, the default behaviour of +Readline is sufficient. This section describes how to use Readline in +the simplest way possible, perhaps to replace calls in your code to +@code{gets()} or @code{fgets()}. + +@findex readline +@cindex readline, function + +The function @code{readline()} prints a prompt @var{prompt} +and then reads and returns a single line of text from the user. +If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed. +The line @code{readline} returns is allocated with @code{malloc()}; +the caller should @code{free()} the line when it has finished with it. +The declaration for @code{readline} in ANSI C is + +@example +@code{char *readline (const char *@var{prompt});} +@end example + +@noindent +So, one might say +@example +@code{char *line = readline ("Enter a line: ");} +@end example +@noindent +in order to read a line of text from the user. +The line returned has the final newline removed, so only the +text remains. + +If @code{readline} encounters an @code{EOF} while reading the line, and the +line is empty at that point, then @code{(char *)NULL} is returned. +Otherwise, the line is ended just as if a newline had been typed. + +Readline performs some expansion on the @var{prompt} before it is +displayed on the screen. See the description of @code{rl_expand_prompt} +(@pxref{Redisplay}) for additional details, especially if @var{prompt} +will contain characters that do not consume physical screen space when +displayed. + +If you want the user to be able to get at the line later, (with +@key{C-p} for example), you must call @code{add_history()} to save the +line away in a @dfn{history} list of such lines. + +@example +@code{add_history (line)}; +@end example + +@noindent +For full details on the GNU History Library, see the associated manual. + +It is preferable to avoid saving empty lines on the history list, since +users rarely have a burning need to reuse a blank line. Here is +a function which usefully replaces the standard @code{gets()} library +function, and has the advantage of no static buffer to overflow: + +@example +/* A static variable for holding the line. */ +static char *line_read = (char *)NULL; + +/* Read a string, and return a pointer to it. + Returns NULL on EOF. */ +char * +rl_gets () +@{ + /* If the buffer has already been allocated, + return the memory to the free pool. */ + if (line_read) + @{ + free (line_read); + line_read = (char *)NULL; + @} + + /* Get a line from the user. */ + line_read = readline (""); + + /* If the line has any text in it, + save it on the history. */ + if (line_read && *line_read) + add_history (line_read); + + return (line_read); +@} +@end example + +This function gives the user the default behaviour of @key{TAB} +completion: completion on file names. If you do not want Readline to +complete on filenames, you can change the binding of the @key{TAB} key +with @code{rl_bind_key()}. + +@example +@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});} +@end example + +@code{rl_bind_key()} takes two arguments: @var{key} is the character that +you want to bind, and @var{function} is the address of the function to +call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()} +makes @key{TAB} insert itself. +@code{rl_bind_key()} returns non-zero if @var{key} is not a valid +ASCII character code (between 0 and 255). + +Thus, to disable the default @key{TAB} behavior, the following suffices: +@example +@code{rl_bind_key ('\t', rl_insert);} +@end example + +This code should be executed once at the start of your program; you +might write a function called @code{initialize_readline()} which +performs this and other desired initializations, such as installing +custom completers (@pxref{Custom Completers}). + +@node Custom Functions +@section Custom Functions + +Readline provides many functions for manipulating the text of +the line, but it isn't possible to anticipate the needs of all +programs. This section describes the various functions and variables +defined within the Readline library which allow a user program to add +customized functionality to Readline. + +Before declaring any functions that customize Readline's behavior, or +using any functionality Readline provides in other code, an +application writer should include the file @code{<readline/readline.h>} +in any file that uses Readline's features. Since some of the definitions +in @code{readline.h} use the @code{stdio} library, the file +@code{<stdio.h>} should be included before @code{readline.h}. + +@code{readline.h} defines a C preprocessor variable that should +be treated as an integer, @code{RL_READLINE_VERSION}, which may +be used to conditionally compile application code depending on +the installed Readline version. The value is a hexadecimal +encoding of the major and minor version numbers of the library, +of the form 0x@var{MMmm}. @var{MM} is the two-digit major +version number; @var{mm} is the two-digit minor version number. +For Readline 4.2, for example, the value of +@code{RL_READLINE_VERSION} would be @code{0x0402}. + +@menu +* Readline Typedefs:: C declarations to make code readable. +* Function Writing:: Variables and calling conventions. +@end menu + +@node Readline Typedefs +@subsection Readline Typedefs + +For readability, we declare a number of new object types, all pointers +to functions. + +The reason for declaring these new types is to make it easier to write +code describing pointers to C functions with appropriately prototyped +arguments and return values. + +For instance, say we want to declare a variable @var{func} as a pointer +to a function which takes two @code{int} arguments and returns an +@code{int} (this is the type of all of the Readline bindable functions). +Instead of the classic C declaration + +@code{int (*func)();} + +@noindent +or the ANSI-C style declaration + +@code{int (*func)(int, int);} + +@noindent +we may write + +@code{rl_command_func_t *func;} + +The full list of function pointer types available is + +@table @code +@item typedef int rl_command_func_t (int, int); + +@item typedef char *rl_compentry_func_t (const char *, int); + +@item typedef char **rl_completion_func_t (const char *, int, int); + +@item typedef char *rl_quote_func_t (char *, int, char *); + +@item typedef char *rl_dequote_func_t (char *, int); + +@item typedef int rl_compignore_func_t (char **); + +@item typedef void rl_compdisp_func_t (char **, int, int); + +@item typedef int rl_hook_func_t (void); + +@item typedef int rl_getc_func_t (FILE *); + +@item typedef int rl_linebuf_func_t (char *, int); + +@item typedef int rl_intfunc_t (int); +@item #define rl_ivoidfunc_t rl_hook_func_t +@item typedef int rl_icpfunc_t (char *); +@item typedef int rl_icppfunc_t (char **); + +@item typedef void rl_voidfunc_t (void); +@item typedef void rl_vintfunc_t (int); +@item typedef void rl_vcpfunc_t (char *); +@item typedef void rl_vcppfunc_t (char **); + +@end table + +@node Function Writing +@subsection Writing a New Function + +In order to write new functions for Readline, you need to know the +calling conventions for keyboard-invoked functions, and the names of the +variables that describe the current state of the line read so far. + +The calling sequence for a command @code{foo} looks like + +@example +@code{int foo (int count, int key)} +@end example + +@noindent +where @var{count} is the numeric argument (or 1 if defaulted) and +@var{key} is the key that invoked this function. + +It is completely up to the function as to what should be done with the +numeric argument. Some functions use it as a repeat count, some +as a flag, and others to choose alternate behavior (refreshing the current +line as opposed to refreshing the screen, for example). Some choose to +ignore it. In general, if a +function uses the numeric argument as a repeat count, it should be able +to do something useful with both negative and positive arguments. +At the very least, it should be aware that it can be passed a +negative argument. + +A command function should return 0 if its action completes successfully, +and a value greater than zero if some error occurs. +This is the convention obeyed by all of the builtin Readline bindable +command functions. + +@node Readline Variables +@section Readline Variables + +These variables are available to function writers. + +@deftypevar {char *} rl_line_buffer +This is the line gathered so far. You are welcome to modify the +contents of the line, but see @ref{Allowing Undoing}. The +function @code{rl_extend_line_buffer} is available to increase +the memory allocated to @code{rl_line_buffer}. +@end deftypevar + +@deftypevar int rl_point +The offset of the current cursor position in @code{rl_line_buffer} +(the @emph{point}). +@end deftypevar + +@deftypevar int rl_end +The number of characters present in @code{rl_line_buffer}. When +@code{rl_point} is at the end of the line, @code{rl_point} and +@code{rl_end} are equal. +@end deftypevar + +@deftypevar int rl_mark +The @var{mark} (saved position) in the current line. If set, the mark +and point define a @emph{region}. +@end deftypevar + +@deftypevar int rl_done +Setting this to a non-zero value causes Readline to return the current +line immediately. +Readline will set this variable when it has read a key sequence bound +to @code{accept-line} and is about to return the line to the caller. +@end deftypevar + +@deftypevar int rl_eof_found +Readline will set this variable when it has read an EOF character (e.g., the +stty @samp{EOF} character) on an empty line or encountered a read error and +is about to return a NULL line to the caller. +@end deftypevar + +@deftypevar int rl_num_chars_to_read +Setting this to a positive value before calling @code{readline()} causes +Readline to return after accepting that many characters, rather +than reading up to a character bound to @code{accept-line}. +@end deftypevar + +@deftypevar int rl_pending_input +Setting this to a value makes it the next keystroke read. This is a +way to stuff a single character into the input stream. +@end deftypevar + +@deftypevar int rl_dispatching +Set to a non-zero value if a function is being called from a key binding; +zero otherwise. Application functions can test this to discover whether +they were called directly or by Readline's dispatching mechanism. +@end deftypevar + +@deftypevar int rl_erase_empty_line +Setting this to a non-zero value causes Readline to completely erase +the current line, including any prompt, any time a newline is typed as +the only character on an otherwise-empty line. The cursor is moved to +the beginning of the newly-blank line. +@end deftypevar + +@deftypevar {char *} rl_prompt +The prompt Readline uses. This is set from the argument to +@code{readline()}, and should not be assigned to directly. +The @code{rl_set_prompt()} function (@pxref{Redisplay}) may +be used to modify the prompt string after calling @code{readline()}. +@end deftypevar + +@deftypevar {char *} rl_display_prompt +The string displayed as the prompt. This is usually identical to +@var{rl_prompt}, but may be changed temporarily by functions that +use the prompt string as a message area, such as incremental search. +@end deftypevar + +@deftypevar int rl_already_prompted +If an application wishes to display the prompt itself, rather than have +Readline do it the first time @code{readline()} is called, it should set +this variable to a non-zero value after displaying the prompt. +The prompt must also be passed as the argument to @code{readline()} so +the redisplay functions can update the display properly. +The calling application is responsible for managing the value; Readline +never sets it. +@end deftypevar + +@deftypevar {const char *} rl_library_version +The version number of this revision of the library. +@end deftypevar + +@deftypevar int rl_readline_version +An integer encoding the current version of the library. The encoding is +of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version +number, and @var{mm} is the two-digit minor version number. +For example, for Readline-4.2, @code{rl_readline_version} would have the +value 0x0402. +@end deftypevar + +@deftypevar {int} rl_gnu_readline_p +Always set to 1, denoting that this is @sc{gnu} Readline rather than some +emulation. +@end deftypevar + +@deftypevar {const char *} rl_terminal_name +The terminal type, used for initialization. If not set by the application, +Readline sets this to the value of the @env{TERM} environment variable +the first time it is called. +@end deftypevar + +@deftypevar {const char *} rl_readline_name +This variable is set to a unique name by each application using Readline. +The value allows conditional parsing of the inputrc file +(@pxref{Conditional Init Constructs}). +@end deftypevar + +@deftypevar {FILE *} rl_instream +The stdio stream from which Readline reads input. +If @code{NULL}, Readline defaults to @var{stdin}. +@end deftypevar + +@deftypevar {FILE *} rl_outstream +The stdio stream to which Readline performs output. +If @code{NULL}, Readline defaults to @var{stdout}. +@end deftypevar + +@deftypevar int rl_prefer_env_winsize +If non-zero, Readline gives values found in the @env{LINES} and +@env{COLUMNS} environment variables greater precedence than values fetched +from the kernel when computing the screen dimensions. +@end deftypevar + +@deftypevar {rl_command_func_t *} rl_last_func +The address of the last command function Readline executed. May be used to +test whether or not a function is being executed twice in succession, for +example. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_startup_hook +If non-zero, this is the address of a function to call just +before @code{readline} prints the first prompt. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_pre_input_hook +If non-zero, this is the address of a function to call after +the first prompt has been printed and just before @code{readline} +starts reading input characters. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_event_hook +If non-zero, this is the address of a function to call periodically +when Readline is waiting for terminal input. +By default, this will be called at most ten times a second if there +is no keyboard input. +@end deftypevar + +@deftypevar {rl_getc_func_t *} rl_getc_function +If non-zero, Readline will call indirectly through this pointer +to get a character from the input stream. By default, it is set to +@code{rl_getc}, the default Readline character input function +(@pxref{Character Input}). +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_signal_event_hook +If non-zero, this is the address of a function to call if a read system +call is interrupted when Readline is reading terminal input. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_timeout_event_hook +If non-zero, this is the address of a function to call if Readline times +out while reading input. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_input_available_hook +If non-zero, Readline will use this function's return value when it needs +to determine whether or not there is available input on the current input +source. +The default hook checks @code{rl_instream}; if an application is using a +different input source, it should set the hook appropriately. +Readline queries for available input when implementing intra-key-sequence +timeouts during input and incremental searches. +This may use an application-specific timeout before returning a value; +Readline uses the value passed to @code{rl_set_keyboard_input_timeout()} +or the value of the user-settable @var{keyseq-timeout} variable. +This is designed for use by applications using Readline's callback interface +(@pxref{Alternate Interface}), which may not use the traditional +@code{read(2)} and file descriptor interface, or other applications using +a different input mechanism. +If an application uses an input mechanism or hook that can potentially exceed +the value of @var{keyseq-timeout}, it should increase the timeout or set +this hook appropriately even when not using the callback interface. +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. +@end deftypevar + +@deftypevar {rl_voidfunc_t *} rl_redisplay_function +If non-zero, Readline will call indirectly through this pointer +to update the display with the current contents of the editing buffer. +By default, it is set to @code{rl_redisplay}, the default Readline +redisplay function (@pxref{Redisplay}). +@end deftypevar + +@deftypevar {rl_vintfunc_t *} rl_prep_term_function +If non-zero, Readline will call indirectly through this pointer +to initialize the terminal. The function takes a single argument, an +@code{int} flag that says whether or not to use eight-bit characters. +By default, this is set to @code{rl_prep_terminal} +(@pxref{Terminal Management}). +@end deftypevar + +@deftypevar {rl_voidfunc_t *} rl_deprep_term_function +If non-zero, Readline will call indirectly through this pointer +to reset the terminal. This function should undo the effects of +@code{rl_prep_term_function}. +By default, this is set to @code{rl_deprep_terminal} +(@pxref{Terminal Management}). +@end deftypevar + +@deftypevar {Keymap} rl_executing_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +currently executing Readline function was found. +@end deftypevar + +@deftypevar {Keymap} rl_binding_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +last key binding occurred. +@end deftypevar + +@deftypevar {char *} rl_executing_macro +This variable is set to the text of any currently-executing macro. +@end deftypevar + +@deftypevar int rl_executing_key +The key that caused the dispatch to the currently-executing Readline function. +@end deftypevar + +@deftypevar {char *} rl_executing_keyseq +The full key sequence that caused the dispatch to the currently-executing +Readline function. +@end deftypevar + +@deftypevar int rl_key_sequence_length +The number of characters in @var{rl_executing_keyseq}. +@end deftypevar + +@deftypevar {int} rl_readline_state +A variable with bit values that encapsulate the current Readline state. +A bit is set with the @code{RL_SETSTATE} macro, and unset with the +@code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test +whether a particular state bit is set. Current state bits include: + +@table @code +@item RL_STATE_NONE +Readline has not yet been called, nor has it begun to initialize. +@item RL_STATE_INITIALIZING +Readline is initializing its internal data structures. +@item RL_STATE_INITIALIZED +Readline has completed its initialization. +@item RL_STATE_TERMPREPPED +Readline has modified the terminal modes to do its own input and redisplay. +@item RL_STATE_READCMD +Readline is reading a command from the keyboard. +@item RL_STATE_METANEXT +Readline is reading more input after reading the meta-prefix character. +@item RL_STATE_DISPATCHING +Readline is dispatching to a command. +@item RL_STATE_MOREINPUT +Readline is reading more input while executing an editing command. +@item RL_STATE_ISEARCH +Readline is performing an incremental history search. +@item RL_STATE_NSEARCH +Readline is performing a non-incremental history search. +@item RL_STATE_SEARCH +Readline is searching backward or forward through the history for a string. +@item RL_STATE_NUMERICARG +Readline is reading a numeric argument. +@item RL_STATE_MACROINPUT +Readline is currently getting its input from a previously-defined keyboard +macro. +@item RL_STATE_MACRODEF +Readline is currently reading characters defining a keyboard macro. +@item RL_STATE_OVERWRITE +Readline is in overwrite mode. +@item RL_STATE_COMPLETING +Readline is performing word completion. +@item RL_STATE_SIGHANDLER +Readline is currently executing the readline signal handler. +@item RL_STATE_UNDOING +Readline is performing an undo. +@item RL_STATE_INPUTPENDING +Readline has input pending due to a call to @code{rl_execute_next()}. +@item RL_STATE_TTYCSAVED +Readline has saved the values of the terminal's special characters. +@item RL_STATE_CALLBACK +Readline is currently using the alternate (callback) interface +(@pxref{Alternate Interface}). +@item RL_STATE_VIMOTION +Readline is reading the argument to a vi-mode "motion" command. +@item RL_STATE_MULTIKEY +Readline is reading a multiple-keystroke command. +@item RL_STATE_VICMDONCE +Readline has entered vi command (movement) mode at least one time during +the current call to @code{readline()}. +@item RL_STATE_DONE +Readline has read a key sequence bound to @code{accept-line} +and is about to return the line to the caller. +@item RL_STATE_TIMEOUT +Readline has timed out (it did not receive a line or specified number of +characters before the timeout duration specified by @code{rl_set_timeout} +elapsed) and is returning that status to the caller. +@item RL_STATE_EOF +Readline has read an EOF character (e.g., the stty @samp{EOF} character) +or encountered a read error and is about to return a NULL line to the caller. +@end table + +@end deftypevar + +@deftypevar {int} rl_explicit_arg +Set to a non-zero value if an explicit numeric argument was specified by +the user. Only valid in a bindable command function. +@end deftypevar + +@deftypevar {int} rl_numeric_arg +Set to the value of any numeric argument explicitly specified by the user +before executing the current Readline function. Only valid in a bindable +command function. +@end deftypevar + +@deftypevar {int} rl_editing_mode +Set to a value denoting Readline's current editing mode. A value of +@var{1} means Readline is currently in emacs mode; @var{0} +means that vi mode is active. +@end deftypevar + + +@node Readline Convenience Functions +@section Readline Convenience Functions + +@menu +* Function Naming:: How to give a function you write a name. +* Keymaps:: Making keymaps. +* Binding Keys:: Changing Keymaps. +* Associating Function Names and Bindings:: Translate function names to + key sequences. +* Allowing Undoing:: How to make your functions undoable. +* Redisplay:: Functions to control line display. +* Modifying Text:: Functions to modify @code{rl_line_buffer}. +* Character Input:: Functions to read keyboard input. +* Terminal Management:: Functions to manage terminal settings. +* Utility Functions:: Generally useful functions and hooks. +* Miscellaneous Functions:: Functions that don't fall into any category. +* Alternate Interface:: Using Readline in a `callback' fashion. +* A Readline Example:: An example Readline function. +* Alternate Interface Example:: An example program using the alternate interface. +@end menu + +@node Function Naming +@subsection Naming a Function + +The user can dynamically change the bindings of keys while using +Readline. This is done by representing the function with a descriptive +name. The user is able to type the descriptive name when referring to +the function. Thus, in an init file, one might find + +@example +Meta-Rubout: backward-kill-word +@end example + +This binds the keystroke @key{Meta-Rubout} to the function +@emph{descriptively} named @code{backward-kill-word}. You, as the +programmer, should bind the functions you write to descriptive names as +well. Readline provides a function for doing that: + +@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key) +Add @var{name} to the list of named functions. Make @var{function} be +the function that gets called. If @var{key} is not -1, then bind it to +@var{function} using @code{rl_bind_key()}. +@end deftypefun + +Using this function alone is sufficient for most applications. +It is the recommended way to add a few functions to the default +functions that Readline has built in. +If you need to do something other than adding a function to Readline, +you may need to use the underlying functions described below. + +@node Keymaps +@subsection Selecting a Keymap + +Key bindings take place on a @dfn{keymap}. The keymap is the +association between the keys that the user types and the functions that +get run. You can make your own keymaps, copy existing keymaps, and tell +Readline which keymap to use. + +@deftypefun Keymap rl_make_bare_keymap (void) +Returns a new, empty keymap. The space for the keymap is allocated with +@code{malloc()}; the caller should free it by calling +@code{rl_free_keymap()} when done. +@end deftypefun + +@deftypefun Keymap rl_copy_keymap (Keymap map) +Return a new keymap which is a copy of @var{map}. +@end deftypefun + +@deftypefun Keymap rl_make_keymap (void) +Return a new keymap with the printing characters bound to rl_insert, +the lowercase Meta characters bound to run their equivalents, and +the Meta digits bound to produce numeric arguments. +@end deftypefun + +@deftypefun void rl_discard_keymap (Keymap keymap) +Free the storage associated with the data in @var{keymap}. +The caller should free @var{keymap}. +@end deftypefun + +@deftypefun void rl_free_keymap (Keymap keymap) +Free all storage associated with @var{keymap}. This calls +@code{rl_discard_keymap} to free subordindate keymaps and macros. +@end deftypefun + +@deftypefun int rl_empty_keymap (Keymap keymap) +Return non-zero if there are no keys bound to functions in @var{keymap}; +zero if there are any keys bound. +@end deftypefun + +Readline has several internal keymaps. These functions allow you to +change which keymap is active. + +@deftypefun Keymap rl_get_keymap (void) +Returns the currently active keymap. +@end deftypefun + +@deftypefun void rl_set_keymap (Keymap keymap) +Makes @var{keymap} the currently active keymap. +@end deftypefun + +@deftypefun Keymap rl_get_keymap_by_name (const char *name) +Return the keymap matching @var{name}. @var{name} is one which would +be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). +@end deftypefun + +@deftypefun {char *} rl_get_keymap_name (Keymap keymap) +Return the name matching @var{keymap}. @var{name} is one which would +be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). +@end deftypefun + +@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap) +Set the name of @var{keymap}. This name will then be "registered" and +available for use in a @code{set keymap} inputrc directive +@pxref{Readline Init File}). +The @var{name} may not be one of Readline's builtin keymap names; +you may not add a different name for one of Readline's builtin keymaps. +You may replace the name associated with a given keymap by calling this +function more than once with the same @var{keymap} argument. +You may associate a registered @var{name} with a new keymap by calling this +function more than once with the same @var{name} argument. +There is no way to remove a named keymap once the name has been +registered. +Readline will make a copy of @var{name}. +The return value is greater than zero unless @var{name} is one of +Readline's builtin keymap names or @var{keymap} is one of Readline's +builtin keymaps. +@end deftypefun + +@node Binding Keys +@subsection Binding Keys + +Key sequences are associate with functions through the keymap. +Readline has several internal keymaps: @code{emacs_standard_keymap}, +@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap}, +@code{vi_movement_keymap}, and @code{vi_insertion_keymap}. +@code{emacs_standard_keymap} is the default, and the examples in +this manual assume that. + +Since @code{readline()} installs a set of default key bindings the first +time it is called, there is always the danger that a custom binding +installed before the first call to @code{readline()} will be overridden. +An alternate mechanism is to install custom key bindings in an +initialization function assigned to the @code{rl_startup_hook} variable +(@pxref{Readline Variables}). + +These functions manage key bindings. + +@deftypefun int rl_bind_key (int key, rl_command_func_t *function) +Binds @var{key} to @var{function} in the currently active keymap. +Returns non-zero in the case of an invalid @var{key}. +@end deftypefun + +@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map) +Bind @var{key} to @var{function} in @var{map}. +Returns non-zero in the case of an invalid @var{key}. +@end deftypefun + +@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function) +Binds @var{key} to @var{function} if it is not already bound in the +currently active keymap. +Returns non-zero in the case of an invalid @var{key} or if @var{key} is +already bound. +@end deftypefun + +@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map) +Binds @var{key} to @var{function} if it is not already bound in @var{map}. +Returns non-zero in the case of an invalid @var{key} or if @var{key} is +already bound. +@end deftypefun + +@deftypefun int rl_unbind_key (int key) +Bind @var{key} to the null function in the currently active keymap. +Returns non-zero in case of error. +@end deftypefun + +@deftypefun int rl_unbind_key_in_map (int key, Keymap map) +Bind @var{key} to the null function in @var{map}. +Returns non-zero in case of error. +@end deftypefun + +@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map) +Unbind all keys that execute @var{function} in @var{map}. +@end deftypefun + +@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map) +Unbind all keys that are bound to @var{command} in @var{map}. +@end deftypefun + +@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function) +Bind the key sequence represented by the string @var{keyseq} to the function +@var{function}, beginning in the current keymap. +This makes new keymaps as necessary. +The return value is non-zero if @var{keyseq} is invalid. +@end deftypefun + +@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) +Bind the key sequence represented by the string @var{keyseq} to the function +@var{function}. This makes new keymaps as necessary. +Initial bindings are performed in @var{map}. +The return value is non-zero if @var{keyseq} is invalid. +@end deftypefun + +@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map) +Equivalent to @code{rl_bind_keyseq_in_map}. +@end deftypefun + +@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function) +Binds @var{keyseq} to @var{function} if it is not already bound in the +currently active keymap. +Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is +already bound. +@end deftypefun + +@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) +Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}. +Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is +already bound. +@end deftypefun + +@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map) +Bind the key sequence represented by the string @var{keyseq} to the arbitrary +pointer @var{data}. @var{type} says what kind of data is pointed to by +@var{data}; this can be a function (@code{ISFUNC}), a macro +(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as +necessary. The initial keymap in which to do bindings is @var{map}. +@end deftypefun + +@deftypefun int rl_parse_and_bind (char *line) +Parse @var{line} as if it had been read from the @code{inputrc} file and +perform any key bindings and variable assignments found +(@pxref{Readline Init File}). +@end deftypefun + +@deftypefun int rl_read_init_file (const char *filename) +Read keybindings and variable assignments from @var{filename} +(@pxref{Readline Init File}). +@end deftypefun + +@node Associating Function Names and Bindings +@subsection Associating Function Names and Bindings + +These functions allow you to find out what keys invoke named functions +and the functions invoked by a particular key sequence. You may also +associate a new function name with an arbitrary function. + +@deftypefun {rl_command_func_t *} rl_named_function (const char *name) +Return the function with name @var{name}. +@end deftypefun + +@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type) +Return the function invoked by @var{keyseq} in keymap @var{map}. +If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is +not @code{NULL}, the type of the object is returned in the @code{int} variable +it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}). +It takes a "translated" key sequence and should not be used if the key sequence +can include NUL. +@end deftypefun + +@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type) +Return the function invoked by @var{keyseq} of length @var{len} +in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the +addition of the @var{len} parameter. +It takes a "translated" key sequence and should be used if the key sequence +can include NUL. +@end deftypefun + +@deftypefun {int} rl_trim_arg_from_keyseq (const char *keyseq, size_t len, Keymap map) +If there is a numeric argument at the beginning of @var{keyseq}, possibly +including digits, return the index of the first character in @var{keyseq} +following the numeric argument. +This can be used to skip over the numeric argument (which is available as +@code{rl_numeric_arg} while traversing the key sequence that invoked the +current command. +@end deftypefun + +@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function) +Return an array of strings representing the key sequences used to +invoke @var{function} in the current keymap. +@end deftypefun + +@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map) +Return an array of strings representing the key sequences used to +invoke @var{function} in the keymap @var{map}. +@end deftypefun + +@deftypefun void rl_function_dumper (int readable) +Print the Readline function names and the key sequences currently +bound to them to @code{rl_outstream}. If @var{readable} is non-zero, +the list is formatted in such a way that it can be made part of an +@code{inputrc} file and re-read. +@end deftypefun + +@deftypefun void rl_list_funmap_names (void) +Print the names of all bindable Readline functions to @code{rl_outstream}. +@end deftypefun + +@deftypefun {const char **} rl_funmap_names (void) +Return a NULL terminated array of known function names. The array is +sorted. The array itself is allocated, but not the strings inside. You +should free the array, but not the pointers, using @code{free} or +@code{rl_free} when you are done. +@end deftypefun + +@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function) +Add @var{name} to the list of bindable Readline command names, and make +@var{function} the function to be called when @var{name} is invoked. +@end deftypefun + +@node Allowing Undoing +@subsection Allowing Undoing + +Supporting the undo command is a painless thing, and makes your +functions much more useful. It is certainly easy to try +something if you know you can undo it. + +If your function simply inserts text once, or deletes text once, and +uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then +undoing is already done for you automatically. + +If you do multiple insertions or multiple deletions, or any combination +of these operations, you should group them together into one operation. +This is done with @code{rl_begin_undo_group()} and +@code{rl_end_undo_group()}. + +The types of events that can be undone are: + +@smallexample +enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; +@end smallexample + +Notice that @code{UNDO_DELETE} means to insert some text, and +@code{UNDO_INSERT} means to delete some text. That is, the undo code +tells what to undo, not how to undo it. @code{UNDO_BEGIN} and +@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and +@code{rl_end_undo_group()}. + +@deftypefun int rl_begin_undo_group (void) +Begins saving undo information in a group construct. The undo +information usually comes from calls to @code{rl_insert_text()} and +@code{rl_delete_text()}, but could be the result of calls to +@code{rl_add_undo()}. +@end deftypefun + +@deftypefun int rl_end_undo_group (void) +Closes the current undo group started with @code{rl_begin_undo_group +()}. There should be one call to @code{rl_end_undo_group()} +for each call to @code{rl_begin_undo_group()}. +@end deftypefun + +@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text) +Remember how to undo an event (according to @var{what}). The affected +text runs from @var{start} to @var{end}, and encompasses @var{text}. +@end deftypefun + +@deftypefun void rl_free_undo_list (void) +Free the existing undo list. +@end deftypefun + +@deftypefun int rl_do_undo (void) +Undo the first thing on the undo list. Returns @code{0} if there was +nothing to undo, non-zero if something was undone. +@end deftypefun + +Finally, if you neither insert nor delete text, but directly modify the +existing text (e.g., change its case), call @code{rl_modifying()} +once, just before you modify the text. You must supply the indices of +the text range that you are going to modify. + +@deftypefun int rl_modifying (int start, int end) +Tell Readline to save the text between @var{start} and @var{end} as a +single undo unit. It is assumed that you will subsequently modify +that text. +@end deftypefun + +@node Redisplay +@subsection Redisplay + +@deftypefun void rl_redisplay (void) +Change what's displayed on the screen to reflect the current contents +of @code{rl_line_buffer}. +@end deftypefun + +@deftypefun int rl_forced_update_display (void) +Force the line to be updated and redisplayed, whether or not +Readline thinks the screen display is correct. +@end deftypefun + +@deftypefun int rl_on_new_line (void) +Tell the update functions that we have moved onto a new (empty) line, +usually after outputting a newline. +@end deftypefun + +@deftypefun int rl_on_new_line_with_prompt (void) +Tell the update functions that we have moved onto a new line, with +@var{rl_prompt} already displayed. +This could be used by applications that want to output the prompt string +themselves, but still need Readline to know the prompt string length for +redisplay. +It should be used after setting @var{rl_already_prompted}. +@end deftypefun + +@deftypefun int rl_clear_visible_line (void) +Clear the screen lines corresponding to the current line's contents. +@end deftypefun + +@deftypefun int rl_reset_line_state (void) +Reset the display state to a clean state and redisplay the current line +starting on a new line. +@end deftypefun + +@deftypefun int rl_crlf (void) +Move the cursor to the start of the next screen line. +@end deftypefun + +@deftypefun int rl_show_char (int c) +Display character @var{c} on @code{rl_outstream}. +If Readline has not been set to display meta characters directly, this +will convert meta characters to a meta-prefixed key sequence. +This is intended for use by applications which wish to do their own +redisplay. +@end deftypefun + +@deftypefun int rl_message (const char *, @dots{}) +The arguments are a format string as would be supplied to @code{printf}, +possibly containing conversion specifications such as @samp{%d}, and +any additional arguments necessary to satisfy the conversion specifications. +The resulting string is displayed in the @dfn{echo area}. The echo area +is also used to display numeric arguments and search strings. +You should call @code{rl_save_prompt} to save the prompt information +before calling this function. +@end deftypefun + +@deftypefun int rl_clear_message (void) +Clear the message in the echo area. If the prompt was saved with a call to +@code{rl_save_prompt} before the last call to @code{rl_message}, +call @code{rl_restore_prompt} before calling this function. +@end deftypefun + +@deftypefun void rl_save_prompt (void) +Save the local Readline prompt display state in preparation for +displaying a new message in the message area with @code{rl_message()}. +@end deftypefun + +@deftypefun void rl_restore_prompt (void) +Restore the local Readline prompt display state saved by the most +recent call to @code{rl_save_prompt}. +if @code{rl_save_prompt} was called to save the prompt before a call +to @code{rl_message}, this function should be called before the +corresponding call to @code{rl_clear_message}. +@end deftypefun + +@deftypefun int rl_expand_prompt (char *prompt) +Expand any special character sequences in @var{prompt} and set up the +local Readline prompt redisplay variables. +This function is called by @code{readline()}. It may also be called to +expand the primary prompt if the @code{rl_on_new_line_with_prompt()} +function or @code{rl_already_prompted} variable is used. +It returns the number of visible characters on the last line of the +(possibly multi-line) prompt. +Applications may indicate that the prompt contains characters that take +up no physical screen space when displayed by bracketing a sequence of +such characters with the special markers @code{RL_PROMPT_START_IGNORE} +and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h} as +@samp{\001} and @samp{\002}, respectively). +This may be used to embed terminal-specific escape sequences in prompts. +@end deftypefun + +@deftypefun int rl_set_prompt (const char *prompt) +Make Readline use @var{prompt} for subsequent redisplay. This calls +@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt} +to the result. +@end deftypefun + +@node Modifying Text +@subsection Modifying Text + +@deftypefun int rl_insert_text (const char *text) +Insert @var{text} into the line at the current cursor position. +Returns the number of characters inserted. +@end deftypefun + +@deftypefun int rl_delete_text (int start, int end) +Delete the text between @var{start} and @var{end} in the current line. +Returns the number of characters deleted. +@end deftypefun + +@deftypefun {char *} rl_copy_text (int start, int end) +Return a copy of the text between @var{start} and @var{end} in +the current line. +@end deftypefun + +@deftypefun int rl_kill_text (int start, int end) +Copy the text between @var{start} and @var{end} in the current line +to the kill ring, appending or prepending to the last kill if the +last command was a kill command. The text is deleted. +If @var{start} is less than @var{end}, +the text is appended, otherwise prepended. If the last command was +not a kill, a new kill ring slot is used. +@end deftypefun + +@deftypefun int rl_push_macro_input (char *macro) +Cause @var{macro} to be inserted into the line, as if it had been invoked +by a key bound to a macro. Not especially useful; use +@code{rl_insert_text()} instead. +@end deftypefun + +@node Character Input +@subsection Character Input + +@deftypefun int rl_read_key (void) +Return the next character available from Readline's current input stream. +This handles input inserted into +the input stream via @var{rl_pending_input} (@pxref{Readline Variables}) +and @code{rl_stuff_char()}, macros, and characters read from the keyboard. +While waiting for input, this function will call any function assigned to +the @code{rl_event_hook} variable. +@end deftypefun + +@deftypefun int rl_getc (FILE *stream) +Return the next character available from @var{stream}, which is assumed to +be the keyboard. +@end deftypefun + +@deftypefun int rl_stuff_char (int c) +Insert @var{c} into the Readline input stream. It will be "read" +before Readline attempts to read characters from the terminal with +@code{rl_read_key()}. Up to 512 characters may be pushed back. +@code{rl_stuff_char} returns 1 if the character was successfully inserted; +0 otherwise. +@end deftypefun + +@deftypefun int rl_execute_next (int c) +Make @var{c} be the next command to be executed when @code{rl_read_key()} +is called. This sets @var{rl_pending_input}. +@end deftypefun + +@deftypefun int rl_clear_pending_input (void) +Unset @var{rl_pending_input}, effectively negating the effect of any +previous call to @code{rl_execute_next()}. This works only if the +pending input has not already been read with @code{rl_read_key()}. +@end deftypefun + +@deftypefun int rl_set_keyboard_input_timeout (int u) +While waiting for keyboard input in @code{rl_read_key()}, Readline will +wait for @var{u} microseconds for input before calling any function +assigned to @code{rl_event_hook}. @var{u} must be greater than or equal +to zero (a zero-length timeout is equivalent to a poll). +The default waiting period is one-tenth of a second. +Returns the old timeout value. +@end deftypefun + +@deftypefun int rl_set_timeout (unsigned int secs, unsigned int usecs) +Set a timeout for subsequent calls to @code{readline()}. If Readline does +not read a complete line, or the number of characters specified by +@code{rl_num_chars_to_read}, before the duration specified by @var{secs} +(in seconds) and @var{usecs} (microseconds), it returns and sets +@code{RL_STATE_TIMEOUT} in @code{rl_readline_state}. +Passing 0 for @code{secs} and @code{usecs} cancels any previously set +timeout; the convenience macro @code{rl_clear_timeout()} is shorthand +for this. +Returns 0 if the timeout is set successfully. +@end deftypefun + +@deftypefun int rl_timeout_remaining (unsigned int *secs, unsigned int *usecs) +Return the number of seconds and microseconds remaining in the current +timeout duration in @var{*secs} and @var{*usecs}, respectively. +Both @var{*secs} and @var{*usecs} must be non-NULL to return any values. +The return value is -1 on error or when there is no timeout set, +0 when the timeout has expired (leaving @var{*secs} and @var{*usecs} +unchanged), +and 1 if the timeout has not expired. +If either of @var{secs} and @var{usecs} is @code{NULL}, +the return value indicates whether the timeout has expired. +@end deftypefun + +@node Terminal Management +@subsection Terminal Management + +@deftypefun void rl_prep_terminal (int meta_flag) +Modify the terminal settings for Readline's use, so @code{readline()} +can read a single character at a time from the keyboard. +The @var{meta_flag} argument should be non-zero if Readline should +read eight-bit input. +@end deftypefun + +@deftypefun void rl_deprep_terminal (void) +Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in +the state in which it was before the most recent call to +@code{rl_prep_terminal()}. +@end deftypefun + +@deftypefun void rl_tty_set_default_bindings (Keymap kmap) +Read the operating system's terminal editing characters (as would be +displayed by @code{stty}) to their Readline equivalents. +The bindings are performed in @var{kmap}. +@end deftypefun + +@deftypefun void rl_tty_unset_default_bindings (Keymap kmap) +Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so +that the terminal editing characters are bound to @code{rl_insert}. +The bindings are performed in @var{kmap}. +@end deftypefun + +@deftypefun int rl_tty_set_echoing (int value) +Set Readline's idea of whether or not it is echoing output to its output +stream (@var{rl_outstream}). If @var{value} is 0, Readline does not display +output to @var{rl_outstream}; any other value enables output. The initial +value is set when Readline initializes the terminal settings. +This function returns the previous value. +@end deftypefun + +@deftypefun int rl_reset_terminal (const char *terminal_name) +Reinitialize Readline's idea of the terminal settings using +@var{terminal_name} as the terminal type (e.g., @code{vt100}). +If @var{terminal_name} is @code{NULL}, the value of the @code{TERM} +environment variable is used. +@end deftypefun + +@node Utility Functions +@subsection Utility Functions + +@deftypefun int rl_save_state (struct readline_state *sp) +Save a snapshot of Readline's internal state to @var{sp}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for allocating the structure. +@end deftypefun + +@deftypefun int rl_restore_state (struct readline_state *sp) +Restore Readline's internal state to that stored in @var{sp}, which must +have been saved by a call to @code{rl_save_state}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for freeing the structure. +@end deftypefun + +@deftypefun void rl_free (void *mem) +Deallocate the memory pointed to by @var{mem}. @var{mem} must have been +allocated by @code{malloc}. +@end deftypefun + +@deftypefun void rl_replace_line (const char *text, int clear_undo) +Replace the contents of @code{rl_line_buffer} with @var{text}. +The point and mark are preserved, if possible. +If @var{clear_undo} is non-zero, the undo list associated with the +current line is cleared. +@end deftypefun + +@deftypefun void rl_extend_line_buffer (int len) +Ensure that @code{rl_line_buffer} has enough space to hold @var{len} +characters, possibly reallocating it if necessary. +@end deftypefun + +@deftypefun int rl_initialize (void) +Initialize or re-initialize Readline's internal state. +It's not strictly necessary to call this; @code{readline()} calls it before +reading any input. +@end deftypefun + +@deftypefun int rl_ding (void) +Ring the terminal bell, obeying the setting of @code{bell-style}. +@end deftypefun + +@deftypefun int rl_alphabetic (int c) +Return 1 if @var{c} is an alphabetic character. +@end deftypefun + +@deftypefun void rl_display_match_list (char **matches, int len, int max) +A convenience function for displaying a list of strings in +columnar format on Readline's output stream. @code{matches} is the list +of strings, in argv format, such as a list of completion matches. +@code{len} is the number of strings in @code{matches}, and @code{max} +is the length of the longest string in @code{matches}. This function uses +the setting of @code{print-completions-horizontally} to select how the +matches are displayed (@pxref{Readline Init File Syntax}). +When displaying completions, this function sets the number of columns used +for display to the value of @code{completion-display-width}, the value of +the environment variable @env{COLUMNS}, or the screen width, in that order. +@end deftypefun + +The following are implemented as macros, defined in @code{chardefs.h}. +Applications should refrain from using them. + +@deftypefun int _rl_uppercase_p (int c) +Return 1 if @var{c} is an uppercase alphabetic character. +@end deftypefun + +@deftypefun int _rl_lowercase_p (int c) +Return 1 if @var{c} is a lowercase alphabetic character. +@end deftypefun + +@deftypefun int _rl_digit_p (int c) +Return 1 if @var{c} is a numeric character. +@end deftypefun + +@deftypefun int _rl_to_upper (int c) +If @var{c} is a lowercase alphabetic character, return the corresponding +uppercase character. +@end deftypefun + +@deftypefun int _rl_to_lower (int c) +If @var{c} is an uppercase alphabetic character, return the corresponding +lowercase character. +@end deftypefun + +@deftypefun int _rl_digit_value (int c) +If @var{c} is a number, return the value it represents. +@end deftypefun + +@node Miscellaneous Functions +@subsection Miscellaneous Functions + +@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map) +Bind the key sequence @var{keyseq} to invoke the macro @var{macro}. +The binding is performed in @var{map}. When @var{keyseq} is invoked, the +@var{macro} will be inserted into the line. This function is deprecated; +use @code{rl_generic_bind()} instead. +@end deftypefun + +@deftypefun void rl_macro_dumper (int readable) +Print the key sequences bound to macros and their values, using +the current keymap, to @code{rl_outstream}. +If @var{readable} is non-zero, the list is formatted in such a way +that it can be made part of an @code{inputrc} file and re-read. +@end deftypefun + +@deftypefun int rl_variable_bind (const char *variable, const char *value) +Make the Readline variable @var{variable} have @var{value}. +This behaves as if the Readline command +@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} +file (@pxref{Readline Init File Syntax}). +@end deftypefun + +@deftypefun {char *} rl_variable_value (const char *variable) +Return a string representing the value of the Readline variable @var{variable}. +For boolean variables, this string is either @samp{on} or @samp{off}. +@end deftypefun + +@deftypefun void rl_variable_dumper (int readable) +Print the Readline variable names and their current values +to @code{rl_outstream}. +If @var{readable} is non-zero, the list is formatted in such a way +that it can be made part of an @code{inputrc} file and re-read. +@end deftypefun + +@deftypefun int rl_set_paren_blink_timeout (int u) +Set the time interval (in microseconds) that Readline waits when showing +a balancing character when @code{blink-matching-paren} has been enabled. +@end deftypefun + +@deftypefun {char *} rl_get_termcap (const char *cap) +Retrieve the string value of the termcap capability @var{cap}. +Readline fetches the termcap entry for the current terminal name and +uses those capabilities to move around the screen line and perform other +terminal-specific operations, like erasing a line. Readline does not +use all of a terminal's capabilities, and this function will return +values for only those capabilities Readline uses. +@end deftypefun + +@deftypefun {void} rl_clear_history (void) +Clear the history list by deleting all of the entries, in the same manner +as the History library's @code{clear_history()} function. +This differs from @code{clear_history} because it frees private data +Readline saves in the history list. +@end deftypefun + +@deftypefun {void} rl_activate_mark (void) +Enable an @emph{active} mark. +When this is enabled, the text between point and mark (the @var{region}) is +displayed in the terminal's standout mode (a @var{face}). +This is called by various Readline functions that set the mark and insert +text, and is available for applications to call. +@end deftypefun + +@deftypefun {void} rl_deactivate_mark (void) +Turn off the active mark. +@end deftypefun + +@deftypefun {void} rl_keep_mark_active (void) +Indicate that the mark should remain active when the current Readline +function completes and after redisplay occurs. +In most cases, the mark remains active for only the duration of a single +bindable Readline function. +@end deftypefun + +@deftypefun {int} rl_mark_active_p (void) +Return a non-zero value if the mark is currently active; zero otherwise. +@end deftypefun + +@node Alternate Interface +@subsection Alternate Interface + +An alternate interface is available to plain @code{readline()}. Some +applications need to interleave keyboard I/O with file, device, or +window system I/O, typically by using a main loop to @code{select()} +on various file descriptors. To accommodate this need, Readline can +also be invoked as a `callback' function from an event loop. There +are functions available to make this easy. + +@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler) +Set up the terminal for Readline I/O and display the initial +expanded value of @var{prompt}. Save the value of @var{lhandler} to +use as a handler function to call when a complete line of input has been +entered. +The handler function receives the text of the line as an argument. +As with @code{readline()}, the handler function should @code{free} the +line when it it finished with it. +@end deftypefun + +@deftypefun void rl_callback_read_char (void) +Whenever an application determines that keyboard input is available, it +should call @code{rl_callback_read_char()}, which will read the next +character from the current input source. +If that character completes the line, @code{rl_callback_read_char} will +invoke the @var{lhandler} function installed by +@code{rl_callback_handler_install} to process the line. +Before calling the @var{lhandler} function, the terminal settings are +reset to the values they had before calling +@code{rl_callback_handler_install}. +If the @var{lhandler} function returns, +and the line handler remains installed, +the terminal settings are modified for Readline's use again. +@code{EOF} is indicated by calling @var{lhandler} with a +@code{NULL} line. +@end deftypefun + +@deftypefun void rl_callback_sigcleanup (void) +Clean up any internal state the callback interface uses to maintain state +between calls to rl_callback_read_char (e.g., the state of any active +incremental searches). This is intended to be used by applications that +wish to perform their own signal handling; Readline's internal signal handler +calls this when appropriate. +@end deftypefun + +@deftypefun void rl_callback_handler_remove (void) +Restore the terminal to its initial state and remove the line handler. +You may call this function from within a callback as well as independently. +If the @var{lhandler} installed by @code{rl_callback_handler_install} +does not exit the program, either this function or the function referred +to by the value of @code{rl_deprep_term_function} should be called before +the program exits to reset the terminal settings. +@end deftypefun + +@node A Readline Example +@subsection A Readline Example + +Here is a function which changes lowercase characters to their uppercase +equivalents, and uppercase characters to lowercase. If +this function was bound to @samp{M-c}, then typing @samp{M-c} would +change the case of the character under point. Typing @samp{M-1 0 M-c} +would change the case of the following 10 characters, leaving the cursor on +the last character changed. + +@example +/* Invert the case of the COUNT following characters. */ +int +invert_case_line (count, key) + int count, key; +@{ + register int start, end, i; + + start = rl_point; + + if (rl_point >= rl_end) + return (0); + + if (count < 0) + @{ + direction = -1; + count = -count; + @} + else + direction = 1; + + /* Find the end of the range to modify. */ + end = start + (count * direction); + + /* Force it to be within range. */ + if (end > rl_end) + end = rl_end; + else if (end < 0) + end = 0; + + if (start == end) + return (0); + + if (start > end) + @{ + int temp = start; + start = end; + end = temp; + @} + + /* Tell readline that we are modifying the line, + so it will save the undo information. */ + rl_modifying (start, end); + + for (i = start; i != end; i++) + @{ + if (_rl_uppercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); + else if (_rl_lowercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); + @} + /* Move point to on top of the last character changed. */ + rl_point = (direction == 1) ? end - 1 : start; + return (0); +@} +@end example + +@node Alternate Interface Example +@subsection Alternate Interface Example + +Here is a complete program that illustrates Readline's alternate interface. +It reads lines from the terminal and displays them, providing the +standard history and TAB completion functions. +It understands the EOF character or "exit" to exit the program. + +@example +/* Standard include files. stdio.h is required. */ +#include <stdlib.h> +#include <string.h> +#include <unistd.h> +#include <locale.h> + +/* Used for select(2) */ +#include <sys/types.h> +#include <sys/select.h> + +#include <signal.h> + +#include <stdio.h> + +/* Standard readline include files. */ +#include <readline/readline.h> +#include <readline/history.h> + +static void cb_linehandler (char *); +static void sighandler (int); + +int running; +int sigwinch_received; +const char *prompt = "rltest$ "; + +/* Handle SIGWINCH and window size changes when readline is not active and + reading a character. */ +static void +sighandler (int sig) +@{ + sigwinch_received = 1; +@} + +/* Callback function called for each line when accept-line executed, EOF + seen, or EOF character read. This sets a flag and returns; it could + also call exit(3). */ +static void +cb_linehandler (char *line) +@{ + /* Can use ^D (stty eof) or `exit' to exit. */ + if (line == NULL || strcmp (line, "exit") == 0) + @{ + if (line == 0) + printf ("\n"); + printf ("exit\n"); + /* This function needs to be called to reset the terminal settings, + and calling it from the line handler keeps one extra prompt from + being displayed. */ + rl_callback_handler_remove (); + + running = 0; + @} + else + @{ + if (*line) + add_history (line); + printf ("input line: %s\n", line); + free (line); + @} +@} + +int +main (int c, char **v) +@{ + fd_set fds; + int r; + + /* Set the default locale values according to environment variables. */ + setlocale (LC_ALL, ""); + + /* Handle window size changes when readline is not active and reading + characters. */ + signal (SIGWINCH, sighandler); + + /* Install the line handler. */ + rl_callback_handler_install (prompt, cb_linehandler); + + /* Enter a simple event loop. This waits until something is available + to read on readline's input stream (defaults to standard input) and + calls the builtin character read callback to read it. It does not + have to modify the user's terminal settings. */ + running = 1; + while (running) + @{ + FD_ZERO (&fds); + FD_SET (fileno (rl_instream), &fds); + + r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); + if (r < 0 && errno != EINTR) + @{ + perror ("rltest: select"); + rl_callback_handler_remove (); + break; + @} + if (sigwinch_received) + @{ + rl_resize_terminal (); + sigwinch_received = 0; + @} + if (r < 0) + continue; + + if (FD_ISSET (fileno (rl_instream), &fds)) + rl_callback_read_char (); + @} + + printf ("rltest: Event loop has exited\n"); + return 0; +@} +@end example + +@node Readline Signal Handling +@section Readline Signal Handling + +Signals are asynchronous events sent to a process by the Unix kernel, +sometimes on behalf of another process. They are intended to indicate +exceptional events, like a user pressing the terminal's interrupt key, +or a network connection being broken. There is a class of signals that can +be sent to the process currently reading input from the keyboard. Since +Readline changes the terminal attributes when it is called, it needs to +perform special processing when such a signal is received in order to +restore the terminal to a sane state, or provide application writers with +functions to do so manually. + +Readline contains an internal signal handler that is installed for a +number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, +@code{SIGHUP}, +@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}). +When one of these signals is received, the signal handler +will reset the terminal attributes to those that were in effect before +@code{readline()} was called, reset the signal handling to what it was +before @code{readline()} was called, and resend the signal to the calling +application. +If and when the calling application's signal handler returns, Readline +will reinitialize the terminal and continue to accept input. +When a @code{SIGINT} is received, the Readline signal handler performs +some additional work, which will cause any partially-entered line to be +aborted (see the description of @code{rl_free_line_state()} below). + +There is an additional Readline signal handler, for @code{SIGWINCH}, which +the kernel sends to a process whenever the terminal's size changes (for +example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH} +handler updates Readline's internal screen size information, and then calls +any @code{SIGWINCH} signal handler the calling application has installed. +Readline calls the application's @code{SIGWINCH} signal handler without +resetting the terminal to its original state. If the application's signal +handler does more than update its idea of the terminal size and return (for +example, a @code{longjmp} back to a main processing loop), it @emph{must} +call @code{rl_cleanup_after_signal()} (described below), to restore the +terminal state. + +When an application is using the callback interface +(@pxref{Alternate Interface}), Readline installs signal handlers only for +the duration of the call to @code{rl_callback_read_char}. Applications +using the callback interface should be prepared to clean up Readline's +state if they wish to handle the signal before the line handler completes +and restores the terminal state. + +If an application using the callback interface wishes to have Readline +install its signal handlers at the time the application calls +@code{rl_callback_handler_install} and remove them only when a complete +line of input has been read, it should set the +@code{rl_persistent_signal_handlers} variable to a non-zero value. +This allows an application to defer all of the handling of the signals +Readline catches to Readline. +Applications should use this variable with care; it can result in Readline +catching signals and not acting on them (or allowing the application to react +to them) until the application calls @code{rl_callback_read_char}. This +can result in an application becoming less responsive to keyboard signals +like SIGINT. +If an application does not want or need to perform any signal handling, or +does not need to do any processing between calls to @code{rl_callback_read_char}, +setting this variable may be desirable. + +Readline provides two variables that allow application writers to +control whether or not it will catch certain signals and act on them +when they are received. It is important that applications change the +values of these variables only when calling @code{readline()}, not in +a signal handler, so Readline's internal signal state is not corrupted. + +@deftypevar int rl_catch_signals +If this variable is non-zero, Readline will install signal handlers for +@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, +@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. + +The default value of @code{rl_catch_signals} is 1. +@end deftypevar + +@deftypevar int rl_catch_sigwinch +If this variable is set to a non-zero value, +Readline will install a signal handler for @code{SIGWINCH}. + +The default value of @code{rl_catch_sigwinch} is 1. +@end deftypevar + +@deftypevar int rl_persistent_signal_handlers +If an application using the callback interface wishes Readline's signal +handlers to be installed and active during the set of calls to +@code{rl_callback_read_char} that constitutes an entire single line, +it should set this variable to a non-zero value. + +The default value of @code{rl_persistent_signal_handlers} is 0. +@end deftypevar + +@deftypevar int rl_change_environment +If this variable is set to a non-zero value, +and Readline is handling @code{SIGWINCH}, Readline will modify the +@var{LINES} and @var{COLUMNS} environment variables upon receipt of a +@code{SIGWINCH} + +The default value of @code{rl_change_environment} is 1. +@end deftypevar + +If an application does not wish to have Readline catch any signals, or +to handle signals other than those Readline catches (@code{SIGHUP}, +for example), +Readline provides convenience functions to do the necessary terminal +and internal state cleanup upon receipt of a signal. + +@deftypefun int rl_pending_signal (void) +Return the signal number of the most recent signal Readline received but +has not yet handled, or 0 if there is no pending signal. +@end deftypefun + +@deftypefun void rl_cleanup_after_signal (void) +This function will reset the state of the terminal to what it was before +@code{readline()} was called, and remove the Readline signal handlers for +all signals, depending on the values of @code{rl_catch_signals} and +@code{rl_catch_sigwinch}. +@end deftypefun + +@deftypefun void rl_free_line_state (void) +This will free any partial state associated with the current input line +(undo information, any partial history entry, any partially-entered +keyboard macro, and any partially-entered numeric argument). This +should be called before @code{rl_cleanup_after_signal()}. The +Readline signal handler for @code{SIGINT} calls this to abort the +current input line. +@end deftypefun + +@deftypefun void rl_reset_after_signal (void) +This will reinitialize the terminal and reinstall any Readline signal +handlers, depending on the values of @code{rl_catch_signals} and +@code{rl_catch_sigwinch}. +@end deftypefun + +If an application wants to force Readline to handle any signals that +have arrived while it has been executing, @code{rl_check_signals()} +will call Readline's internal signal handler if there are any pending +signals. This is primarily intended for those applications that use +a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish +to handle signals received while waiting for input. + +@deftypefun void rl_check_signals (void) +If there are any pending signals, call Readline's internal signal handling +functions to process them. @code{rl_pending_signal()} can be used independently +to determine whether or not there are any pending signals. +@end deftypefun + +If an application does not wish Readline to catch @code{SIGWINCH}, it may +call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force +Readline to update its idea of the terminal size when it receives +a @code{SIGWINCH}. + +@deftypefun void rl_echo_signal_char (int sig) +If an application wishes to install its own signal handlers, but still +have Readline display characters that generate signals, calling this +function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or +@code{SIGTSTP} will display the character generating that signal. +@end deftypefun + +@deftypefun void rl_resize_terminal (void) +Update Readline's internal screen size by reading values from the kernel. +@end deftypefun + +@deftypefun void rl_set_screen_size (int rows, int cols) +Set Readline's idea of the terminal size to @var{rows} rows and +@var{cols} columns. If either @var{rows} or @var{columns} is less than +or equal to 0, Readline's idea of that terminal dimension is unchanged. +This is intended to tell Readline the physical dimensions of the terminal, +and is used internally to calculate the maximum number of characters that +may appear on a single line and on the screen. +@end deftypefun + +If an application does not want to install a @code{SIGWINCH} handler, but +is still interested in the screen dimensions, it may query Readline's idea +of the screen size. + +@deftypefun void rl_get_screen_size (int *rows, int *cols) +Return Readline's idea of the terminal's size in the +variables pointed to by the arguments. +@end deftypefun + +@deftypefun void rl_reset_screen_size (void) +Cause Readline to reobtain the screen size and recalculate its dimensions. +@end deftypefun + +The following functions install and remove Readline's signal handlers. + +@deftypefun int rl_set_signals (void) +Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, +@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, +@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of +@code{rl_catch_signals} and @code{rl_catch_sigwinch}. +@end deftypefun + +@deftypefun int rl_clear_signals (void) +Remove all of the Readline signal handlers installed by +@code{rl_set_signals()}. +@end deftypefun + +@node Custom Completers +@section Custom Completers +@cindex application-specific completion functions + +Typically, a program that reads commands from the user has a way of +disambiguating commands and data. If your program is one of these, then +it can provide completion for commands, data, or both. +The following sections describe how your program and Readline +cooperate to provide this service. + +@menu +* How Completing Works:: The logic used to do completion. +* Completion Functions:: Functions provided by Readline. +* Completion Variables:: Variables which control completion. +* A Short Completion Example:: An example of writing completer subroutines. +@end menu + +@node How Completing Works +@subsection How Completing Works + +In order to complete some text, the full list of possible completions +must be available. That is, it is not possible to accurately +expand a partial word without knowing all of the possible words +which make sense in that context. The Readline library provides +the user interface to completion, and two of the most common +completion functions: filename and username. For completing other types +of text, you must write your own completion function. This section +describes exactly what such functions must do, and provides an example. + +There are three major functions used to perform completion: + +@enumerate +@item +The user-interface function @code{rl_complete()}. This function is +called with the same arguments as other bindable Readline functions: +@var{count} and @var{invoking_key}. +It isolates the word to be completed and calls +@code{rl_completion_matches()} to generate a list of possible completions. +It then either lists the possible completions, inserts the possible +completions, or actually performs the +completion, depending on which behavior is desired. + +@item +The internal function @code{rl_completion_matches()} uses an +application-supplied @dfn{generator} function to generate the list of +possible matches, and then returns the array of these matches. +The caller should place the address of its generator function in +@code{rl_completion_entry_function}. + +@item +The generator function is called repeatedly from +@code{rl_completion_matches()}, returning a string each time. The +arguments to the generator function are @var{text} and @var{state}. +@var{text} is the partial word to be completed. @var{state} is zero the +first time the function is called, allowing the generator to perform +any necessary initialization, and a positive non-zero integer for +each subsequent call. The generator function returns +@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are +no more possibilities left. Usually the generator function computes the +list of possible completions when @var{state} is zero, and returns them +one at a time on subsequent calls. Each string the generator function +returns as a match must be allocated with @code{malloc()}; Readline +frees the strings when it has finished with them. +Such a generator function is referred to as an +@dfn{application-specific completion function}. + +@end enumerate + +@deftypefun int rl_complete (int ignore, int invoking_key) +Complete the word at or before point. You have supplied the function +that does the initial simple matching selection algorithm (see +@code{rl_completion_matches()}). The default is to do filename completion. +@end deftypefun + +@deftypevar {rl_compentry_func_t *} rl_completion_entry_function +This is a pointer to the generator function for +@code{rl_completion_matches()}. +If the value of @code{rl_completion_entry_function} is +@code{NULL} then the default filename generator +function, @code{rl_filename_completion_function()}, is used. +An @dfn{application-specific completion function} is a function whose +address is assigned to @code{rl_completion_entry_function} and whose +return values are used to generate possible completions. +@end deftypevar + +@node Completion Functions +@subsection Completion Functions + +Here is the complete list of callable completion functions present in +Readline. + +@deftypefun int rl_complete_internal (int what_to_do) +Complete the word at or before point. @var{what_to_do} says what to do +with the completion. A value of @samp{?} means list the possible +completions. @samp{TAB} means do standard completion. @samp{*} means +insert all of the possible completions. @samp{!} means to display +all of the possible completions, if there is more than one, as well as +performing partial completion. @samp{@@} is similar to @samp{!}, but +possible completions are not listed if the possible completions share +a common prefix. +@end deftypefun + +@deftypefun int rl_complete (int ignore, int invoking_key) +Complete the word at or before point. You have supplied the function +that does the initial simple matching selection algorithm (see +@code{rl_completion_matches()} and @code{rl_completion_entry_function}). +The default is to do filename +completion. This calls @code{rl_complete_internal()} with an +argument depending on @var{invoking_key}. +@end deftypefun + +@deftypefun int rl_possible_completions (int count, int invoking_key) +List the possible completions. See description of @code{rl_complete +()}. This calls @code{rl_complete_internal()} with an argument of +@samp{?}. +@end deftypefun + +@deftypefun int rl_insert_completions (int count, int invoking_key) +Insert the list of possible completions into the line, deleting the +partially-completed word. See description of @code{rl_complete()}. +This calls @code{rl_complete_internal()} with an argument of @samp{*}. +@end deftypefun + +@deftypefun int rl_completion_mode (rl_command_func_t *cfunc) +Returns the appropriate value to pass to @code{rl_complete_internal()} +depending on whether @var{cfunc} was called twice in succession and +the values of the @code{show-all-if-ambiguous} and +@code{show-all-if-unmodified} variables. +Application-specific completion functions may use this function to present +the same interface as @code{rl_complete()}. +@end deftypefun + +@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func) +Returns an array of strings which is a list of completions for +@var{text}. If there are no completions, returns @code{NULL}. +The first entry in the returned array is the substitution for @var{text}. +The remaining entries are the possible completions. The array is +terminated with a @code{NULL} pointer. + +@var{entry_func} is a function of two args, and returns a +@code{char *}. The first argument is @var{text}. The second is a +state argument; it is zero on the first call, and non-zero on subsequent +calls. @var{entry_func} returns a @code{NULL} pointer to the caller +when there are no more matches. +@end deftypefun + +@deftypefun {char *} rl_filename_completion_function (const char *text, int state) +A generator function for filename completion in the general case. +@var{text} is a partial filename. +The Bash source is a useful reference for writing application-specific +completion functions (the Bash completion functions call this and other +Readline functions). +@end deftypefun + +@deftypefun {char *} rl_username_completion_function (const char *text, int state) +A completion generator for usernames. @var{text} contains a partial +username preceded by a random character (usually @samp{~}). As with all +completion generators, @var{state} is zero on the first call and non-zero +for subsequent calls. +@end deftypefun + +@node Completion Variables +@subsection Completion Variables + +@deftypevar {rl_compentry_func_t *} rl_completion_entry_function +A pointer to the generator function for @code{rl_completion_matches()}. +@code{NULL} means to use @code{rl_filename_completion_function()}, +the default filename completer. +@end deftypevar + +@deftypevar {rl_completion_func_t *} rl_attempted_completion_function +A pointer to an alternative function to create matches. +The function is called with @var{text}, @var{start}, and @var{end}. +@var{start} and @var{end} are indices in @code{rl_line_buffer} defining +the boundaries of @var{text}, which is a character string. +If this function exists and returns @code{NULL}, or if this variable is +set to @code{NULL}, then @code{rl_complete()} will call the value of +@code{rl_completion_entry_function} to generate matches, otherwise the +array of strings returned will be used. +If this function sets the @code{rl_attempted_completion_over} +variable to a non-zero value, Readline will not perform its default +completion even if this function returns no matches. +@end deftypevar + +@deftypevar {rl_quote_func_t *} rl_filename_quoting_function +A pointer to a function that will quote a filename in an +application-specific fashion. This is called if filename completion is being +attempted and one of the characters in @code{rl_filename_quote_characters} +appears in a completed filename. The function is called with +@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text} +is the filename to be quoted. The @var{match_type} is either +@code{SINGLE_MATCH}, if there is only one completion match, or +@code{MULT_MATCH}. Some functions use this to decide whether or not to +insert a closing quote character. The @var{quote_pointer} is a pointer +to any opening quote character the user typed. Some functions choose +to reset this character. +@end deftypevar + +@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function +A pointer to a function that will remove application-specific quoting +characters from a filename before completion is attempted, so those +characters do not interfere with matching the text against names in +the filesystem. It is called with @var{text}, the text of the word +to be dequoted, and @var{quote_char}, which is the quoting character +that delimits the filename (usually @samp{'} or @samp{"}). If +@var{quote_char} is zero, the filename was not in an embedded string. +@end deftypevar + +@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p +A pointer to a function to call that determines whether or not a specific +character in the line buffer is quoted, according to whatever quoting +mechanism the program calling Readline uses. The function is called with +two arguments: @var{text}, the text of the line, and @var{index}, the +index of the character in the line. It is used to decide whether a +character found in @code{rl_completer_word_break_characters} should be +used to break words for the completer. +@end deftypevar + +@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function +This function, if defined, is called by the completer when real filename +completion is done, after all the matching names have been generated. +It is passed a @code{NULL} terminated array of matches. +The first element (@code{matches[0]}) is the +maximal substring common to all matches. This function can +re-arrange the list of matches as required, but each element deleted +from the array must be freed. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook +This function, if defined, is allowed to modify the directory portion +of filenames Readline completes. +It could be used to expand symbolic links or shell variables in pathnames. +It is called with the address of a string (the current directory name) as an +argument, and may modify that string. +If the string is replaced with a new string, the old value should be freed. +Any modified directory name should have a trailing slash. +The modified value will be used as part of the completion, replacing +the directory portion of the pathname the user typed. +At the least, even if no other expansion is performed, this function should +remove any quote characters from the directory name, because its result will +be passed directly to @code{opendir()}. + +The directory completion hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook; +If non-zero, this is the address of a function to call when completing +a directory name. This function takes the address of the directory name +to be modified as an argument. Unlike @code{rl_directory_completion_hook}, +it only modifies the directory name used in @code{opendir}, not what is +displayed when the possible completions are printed or inserted. It is +called before rl_directory_completion_hook. +At the least, even if no other expansion is performed, this function should +remove any quote characters from the directory name, because its result will +be passed directly to @code{opendir()}. + +The directory rewrite hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook +If non-zero, this is the address of a function for the completer to +call before deciding which character to append to a completed name. +This function modifies its filename name argument, and the modified value +is passed to @code{stat()} to determine the file's type and characteristics. +This function does not need to remove quote characters from the filename. + +The stat hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook +If non-zero, this is the address of a function called when reading +directory entries from the filesystem for completion and comparing +them to the partial word to be completed. The function should +perform any necessary application or system-specific conversion on +the filename, such as converting between character sets or converting +from a filesystem format to a character input format. +The function takes two arguments: @var{fname}, the filename to be converted, +and @var{fnlen}, its length in bytes. +It must either return its first argument (if no conversion takes place) +or the converted filename in newly-allocated memory. The converted +form is used to compare against the word to be completed, and, if it +matches, is added to the list of matches. Readline will free the +allocated string. +@end deftypevar + +@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook +If non-zero, then this is the address of a function to call when +completing a word would normally display the list of possible matches. +This function is called in lieu of Readline displaying the list. +It takes three arguments: +(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length}) +where @var{matches} is the array of matching strings, +@var{num_matches} is the number of strings in that array, and +@var{max_length} is the length of the longest string in that array. +Readline provides a convenience function, @code{rl_display_match_list}, +that takes care of doing the display to Readline's output stream. +You may call that function from this hook. +@end deftypevar + +@deftypevar {const char *} rl_basic_word_break_characters +The basic list of characters that signal a break between words for the +completer routine. The default value of this variable is the characters +which break words for completion in Bash: +@code{" \t\n\"\\'`@@$><=;|&@{("}. +@end deftypevar + +@deftypevar {const char *} rl_basic_quote_characters +A list of quote characters which can cause a word break. +@end deftypevar + +@deftypevar {const char *} rl_completer_word_break_characters +The list of characters that signal a break between words for +@code{rl_complete_internal()}. The default list is the value of +@code{rl_basic_word_break_characters}. +@end deftypevar + +@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook +If non-zero, this is the address of a function to call when Readline is +deciding where to separate words for word completion. It should return +a character string like @code{rl_completer_word_break_characters} to be +used to perform the current completion. The function may choose to set +@code{rl_completer_word_break_characters} itself. If the function +returns @code{NULL}, @code{rl_completer_word_break_characters} is used. +@end deftypevar + +@deftypevar {const char *} rl_completer_quote_characters +A list of characters which can be used to quote a substring of the line. +Completion occurs on the entire substring, and within the substring +@code{rl_completer_word_break_characters} are treated as any other character, +unless they also appear within this list. +@end deftypevar + +@deftypevar {const char *} rl_filename_quote_characters +A list of characters that cause a filename to be quoted by the completer +when they appear in a completed filename. The default is the null string. +@end deftypevar + +@deftypevar {const char *} rl_special_prefixes +The list of characters that are word break characters, but should be +left in @var{text} when it is passed to the completion function. +Programs can use this to help determine what kind of completing to do. +For instance, Bash sets this variable to "$@@" so that it can complete +shell variables and hostnames. +@end deftypevar + +@deftypevar int rl_completion_query_items +Up to this many items will be displayed in response to a +possible-completions call. After that, Readline asks the user for +confirmation before displaying them. +The default value is 100. A negative value +indicates that Readline should never ask for confirmation. +@end deftypevar + +@deftypevar {int} rl_completion_append_character +When a single completion alternative matches at the end of the command +line, this character is appended to the inserted completion text. The +default is a space character (@samp{ }). Setting this to the null +character (@samp{\0}) prevents anything being appended automatically. +This can be changed in application-specific completion functions to +provide the ``most sensible word separator character'' according to +an application-specific command line syntax specification. +It is set to the default before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_suppress_append +If non-zero, @var{rl_completion_append_character} is not appended to +matches at the end of the command line, as described above. +It is set to 0 before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_quote_character +When Readline is completing quoted text, as delimited by one of the +characters in @var{rl_completer_quote_characters}, it sets this variable +to the quoting character found. +This is set before any application-specific completion function is called. +@end deftypevar + +@deftypevar int rl_completion_suppress_quote +If non-zero, Readline does not append a matching quote character when +performing completion on a quoted string. +It is set to 0 before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_found_quote +When Readline is completing quoted text, it sets this variable +to a non-zero value if the word being completed contains or is delimited +by any quoting characters, including backslashes. +This is set before any application-specific completion function is called. +@end deftypevar + +@deftypevar int rl_completion_mark_symlink_dirs +If non-zero, a slash will be appended to completed filenames that are +symbolic links to directory names, subject to the value of the +user-settable @var{mark-directories} variable. +This variable exists so that application-specific completion functions +can override the user's global preference (set via the +@var{mark-symlinked-directories} Readline variable) if appropriate. +This variable is set to the user's preference before any +application-specific completion function is called, so unless that +function modifies the value, the user's preferences are honored. +@end deftypevar + +@deftypevar int rl_ignore_completion_duplicates +If non-zero, then duplicates in the matches are removed. +The default is 1. +@end deftypevar + +@deftypevar int rl_filename_completion_desired +Non-zero means that the results of the matches are to be treated as +filenames. This is @emph{always} zero when completion is attempted, +and can only be changed +within an application-specific completion function. If it is set to a +non-zero value by such a function, directory names have a slash appended +and Readline attempts to quote completed filenames if they contain any +characters in @code{rl_filename_quote_characters} and +@code{rl_filename_quoting_desired} is set to a non-zero value. +@end deftypevar + +@deftypevar int rl_filename_quoting_desired +Non-zero means that the results of the matches are to be quoted using +double quotes (or an application-specific quoting mechanism) if the +completed filename contains any characters in +@code{rl_filename_quote_chars}. This is @emph{always} non-zero +when completion is attempted, and can only be changed within an +application-specific completion function. +The quoting is effected via a call to the function pointed to +by @code{rl_filename_quoting_function}. +@end deftypevar + +@deftypevar int rl_attempted_completion_over +If an application-specific completion function assigned to +@code{rl_attempted_completion_function} sets this variable to a non-zero +value, Readline will not perform its default filename completion even +if the application's completion function returns no matches. +It should be set only by an application's completion function. +@end deftypevar + +@deftypevar int rl_sort_completion_matches +If an application sets this variable to 0, Readline will not sort the +list of completions (which implies that it cannot remove any duplicate +completions). The default value is 1, which means that Readline will +sort the completions and, depending on the value of +@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate +matches. +@end deftypevar + +@deftypevar int rl_completion_type +Set to a character describing the type of completion Readline is currently +attempting; see the description of @code{rl_complete_internal()} +(@pxref{Completion Functions}) for the list of characters. +This is set to the appropriate value before any application-specific +completion function is called, allowing such functions to present +the same interface as @code{rl_complete()}. +@end deftypevar + +@deftypevar int rl_completion_invoking_key +Set to the final character in the key sequence that invoked one of the +completion functions that call @code{rl_complete_internal()}. This is +set to the appropriate value before any application-specific completion +function is called. +@end deftypevar + +@deftypevar int rl_inhibit_completion +If this variable is non-zero, completion is inhibited. The completion +character will be inserted as any other bound to @code{self-insert}. +@end deftypevar + +@node A Short Completion Example +@subsection A Short Completion Example + +Here is a small application demonstrating the use of the GNU Readline +library. It is called @code{fileman}, and the source code resides in +@file{examples/fileman.c}. This sample application provides +completion of command names, line editing features, and access to the +history list. + +@page +@smallexample +/* fileman.c -- A tiny application which demonstrates how to use the + GNU Readline library. This application interactively allows users + to manipulate files and their modes. */ + +#ifdef HAVE_CONFIG_H +# include <config.h> +#endif + +#include <sys/types.h> +#ifdef HAVE_SYS_FILE_H +# include <sys/file.h> +#endif +#include <sys/stat.h> + +#ifdef HAVE_UNISTD_H +# include <unistd.h> +#endif + +#include <fcntl.h> +#include <stdio.h> +#include <errno.h> +#include <locale.h> + +#if defined (HAVE_STRING_H) +# include <string.h> +#else /* !HAVE_STRING_H */ +# include <strings.h> +#endif /* !HAVE_STRING_H */ + +#ifdef HAVE_STDLIB_H +# include <stdlib.h> +#endif + +#include <time.h> + +#include <readline/readline.h> +#include <readline/history.h> + +extern char *xmalloc PARAMS((size_t)); + +/* The names of functions that actually do the manipulation. */ +int com_list PARAMS((char *)); +int com_view PARAMS((char *)); +int com_rename PARAMS((char *)); +int com_stat PARAMS((char *)); +int com_pwd PARAMS((char *)); +int com_delete PARAMS((char *)); +int com_help PARAMS((char *)); +int com_cd PARAMS((char *)); +int com_quit PARAMS((char *)); + +/* A structure which contains information on the commands this program + can understand. */ + +typedef struct @{ + char *name; /* User printable name of the function. */ + rl_icpfunc_t *func; /* Function to call to do the job. */ + char *doc; /* Documentation for this function. */ +@} COMMAND; + +COMMAND commands[] = @{ + @{ "cd", com_cd, "Change to directory DIR" @}, + @{ "delete", com_delete, "Delete FILE" @}, + @{ "help", com_help, "Display this text" @}, + @{ "?", com_help, "Synonym for `help'" @}, + @{ "list", com_list, "List files in DIR" @}, + @{ "ls", com_list, "Synonym for `list'" @}, + @{ "pwd", com_pwd, "Print the current working directory" @}, + @{ "quit", com_quit, "Quit using Fileman" @}, + @{ "rename", com_rename, "Rename FILE to NEWNAME" @}, + @{ "stat", com_stat, "Print out statistics on FILE" @}, + @{ "view", com_view, "View the contents of FILE" @}, + @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @} +@}; + +/* Forward declarations. */ +char *stripwhite (); +COMMAND *find_command (); + +/* The name of this program, as taken from argv[0]. */ +char *progname; + +/* When non-zero, this global means the user is done using this program. */ +int done; + +char * +dupstr (s) + char *s; +@{ + char *r; + + r = xmalloc (strlen (s) + 1); + strcpy (r, s); + return (r); +@} + +main (argc, argv) + int argc; + char **argv; +@{ + char *line, *s; + + setlocale (LC_ALL, ""); + + progname = argv[0]; + + initialize_readline (); /* Bind our completer. */ + + /* Loop reading and executing lines until the user quits. */ + for ( ; done == 0; ) + @{ + line = readline ("FileMan: "); + + if (!line) + break; + + /* Remove leading and trailing whitespace from the line. + Then, if there is anything left, add it to the history list + and execute it. */ + s = stripwhite (line); + + if (*s) + @{ + add_history (s); + execute_line (s); + @} + + free (line); + @} + exit (0); +@} + +/* Execute a command line. */ +int +execute_line (line) + char *line; +@{ + register int i; + COMMAND *command; + char *word; + + /* Isolate the command word. */ + i = 0; + while (line[i] && whitespace (line[i])) + i++; + word = line + i; + + while (line[i] && !whitespace (line[i])) + i++; + + if (line[i]) + line[i++] = '\0'; + + command = find_command (word); + + if (!command) + @{ + fprintf (stderr, "%s: No such command for FileMan.\n", word); + return (-1); + @} + + /* Get argument to command, if any. */ + while (whitespace (line[i])) + i++; + + word = line + i; + + /* Call the function. */ + return ((*(command->func)) (word)); +@} + +/* Look up NAME as the name of a command, and return a pointer to that + command. Return a NULL pointer if NAME isn't a command name. */ +COMMAND * +find_command (name) + char *name; +@{ + register int i; + + for (i = 0; commands[i].name; i++) + if (strcmp (name, commands[i].name) == 0) + return (&commands[i]); + + return ((COMMAND *)NULL); +@} + +/* Strip whitespace from the start and end of STRING. Return a pointer + into STRING. */ +char * +stripwhite (string) + char *string; +@{ + register char *s, *t; + + for (s = string; whitespace (*s); s++) + ; + + if (*s == 0) + return (s); + + t = s + strlen (s) - 1; + while (t > s && whitespace (*t)) + t--; + *++t = '\0'; + + return s; +@} + +/* **************************************************************** */ +/* */ +/* Interface to Readline Completion */ +/* */ +/* **************************************************************** */ + +char *command_generator PARAMS((const char *, int)); +char **fileman_completion PARAMS((const char *, int, int)); + +/* Tell the GNU Readline library how to complete. We want to try to complete + on command names if this is the first word in the line, or on filenames + if not. */ +initialize_readline () +@{ + /* Allow conditional parsing of the ~/.inputrc file. */ + rl_readline_name = "FileMan"; + + /* Tell the completer that we want a crack first. */ + rl_attempted_completion_function = fileman_completion; +@} + +/* Attempt to complete on the contents of TEXT. START and END bound the + region of rl_line_buffer that contains the word to complete. TEXT is + the word to complete. We can use the entire contents of rl_line_buffer + in case we want to do some simple parsing. Return the array of matches, + or NULL if there aren't any. */ +char ** +fileman_completion (text, start, end) + const char *text; + int start, end; +@{ + char **matches; + + matches = (char **)NULL; + + /* If this word is at the start of the line, then it is a command + to complete. Otherwise it is the name of a file in the current + directory. */ + if (start == 0) + matches = rl_completion_matches (text, command_generator); + + return (matches); +@} + +/* Generator function for command completion. STATE lets us know whether + to start from scratch; without any state (i.e. STATE == 0), then we + start at the top of the list. */ +char * +command_generator (text, state) + const char *text; + int state; +@{ + static int list_index, len; + char *name; + + /* If this is a new word to complete, initialize now. This includes + saving the length of TEXT for efficiency, and initializing the index + variable to 0. */ + if (!state) + @{ + list_index = 0; + len = strlen (text); + @} + + /* Return the next name which partially matches from the command list. */ + while (name = commands[list_index].name) + @{ + list_index++; + + if (strncmp (name, text, len) == 0) + return (dupstr(name)); + @} + + /* If no names matched, then return NULL. */ + return ((char *)NULL); +@} + +/* **************************************************************** */ +/* */ +/* FileMan Commands */ +/* */ +/* **************************************************************** */ + +/* String to pass to system (). This is for the LIST, VIEW and RENAME + commands. */ +static char syscom[1024]; + +/* List the file(s) named in arg. */ +com_list (arg) + char *arg; +@{ + if (!arg) + arg = ""; + + sprintf (syscom, "ls -FClg %s", arg); + return (system (syscom)); +@} + +com_view (arg) + char *arg; +@{ + if (!valid_argument ("view", arg)) + return 1; + +#if defined (__MSDOS__) + /* more.com doesn't grok slashes in pathnames */ + sprintf (syscom, "less %s", arg); +#else + sprintf (syscom, "more %s", arg); +#endif + return (system (syscom)); +@} + +com_rename (arg) + char *arg; +@{ + too_dangerous ("rename"); + return (1); +@} + +com_stat (arg) + char *arg; +@{ + struct stat finfo; + + if (!valid_argument ("stat", arg)) + return (1); + + if (stat (arg, &finfo) == -1) + @{ + perror (arg); + return (1); + @} + + printf ("Statistics for `%s':\n", arg); + + printf ("%s has %d link%s, and is %d byte%s in length.\n", + arg, + finfo.st_nlink, + (finfo.st_nlink == 1) ? "" : "s", + finfo.st_size, + (finfo.st_size == 1) ? "" : "s"); + printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); + printf (" Last access at: %s", ctime (&finfo.st_atime)); + printf (" Last modified at: %s", ctime (&finfo.st_mtime)); + return (0); +@} + +com_delete (arg) + char *arg; +@{ + too_dangerous ("delete"); + return (1); +@} + +/* Print out help for ARG, or for all of the commands if ARG is + not present. */ +com_help (arg) + char *arg; +@{ + register int i; + int printed = 0; + + for (i = 0; commands[i].name; i++) + @{ + if (!*arg || (strcmp (arg, commands[i].name) == 0)) + @{ + printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); + printed++; + @} + @} + + if (!printed) + @{ + printf ("No commands match `%s'. Possibilities are:\n", arg); + + for (i = 0; commands[i].name; i++) + @{ + /* Print in six columns. */ + if (printed == 6) + @{ + printed = 0; + printf ("\n"); + @} + + printf ("%s\t", commands[i].name); + printed++; + @} + + if (printed) + printf ("\n"); + @} + return (0); +@} + +/* Change to the directory ARG. */ +com_cd (arg) + char *arg; +@{ + if (chdir (arg) == -1) + @{ + perror (arg); + return 1; + @} + + com_pwd (""); + return (0); +@} + +/* Print out the current working directory. */ +com_pwd (ignore) + char *ignore; +@{ + char dir[1024], *s; + + s = getcwd (dir, sizeof(dir) - 1); + if (s == 0) + @{ + printf ("Error getting pwd: %s\n", dir); + return 1; + @} + + printf ("Current directory is %s\n", dir); + return 0; +@} + +/* The user wishes to quit using this program. Just set DONE non-zero. */ +com_quit (arg) + char *arg; +@{ + done = 1; + return (0); +@} + +/* Function which tells you that you can't do this. */ +too_dangerous (caller) + char *caller; +@{ + fprintf (stderr, + "%s: Too dangerous for me to distribute. Write it yourself.\n", + caller); +@} + +/* Return non-zero if ARG is a valid argument for CALLER, else print + an error message and return zero. */ +int +valid_argument (caller, arg) + char *caller, *arg; +@{ + if (!arg || !*arg) + @{ + fprintf (stderr, "%s: Argument required.\n", caller); + return (0); + @} + + return (1); +@} +@end smallexample diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi new file mode 100644 index 0000000..cbcbb45 --- /dev/null +++ b/lib/readline/doc/rluser.texi @@ -0,0 +1,2488 @@ +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rluser.info +@comment %**end of header (This is for running Texinfo on a region.) + +@ignore +This file documents the end user interface to the GNU command line +editing features. It is to be an appendix to manuals for programs which +use these features. There is a document entitled "readline.texinfo" +which contains both end-user and programmer documentation for the +GNU Readline Library. + +Copyright (C) 1988--2022 Free Software Foundation, Inc. + +Authored by Brian Fox and Chet Ramey. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@comment If you are including this manual as an appendix, then set the +@comment variable readline-appendix. + +@ifclear BashFeatures +@defcodeindex bt +@end ifclear + +@node Command Line Editing +@chapter Command Line Editing + +This chapter describes the basic features of the @sc{gnu} +command line editing interface. +@ifset BashFeatures +Command line editing is provided by the Readline library, which is +used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive shell, +unless the @option{--noediting} option is supplied at shell invocation. +Line editing is also used when using the @option{-e} option to the +@code{read} builtin command (@pxref{Bash Builtins}). +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the @option{-o emacs} or +@option{-o vi} options to the @code{set} builtin command +(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or +@option{+o vi} options to @code{set}. +@end ifset + +@menu +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. +@ifset BashFeatures +* Programmable Completion:: How to specify the possible completions for + a specific command. +* Programmable Completion Builtins:: Builtin commands to specify how to + complete arguments for a particular command. +* A Programmable Completion Example:: An example shell function for + generating possible completions. +@end ifset +@end menu + +@node Introduction and Notation +@section Introduction to Line Editing + +The following paragraphs describe the notation used to represent +keystrokes. + +The text @kbd{C-k} is read as `Control-K' and describes the character +produced when the @key{k} key is pressed while the Control key +is depressed. + +The text @kbd{M-k} is read as `Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the @key{k} +key is pressed. +The Meta key is labeled @key{ALT} on many keyboards. +On keyboards with two keys labeled @key{ALT} (usually to either side of +the space bar), the @key{ALT} on the left side is generally set to +work as a Meta key. +The @key{ALT} key on the right may also be configured to work as a +Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + +If you do not have a Meta or @key{ALT} key, or another key working as +a Meta key, the identical keystroke can be generated by typing @key{ESC} +@emph{first}, and then typing @key{k}. +Either process is known as @dfn{metafying} the @key{k} key. + +The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the +character produced by @dfn{metafying} @kbd{C-k}. + +In addition, several keys have their own names. Specifically, +@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all +stand for themselves when seen in this text, or in an init file +(@pxref{Readline Init File}). +If your keyboard lacks a @key{LFD} key, typing @key{C-j} will +produce the desired character. +The @key{RET} key may be labeled @key{Return} or @key{Enter} on +some keyboards. + +@node Readline Interaction +@section Readline Interaction +@cindex interaction, readline + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press @key{RET}. You do not have to be at the +end of the line to press @key{RET}; the entire line is accepted +regardless of the location of the cursor within the line. + +@menu +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. +@end menu + +@node Readline Bare Essentials +@subsection Readline Bare Essentials +@cindex notation, readline +@cindex command editing +@cindex editing command lines + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your +erase character to back up and delete the mistyped character. + +Sometimes you may mistype a character, and +not notice the error until you have typed several other characters. In +that case, you can type @kbd{C-b} to move the cursor to the left, and then +correct your mistake. Afterwards, you can move the cursor to the right +with @kbd{C-f}. + +When you add text in the middle of a line, you will notice that characters +to the right of the cursor are `pushed over' to make room for the text +that you have inserted. Likewise, when you delete text behind the cursor, +characters to the right of the cursor are `pulled back' to fill in the +blank space created by the removal of the text. A list of the bare +essentials for editing the text of an input line follows. + +@table @asis +@item @kbd{C-b} +Move back one character. +@item @kbd{C-f} +Move forward one character. +@item @key{DEL} or @key{Backspace} +Delete the character to the left of the cursor. +@item @kbd{C-d} +Delete the character underneath the cursor. +@item @w{Printing characters} +Insert the character into the line at the cursor. +@item @kbd{C-_} or @kbd{C-x C-u} +Undo the last editing command. You can undo all the way back to an +empty line. +@end table + +@noindent +(Depending on your configuration, the @key{Backspace} key might be set to +delete the character to the left of the cursor and the @key{DEL} key set +to delete the character underneath the cursor, like @kbd{C-d}, rather +than the character to the left of the cursor.) + +@node Readline Movement Commands +@subsection Readline Movement Commands + + +The above table describes the most basic keystrokes that you need +in order to do editing of the input line. For your convenience, many +other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, +@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly +about the line. + +@table @kbd +@item C-a +Move to the start of the line. +@item C-e +Move to the end of the line. +@item M-f +Move forward a word, where a word is composed of letters and digits. +@item M-b +Move backward a word. +@item C-l +Clear the screen, reprinting the current line at the top. +@end table + +Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. + +@node Readline Killing Commands +@subsection Readline Killing Commands + +@cindex killing text +@cindex yanking text + +@dfn{Killing} text means to delete the text from the line, but to save +it away for later use, usually by @dfn{yanking} (re-inserting) +it back into the line. +(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) + +If the description for a command says that it `kills' text, then you can +be sure that you can get the text back in a different (or the same) +place later. + +When you use a kill command, the text is saved in a @dfn{kill-ring}. +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill +ring is not line specific; the text that you killed on a previously +typed line is available to be yanked back later, when you are typing +another line. +@cindex kill ring + +Here is the list of commands for killing text. + +@table @kbd +@item C-k +Kill the text from the current cursor position to the end of the line. + +@item M-d +Kill from the cursor to the end of the current word, or, if between +words, to the end of the next word. +Word boundaries are the same as those used by @kbd{M-f}. + +@item M-@key{DEL} +Kill from the cursor to the start of the current word, or, if between +words, to the start of the previous word. +Word boundaries are the same as those used by @kbd{M-b}. + +@item C-w +Kill from the cursor to the previous whitespace. This is different than +@kbd{M-@key{DEL}} because the word boundaries differ. + +@end table + +Here is how to @dfn{yank} the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. + +@table @kbd +@item C-y +Yank the most recently killed text back into the buffer at the cursor. + +@item M-y +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is @kbd{C-y} or @kbd{M-y}. +@end table + +@node Readline Arguments +@subsection Readline Arguments + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the @i{sign} of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type @samp{M-- C-k}. + +The general way to pass numeric arguments to a command is to type meta +digits before the command. If the first `digit' typed is a minus +sign (@samp{-}), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}, +which will delete the next ten characters on the input line. + +@node Searching +@subsection Searching for Commands in the History + +Readline provides commands for searching through the command history +@ifset BashFeatures +(@pxref{Bash History Facilities}) +@end ifset +for lines containing a specified string. +There are two search modes: @dfn{incremental} and @dfn{non-incremental}. + +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, Readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +To search backward in the history for a particular string, type +@kbd{C-r}. Typing @kbd{C-s} searches forward through the history. +The characters present in the value of the @code{isearch-terminators} variable +are used to terminate an incremental search. +If that variable has not been assigned a value, the @key{ESC} and +@kbd{C-J} characters will terminate an incremental search. +@kbd{C-g} will abort an incremental search and restore the original line. +When the search is terminated, the history entry containing the +search string becomes the current line. + +To find other matching entries in the history list, type @kbd{C-r} or +@kbd{C-s} as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a Readline command will terminate +the search and execute that command. +For instance, a @key{RET} will terminate the search and accept +the line, thereby executing the command from the history list. +A movement command will terminate the search, make the last line found +the current line, and begin editing. + +Readline remembers the last incremental search string. If two +@kbd{C-r}s are typed without any intervening characters defining a new +search string, any remembered search string is used. + +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + +@node Readline Init File +@section Readline Init File +@cindex initialization file, readline + +Although the Readline library comes with a set of Emacs-like +keybindings installed by default, it is possible to use a different set +of keybindings. +Any user can customize programs that use Readline by putting +commands in an @dfn{inputrc} file, +conventionally in their home directory. +The name of this +@ifset BashFeatures +file is taken from the value of the shell variable @env{INPUTRC}. If +@end ifset +@ifclear BashFeatures +file is taken from the value of the environment variable @env{INPUTRC}. If +@end ifclear +that variable is unset, the default is @file{~/.inputrc}. If that +file does not exist or cannot be read, the ultimate default is +@file{/etc/inputrc}. +@ifset BashFeatures +The @w{@code{bind}} builtin command can also be used to set Readline +keybindings and variables. +@xref{Bash Builtins}. +@end ifset + +When a program which uses the Readline library starts up, the +init file is read, and the key bindings are set. + +In addition, the @code{C-x C-r} command re-reads this init file, thus +incorporating any changes that you might have made to it. + +@menu +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. +@end menu + +@node Readline Init File Syntax +@subsection Readline Init File Syntax + +There are only a few basic constructs allowed in the +Readline init file. Blank lines are ignored. +Lines beginning with a @samp{#} are comments. +Lines beginning with a @samp{$} indicate conditional +constructs (@pxref{Conditional Init Constructs}). Other lines +denote variable settings and key bindings. + +@table @asis +@item Variable Settings +You can modify the run-time behavior of Readline by +altering the values of variables in Readline +using the @code{set} command within the init file. +The syntax is simple: + +@example +set @var{variable} @var{value} +@end example + +@noindent +Here, for example, is how to +change from the default Emacs-like key binding to use +@code{vi} line editing commands: + +@example +set editing-mode vi +@end example + +Variable names and values, where appropriate, are recognized without regard +to case. Unrecognized variable names are ignored. + +Boolean variables (those that can be set to on or off) are set to on if +the value is null or empty, @var{on} (case-insensitive), or 1. Any other +value results in the variable being set to off. + +@ifset BashFeatures +The @w{@code{bind -V}} command lists the current Readline variable names +and values. @xref{Bash Builtins}. +@end ifset + +A great deal of run-time behavior is changeable with the following +variables. + +@cindex variables, readline +@table @code + +@item active-region-start-color +@vindex active-region-start-color +A string variable that controls the text color and background when displaying +the text in the active region (see the description of +@code{enable-active-region} below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal's terminfo description. +A sample value might be @samp{\e[01;33m}. + +@item active-region-end-color +@vindex active-region-end-color +A string variable that "undoes" the effects of @code{active-region-start-color} +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal's terminfo description. +A sample value might be @samp{\e[0m}. + +@item bell-style +@vindex bell-style +Controls what happens when Readline wants to ring the terminal bell. +If set to @samp{none}, Readline never rings the bell. If set to +@samp{visible}, Readline uses a visible bell if one is available. +If set to @samp{audible} (the default), Readline attempts to ring +the terminal's bell. + +@item bind-tty-special-chars +@vindex bind-tty-special-chars +If set to @samp{on} (the default), Readline attempts to bind the control +characters treated specially by the kernel's terminal driver to their +Readline equivalents. + +@item blink-matching-paren +@vindex blink-matching-paren +If set to @samp{on}, Readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. The default +is @samp{off}. + +@item colored-completion-prefix +@vindex colored-completion-prefix +If set to @samp{on}, when listing completions, Readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the @env{LS_COLORS} +environment variable. +If there is a color definition in @env{LS_COLORS} for the custom suffix +@samp{readline-colored-completion-prefix}, Readline uses this color for +the common prefix instead of its default. +The default is @samp{off}. + +@item colored-stats +@vindex colored-stats +If set to @samp{on}, Readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the @env{LS_COLORS} +environment variable. +The default is @samp{off}. + +@item comment-begin +@vindex comment-begin +The string to insert at the beginning of the line when the +@code{insert-comment} command is executed. The default value +is @code{"#"}. + +@item completion-display-width +@vindex completion-display-width +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is -1. + +@item completion-ignore-case +@vindex completion-ignore-case +If set to @samp{on}, Readline performs filename matching and completion +in a case-insensitive fashion. +The default value is @samp{off}. + +@item completion-map-case +@vindex completion-map-case +If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline +treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when +performing case-insensitive filename matching and completion. +The default value is @samp{off}. + +@item completion-prefix-display-length +@vindex completion-prefix-display-length +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. + +@item completion-query-items +@vindex completion-query-items +The number of possible completions that determines when the user is +asked whether the list of possibilities should be displayed. +If the number of possible completions is greater than or equal to this value, +Readline will ask whether or not the user wishes to view them; +otherwise, they are simply listed. +This variable must be set to an integer value greater than or equal to zero. +A zero value means Readline should never ask; negative values are +treated as zero. +The default limit is @code{100}. + +@item convert-meta +@vindex convert-meta +If set to @samp{on}, Readline will convert characters with the +eighth bit set to an @sc{ascii} key sequence by stripping the eighth +bit and prefixing an @key{ESC} character, converting them to a +meta-prefixed key sequence. +The default value is @samp{on}, but +will be set to @samp{off} if the locale is one that contains +eight-bit characters. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item disable-completion +@vindex disable-completion +If set to @samp{On}, Readline will inhibit word completion. +Completion characters will be inserted into the line as if they had +been mapped to @code{self-insert}. The default is @samp{off}. + +@item echo-control-characters +@vindex echo-control-characters +When set to @samp{on}, on operating systems that indicate they support it, +Readline echoes a character corresponding to a signal generated from the +keyboard. The default is @samp{on}. + +@item editing-mode +@vindex editing-mode +The @code{editing-mode} variable controls which default set of +key bindings is used. By default, Readline starts up in Emacs editing +mode, where the keystrokes are most similar to Emacs. This variable can be +set to either @samp{emacs} or @samp{vi}. + +@item emacs-mode-string +@vindex emacs-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{@@}. + +@item enable-active-region +@vindex enable-active-region +The @dfn{point} is the current cursor position, and @dfn{mark} refers +to a saved cursor position (@pxref{Commands For Moving}). +The text between the point and mark is referred to as the @dfn{region}. +When this variable is set to @samp{On}, Readline allows certain commands +to designate the region as @dfn{active}. +When the region is active, Readline highlights the text in the region using +the value of the @code{active-region-start-color}, which defaults to the +string that enables +the terminal's standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +The default is @samp{On}. + +@item enable-bracketed-paste +@vindex enable-bracketed-paste +When set to @samp{On}, Readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This is called putting the terminal into @dfn{bracketed paste mode}; +it prevents Readline from executing any editing commands bound to key +sequences appearing in the pasted text. +The default is @samp{On}. + +@item enable-keypad +@vindex enable-keypad +When set to @samp{on}, Readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. The default is @samp{off}. + +@item enable-meta-key +When set to @samp{on}, Readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +The default is @samp{on}. + +@item expand-tilde +@vindex expand-tilde +If set to @samp{on}, tilde expansion is performed when Readline +attempts word completion. The default is @samp{off}. + +@item history-preserve-point +@vindex history-preserve-point +If set to @samp{on}, the history code attempts to place the point (the +current cursor position) at the +same location on each history line retrieved with @code{previous-history} +or @code{next-history}. The default is @samp{off}. + +@item history-size +@vindex history-size +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is not limited. +If an attempt is made to set @var{history-size} to a non-numeric value, +the maximum number of history entries will be set to 500. + +@item horizontal-scroll-mode +@vindex horizontal-scroll-mode +This variable can be set to either @samp{on} or @samp{off}. Setting it +to @samp{on} means that the text of the lines being edited will scroll +horizontally on a single screen line when they are longer than the width +of the screen, instead of wrapping onto a new screen line. +This variable is automatically set to @samp{on} for terminals of height 1. +By default, this variable is set to @samp{off}. + +@item input-meta +@vindex input-meta +@vindex meta-flag +If set to @samp{on}, Readline will enable eight-bit input (it +will not clear the eighth bit in the characters it reads), +regardless of what the terminal claims it can support. The +default value is @samp{off}, but Readline will set it to @samp{on} if the +locale contains eight-bit characters. +The name @code{meta-flag} is a synonym for this variable. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item isearch-terminators +@vindex isearch-terminators +The string of characters that should terminate an incremental search without +subsequently executing the character as a command (@pxref{Searching}). +If this variable has not been given a value, the characters @key{ESC} and +@kbd{C-J} will terminate an incremental search. + +@item keymap +@vindex keymap +Sets Readline's idea of the current keymap for key binding commands. +Built-in @code{keymap} names are +@code{emacs}, +@code{emacs-standard}, +@code{emacs-meta}, +@code{emacs-ctlx}, +@code{vi}, +@code{vi-move}, +@code{vi-command}, and +@code{vi-insert}. +@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a +synonym); @code{emacs} is equivalent to @code{emacs-standard}. +Applications may add additional names. +The default value is @code{emacs}. +The value of the @code{editing-mode} variable also affects the +default keymap. + +@item keyseq-timeout +Specifies the duration Readline will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, Readline will use the shorter +but complete key sequence. +Readline uses this value to determine whether or not input is +available on the current input source (@code{rl_instream} by default). +The value is specified in milliseconds, so a value of 1000 means that +Readline will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, Readline will wait until another key is pressed to +decide which key sequence to complete. +The default value is @code{500}. + +@item mark-directories +If set to @samp{on}, completed directory names have a slash +appended. The default is @samp{on}. + +@item mark-modified-lines +@vindex mark-modified-lines +This variable, when set to @samp{on}, causes Readline to display an +asterisk (@samp{*}) at the start of history lines which have been modified. +This variable is @samp{off} by default. + +@item mark-symlinked-directories +@vindex mark-symlinked-directories +If set to @samp{on}, completed names which are symbolic links +to directories have a slash appended (subject to the value of +@code{mark-directories}). +The default is @samp{off}. + +@item match-hidden-files +@vindex match-hidden-files +This variable, when set to @samp{on}, causes Readline to match files whose +names begin with a @samp{.} (hidden files) when performing filename +completion. +If set to @samp{off}, the leading @samp{.} must be +supplied by the user in the filename to be completed. +This variable is @samp{on} by default. + +@item menu-complete-display-prefix +@vindex menu-complete-display-prefix +If set to @samp{on}, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. The default is @samp{off}. + +@item output-meta +@vindex output-meta +If set to @samp{on}, Readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is @samp{off}, but Readline will set it to @samp{on} if the +locale contains eight-bit characters. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item page-completions +@vindex page-completions +If set to @samp{on}, Readline uses an internal @code{more}-like pager +to display a screenful of possible completions at a time. +This variable is @samp{on} by default. + +@item print-completions-horizontally +If set to @samp{on}, Readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +The default is @samp{off}. + +@item revert-all-at-newline +@vindex revert-all-at-newline +If set to @samp{on}, Readline will undo all changes to history lines +before returning when @code{accept-line} is executed. By default, +history lines may be modified and retain individual undo lists across +calls to @code{readline()}. The default is @samp{off}. + +@item show-all-if-ambiguous +@vindex show-all-if-ambiguous +This alters the default behavior of the completion functions. If +set to @samp{on}, +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +The default value is @samp{off}. + +@item show-all-if-unmodified +@vindex show-all-if-unmodified +This alters the default behavior of the completion functions in +a fashion similar to @var{show-all-if-ambiguous}. +If set to @samp{on}, +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +The default value is @samp{off}. + +@item show-mode-in-prompt +@vindex show-mode-in-prompt +If set to @samp{on}, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., @var{emacs-mode-string}). +The default value is @samp{off}. + +@item skip-completed-text +@vindex skip-completed-text +If set to @samp{on}, this alters the default completion behavior when +inserting a single match into the line. It's only active when +performing completion in the middle of a word. If enabled, Readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +For instance, if this is enabled, attempting completion when the cursor +is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile} +rather than @samp{Makefilefile}, assuming there is a single possible +completion. +The default value is @samp{off}. + +@item vi-cmd-mode-string +@vindex vi-cmd-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{(cmd)}. + +@item vi-ins-mode-string +@vindex vi-ins-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{(ins)}. + +@item visible-stats +@vindex visible-stats +If set to @samp{on}, a character denoting a file's type +is appended to the filename when listing possible +completions. The default is @samp{off}. + +@end table + +@item Key Bindings +The syntax for controlling key bindings in the init file is +simple. First you need to find the name of the command that you +want to change. The following sections contain tables of the command +name, the default keybinding, if any, and a short description of what +the command does. + +Once you know the name of the command, simply place on a line +in the init file the name of the key +you wish to bind the command to, a colon, and then the name of the +command. +There can be no space between the key name and the colon -- that will be +interpreted as part of the key name. +The name of the key can be expressed in different ways, depending on +what you find most comfortable. + +In addition to command names, Readline allows keys to be bound +to a string that is inserted when the key is pressed (a @var{macro}). + +@ifset BashFeatures +The @w{@code{bind -p}} command displays Readline function names and +bindings in a format that can be put directly into an initialization file. +@xref{Bash Builtins}. +@end ifset + +@table @asis +@item @w{@var{keyname}: @var{function-name} or @var{macro}} +@var{keyname} is the name of a key spelled out in English. For example: +@example +Control-u: universal-argument +Meta-Rubout: backward-kill-word +Control-o: "> output" +@end example + +In the example above, @kbd{C-u} is bound to the function +@code{universal-argument}, +@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and +@kbd{C-o} is bound to run the macro +expressed on the right hand side (that is, to insert the text +@samp{> output} into the line). + +A number of symbolic character names are recognized while +processing this key binding syntax: +@var{DEL}, +@var{ESC}, +@var{ESCAPE}, +@var{LFD}, +@var{NEWLINE}, +@var{RET}, +@var{RETURN}, +@var{RUBOUT}, +@var{SPACE}, +@var{SPC}, +and +@var{TAB}. + +@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} +@var{keyseq} differs from @var{keyname} above in that strings +denoting an entire key sequence can be specified, by placing +the key sequence in double quotes. Some @sc{gnu} Emacs style key +escapes can be used, as in the following example, but the +special character names are not recognized. + +@example +"\C-u": universal-argument +"\C-x\C-r": re-read-init-file +"\e[11~": "Function Key 1" +@end example + +In the above example, @kbd{C-u} is again bound to the function +@code{universal-argument} (just as it was in the first example), +@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file}, +and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert +the text @samp{Function Key 1}. + +@end table + +The following @sc{gnu} Emacs style escape sequences are available when +specifying key sequences: + +@table @code +@item @kbd{\C-} +control prefix +@item @kbd{\M-} +meta prefix +@item @kbd{\e} +an escape character +@item @kbd{\\} +backslash +@item @kbd{\"} +@key{"}, a double quotation mark +@item @kbd{\'} +@key{'}, a single quote or apostrophe +@end table + +In addition to the @sc{gnu} Emacs style escape sequences, a second +set of backslash escapes is available: + +@table @code +@item \a +alert (bell) +@item \b +backspace +@item \d +delete +@item \f +form feed +@item \n +newline +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \@var{nnn} +the eight-bit character whose value is the octal value @var{nnn} +(one to three digits) +@item \x@var{HH} +the eight-bit character whose value is the hexadecimal value @var{HH} +(one or two hex digits) +@end table + +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including @samp{"} and @samp{'}. +For example, the following binding will make @samp{@kbd{C-x} \} +insert a single @samp{\} into the line: +@example +"\C-x\\": "\\" +@end example + +@end table + +@node Conditional Init Constructs +@subsection Conditional Init Constructs + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. + +@table @code +@item $if +The @code{$if} construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +Readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. + +@table @code +@item mode +The @code{mode=} form of the @code{$if} directive is used to test +whether Readline is in @code{emacs} or @code{vi} mode. +This may be used in conjunction +with the @samp{set keymap} command, for instance, to set bindings in +the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if +Readline is starting out in @code{emacs} mode. + +@item term +The @code{term=} form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +@samp{=} is tested against both the full name of the terminal and +the portion of the terminal name before the first @samp{-}. This +allows @code{sun} to match both @code{sun} and @code{sun-cmd}, +for instance. + +@item version +The @code{version} test may be used to perform comparisons against +specific Readline versions. +The @code{version} expands to the current Readline version. +The set of comparison operators includes +@samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<}, +and @samp{>}. +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., @samp{7.1}). If the minor version is omitted, it +is assumed to be @samp{0}. +The operator may be separated from the string @code{version} and +from the version number argument by whitespace. +The following example sets a variable if the Readline version being used +is 7.0 or newer: +@example +$if version >= 7.0 +set show-mode-in-prompt on +$endif +@end example + +@item application +The @var{application} construct is used to include +application-specific settings. Each program using the Readline +library sets the @var{application name}, and you can test for +a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in Bash: +@example +$if Bash +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +$endif +@end example + +@item variable +The @var{variable} construct provides simple equality tests for Readline +variables and values. +The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values @var{on} and @var{off}. +The following example is equivalent to the @code{mode=emacs} test described +above: +@example +$if editing-mode == emacs +set show-mode-in-prompt on +$endif +@end example +@end table + +@item $endif +This command, as seen in the previous example, terminates an +@code{$if} command. + +@item $else +Commands in this branch of the @code{$if} directive are executed if +the test fails. + +@item $include +This directive takes a single filename as an argument and reads commands +and bindings from that file. +For example, the following directive reads from @file{/etc/inputrc}: +@example +$include /etc/inputrc +@end example +@end table + +@node Sample Init File +@subsection Sample Init File + +Here is an example of an @var{inputrc} file. This illustrates key +binding, variable assignment, and conditional syntax. + +@example +@page +# This file controls the behaviour of line input editing for +# programs that use the GNU Readline library. Existing +# programs include FTP, Bash, and GDB. +# +# You can re-read the inputrc file with C-x C-r. +# Lines beginning with '#' are comments. +# +# First, include any system-wide bindings and variable +# assignments from /etc/Inputrc +$include /etc/Inputrc + +# +# Set various bindings for emacs mode. + +set editing-mode emacs + +$if mode=emacs + +Meta-Control-h: backward-kill-word Text after the function name is ignored + +# +# Arrow keys in keypad mode +# +#"\M-OD": backward-char +#"\M-OC": forward-char +#"\M-OA": previous-history +#"\M-OB": next-history +# +# Arrow keys in ANSI mode +# +"\M-[D": backward-char +"\M-[C": forward-char +"\M-[A": previous-history +"\M-[B": next-history +# +# Arrow keys in 8 bit keypad mode +# +#"\M-\C-OD": backward-char +#"\M-\C-OC": forward-char +#"\M-\C-OA": previous-history +#"\M-\C-OB": next-history +# +# Arrow keys in 8 bit ANSI mode +# +#"\M-\C-[D": backward-char +#"\M-\C-[C": forward-char +#"\M-\C-[A": previous-history +#"\M-\C-[B": next-history + +C-q: quoted-insert + +$endif + +# An old-style binding. This happens to be the default. +TAB: complete + +# Macros that are convenient for shell interaction +$if Bash +# edit the path +"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f" +# prepare to type a quoted word -- +# insert open and close double quotes +# and move to just after the open quote +"\C-x\"": "\"\"\C-b" +# insert a backslash (testing backslash escapes +# in sequences and macros) +"\C-x\\": "\\" +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +# Add a binding to refresh the line, which is unbound +"\C-xr": redraw-current-line +# Edit variable on current line. +"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" +$endif + +# use a visible bell if one is available +set bell-style visible + +# don't strip characters to 7 bits when reading +set input-meta on + +# allow iso-latin1 characters to be inserted rather +# than converted to prefix-meta sequences +set convert-meta off + +# display characters with the eighth bit set directly +# rather than as meta-prefixed characters +set output-meta on + +# if there are 150 or more possible completions for a word, +# ask whether or not the user wants to see all of them +set completion-query-items 150 + +# For FTP +$if Ftp +"\C-xg": "get \M-?" +"\C-xt": "put \M-?" +"\M-.": yank-last-arg +$endif +@end example + +@node Bindable Readline Commands +@section Bindable Readline Commands + +@menu +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. +@end menu + +This section describes Readline commands that may be bound to key +sequences. +@ifset BashFeatures +You can list your key bindings by executing +@w{@code{bind -P}} or, for a more terse format, suitable for an +@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.) +@end ifset +Command names without an accompanying key sequence are unbound by default. + +In the following descriptions, @dfn{point} refers to the current cursor +position, and @dfn{mark} refers to a cursor position saved by the +@code{set-mark} command. +The text between the point and mark is referred to as the @dfn{region}. + +@node Commands For Moving +@subsection Commands For Moving +@ftable @code +@item beginning-of-line (C-a) +Move to the start of the current line. + +@item end-of-line (C-e) +Move to the end of the line. + +@item forward-char (C-f) +Move forward a character. + +@item backward-char (C-b) +Move back a character. + +@item forward-word (M-f) +Move forward to the end of the next word. +Words are composed of letters and digits. + +@item backward-word (M-b) +Move back to the start of the current or previous word. +Words are composed of letters and digits. + +@ifset BashFeatures +@item shell-forward-word (M-C-f) +Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. + +@item shell-backward-word (M-C-b) +Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +@end ifset + +@item previous-screen-line () +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. + +@item next-screen-line () +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if the length +of the current Readline line is not greater than the length of the prompt +plus the screen width. + +@item clear-display (M-C-l) +Clear the screen and, if possible, the terminal's scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. + +@item clear-screen (C-l) +Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. + +@item redraw-current-line () +Refresh the current line. By default, this is unbound. + +@end ftable + +@node Commands For History +@subsection Commands For Manipulating The History + +@ftable @code +@item accept-line (Newline or Return) +@ifset BashFeatures +Accept the line regardless of where the cursor is. +If this line is +non-empty, add it to the history list according to the setting of +the @env{HISTCONTROL} and @env{HISTIGNORE} variables. +If this line is a modified history line, then restore the history line +to its original state. +@end ifset +@ifclear BashFeatures +Accept the line regardless of where the cursor is. +If this line is +non-empty, it may be added to the history list for future recall with +@code{add_history()}. +If this line is a modified history line, the history line is restored +to its original state. +@end ifclear + +@item previous-history (C-p) +Move `back' through the history list, fetching the previous command. + +@item next-history (C-n) +Move `forward' through the history list, fetching the next command. + +@item beginning-of-history (M-<) +Move to the first line in the history. + +@item end-of-history (M->) +Move to the end of the input history, i.e., the line currently +being entered. + +@item reverse-search-history (C-r) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. + +@item forward-search-history (C-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. + +@item non-incremental-reverse-search-history (M-p) +Search backward starting at the current line and moving `up' +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. + +@item non-incremental-forward-search-history (M-n) +Search forward starting at the current line and moving `down' +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. + +@item history-search-forward () +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-search-backward () +Search backward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-substring-search-forward () +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-substring-search-backward () +Search backward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item yank-nth-arg (M-C-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument @var{n}, +insert the @var{n}th word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the @var{n}th word from the end of the previous command. +Once the argument @var{n} is computed, the argument is extracted +as if the @samp{!@var{n}} history expansion had been specified. + +@item yank-last-arg (M-. or M-_) +Insert last argument to the previous command (the last word of the +previous history entry). +With a numeric argument, behave exactly like @code{yank-nth-arg}. +Successive calls to @code{yank-last-arg} move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last argument, +as if the @samp{!$} history expansion had been specified. + +@item operate-and-get-next (C-o) +Accept the current line for return to the calling application as if a +newline had been entered, +and fetch the next line relative to the current line from the history +for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. + +@item fetch-history () +With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. + +@end ftable + +@node Commands For Text +@subsection Commands For Changing Text + +@ftable @code + +@item @i{end-of-file} (usually C-d) +The character indicating end-of-file as set, for example, by +@code{stty}. If this character is read when there are no characters +on the line, and point is at the beginning of the line, Readline +interprets it as the end of input and returns @sc{eof}. + +@item delete-char (C-d) +Delete the character at point. If this function is bound to the +same character as the tty @sc{eof} character, as @kbd{C-d} +commonly is, see above for the effects. + +@item backward-delete-char (Rubout) +Delete the character behind the cursor. A numeric argument means +to kill the characters instead of deleting them. + +@item forward-backward-delete-char () +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. By default, this is not bound to a key. + +@item quoted-insert (C-q or C-v) +Add the next character typed to the line verbatim. This is +how to insert key sequences like @kbd{C-q}, for example. + +@ifclear BashFeatures +@item tab-insert (M-@key{TAB}) +Insert a tab character. +@end ifclear + +@item self-insert (a, b, A, 1, !, @dots{}) +Insert yourself. + +@item bracketed-paste-begin () +This function is intended to be bound to the "bracketed paste" escape +sequence sent by some terminals, and such a binding is assigned by default. +It allows Readline to insert the pasted text as a single unit without treating +each character as if it had been read from the keyboard. The characters +are inserted as if each one was bound to @code{self-insert} instead of +executing any editing commands. + +Bracketed paste sets the region (the characters between point and the mark) +to the inserted text. It uses the concept of an @emph{active mark}: when the +mark is active, Readline redisplay uses the terminal's standout mode to +denote the region. + +@item transpose-chars (C-t) +Drag the character before the cursor forward over +the character at the cursor, moving the +cursor forward as well. If the insertion point +is at the end of the line, then this +transposes the last two characters of the line. +Negative arguments have no effect. + +@item transpose-words (M-t) +Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. + +@item upcase-word (M-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move the cursor. + +@item downcase-word (M-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move the cursor. + +@item capitalize-word (M-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move the cursor. + +@item overwrite-mode () +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +@code{emacs} mode; @code{vi} mode does overwrite differently. +Each call to @code{readline()} starts in insert mode. + +In overwrite mode, characters bound to @code{self-insert} replace +the text at point rather than pushing the text to the right. +Characters bound to @code{backward-delete-char} replace the character +before point with a space. + +By default, this command is unbound. + +@end ftable + +@node Commands For Killing +@subsection Killing And Yanking + +@ftable @code + +@item kill-line (C-k) +Kill the text from point to the end of the line. +With a negative numeric argument, kill backward from the cursor to the +beginning of the current line. + +@item backward-kill-line (C-x Rubout) +Kill backward from the cursor to the beginning of the current line. +With a negative numeric argument, kill forward from the cursor to the +end of the current line. + +@item unix-line-discard (C-u) +Kill backward from the cursor to the beginning of the current line. + +@item kill-whole-line () +Kill all characters on the current line, no matter where point is. +By default, this is unbound. + +@item kill-word (M-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as @code{forward-word}. + +@item backward-kill-word (M-@key{DEL}) +Kill the word behind point. +Word boundaries are the same as @code{backward-word}. + +@ifset BashFeatures +@item shell-kill-word (M-C-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as @code{shell-forward-word}. + +@item shell-backward-kill-word () +Kill the word behind point. +Word boundaries are the same as @code{shell-backward-word}. +@end ifset + +@item shell-transpose-words (M-C-t) +Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. +Word boundaries are the same as @code{shell-forward-word} and +@code{shell-backward-word}. + +@item unix-word-rubout (C-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. + +@item unix-filename-rubout () +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. + +@item delete-horizontal-space () +Delete all spaces and tabs around point. By default, this is unbound. + +@item kill-region () +Kill the text in the current region. +By default, this command is unbound. + +@item copy-region-as-kill () +Copy the text in the region to the kill buffer, so it can be yanked +right away. By default, this command is unbound. + +@item copy-backward-word () +Copy the word before point to the kill buffer. +The word boundaries are the same as @code{backward-word}. +By default, this command is unbound. + +@item copy-forward-word () +Copy the word following point to the kill buffer. +The word boundaries are the same as @code{forward-word}. +By default, this command is unbound. + +@item yank (C-y) +Yank the top of the kill ring into the buffer at point. + +@item yank-pop (M-y) +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is @code{yank} or @code{yank-pop}. +@end ftable + +@node Numeric Arguments +@subsection Specifying Numeric Arguments +@ftable @code + +@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--}) +Add this digit to the argument already accumulating, or start a new +argument. @kbd{M--} starts a negative argument. + +@item universal-argument () +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing @code{universal-argument} +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit nor minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +By default, this is not bound to a key. +@end ftable + +@node Commands For Completion +@subsection Letting Readline Type For You + +@ftable @code +@item complete (@key{TAB}) +Attempt to perform completion on the text before point. +The actual completion performed is application-specific. +@ifset BashFeatures +Bash attempts completion treating the text as a variable (if the +text begins with @samp{$}), username (if the text begins with +@samp{~}), hostname (if the text begins with @samp{@@}), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +@end ifset +@ifclear BashFeatures +The default is filename completion. +@end ifclear + +@item possible-completions (M-?) +List the possible completions of the text before point. +When displaying completions, Readline sets the number of columns used +for display to the value of @code{completion-display-width}, the value of +the environment variable @env{COLUMNS}, or the screen width, in that order. + +@item insert-completions (M-*) +Insert all completions of the text before point that would have +been generated by @code{possible-completions}. + +@item menu-complete () +Similar to @code{complete}, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of @code{menu-complete} steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of @code{bell-style}) +and the original text is restored. +An argument of @var{n} moves @var{n} positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to @key{TAB}, but is unbound +by default. + +@item menu-complete-backward () +Identical to @code{menu-complete}, but moves backward through the list +of possible completions, as if @code{menu-complete} had been given a +negative argument. + +@item delete-char-or-list () +Deletes the character under the cursor if not at the beginning or +end of the line (like @code{delete-char}). +If at the end of the line, behaves identically to +@code{possible-completions}. +This command is unbound by default. + +@ifset BashFeatures +@item complete-filename (M-/) +Attempt filename completion on the text before point. + +@item possible-filename-completions (C-x /) +List the possible completions of the text before point, +treating it as a filename. + +@item complete-username (M-~) +Attempt completion on the text before point, treating +it as a username. + +@item possible-username-completions (C-x ~) +List the possible completions of the text before point, +treating it as a username. + +@item complete-variable (M-$) +Attempt completion on the text before point, treating +it as a shell variable. + +@item possible-variable-completions (C-x $) +List the possible completions of the text before point, +treating it as a shell variable. + +@item complete-hostname (M-@@) +Attempt completion on the text before point, treating +it as a hostname. + +@item possible-hostname-completions (C-x @@) +List the possible completions of the text before point, +treating it as a hostname. + +@item complete-command (M-!) +Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, shell builtins, and finally executable filenames, +in that order. + +@item possible-command-completions (C-x !) +List the possible completions of the text before point, +treating it as a command name. + +@item dynamic-complete-history (M-@key{TAB}) +Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. + +@item dabbrev-expand () +Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. + +@item complete-into-braces (M-@{) +Perform filename completion and insert the list of possible completions +enclosed within braces so the list is available to the shell +(@pxref{Brace Expansion}). + +@end ifset +@end ftable + +@node Keyboard Macros +@subsection Keyboard Macros +@ftable @code + +@item start-kbd-macro (C-x () +Begin saving the characters typed into the current keyboard macro. + +@item end-kbd-macro (C-x )) +Stop saving the characters typed into the current keyboard macro +and save the definition. + +@item call-last-kbd-macro (C-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. + +@item print-last-kbd-macro () +Print the last keyboard macro defined in a format suitable for the +@var{inputrc} file. + +@end ftable + +@node Miscellaneous Commands +@subsection Some Miscellaneous Commands +@ftable @code + +@item re-read-init-file (C-x C-r) +Read in the contents of the @var{inputrc} file, and incorporate +any bindings or variable assignments found there. + +@item abort (C-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +@code{bell-style}). + +@item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{}) +If the metafied character @var{x} is upper case, run the command +that is bound to the corresponding metafied lower case character. +The behavior is undefined if @var{x} is already lower case. + +@item prefix-meta (@key{ESC}) +Metafy the next character typed. This is for keyboards +without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing +@kbd{M-f}. + +@item undo (C-_ or C-x C-u) +Incremental undo, separately remembered for each line. + +@item revert-line (M-r) +Undo all changes made to this line. This is like executing the @code{undo} +command enough times to get back to the beginning. + +@ifset BashFeatures +@item tilde-expand (M-&) +@end ifset +@ifclear BashFeatures +@item tilde-expand (M-~) +@end ifclear +Perform tilde expansion on the current word. + +@item set-mark (C-@@) +Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. + +@item exchange-point-and-mark (C-x C-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. + +@item character-search (C-]) +A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. + +@item character-search-backward (M-C-]) +A character is read and point is moved to the previous occurrence +of that character. A negative argument searches for subsequent +occurrences. + +@item skip-csi-sequence () +Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a Readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC-[. + +@item insert-comment (M-#) +Without a numeric argument, the value of the @code{comment-begin} +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of @code{comment-begin}, the value is inserted, otherwise +the characters in @code{comment-begin} are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +@ifset BashFeatures +The default value of @code{comment-begin} causes this command +to make the current line a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +@end ifset + +@item dump-functions () +Print all of the functions and their key bindings to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@item dump-variables () +Print all of the settable variables and their values to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@item dump-macros () +Print all of the Readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@ifset BashFeatures +@item spell-correct-word (C-x s) +Perform spelling correction on the current word, treating it as a directory +or filename, in the same way as the @code{cdspell} shell option. +Word boundaries are the same as those used by @code{shell-forward-word}. + +@item glob-complete-word (M-g) +The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching file names for possible completions. + +@item glob-expand-word (C-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching file names is inserted, replacing the word. +If a numeric argument is supplied, a @samp{*} is appended before +pathname expansion. + +@item glob-list-expansions (C-x g) +The list of expansions that would have been generated by +@code{glob-expand-word} is displayed, and the line is redrawn. +If a numeric argument is supplied, a @samp{*} is appended before +pathname expansion. + +@item display-shell-version (C-x C-v) +Display version information about the current instance of Bash. + +@item shell-expand-line (M-C-e) +Expand the line as the shell does. +This performs alias and history expansion as well as all of the shell +word expansions (@pxref{Shell Expansions}). + +@item history-expand-line (M-^) +Perform history expansion on the current line. + +@item magic-space () +Perform history expansion on the current line and insert a space +(@pxref{History Interaction}). + +@item alias-expand-line () +Perform alias expansion on the current line (@pxref{Aliases}). + +@item history-and-alias-expand-line () +Perform history and alias expansion on the current line. + +@item insert-last-argument (M-. or M-_) +A synonym for @code{yank-last-arg}. + +@item edit-and-execute-command (C-x C-e) +Invoke an editor on the current command line, and execute the result as shell +commands. +Bash attempts to invoke +@code{$VISUAL}, @code{$EDITOR}, and @code{emacs} +as the editor, in that order. + +@end ifset + +@ifclear BashFeatures +@item emacs-editing-mode (C-e) +When in @code{vi} command mode, this causes a switch to @code{emacs} +editing mode. + +@item vi-editing-mode (M-C-j) +When in @code{emacs} editing mode, this causes a switch to @code{vi} +editing mode. + +@end ifclear + +@end ftable + +@node Readline vi Mode +@section Readline vi Mode + +While the Readline library does not have a full set of @code{vi} +editing functions, it does contain enough to allow simple editing +of the line. The Readline @code{vi} mode behaves as specified in +the @sc{posix} standard. + +@ifset BashFeatures +In order to switch interactively between @code{emacs} and @code{vi} +editing modes, use the @samp{set -o emacs} and @samp{set -o vi} +commands (@pxref{The Set Builtin}). +@end ifset +@ifclear BashFeatures +In order to switch interactively between @code{emacs} and @code{vi} +editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode +when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode). +@end ifclear +The Readline default is @code{emacs} mode. + +When you enter a line in @code{vi} mode, you are already placed in +`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC} +switches you into `command' mode, where you can edit the text of the +line with the standard @code{vi} movement keys, move to previous +history lines with @samp{k} and subsequent lines with @samp{j}, and +so forth. + +@ifset BashFeatures +@node Programmable Completion +@section Programmable Completion +@cindex programmable completion + +When word completion is attempted for an argument to a command for +which a completion specification (a @var{compspec}) has been defined +using the @code{complete} builtin (@pxref{Programmable Completion Builtins}), +the programmable completion facilities are invoked. + +First, the command name is identified. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is the empty string (completion attempted at the +beginning of an empty line), any compspec defined with +the @option{-E} option to @code{complete} is used. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +If those searches do not result in a compspec, any compspec defined with +the @option{-D} option to @code{complete} is used as the default. +If there is no default compspec, Bash attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion + +Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default Bash completion +described above (@pxref{Commands For Completion}) is performed. + +First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the @option{-f} or @option{-d} option is used for filename or +directory name completion, the shell variable @env{FIGNORE} is +used to filter the matches. +@xref{Bash Variables}, for a description of @env{FIGNORE}. + +Any completions specified by a filename expansion pattern to the +@option{-G} option are generated next. +The words generated by the pattern need not match the word being completed. +The @env{GLOBIGNORE} shell variable is not used to filter the matches, +but the @env{FIGNORE} shell variable is used. + +Next, the string specified as the argument to the @option{-W} option +is considered. +The string is first split using the characters in the @env{IFS} +special variable as delimiters. +Shell quoting is honored within the string, in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of @env{IFS}. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above (@pxref{Shell Expansions}). +The results are split using the rules described above +(@pxref{Word Splitting}). +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. + +After these matches have been generated, any shell function or command +specified with the @option{-F} and @option{-C} options is invoked. +When the command or function is invoked, the @env{COMP_LINE}, +@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are +assigned values as described above (@pxref{Bash Variables}). +If a shell function is being invoked, the @env{COMP_WORDS} and +@env{COMP_CWORD} variables are also set. +When the function or command is invoked, the first argument ($1) is the +name of the command whose arguments are being completed, the +second argument ($2) is the word being completed, and the third argument +($3) is the word preceding the word being completed on the current command +line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. + +Any function specified with @option{-F} is invoked first. +The function may use any of the shell facilities, including the +@code{compgen} and @code{compopt} builtins described below +(@pxref{Programmable Completion Builtins}), to generate the matches. +It must put the possible completions in the @env{COMPREPLY} array +variable, one per array element. + +Next, any command specified with the @option{-C} option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to +the standard output. +Backslash may be used to escape a newline, if necessary. + +After all of the possible completions are generated, any filter +specified with the @option{-X} option is applied to the list. +The filter is a pattern as used for pathname expansion; a @samp{&} +in the pattern is replaced with the text of the word being completed. +A literal @samp{&} may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading @samp{!} negates the pattern; in this case any completion +not matching the pattern will be removed. +If the @code{nocasematch} shell option +(see the description of @code{shopt} in @ref{The Shopt Builtin}) +is enabled, the match is performed without regard to the case +of alphabetic characters. + +Finally, any prefix and suffix specified with the @option{-P} and @option{-S} +options are added to each member of the completion list, and the result is +returned to the Readline completion code as the list of possible +completions. + +If the previously-applied actions do not generate any matches, and the +@option{-o dirnames} option was supplied to @code{complete} when the +compspec was defined, directory name completion is attempted. + +If the @option{-o plusdirs} option was supplied to @code{complete} when +the compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. + +By default, if a compspec is found, whatever it generates is returned to +the completion code as the full set of possible completions. +The default Bash completions are not attempted, and the Readline default +of filename completion is disabled. +If the @option{-o bashdefault} option was supplied to @code{complete} when +the compspec was defined, the default Bash completions are attempted +if the compspec generates no matches. +If the @option{-o default} option was supplied to @code{complete} when the +compspec was defined, Readline's default completion will be performed +if the compspec (and, if attempted, the default Bash completions) +generate no matches. + +When a compspec indicates that directory name completion is desired, +the programmable completion functions force Readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the @var{mark-directories} Readline variable, regardless +of the setting of the @var{mark-symlinked-directories} Readline variable. + +There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with @option{-D}. It's possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes +the compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is executed), +programmable completion restarts from the beginning, with an +attempt to find a new compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather than +being loaded all at once. + +For instance, assuming that there is a library of compspecs, each kept in a +file corresponding to the name of the command, the following default +completion function would load completions dynamically: + +@example +_completion_loader() +@{ + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 +@} +complete -D -F _completion_loader -o bashdefault -o default +@end example + +@node Programmable Completion Builtins +@section Programmable Completion Builtins +@cindex completion builtins + +Three builtin commands are available to manipulate the programmable completion +facilities: one to specify how the arguments to a particular command are to +be completed, and two to modify the completion as it is happening. + +@table @code +@item compgen +@btindex compgen +@example +@code{compgen [@var{option}] [@var{word}]} +@end example + +Generate possible completion matches for @var{word} according to +the @var{option}s, which may be any option accepted by the +@code{complete} +builtin with the exception of @option{-p} and @option{-r}, and write +the matches to the standard output. +When using the @option{-F} or @option{-C} options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. + +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If @var{word} is specified, only those completions matching @var{word} +will be displayed. + +The return value is true unless an invalid option is supplied, or no +matches were generated. + +@item complete +@btindex complete +@example +@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-A @var{action}] [-G @var{globpat}] +[-W @var{wordlist}] [-F @var{function}] [-C @var{command}] [-X @var{filterpat}] +[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]} +@code{complete -pr [-DEI] [@var{name} @dots{}]} +@end example + +Specify how arguments to each @var{name} should be completed. +If the @option{-p} option is supplied, or if no options are supplied, existing +completion specifications are printed in a way that allows them to be +reused as input. +The @option{-r} option removes a completion specification for +each @var{name}, or, if no @var{name}s are supplied, all +completion specifications. +The @option{-D} option indicates that other supplied options and actions should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The @option{-E} option indicates that other supplied options and actions should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The @option{-I} option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I}. +If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other +@var{name} arguments are ignored; these completions only apply to the case +specified by the option. + +The process of applying these completion specifications when word completion +is attempted is described above (@pxref{Programmable Completion}). + +Other options, if specified, have the following meanings. +The arguments to the @option{-G}, @option{-W}, and @option{-X} options +(and, if necessary, the @option{-P} and @option{-S} options) +should be quoted to protect them from expansion before the +@code{complete} builtin is invoked. + + +@table @code +@item -o @var{comp-option} +The @var{comp-option} controls several aspects of the compspec's behavior +beyond the simple generation of completions. +@var{comp-option} may be one of: + +@table @code + +@item bashdefault +Perform the rest of the default Bash completions if the compspec +generates no matches. + +@item default +Use Readline's default filename completion if the compspec generates +no matches. + +@item dirnames +Perform directory name completion if the compspec generates no matches. + +@item filenames +Tell Readline that the compspec generates filenames, so it can perform any +filename-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +This option is intended to be used with shell functions specified +with @option{-F}. + +@item noquote +Tell Readline not to quote the completed words if they are filenames +(quoting filenames is the default). + +@item nosort +Tell Readline not to sort the list of possible completions alphabetically. + +@item nospace +Tell Readline not to append a space (the default) to words completed at +the end of the line. + +@item plusdirs +After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. + +@end table + +@item -A @var{action} +The @var{action} may be one of the following to generate a list of possible +completions: + +@table @code +@item alias +Alias names. May also be specified as @option{-a}. + +@item arrayvar +Array variable names. + +@item binding +Readline key binding names (@pxref{Bindable Readline Commands}). + +@item builtin +Names of shell builtin commands. May also be specified as @option{-b}. + +@item command +Command names. May also be specified as @option{-c}. + +@item directory +Directory names. May also be specified as @option{-d}. + +@item disabled +Names of disabled shell builtins. + +@item enabled +Names of enabled shell builtins. + +@item export +Names of exported shell variables. May also be specified as @option{-e}. + +@item file +File names. May also be specified as @option{-f}. + +@item function +Names of shell functions. + +@item group +Group names. May also be specified as @option{-g}. + +@item helptopic +Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}). + +@item hostname +Hostnames, as taken from the file specified by the +@env{HOSTFILE} shell variable (@pxref{Bash Variables}). + +@item job +Job names, if job control is active. May also be specified as @option{-j}. + +@item keyword +Shell reserved words. May also be specified as @option{-k}. + +@item running +Names of running jobs, if job control is active. + +@item service +Service names. May also be specified as @option{-s}. + +@item setopt +Valid arguments for the @option{-o} option to the @code{set} builtin +(@pxref{The Set Builtin}). + +@item shopt +Shell option names as accepted by the @code{shopt} builtin +(@pxref{Bash Builtins}). + +@item signal +Signal names. + +@item stopped +Names of stopped jobs, if job control is active. + +@item user +User names. May also be specified as @option{-u}. + +@item variable +Names of all shell variables. May also be specified as @option{-v}. +@end table + +@item -C @var{command} +@var{command} is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the @option{-F} option. + +@item -F @var{function} +The shell function @var{function} is executed in the current shell +environment. +When it is executed, $1 is the name of the command whose arguments are +being completed, $2 is the word being completed, and $3 is the word +preceding the word being completed, as described above +(@pxref{Programmable Completion}). +When it finishes, the possible completions are retrieved from the value +of the @env{COMPREPLY} array variable. + +@item -G @var{globpat} +The filename expansion pattern @var{globpat} is expanded to generate +the possible completions. + +@item -P @var{prefix} +@var{prefix} is added at the beginning of each possible completion +after all other options have been applied. + +@item -S @var{suffix} +@var{suffix} is appended to each possible completion +after all other options have been applied. + +@item -W @var{wordlist} +The @var{wordlist} is split using the characters in the +@env{IFS} special variable as delimiters, and each resultant word +is expanded. +The possible completions are the members of the resultant list which +match the word being completed. + +@item -X @var{filterpat} +@var{filterpat} is a pattern as used for filename expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +@var{filterpat} is removed from the list. +A leading @samp{!} in @var{filterpat} negates the pattern; in this +case, any completion not matching @var{filterpat} is removed. +@end table + +The return value is true unless an invalid option is supplied, an option +other than @option{-p} or @option{-r} is supplied without a @var{name} +argument, an attempt is made to remove a completion specification for +a @var{name} for which no specification exists, or +an error occurs adding a completion specification. + +@item compopt +@btindex compopt +@example +@code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}] +@end example +Modify completion options for each @var{name} according to the +@var{option}s, or for the currently-executing completion if no @var{name}s +are supplied. +If no @var{option}s are given, display the completion options for each +@var{name} or the current completion. +The possible values of @var{option} are those valid for the @code{complete} +builtin described above. +The @option{-D} option indicates that other supplied options should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The @option{-E} option indicates that other supplied options should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The @option{-I} option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. + +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I} + +The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a @var{name} for which no completion +specification exists, or an output error occurs. + +@end table + +@node A Programmable Completion Example +@section A Programmable Completion Example + +The most common way to obtain additional completion functionality beyond +the default actions @code{complete} and @code{compgen} provide is to use +a shell function and bind it to a particular command using @code{complete -F}. + +The following function provides completions for the @code{cd} builtin. +It is a reasonably good example of what shell functions must do when +used for completion. This function uses the word passed as @code{$2} +to determine the directory name to complete. You can also use the +@code{COMP_WORDS} array variable; the current word is indexed by the +@code{COMP_CWORD} variable. + +The function relies on the @code{complete} and @code{compgen} builtins +to do much of the work, adding only the things that the Bash @code{cd} +does beyond accepting basic directory names: +tilde expansion (@pxref{Tilde Expansion}), +searching directories in @var{$CDPATH}, which is described above +(@pxref{Bourne Shell Builtins}), +and basic support for the @code{cdable_vars} shell option +(@pxref{The Shopt Builtin}). +@code{_comp_cd} modifies the value of @var{IFS} so that it contains only +a newline to accommodate file names containing spaces and tabs -- +@code{compgen} prints the possible completions it generates one per line. + +Possible completions go into the @var{COMPREPLY} array variable, one +completion per array element. The programmable completion system retrieves +the completions from there when the function returns. + +@example +# A completion function for the cd builtin +# based on the cd completion function from the bash_completion package +_comp_cd() +@{ + local IFS=$' \t\n' # normalize IFS + local cur _skipdot _cdpath + local i j k + + # Tilde expansion, which also expands tilde to full pathname + case "$2" in + \~*) eval cur="$2" ;; + *) cur=$2 ;; + esac + + # no cdpath or absolute pathname -- straight directory completion + if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then + # compgen prints paths one per line; could also use while loop + IFS=$'\n' + COMPREPLY=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + # CDPATH+directories in the current directory if not in CDPATH + else + IFS=$'\n' + _skipdot=false + # preprocess CDPATH to convert null directory names to . + _cdpath=$@{CDPATH/#:/.:@} + _cdpath=$@{_cdpath//::/:.:@} + _cdpath=$@{_cdpath/%:/:.@} + for i in $@{_cdpath//:/$'\n'@}; do + if [[ $i -ef . ]]; then _skipdot=true; fi + k="$@{#COMPREPLY[@@]@}" + for j in $( compgen -d -- "$i/$cur" ); do + COMPREPLY[k++]=$@{j#$i/@} # cut off directory + done + done + $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + fi + + # variable names if appropriate shell option set and no completions + if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then + COMPREPLY=( $(compgen -v -- "$cur") ) + fi + + return 0 +@} +@end example + +We install the completion function using the @option{-F} option to +@code{complete}: + +@example +# Tell readline to quote appropriate and append slashes to directories; +# use the bash default completion for other arguments +complete -o filenames -o nospace -o bashdefault -F _comp_cd cd +@end example + +@noindent +Since we'd like Bash and Readline to take care of some +of the other details for us, we use several other options to tell Bash +and Readline what to do. The @option{-o filenames} option tells Readline +that the possible completions should be treated as filenames, and quoted +appropriately. That option will also cause Readline to append a slash to +filenames it can determine are directories (which is why we might want to +extend @code{_comp_cd} to append a slash if we're using directories found +via @var{CDPATH}: Readline can't tell those completions are directories). +The @option{-o nospace} option tells Readline to not append a space +character to the directory name, in case we want to append to it. +The @option{-o bashdefault} option brings in the rest of the "Bash default" +completions -- possible completions that Bash adds to the default Readline +set. These include things like command name completion, variable completion +for words beginning with @samp{$} or @samp{$@{}, completions containing pathname +expansion patterns (@pxref{Filename Expansion}), and so on. + +Once installed using @code{complete}, @code{_comp_cd} will be called every +time we attempt word completion for a @code{cd} command. + +Many more examples -- an extensive collection of completions for most of +the common GNU, Unix, and Linux commands -- are available as part of the +bash_completion project. This is installed by default on many GNU/Linux +distributions. Originally written by Ian Macdonald, the project now lives +at @url{https://github.com/scop/bash-completion/}. There are ports for +other systems such as Solaris and Mac OS X. + +An older version of the bash_completion package is distributed with bash +in the @file{examples/complete} subdirectory. + +@end ifset diff --git a/lib/readline/doc/rluserman.texi b/lib/readline/doc/rluserman.texi new file mode 100644 index 0000000..ae9ec6e --- /dev/null +++ b/lib/readline/doc/rluserman.texi @@ -0,0 +1,70 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rluserman.info +@settitle GNU Readline Library +@include version.texi + +@comment %**end of header (This is for running Texinfo on a region.) + +@copying +This manual describes the end user interface of the GNU Readline Library +(version @value{VERSION}, @value{UPDATED}), a library which aids in the +consistency of user interface across discrete programs which provide +a command line interface. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* RLuserman: (rluserman). The GNU readline library User's Manual. +@end direntry + +@titlepage +@title GNU Readline Library User Interface +@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Readline Library + +This document describes the end user interface of the GNU Readline Library, +a utility which aids in the consistency of user interface across discrete +programs which provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. + +@menu +* Command Line Editing:: GNU Readline User's Manual. +* GNU Free Documentation License:: License for copying this manual. +@end menu +@end ifnottex + +@include rluser.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@bye diff --git a/lib/readline/doc/version.texi b/lib/readline/doc/version.texi new file mode 100644 index 0000000..d310273 --- /dev/null +++ b/lib/readline/doc/version.texi @@ -0,0 +1,11 @@ +@ignore +Copyright (C) 1988-2022 Free Software Foundation, Inc. +@end ignore + +@set EDITION 8.2 +@set VERSION 8.2 + +@set UPDATED 19 September 2022 +@set UPDATED-MONTH September 2022 + +@set LASTCHANGE Mon Sep 19 11:15:16 EDT 2022 |