tkrunner.1

.\" Copyright (c) 2020 Peter Piwowarski <peterjpiwowarski@gmail.com>
.\"
.\" Permission to use, copy, modify, and distribute this manual for any
.\" purpose with or without fee is hereby granted.
.\"
.\" THE MANUAL IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS MANUAL INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS MANUAL.
.Dd $Mdocdate$
.Dt TKRUNNER 1
.Os
.Sh NAME
.Nm tkrunner
.Nd run command dialog for X in Tcl/Tk
.Sh SYNOPSIS
.Nm tkrunner
.Op -quiet
.Sh DESCRIPTION
.Nm
displays a Run Command dialog box that accepts an extended
.Xr Tcl n
syntax.
It is intended to be invoked from an X startup file such as
.Pa ~/.xsession
or
.Pa ~/.xinitrc
in the background:
.Bd -literal -offset -indent
tkrunner -quiet &
.Ed
.Pp
and then bound to a keyboard shortcut in your window manager or desktop
environment.
When
.Nm
is first invoked, it displays its window
.Pq unless told otherwise with -quiet
but stays resident after it is destroyed.
Afterwards, when invoked again,
.Nm
will instruct the running instance to display its window again, using Tk's
.Xr send n
facility.
.Ss USAGE
The Run Command dialog accepts the full
.Xr Tcl n
syntax, with several extensions.
Specifically, the environment it provides differs from a clean, default Tcl
interpreter as follows:
.Bl -bullet
.It
The
.Xr http n
package is loaded.
.Po
It is used internally for URL processing.
.Pc
.It
The
.Sy trun
package is loaded, which provides the
.Sy ::trun
namespace
.Pq described below .
.It
The default
.Sy namespace path
contains the
.Xr mathop n
and
.Xr mathfunc n
namespaces, as well as
.Sy ::trun .
.It
The
.Sy ::trun
namespace itself provides several commands:
.Bl -tag -width 8
.It Cm 1glob Ar arg Op arg...
Identical to
.Xr glob n ,
but returns only the first element of the list of matches; useful for specifying
URLs.
.It Cm runcmd Ar arg Op arg...
Accepts the same pipeline syntax as
.Xr exec n
while automatically redirecting pipeline output to a temporary file, and
backgrounding the pipeline.
.It Cm openurl Ar url
Passes its
.Ar url
argument directly to
.Xr xdg-open 1
via runcmd.
.It Cm go Ar url
Alias to
.Sy openurl .
.El
.It
The
.Sy ::trun
namespace contains a child namespace called
.Sy shortcuts
that supplies implementations of the shortcuts described under
.Sx SHORTCUTS
as commands.
.It
The
.Sy namespace unknown
facility is used to implement syntactic sugar as follows:
.Bl -dash
.It
Command lines that appear to be valid URLs are passed to
.Sy openurl .
.It
Command lines that are valid, absolute paths to files that are not executable
are passed to
.Xr xdg-open 1
without a URL scheme, via
.Sy openurl .
.It
Command lines that are valid shortcut specifications are transformed into a Tcl
list with the portion before the first colon as the first element, and the
portion after the first colon as the second element; the result is then
evaluated in the
.Sy ::trun::shortcuts
namespace as a command.
The commandline
.Sq dd:tcl documentation
is therefore transformed to
.Sq dd {tcl documentation}
and evaluated.
.It
All other command lines are treated as
.Xr exec n
pipelines and passed to
.Sy runcmd .
.El
Any command that causes the unknown handler to be invoked also causes the dialog
to be hidden after a few seconds.
.It
The command
.Sy hide
is present in the root namespace, and causes the dialog box to hide itself.
.It
There exists a
.Sy ::Tkrunner
namespace, which should be treated as reserved by the
.Nm
implementation.
Its contents are deliberately undocumented and may change without notice for the
implementation's convenience.
.El
.Pp
Commands entered at the dialog box are evaluated and their results added to the
history display at the bottom of the dialog, preceded by a sequence number
indicating which command produced the results.
Any errors are also caught and indicated here.
The command itself is also added to the command history, which may be navigated
by pressing the Up and Down keys while the command entry widget has input focus.
The numeric indicator to the left of the command entry widget will update to
show which results in the output history it corresponds to.
.Pp
The execution environment provided by
.Nm
is a child
.Xr interp n
and therefore cannot directly introspect or mangle the main application's state,
but it does have full control over its own state, and the full Tcl language is
at its disposal.
.Ss SHORTCUTS
Shortcuts are inspired by the Web Shortcuts supported by
.Sy Konqueror
and
.Sy KRunner .
Shortcut specifications consist of a shortcut name and a shortcut query,
separated by a single colon, for example:
.Bd -literal -offset -indent
wp:Main Page
.Ed
.Pp
Running a shortcut generally results in a URL being opened in the user's default
application with
.Xr xdg-open 1 ,
but other behaviors are possible.
The currently implemented shortcuts are:
.Bl -tag -width 8
.It Cm amazon
Amazon.com search for the shortcut query.
.It Cm deb
Debian package search for the shortcut query.
.It Cm dd
DuckDuckGo search for the shortcut query.
.It Cm dman
Debian manpage search for the shortcut query, interpreted as for the
.Sy man
shortcut.
.It Cm ebay
eBay search for the shortcut query.
.It Cm gg
Google search for the shortcut query.
.It Cm man
Local manpage search.
The shortcut query is interpreted as a manual page
specifier in the typical name(section) format, and a lookup is performed with
.Xr man 1 ;
if the section is omitted, the section argument to
.Xr man 1
will be omitted.
All matching manual pages will be formatted as HTML using
.Xr mandoc 1
and opened with
.Xr xdg-open 1 .
.Xr mandoc 1
must be installed, and the system's implementation of
.Xr man 1
must support the
.Fl w
option to print the paths to manual page source files.
.It Cm om
man.openbsd.org search for the shortcut query, interpreted as for the
.Sy man
shortcut.
.It Cm mbl
man.bsd.lv search for the shortcut query, interpreted as for the
.Sy man
shortcut.
.It Cm op
openports.pl pkgname search for the shortcut query.
.It Cm tip
Interpret the shortcut query as a Tcl Improvement Proposal (TIP) number and open
it.
.It Cm tips
Search Tcl Improvement Proposals for the shortcut query.
.It Cm thash
Interpret the shortcut query as a commit hash in one of the
.Lk https://core.tcl-lang.org
fossil repositories and attempt to open it.
.It Cm tw
Full-text Tcl wiki search for the shortcut query.
.It Cm vman
man.voidlinux.org search for the shortcut query, interpreted as for the
.Sy man
shortcut.
.It Cm wp
Wikipedia search for the shortcut query.
.It Cm wikt
Wiktionary search for the shortcut query.
.It Cm yt
YouTube search for the shortcut query.
.El
.Pp
All shortcuts are implemented as commands in the ::trun::shortcuts namespace.
.Sh REMOTE-CALLABLE COMMANDS
The following commands are defined in the application's root interpreter and may
be called by other Tk applications with
.Xr send n .
.Nm
uses
.Dq tkrunner
as its Tk application name.
.Bl -tag -width 8
.It Cm show
Shows the Run Command dialog, raising its focus it it is already shown.
.It Cm hide
Hides the Run Command dialog, if it is shown.
.It Cm run Ar cmd
Run a command as though it was entered at the dialog box, properly registering
it in the command history.
.El
.Sh EXAMPLES
Run a program in the default search path:
.Bd -literal -offset -indent
xterm
.Ed
.Pp
Open a directory full of text files in
.Xr kate 1
using the
.Xr glob n
command
.Po
note that Tcl syntax applies, not the Bourne shell as in most other
run-command dialog utilities
.Pc :
.Bd -literal -offset -indent
kate {*}[glob -types f /home/user/src/tkrunner/*]
.Ed
.Pp
Open a file under the current user's home directory; note the use of the
.Sy 1glob
command to avoid the need for a construct like
.Qo
[lindex [glob ~/downloads/paper.pdf] 0]
.Qc :
.Bd -literal -offset -indent
file://[1glob ~/Downloads/paper.pdf]
.Ed
.Pp
Evaluate arithmetic expressions in infix notation
.Po with the
.Xr expr n
command
.Pc :
.Bd -literal -offset -indent
expr {sin(3 * 3.14159 / 2)}
.Ed
.Pp
Or in prefix notation
.Po
with the commands found in the
.Xr mathop n
and
.Xr mathfunc n
namespaces
.Pc :
.Bd -literal -offset -indent
sin [/ [* 3 3.14159] 2]
.Ed
.Pp
Start the spreadsheet program
.Sy abs
.Pq once found in an OpenBSD package of the same name ,
whose name clashed with the
.Xr mathfunc n
command
.Sy abs
.Po
the
.Sq ;hide
at the end may be omitted, since it merely causes the dialog to hide itself
after executing the command
.Pc :
.Bd -literal -offset -indent
runcmd abs ;hide
.Ed
.Pp
See where the clever and pithy quote below came from:
.Bd -literal -offset -indent
yt:Red Green temporary, unless it works
.Ed
.Sh BUGS
Much functionality remains to be implemented.
.Pp
The GUI layout originated as a rough prototype, but seems to be working well.
It should still be considered changeable at the whim of the author.
.Bd -filled -offset none
.Dq This is only temporary, unless it works.
\(em Red Green
.Ed
.Pp
Up-to-date information on any issues may be found on the Github issue tracker:
.Lk https://github.com/oldlaptop/tkrunner/issues