
Small tips and tricks for more effective use of FileRunner
-------------------------------------------------------------
-------------------------------------------------------------

Table of Contents


Latest release expanded notes:

Configure options for commands I:

Configure options for commands II (the filerunner exec call formater (FRECF)):

File links 101 (soft and hard):

Check boxes for configure option:

Config files:

Dockable Menus:

Using Firefox to display .html files:

How to handle file names with blanks in the view (and other) config text:

Right justifying file size in the list boxes:

Grouping the size in groups of three (i.e. 123,456,789):

Puting a space before the file name in the directory list boxes:

Man files and filerunner:

A button to clone a root version of fr:

Filerunner library of tcl/tk routines for your use:

-------------------------------------------------------------
Latest release expanded notes:

VFS

The term VFS (for Virtual File System) is now used in filerunner to describe: 
The connection code that allows ftp, sftp, rsync, adb and others to be used to put file systems from other systems in a filerunner pane. For the most part this code uses an external program to provide content and to execute the requested actions on the displayed files. With this release a well defined interface is provided for the VFS code allowing VFS modules to be packaged and added to the filerunner in a simple and easy manner.

At the same time, the general code in filerunner was expanded to allow almost all actions available to local files to be available to remote files. For example diff will work with files or directories that may be either local or remote. Copy, CopyAs, Move, Rename, and the new MoveAs all work with either or both sides of the operation being remote. (And yes, Rename does involved two different file references each of which may be local or remote.) "View" and "Q-Edit" also will work with either local or remote files, including writing them back.

The term VFS is also part of VFS type II which we define as a way to easily examine the contents of file containers such as "zip", "tar" and their like. The way this is done is to "unpack" such files onto the local disk, such that they look and act like local files. Filerunner provides to 'button' commands (commands with buttons between the panes) to deal with VFS type II containers.
The "Mount" command does 3 things: 1) unpacks the container, 2) optionally gives the result a "Display Name" and 3) Keeps track of the result so that the "UnMount" command can remove the files.
The "UnMount" command 1) optionally repacks the files, 2) deletes the files and 3) removes and "Display Name" generated by the "Mount".
The "Mount" and "UnMount" commands use rule based logic to do what they do. The rules are defined in the "config" file. The "As shipped" version of the "Mount"/"UnMount" rule provides 2 samples 1) that allow access to any of the formats that "7zip" can handle and 2) a rule for .tar.* containers. (Of course these programs must be find-able via the PATH environment variable for these rules to work.)

Display Names

This is a rather simple (at least in concept) mechanism that allows you to give a "Display Name" to an absolute directory or VFS URL. For example you might give the name JOHN to /home/john (or C:\users\John Doe). As mention above, the rule for the "Mount" command allows you to create a "display name" for the result. Also, below see "Directory nil" comments. "Display Names" automatically appear in the "History" drop-down as well as at the top of the "HotList" drop-down. There is a "config" file entry that allows you to define your own "Display Names". The "As shipped" version of filerunner defines the "nil" directory (i.e. "") as <volume>.

Directory nil

The nil (spelled "") directory may also be referred to as the volume directory. Filerunner threats the following as volumes: on windows "c:" or more generally (a-z): and UNC (aka CIFS) volumes on *nix, "/" CIFS and NFS mount points. By making changes to the "passwordLocker" in the config file you can control the entry of the CIFS and NFS entries in the volume directory listing. On start up filerunner attempts to find any external file systems that can be (or are) mounted on the system. (Note that MS has deprecated the network browsers (a high security risk) so finding CIFS (aka UNC aka SMB) connections is no longer an easy task. In the best case it takes a while to find them, if they can be found at all. If, on the other hand, you mount these (or assign dive letters to them) filerunner will easily find them.

trash/recycle

Both the MSW version and the *nix version of filerunner allow you to define an external routing to "delete" a file or directory. This allows you to move such files/directories to the "Trash bin" (*nix wording) or the "Recycle bin".

MS Windows (Elevated fr)

On windows, the Utilities->Run fr Elevated command will launch a filerunner in elevated mode. Be aware that if you define a new color scheme or different fonts while in elevated mode they will be only used in elevated mode. This allows you to easily recognize that a given filerunner is in elevated mode. (On *nix systems the whole of the config file is kept in a different place so the same thing works there.)

MS Windows (opening files)

With this release, filerunner when trying to "open" a file will search the PATH and then will look at the first line of the file. If it looks like a *nix script line (i.e. "#! /??/foo") filerunner will look for "foo" again in the PATH. Note that the path in this file reference is not used as you may not have put the script interpreter in the same place on the MS system.

MS Windows (New buttons)

The "Properties" button opens the MSW systems properties dialog.
The "Short Cut" button creates a short cut to the selected file(s) in the opposite pane directory. The "Short CutAs" button creates a short cut with a different name.

tkcon

Tkcon and the "frputs" command are the main debug tools used to support filerunner development. Both of these are independent of filerunner and may be used to develop other tcl/tk applications. In this release the tkconrc package is defined. This provides a default "rc" file for tkcon as well as "frputs helper files". The helper files redefine <3> in tkcons window to provide a search function (the same one used in the fr view windows) and a set of "frputs" control files that a) give help on how to use "frputs" b) make it easy to set up options for "frputs" and c) will save and/or restore a set of options across several runs of tkcon and the code it is debugging.

