dgtools - argvparse - recover - repo - shistory
dgtools::shistory - a snit type history command.
package require dgtools::shistory
::dgtools::shistory cmd ?option value?
cmd back
cmd canBackward
cmd canForward
cmd canFirst
cmd canLast
cmd cget option
cmd configure option value
cmd current
cmd first
cmd forward
cmd getHistory
cmd home
cmd insert value
cmd last
cmd resetHistory
The shistory type is data structure to allow the storage of text strings in a history. this can be useful to store for instance a browser history or a move history in a board game like Chess or Go.
-home value
The value which is set as the home, it is stored in principle as the first item in the history. Defaults to an empty string.
The shistory type supports a few commands to navigate in a history list.
cmd back
Walks back in history one step and retrieves the value of the history at this position.
cmd canBackward
Returns true if the current position in history is not the first value in history and if the length of history is greater than 1.
cmd canFirst
Returns true if the current position in history is not the first value in history and if history length is greater than 1.
cmd canForward
Returns true if the current position in history is not the last value in history.
cmd canLast
Returns true if the current position in history is not the last value in history.
cmd cget option
Retrieves the given option value for the shistory type. Curently only the -home option is available for cget.
cmd configure option value ?option value ...?
Configures the given option for the shistory type. Curently only the -home option is available for configure.
cmd current
Retrieves the current value of the history.
cmd first
Jumps to the first entry in history and returns it.
cmd forward
Gos one step forward in history and returns the value there.
cmd getHistory
Returns the history, a list of text entries.
cmd insert value
Inserts the value in the history at the actual index.
cmd home
Returns the home index value which was set using the -home option.
cmd last
Jumps to the last value in history and returns the value there.
package require dgtools::shistory
set sh [::dgtools::shistory %AUTO% -home h]
$sh insert a
$sh insert a ;# should not give duplicates
$sh insert a
$sh insert b
puts "\ncanback: [$sh canBackward]"
puts "canforw: [$sh canForward]"
$sh back
$sh insert z
puts [$sh getHistory]
puts [$sh home]
puts "last: [$sh last]"
Installation is easy, you can install and use this dgtools::shistory package if you have a working install of the snit package which can be found in tcllib.
To use the dgtools::shistory package then, you can either sourc it within your Tcl-code:
source /path/to/dgtools/shistory.tcl, or by copying the folder dgtools to a path belonging to your Tcl $auto_path variable or by installing it as an Tcl-module.
To do this, make either yourself a copy of shistory.tcl to a file like shistory-0.1.tm and put this file into a folder named dgtools where the parent folder belongs to your module path.
You must eventually adapt your Tcl-module path by using in your Tcl code the command:
tcl::tm::path add /parent/dir/ of the dgtools directory.
For details of the latter consult see the manual page of tcl::tm.
Alternatively there is an install option you can use as well.
Try tclsh shistory.tcl --install which should perform the procedure described above automatically.
This requires eventually the setting of an environment variables if you have no write access to all
of your module paths. For instance on my computer I have the following entry in my .bashrc
export TCL8_6_TM_PATH=/home/groth/.local/lib/tcl8.6
If I execute tclsh shistory.tcl --install the file shistory.tcl will be copied to
/home/groth/.local/lib/tcl8.6/dgtools/shistory-0.1.tm and is thereafter available for a
package require dgtools::shistory.
The script contains embedded the documentation in Markdown format. To extract the documentation you should use the following command line:
$ tclsh shistory.tcl --man
The output of this command can be used to create a markdown document for conversion into a markdown document that can be converted thereafter into a html or pdf document. If, for instance, you have pandoc installed you could execute the following commands:
tclsh ../shistory.tcl --man > shistory.md
pandoc -i shistory.md -s -o shistory.html
pandoc -i shistory.md -s -o shistory.tex
pdflatex shistory.tex
The shistory snit type was written Detlef Groth, Schwielowsee, Germany.
Copyright (c) 2019-20 Dr. Detlef Groth, E-mail: detlef(at)dgroth(dot)de
dgtools:shistory package - data structure, a list of text entries which can be navigated as history, version 0.2.
Copyright (c) 2019-20 Dr. Detlef Groth, E-mail: detlef(at)dgroth(dot)de
This library is free software; you can use, modify, and redistribute it for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions.
This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.