Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
tclreadline(n)							tclreadline(n)

       tclreadline - gnu readline for the tcl scripting	language

       ::tclreadline::readline command [options]

       The tclreadline package makes the gnu readline available	to the script-
       ing language tcl. The primary purpose of	the package is	to  facilitate
       the  interactive	 script	development by the means of word and file name
       completion as well as history expansion (well known  from  shells  like

       Additionally tclreadline	can also be used for tcl scripts which want to
       use a shell like	input interface. In this case the ::tclreadline::read-
       line read command has to	be called explicitly.

       The advantage of	tclreadline is that it uses the	callback handler mech-
       anism of	the gnu	readline while it processes tcl	 events.  This	way  X
       events  from  a	wish  gui will be processed as well as events from the
       tclreadline line	interface.

       tclreadline is basically	a shared library and a few tcl	scripts	 which
       are  accessed  with the tcl package require command. Therefore tclread-
       line should work	with all common	extensions like	blt,  itcl,  itk,  tix

       If  you	want to	use tclreadline	as a line interface for	developing tcl
       scripts,	you probably don't have	to read	this section. In this case the
       only  thing  you	 should	do is to modify	your .tclshrc according	to the
       section FILES.

       For the functionality of	the GNU	readline you should refer to the read-
       line's documentation.

       The  following  list will give all commands, which are currently	imple-
       mented in the shared  lib  (e.g.   Additional
       commands	 were  introduced  in  a  startup script tclreadlineSetup.tcl,
       which lives in  the  tclreadline	 installation  directory.   (typically
       something  like /usr/local/lib/tclreadline ..)  These commands are pri-
       marily for internal use and not documented here.

       Note that all commands reside in	the namespace ::tclreadline::.

       ::tclreadline::readline add string
	    adds a string to the completer. If the string contains white  spa-
	    ces,  each	of the words will be completed consecutively when hit-
	    ting <Tab>.	Example:

		::tclreadline::readline	add "button pathName ?options?"

	    typing but<Tab> will complete to button. Hitting <Tab> again  will
	    complete to	"button	pathName".  ...

       ::tclreadline::readline complete	string
	    returns 1 if string	is a complete tcl command and 0	otherwise.

       ::tclreadline::readline customcompleter [string]
	    Register  the proc string as custom	completer. This	proc is	called
	    with exactly four arguments	each time completion takes place:  the
	    word to complete ("text"), the "start" and "end" positions of this
	    word in the	line entered so	far, and this line ("line"). The  cus-
	    tom	completion script should return	an array of strings which is a
	    list of completions	for "text".  If	there are no  completions,  it
	    should return an empty string "".  The first entry in the returned
	    list is the	substitution for "text". The remaining entries are the
	    possible  completions.  If the custom completion script returns an
	    empty string and  builtin  completion  is  enabled	(see  tclread-
	    line::readline builtincompleter), the builtin completer is called.
	    tclreadline::readline customcompleter simply returns  the  current
	    custom  completer  if called w/o string. To	turn of	custom comple-
	    tion, call tclreadline::readline  customcompleter  with  an	 empty

	    Example:  %	 puts  $b<TAB> will call the custom completer with the
	    four arguments "$b", "5", "8" and "puts $b".  The custom completer
	    could return a string like "$bl $black $blue", which will complete
	    "$b" to "$bl" (the longest match) and offer	a list of two  further
	    matches "$black" and "$blue".

	    For	 further  reference, see the proc tclreadline::ScriptCompleter
	    in the file	tclreadlineSetup.tcl.

       ::tclreadline::readline builtincompleter	[bool]
	    enable or disable the builtin completer. If	the builtin  completer
	    is	enabled,  it will be invoked either if there is	no custom com-
	    pleter, or the custom completer returned  an  empty	  string.  The
	    builtin  completer is on by	default.  tclreadline::readline	built-
	    incompleter	returns	the current custom completer (also, if	called
	    w/o	the bool argument).

       ::tclreadline::readline eofchar [script]
	    set	 a  script  which  will	be called, if readline returns the eof
	    character (this is typically the case if CTRL-D is entered at  the
	    very  beginning of the line). The default for this script is "puts
	    {};	exit". Setting this to an empty	value disables any  action  on
	    eof.  tclreadline::readline	eof returns the	current	eof script.

       ::tclreadline::readline initialize historyfile
	    initialize the tclreadline interface and read the history from the
	    historyfile. On success an empty string is returned.  This command
	    has	to be called before any	other tclreadline commands.

       ::tclreadline::readline read prompt
	    prints the prompt to stdout	and enters the tclreadline event loop.
	    Both readline and X	events are processed. Returns the  (eventually
	    history-expanded)  input string.  tclreadline::readline read rises
	    an error, if an error occurs while evaluating a script completer.

       ::tclreadline::readline write historyfile
	    writes the history to the historyfile. This	command	is called  au-
	    tomatically	from the internal routine ::tclreadline::Exit.	If the
	    variable tclreadline::historyLength	is non-negative, the  history-
	    file will be truncated to hold only	this number lines.

       ::tclreadline::readline reset-terminal [terminalName]
	    w/o	 argument:  reset the state of the terminal to what it was be-
	    fore tclreadline was used. With argument: reinitialize  readline's
	    idea  of  the terminal settings using terminalName as the terminal
	    type.  The form w/o	argument might not  work  if  tclreadline  was
	    compiled with an older version of libreadline.

       ::tclreadline::readline bell
	    Ring the terminal bell, obeying the	setting	of bell-style -- audi-
	    ble	or visible.

	    Return the current input.

       ::tclreadline::readline update
	    Redraw the current input line.

       ::tclreadline::Print [yes / no]
	    turns on or	off the	default	behavior of tclsh to print the	result
	    of	every  command.	 This is turned	on by default, so it will just
	    behave as the tclsh	w/o tclreadline. Turning off might be  useful,
	    when  reading  binary data for example. If ::tclreadline::Print is
	    called w/o arguments, it returns the current setting.

       ::tclreadline::Loop [historyfile]
	    enter the tclreadline main loop. This command is typically	called
	    from  the  startup resource	file (something	.tclshrc, depending on
	    the	interpreter you	use, see the file `sample.tclshrc'). The  main
	    loop  sets	up  some completion characteristics as variable	-- try
	    something like "puts $b<TAB>" -- and  command  completion  --  try
	    "puts  [in<TAB>".	If the optional	argument historyfile is	given,
	    this file will be used for reading and writing the command history
	    instead  of	 the default .tclsh-history.  ::tclreadline::Loop will
	    normally not return.  If you want to  write	 your  own  main  loop
	    and/or  own	custom completers, it is probably a good idea to start
	    with tclreadline::Loop (see	the file tclreadlineSetup.tcl).

	    a proc which is called by ::tclreadline::Loop and returns a	string
	    which will be displayed as the primary prompt. This	prompt will be
	    something like "[info nameofexecutable] \[[pwd]\]" possibly	 fancy
	    colored.   The  default proc is defined on entering	the ::tclread-
	    line::Loop,	if it is not already defined. So: If you  define  your
	    own	  proc	 ::tclreadline::prompt1	  before  entering  ::tclread-
	    line::Loop,	this proc is called each time the prompt is to be dis-
	    played.  Example:
		package	require	tclreadline
		namespace eval tclreadline {
		    proc prompt1 {} {
			return "[clock format [clock seconds]]>	"

       Note  that non-printable	control	characters as color control characters
       must be enclosed	in literal ctrl-a / ctrl-b to tell readline the	length
       of  the	printable prompt. See for example the variable `prompt_string'
       in the file tclreadlineSetup.tcl	in your	tclreadline  installation  di-

	    a proc which is called by ::tclreadline::Loop and returns a	string
	    which will be displayed as the secondary prompt when interactively
	    prompting  for  continuation  of  an incomplete command.

       tclreadline defines the following variables in the namespace ::tclread-
       line:  (for  backwards  compatibility  the  global  variables  tclread-
	tclreadline_patchLevel and tclreadline_library are still present).

       tclreadline::version (read-only)
	    holds the version string "2.3.8".

       tclreadline::patchLevel (read-only)
	    holds the patch level string "2.3.8".

       tclreadline::library (read-only)
	    holds the library string "/usr/local/lib/tclreadline2.3.8".

       tclreadline::license (read-only)
	    holds a BSD	license	statement.

	    Number  of	lines, which will be written to	the historyfile.  This
	    number is -1 by default, which means that the historyfile will not
	    be truncated.  See also tclreadline::write.

       the  .tclshrc  file  in	the  HOME  directory,  which  is read on tclsh
       startup.	Alternatively, the name	of this	initialization file  might  be
       .wishrc	... depending on what interpreter you use.  These files	should
       typically contain something like
		  if {$tcl_interactive}	{
		      package require tclreadline

       which will enter	the tclreadline	main loop.

       the .tclsh-history file in the HOME directory. On startup commands will
       be  read	 from  this  file. On exit, the	readline history is written to
       this file. Note that if you abort tclsh with <cntrl-c>  no  history  is
       written.	For the	future it is planned to	set up a signal	handler, which
       will write the history on <ctrl-c> before exiting.

       the .inputrc file in the	users HOME directory. This file	is  used  nor-
       mally  for  all	programs which use the gnu readline (e.g.  bash).  The
       `global'	readline settings there	will be	valid  also  for  tclreadline.
       Additionally  the  .inputrc might hold conditional settings for the im-
       plementation name tclreadline. Example of some lines in your .inputrc:
		  $if tclreadline
		  "\C-xp": "puts $env(PATH)"

       For further documentation please	refer to the gnu  readline  documenta-

       citing the readline manual:  It's too big and too slow.

       The official tclreadline	web site at:

       Johannes	Zellner, <>

       Magnus Eriksson <>,	Les Johnson <les@info->,   Harald   Kirsch   <>,    Christian	 Krone
       <>,  Larry  W.  Virden  <>,  David	 Engel
       <>	<>,	  Matthew	Clarke

       David Engel <>, <>

       tclreadline  comes  with	 a  BSD	 type license.	The read-only variable
       tclreadline::license holds the complete license statement.

Johannes Zellner		     2.3.8			tclreadline(n)


Want to link to this manual page? Use this URL:

home | help