-------------------------------------------------------------
Configure options for commands I:

Several places in the configuration file you may want to specify where a file name should appear in a command string.  For example you may want to use a pipe of two (or more) programs where the first program is to get the file. The following discusses how these strings are handled and how you can change them to get the desired result.

First the simple stuff.  You can put 'Tcl' string replacement and function commands in these strings. For example, you may want to pass an environment variable to a program. In this example we want to pass the DISPLAY environment variable to 'emacsclient' (useful if you are logged into a remote system which is using your local display). Here is how you do it:

set config(editor) {emacsclient --no-wait -d $::env(DISPLAY) %s}

In the tcl language, $<id> says replace <id> with its value. "::" says we are talking about a global variable, in this case env(DISPLAY) (which will produce the same string $DISPLAY does in sh or bash.

Function commands are encoded as follows:

set config(editor) {emacsclient --no-wait -d [set ::env(DISPLAY)] %s}

The function and its parameters are enclosed in brackets ([]). In this case the function being called is "set" and with one parameter "set" returns the value of the variable named.  In short both of these examples return the same thing.

The point of the above is to indicate how you may include various internal values and results from filerunner and tcl in your calls.

The last little trick is to cover the case that you want to put something like "$Id" in a command (I do this with diff).  To prevent an error because "Id" is not a variable, put this put "[]" right after the $, e.g. "$[]Id".  The "[]" will go away and the result will be the desired "$Id" with no errors.  You may also want/need to use "\" to protect the "$".  If it needs protection from code further down the call stream you may need additional "\"s.  So, for example "\\\$Id" will end up passing "\$Id" to the program being called.

-------------------------------------------------------------
Configure options for commands II (the filerunner exec call formater (FRECF)):

Tcl uses a built in 'exec' command to call other programs. To do this 'exec' needs to know and build parameter lists for the call. 'Exec' uses spaces and quotes (") to determine where a pamrameter starts and ends. Most of the time putting quotes around file names (which may contain spaces) is all that is needed. However, from time to time you may want to include several file names in a single parameter.

The FRECF was written to make all of this easy, relatively straight forward and, most of all, consistent.  Files are usually passed by selecting one or more files and then pushing one of the center buttons such as Copy, Delete, Diff, etc. This causes filerunner to process one of the configured recipes (i.e. configured format statements). 

A format specification consists of three parts: The "%" start character, an optional position specifier, and the type of conversion. The formater used to process strings from the configuration file recognizes the following format specifiers:

  s             inserts file name after converting to the "native"
                syntax (This is where the "\" is converted to "/".)                
  n             inserts the file name with out converting to "native" syntax
  m             not currently used (watch this space)
  a             replace this with the current default (see below)
  b             add as many default specifiers as required for the given files
  q             same as 's' except use \" quotes
  r             raw conversion, no enclosing quotes or \"
  %             replace with %
  "             replace with "
  { }           (space) remove the % and the space

Native syntax is only different from what filerunner (and Tcl) use on MS windows where all the "/" are converted to "\". This is rather painful as "\" is used in Tcl, *nix and even MS windows as a single character quote mechanism.  The other characters that require special care in handling when passing files to other programs are {}[]"$ and space. All this is handled by the FRECF.

The "%" conversion would look like "%%" in the format statement. It is converted to a single "%".  So, for example, you can refer to MS windows environment variables, e.g.: %%APPDATA%%.

Likewise the """ conversion converts %" into ". This is used when grouping several files into one parameter. This is mostly used with the 'q' conversions which use backslashes to hide the quotes from the 'exec' command or the 'r' conversion which uses no quotes. See example below.

A position specifier consists of a single digit number followed by a "@" and indicates that this position is to be filled by the parameter given by the single digit. The first parameter is 1 so there are at most 9 possible position specifiers. Position specifiers are recognized only on "s", "q", "r" and "n" conversions.

Here is a possible configuration format line for a copy function:

set config(cmd,cpy) {zcopy /k %s %s}

And for a copy routine that wants the parameters reversed:

set config(cmd,cyy) {ycopy /k %2@s %1@s}

All this can be simplified because:

1) The default conversion for MS windows is "%s" and for all other systems it is "%n".
2) If enough conversions are not in the string, default specifiers are added to the end of the string.
3) %s is replaced with the default specifier.
4) %b is replaced with as many default specifiers as needed.
5) If specifiers remain after all parameters are processed, they are discarded.
6) Position specifiers can be mixed with normal specifiers (see rules below)

On mixing position specifiers: Repeats are not allowed. The implicit assignment of parameters to specifiers is left to right.  If a parameter has already been assigned, the next un-assigned parameter is used. An attempt to force assignment of a parameter that has already been used is an error. Thus, in the example above we could have coded:

set config(cmd,cyy) {ycopy /k %2@s %s}

or, since missing specifiers are automatically added:

set config(cmd,cyy) {ycopy /k %2@s }

If you want to pass several files to an editor and have it run in the background:

set config(editor) {{your editor}  %b &}

and for a pipe:

set config(cmd,unarc) {guzip -option %s | tar -options -}

Here is an example of how to tell emacs to diff two files:

set config(cmd,diff) {emacsclient --no-wait -e %"(ediff-files %q %q )%"}

Note that we used the %" to supply the quotes that make the parenthetical expression one parameter. It is also necessary to use the %q conversion to change the file quoting to \" and thus hiding it from 'exec' while still allowing spaces in the file names. 
An alternative here is to use braces to indicate the one parameter. I.e.;

set config(cmd,diff) {emacsclient --no-wait -e {(ediff-files %s %s )}}

In this case the blank in front of the ) is needed by tcl to prevent an error. Braces within a parameter are not touched and will cause problems later (in this case emacs can not find {..}, so quotes are needed here.
To eliminate the annoying window that pops up here you can add & to the end of this. 

FRECF allows file names to be used in larger expressions (such as URLs) where text from the format is to be appended (or pre-pended) to the filename. In these cases you will have the best luck using the %r conversion and putting the quotes where needed using the %". If, for some reason, the space needs to be removed, use the "% " converson which acts like a space but is removed from the result. I.e.:

set config(cmd,diff) {emacsclient --no-wait -e %"(ediff-files %q %q% )%"}

See other examples in the configuration file 'run' command discussion.

-------------------------------------------------------------
File links 101 (soft and hard):

First what links are. A link is an entry in a file folder (directory) that points at another file.  

A soft link is a string that looks very much like a file name that is, in fact, the file that it points to.  It may point anywhere in the file system and in fact completely outside of the file system. (Usage for this below.) 

A hard link on the other hand points directly at the file and must point at a file on the same volume. In fact, this is what each directory entry is.  Each file has at least one hard link or it is considered deleted. It may still exist on the medium but with no directory entries pointing at it it can not be found. The interesting case is where a given file on the medium has more than one hard link pointing at it. The file system keeps track of these links and will release the space only when the link count goes to 0.  While a file system may use hard links internally to manage the medium and its files, the ones of interest here are those that we can use.  The only hard links we can create are ones to files, i.e. hard links to folders are not allowed. 

These two types of links have very different usages. I will give examples of usages I have made of them. 

First, the soft link.  Filerunner has a library of routines that are located in a folder in the master development tree that has the name "frlib" (same as the ship location). I, however, have a larger library of routines of which these are a subset. It is best for my work if I keep these all together in a folder outside of the Filerunner tree.  So to facilitate the keeping of these routines on the same page all the entries in the Filerunner development tree are softlinks to the routines located outside of the tree.

Another use I have seen for softlinks is to put notes to other routines that might share a resource. For example the Emacs editor uses softlinks to indicate that it has a modified copy of a file in hand.  This allows an Emacs editor on another machine which can see the file to know that there may be a conflict.  In this case the link does not point at a file but rather contains the user and system name of the editor that has the modified file.

Here is how I used hard links.  Some time ago I worked on a large project containing thousands of files.  When a new release was made a "patch" was made that allow one to modify the previous release to the now current release.  The patches were much shorter that the whole source tree and could be applied very quickly in most cases. In order to have several releases of the source tree on my (at the time) limited disc space I used hard links. Here is how it worked:
1.) Using the cp hard link option recursively I created a new source tree that was the same as what I had.  The only disc space this required was for the folder entries for each folder. There was only one copy of each file.
2.) Using the "patch" program I updated the new the tree. "Patch" worked by using the old file as input along with the patch information and creating a new result file. It then deleted the old file and renamed the new one.

The net result is that the only additional files on the system were the ones that had been patched.

This allowed me to keep several versions the system on a relatively small amount of disc space.  When I no longer needed a version I just recursively purge it.

As you can see, in this example, it is most useful to have a routine that will recursively create the hard links for a directory tree.  Cp has done this for years.


-------------------------------------------------------------
Check boxes for configure option:

Several of the 'check' options at the top of the 'Configuration' menu can also have check boxes at the top of the filerunner window. Find 'Fast Checkboxes' under 'Miscellaneous' in the 'Configuration Browser'.  This is a great help if you want the 'balloon help' only some of the time, for exammple, or if sometimes you want to see hidden files but not always. 
-------------------------------------------------------------
Config files:

There are two config files that filerunner visits on start up. The user config file is private to the user and is is located here:

  ~/.fr/cmds
    or
  ~/.config/.fr/cmds
    or on MS windows
   %APPDATA%/.fr
     or
   %LOCALAPPDATA%/.fr
     or
   %USERPROFILE%/.fr
   
  The location of the system wide 'config' file varies depending on how filerunner is installed.  (If installed by a user, it is really not system wide.)  In either case it is found by filerunner (and may be found by you) by inspecting the file 'config' in the directory that contains the filerunner code. The easy way to find this is to open a command window at the bottom of filerunner and type:

  %set glob(lib_fr)
  
  This file is built by the INSTALL script and informs filerunner of the location of the 'doc' directory and the system wide config file which is usually called 'filerunnerrc'.


-------------------------------------------------------------
Dockable Menus:

It is easy to create a menu window that you can move to any location on your desk top.  Here is how:

First select an event to bind the menu to.  You want an event you hardly ever use. For this example I use <Shift-1>.  That is mouse 1 with the shift key.  (possible modifiers may be found here:

https://www.tcl.tk/man/tcl8.6/TkCmd/bind.htm

Now open the 'Configuration Browser' (Configuration -> Edit Configuration).
Click on 'Mouse Bindings & menus' near the top left.
Scroll down in the right panel to the set of 'set config(bind,... lines.  Here you want to enter the event and the menu name, for this example I use 'mymenu'.

set config(bind,Shift-1) DoMenu,mymenu

Now scrolling down in the right panel to the menu configuration where you see 'set config(menu,... ' lines.

This is where the menu is defined, e.g.:

set config(menu,mymenu) {
    Copy
    CopyAs
    Delete
    Move
    Rename
    MkDir
    S-Link
    S-LnAs
    Chmod
    View
    Edit
    Q-Edit
    Arc
    UnArc
    UnPack
    ForEach
    Print
 }
Now click 'OK' at the bottom of the window. When you do a 'shift mouse 1' the menu will appear.  To make it dockable click on the dotted line at the top.  Now you may move the menu anywhere you want (i.e. dock it).


-------------------------------------------------------------
Using Firefox to display .html files:

It is convenient to view .html files by using the View command. 

This just works by putting the following in your config(view,extensions) variable:

  { {firefox %s}
    {*.html} }

If you (like me) like to run filerunner as root and want to look at files with firefox (or other programs that don't want to be called by root) you can put a helper file (I call it myfirefox) that looks like this:

#!/bin/bash
#
# if we are root, pass the request to the local account
#
if [ `whoami` = "root" ] ; then 
#    echo "trying su --session-command=myfirefox $@ YOURNAME"
    su --session-command="firefox $@" YOURNAME
else
#    echo "trying firefox $@"
    firefox "$@"
fi

Put this in your ~/bin directory and then change the config(view,extensions) variable to call 'myfirefox' (or what ever you name it).

-------------------------------------------------------------
How to handle file names with blanks in the view (and other) config text:

The configuration file can contain file & path names that are needed to reference helper tasks (editor, view tasks, etc).  If these paths contain blanks you must tell filerunner about them by using braces (for example for firefox):

{{ {/home/john jones/bin/myfirefox} %s}
   {*.html} }

See also the note on 'config(space)' in the configure file.

-------------------------------------------------------------
Right justifying file size in the list boxes:

The directory list box format is controlled by 'script' in the configure file. Open the configuration browser:
 
(Configuration -> Edit Configuration)

and, under appearance select 'ListBoxScripts'. Each fields format is set here.  There is no true right justify in tcl but you can get close by using format %Ns where N is the number of digits you expect in your number.  If the number contains more than N digits the format command will extend the field to the right so the result is right justified until you encounter a number too large for the field.  At the moment I am using: 

    {links {format %3s $nlink}}
    {size  {format %6s $size}}

for the links field and the file size field.

-------------------------------------------------------------
Grouping the size in groups of three (i.e. 123,456,789):

This makes it much easier to read large file sizes.  We use the same idea as above, but it is a little more complex:

     {size {format %8s [string reverse [regsub -all {.{3}(?!$)} [string reverse $size] {&,}]]}}

The above will put commas between each group.  If you prefer a different character (e.g. ".") just change the comma after the "&" above to your prefered character.

-------------------------------------------------------------
Puting a space before the file name in the directory list boxes:

First read the above "Right justifying file size in the list boxes." Using the same trick, use (note the space in front of the %):

    {file  {format " %s" $ffile}}

for the file entry.

-------------------------------------------------------------
Man files and filerunner:

I use the following view extension for man files:
  { {man   {%s} | ul -t dumb}
 {*.1m.gz *.1.gz *.2.gz *.3.gz *.3pm.gz *.3ssl.gz *.3t.gz *.3thr.gz *.3x.gz *.4.gz *.5.gz *.6.gz *.6x.gz *.7.gz *.8.gz *.9.gz *.n.gz *.1 *.1m *.2 *.3 *.3t *.3thr *.3x *.4 *.5 *.6 *.6x *.7 *.8 *.9 *.n *.1x *.2x *.3x *.4x *.5x *.6x *.7x *.8x *.9x *.1x.gz *.2x.gz *.3x.gz *.4x.gz *.5x.gz *.6x.gz *.7x.gz *.8x.gz *.9x.gz}
   -viewtext }

Problem is that man seems to want to come up with different line lengths and thus poor formatting.  To fix this I put this: 

global env
set env(MANWIDTH) 80

in either the local or the system wide 'config' file.  This sets the environment variable MANWIDTH which man uses to set its line length. This file is 'source'ed each time filerunner starts so any program run by file runner will see any environment variables set here.  This does not seem to work on Windows systems, however. (See the tip on config files above for the location of the config files.)

* The location of the 'config' file varies depending on how filerunner is installed.  If it is a system install (i.e. by root) the config file will most likely be /usr/local/config/

-------------------------------------------------------------
A button to clone a root version of fr:

(Note that while this still works, you might try "ucmd" (the third entry in the utilities menu).)

Here is how to create a center button called "root fr" which will run fr in full root mode (not setuid mode).  First add the following lines to the ~/.fr/cmd file (don't have one? then this is the whole file):

set config(usercommands) {
    { {root fr} Doroot {Run filerunner as root}}
}
proc Doroot {args} {CmdRunCmd 0 {root fr}}

Note that if you already have a ~/.fr/cmd file, you may already have a set config(usercommands) entry here.  In that case, just add the line:

    { {root fr} Doroot {Run filerunner as root}}

some where in that list of user commands.  What this does is define a user command with a display name (what will be on the button) of "root fr" that runs the command "Doroot" and has the balloon help message of:

"Run filerunner as root"

The proc line defines the command "Doroot" which, in turn runs "CmdRunCmd" passing it 0 and "root fr".

In the configure file section "RunList" we now need to tell the "CmdRunCmd" what to do with this.  Here is the entry we need to add to the end of the set config(runlist) entry:

   {{{root fr} {sudo su root -c [list fr %s]}}
        { }
        fullname
        async}

(This will be followed by the closing "}" to complete the set config(runlist) command.)

This tells CmdRunCmd to execute:

 "sudo su root -c fr <parm>"

By using it to run "su" we get full root mode and do not have to supply a password.  The -c says
to su to just run a single command which is fr.  <parm> will be the selected directory.  Note you must select a directory prior to clicking on the "root fr" button.

-------------------------------------------------------------
Filerunner library of tcl/tk routines for your use:

The filerunner library are routines in tcl/tk code that are used in filerunner and are written in a general use way so that they may be used in any tcl/tk script (feel free to use in your code).  These routines have comments in them explaining every thing (I hope) you need to know to use them. These routines are located where ever you installed "filerunner" at .../filerunner/frlib/

Enjoy
-------------------------------------------------------------
If you have a good tip to share with other FileRunner users, please send it to the author.  (Tom@wildturkeyranch.net)









































































































































































































































































































































































































































































