Smarter Source Help
Name:Smarter Source
Version:1.0
Last update:2019-11-27 14:13:15



This package is intended to help make the process of augmenting Alpha's code base with your own changes less awkward, especially in the face of program updates. It eliminates the need to source files containing procedures that you may want to override in your global prefs.tcl file.

'Smart Source' vs 'Smarter Source'

For most users who are only working with one installation of Alpha, the Support Folders "Smart Source" feature is sufficient to modify files from Alpha's standard distribution as over-rides. For more information, see the 'Smart Source' Support Folders file. This package extends this type of over-ride functionality even further; the difference between the two is somewhat subtle but can be very important.
You only have one Support Folder for Alpha that will be used by all versions of Alpha that you might have installed. Smarter Source Folders, on the other hand, are specific to the particular version of Alpha that you are using, because the location of the Smarter Source Folder is defined in your preferences, and each Alpha installation is allowed to define its own Prefs folder. Smarter Source files are generally used by AlphaTcl developers who need to maintain the latest stable version of Alpha while they are also working on the latest, cutting-edge beta version of the application and its supporting AlphaTcl library.

Activating Smarter Source

Activating this package creates a new Smarter Source Folder preference, which is initially set to your Alpha Preferences folder.
Select the Alpha ↣ Prefererences ↣ Global Preferences ↣ Files menu item to set a different folder. See the Files Preferences panel.
If you have already turned this package on and have set your Smarter Source Folder, click here to open it.
This package creates a new AlphaDev Menu ↣ Smarter Source submenu with some handy commands to add files to your Smarter Source Folder. These commands include Open AlphaTcl File and Save In Smarter Source.

Using Smarter Source

Basically, you designate a directory to contain your files. Then any time Alpha is instructed to source a file named say filename.extension, it will first look in the directory you have designated, and if there is a file of the identical name there (i.e. filename.extension), it will source that file instead of the original one specified. If there are any files named filename+*.extension, it will source those in the order returned by the [glob] command after either the original filename.extension or the replacement has been sourced.
For example, if your Smarter Source directory contains files named latex+1.tcl, latex+2.tcl then, when TeX mode is initially loaded, Alpha will first source the standard latex.tcl file, then latex+1.tcl, then latex+2.tcl. If there was also a file named latex.tcl in the Smarter Source directory then that file would be sourced _instead_ of the Smarter Source latex.tcl, then latex+1.tcl, then latex+2.tcl.
You may just want to use the name filename+.extension for a single extension file.
Note that latex+10.tcl would be sourced _before_ latex+9.tcl, so you may wish to use latex+01.tcl ... latex+99.tcl to make things clearer.
Smarter Source also operates in a more sophisticated, hierarchical way. If the original file is $HOME/Tcl/Modes/myMode.tcl, the Smarter Source package will actually look for: in that order of priority. Once anything has been found, the search stops.

How Does This Work?

The AlphaTcl system code defines a proc [alpha::useFilesFor] that will attempt to determine if an over-ride exists for any installed $HOME/Tcl source file. The default locations for such over-rides are the local and user Support Folder Tcl directories. (See Support Folders Help for more information.) These directories can be thought of as Smart Source folders.
The AlphaTcl system code then redefines the command [source] to always query [alpha::useFilesFor] to determine the proper location of a file that is about to be loaded. If an over-ride exists, that is used preferentially to the version in the installed distribution.
When the Smarter Source package is turned on, the [alpha::useFilesFor] proc is redefined so that it first checks your Smarter Source Folder for an over-ride, or possibly for two or more files that should be sourced instead of the single installed version. And that's all there is to it!
Note: the [alpha::useFilesFor] procedure is also queried when AlphaTcl package indices are rebuilt, so any initialization/activation/deactivation scripts in your Smarter Source files will be saved and used when Alpha is restarted. This does, however, bring up...

Known Limitations

When AlphaTcl package indices are rebuilt, the initialization, activate, and deactive scripts in any [alpha::mode], [alpha::menu] etc package declarations will reflect those in your Smarter Source files. If you change these scripts, your new versions will be used.
When Tcl indices are rebuilt, however, your Smarter Source files are _not_ used to determine what procedures are available. Smarter Source folders are also explicitly excluded from the auto_path list, so if you are defining a new procedure it will not be sourced by any command [auto_load] call, nor by any command [unknown] call.
What does this limitation mean to you? If you have a modified initialization or activation script in your Smarter Source version of an installed AlphaTcl package, you must _not_ attempt to call or auto_load a procedure that is only found in your Smarter Source file. It will not be found, and an error will be thrown. This is a known limitation, and it will not be addressed. (See Bug #847 for a complete discussion of this issue.)
There are several ways to work around this limitation. The goal here is to ensure that your Smarter Source version of a file is properly sourced before continuing with any other operation. Options include:
(1) First call a dummy proc found in the original version.
Many AlphaTcl files include a dummy proc which provides no functionality but can ensure that a file is properly sourced. If you see a proc like 
	proc fileName.tcl {} {}
in the original source then this is what you can call in your initialization script. So long as this dummy proc also appears in your Smarter Source version, you can be confident that your file has been sourced and any new procedures you have defined are in place.
(2) Add a Smart Source version of the original with your new procedure.
Alpha's Support Folders provide users with a simpler over-ride mechanism. You can create a Support Folders version of the original file, add your new procedure (or even a dummy procedure as described above), and then you will be safe calling this from your package's init scripts.
This works because, unlike your Smarter Source folder, Support Folder folders _are_ included in Tcl index rebuilding and in the auto_path. This means that you can call a procedure that does exist in a Support Folder version but then bypass that to use your Smarter Source version(s) instead. (Very clever, really.)
(3) Attempt to manually [source] the original.
If you include this call 
	uplevel \#0 [list source [file join $HOME Tcl <folder> ... <fileName>]
then the magic of the proc [alpha::useFilesFor] - which this package has redefined - should ensure that your version has been sourced.
(4) Similarly, you can attempt to manually source your new version, i.e. the file in your Smarter Source folder. 
	uplevel \#0 [list source [file join $smarterSourceFolder <folder> ... <fileName>]

(5) A final option would be to convince the AlphaTcl developers to include your Smarter Source version in the standard distribution! If you have some modifications which would benefit other users, they will be considered for the next public release of Alpha.

Important Notes

WARNING:
the Smarter Source Folder should be located outside AlphaTcl's hierarchy of Tcl files (i.e. outside of Alpha's $HOME/Tcl directory), otherwise the content of some of its files may be sourced before the content of the corresponding main file, which is precisely the opposite of what is wanted!
NOTE:
AlphaTcl will allow the Smarter Source package to over-ride rebuilding of Tcl indices and Alpha's package indices to notice the commands and packages which are defined in your Smarter Source Folder. In particular, changes to package init scripts are recognised.
What this does mean, however, is that if you turn Smarter Source on or off when you do have over-ridden packages, you may need to rebuild all these indices for Alpha to function correctly. See also the Known section above.
DEVELOPER'S NOTE:
we may wish to add appropriate warnings/dialogs to prompt the user when these situations may occur.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

All rights reserved.
The Smarter Source package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALPHA COMMUNITY BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.