General Utilities for Tcl
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc
src
test
LICENSE.html
LICENSE.txt
README.html
README.txt
WARNING.txt
changelog.html
changelog.txt
index.html
known-issues.html
latest-fixes.html
my.css
news.html
news.txt
policies.html
preview.png
roadmap.html
string-2-file-preview.png
wishlist.html

README.html

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css" href="my.css">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<link rel="icon" href="favicon.ico" type="image/x-icon">
<title>Readme - Gen</title>
</head>
<body>
<div id = "left">
<a href="index.html" class="navbar" >Home</a>
<a href="known-issues.html" class="navbar">Known Issues</a>
<a href="latest-fixes.html" class="navbar">Latest Fixes</a>
<a href="README.html" class="navbar" id = "current">Readme</a>
<a href="doc/README-doc.html" class="navbar" >doc / Readme</a>
<a href="test/README-test.html" class="navbar" >test / Readme</a>
<a href="doc/manual-home.html" class="navbar" >Manual</a>
<a href="news.html" class="navbar">News</a>
<a href="changelog.html" class="navbar">Changelog</a>
<a href="policies.html" class="navbar">Policies</a>
<a href="roadmap.html" class="navbar" >Roadmap</a>
<a href="wishlist.html" class="navbar">Wishlist</a>
<a href="license.html" class="navbar">License</a>
</div>

<div id = "center">
<div id = "content">
<div id = "AppTitle">Gen</div>
<div id = "PageTitle">Readme</div>
<a href="#C_HOWTO">01| HOW TO USE THIS DOCUMENT</a><br>
<a href="#C_INTRO">02| INTRO</a><br>
<a href="#C_GETTING_STARTED">03| GETTING STARTED</a><br>
<a href="#C_DEPENDENCIES">04| DEPENDENCIES</a><br>
<a href="#C_BUILDING">05| BUILDING</a><br>
<a href="#C_INSTALLATION">06| INSTALLATION</a><br>
<a href="#C_CONFIGURATION">07| CONFIGURATION</a><br>
<a href="#C_MANUAL">08| MANUAL</a><br>
<a href="#C_FAQ">09| FAQ</a><br>
<a href="#C_PLATFORM_NOTES">10| PLATFORM NOTES</a><br>
<a href="#C_TROUBLESHOOTING">11| TROUBLESHOOTING</a><br>
<a href="#C_KNOWN_ISSUES">12| KNOWN ISSUES</a><br>
<a href="#C_BUG_REPORTING">13| BUG REPORTING</a><br>
<a href="#C_FEEDBACK">14| FEEDBACK</a><br>
<a href="#C_TESTING">15| TESTING</a><br>
<a href="#C_CONTRIBUTING">16| CONTRIBUTING</a><br>
<a href="#C_UPDATING">17| UPDATING</a><br>
<a href="#C_RECENT_CHANGES">18| RECENT CHANGES</a><br>
<a href="#C_LICENSE">19| LICENSE</a><br>
<a href="#C_LEGAL">20| LEGAL</a><br>
<a href="#C_CREDITS">21| CREDITS</a><br>
<br>

<h3><a id="C_CATALOG">&mdash;01| HOW TO USE THIS DOCUMENT</a></h3>
<p>(Note that this README is designed to be filled out over the course of many versions. Some sections are currently blank.)</p>
<p>
<span class="question">What is the software about?</span><br>
See <a href="#C_INTRO">INTRO</a>.<br>
</p><p>
<span class="question">Is it OK for me to use? OK for me to modify? OK to make copies?</span><br>
See <a href="#C_LICENSE">LICENSE</a> for info about the software license. License page itself is <a href='license.html'>here</a>.<br>
See <a href="#C_LEGAL">LEGAL</a> for any additional info.<br>
</p><p>
<span class="question">How do I get it working?</span><br>
See <a href="#C_GETTING_STARTED">GETTING STARTED</a> (after you have it installed and configured) to see how to use.<br>
See <a href="#C_DEPENDENCIES">DEPENDENCIES</a> for anything external that is required or optional.
See <a href="#C_BUILDING">BUILDING</a> for how to compile from source.<br>
See <a href="#C_INSTALLATION">INSTALLATION</a> for how to install it on your system (and how to uninstall).<br>
See <a href="#C_CONFIGURATION">CONFIGURATION</a> for how you can customize it for your own use.<br>
</p><p>
<span class="question">I cannot make it work, what now?</span><br>
See <a href="#C_TROUBLESHOOTING">TROUBLESHOOTING</a> for dealing with problems with the software.<br>
See <a href="#C_PLATFORM_NOTES">PLATFORM NOTES</a> for ensuring it works with your platform/OS.<br>
See <a href="#C_MANUAL">MANUAL</a> to make sure you are using it correctly.<br>
See <a href="#C_FAQ">FAQ</a> to see if your question has been answered.<br>
See <a href="#C_KNOWN_ISSUES">KNOWN ISSUES</a> to see if your problem is already known about (and any workarounds / advice).<br>
See <a href="#C_BUG_REPORTING">BUG REPORTING</a> if you want to make a report and get follow-up.<br>
</p><p>
<span class="question">What is in the other sections?</span><br>
<a href="#C_FEEDBACK">FEEDBACK</a> - Info about things like feature requests.<br>
<a href="#C_TESTING">TESTING</a> - How you can test changes you make to the code.<br>
<a href="#C_CONTRIBUTING">CONTRIBUTING</a> - How you improve the product for everyone.<br>
<a href="#C_UPDATING">UPDATING</a> - How to get the latest changes.<br>
<a href="#C_RECENT_CHANGES">RECENT CHANGES</a> - What the latest changest are.<br>
<a href="#C_CREDITS">CREDITS</a> - Third party components used.<br>
</p><p>
</p>
<h3><a id="C_INTRO">&mdash;02| INTRO</a></h3>

<p>Say you are in the middle of solving one problem and find you need to solve another. Suppose you need to insert into a string. You could write code that will do this, but it would be nice and <i>convenient</i> if there were something that does it all for you with one command.</p>
<p>Gen is about making it a little bit easier to write Tcl programs. Gen is supposed to be code that you could well write yourself but do not want to have to.</p>
<p>Gen is <i>General Utilities for Tcl</i>.</p>
<h3><a id="C_GETTING_STARTED">&mdash;03| GETTING STARTED</a></h3>

<p>
Since this is a utilities library, you do not need to do much of anything to get started. The best thing would be to try typing in the examples from the documentation.<br>
</p><p>
If you would like to confirm the library is installed and working then try the following from a Tcl shell.<br>
</p><code>
% package require gen<br>
1.18.0<br>
% set Number 1<br>
1<br>
% AddTo Number 2<br>
3<br>
</code><p>
You should be all set!<br>
</p>

<h3><a id="C_DEPENDENCIES">&mdash;04| DEPENDENCIES</a></h3>
<p>Gen CAN use the following packages, but they are not strictly necessary (see below). You likely will already have got them as part of your Tcl distribution:</p>
<ul>
<li>sqlite3</li>
<li>Tclx</li>
<li>textutil::adjust</li>
<li>textutil::string</li>
<li>ftp</li>
<li>registry (Windows only)</li>
</ul>
<p>
If you do not have these, then check the documentation that came with your distro for information on how to get them.
</p>
<p>
<u>However!</u> Since the introduction of the Partial Loading feature, it is possible to use Gen without having these packages installed. Of course, any commands that need missing packages will not work, but you can still use any other commands that do not need the missing packages. Inside the <a href="#C_MANUAL">MANUAL</a> you can find a page with more details.
</p>

<h3><a id="C_BUILDING">&mdash;05| BUILDING</a></h3>

<p>
Gen is provided as a simple Tcl package and does not need to be built.<br>
</p><p>
</p>
<h3><a id="C_INSTALLATION">&mdash;06| INSTALLATION</a></h3>
<p>
If you are reading this you most likely have already successfully installed Gen.<br>
</p><p>
To install, extract the contents of the archive file (.zip or .tar.gz). That will result in the following files:<br>
</p><p>
</p><p>
</p>
<table><tr><td><code>README.txt</code></td><td>Plenty of info on how to get going.</td></tr><tr><td><code>LICENSE.txt</code></td><td>Terms of use and whatnot.</td></tr><tr><td><code>WARNING.txt</code></td><td>Special notices to prevent surprises.</td></tr><tr><td><code>/src</code></td>
<td>Source files<br>
<table>
<tr>
<td><code>pkgIndex.tcl</code></td>
<td>Used by the Tcl package mechanism.</td>
</tr>
<tr>
<td><code>gen.tcl</code></td>
<td>Main script file.</td>
</tr>
<tr>
<td><code>gen-config.tcl</code></td>
<td>Configuration variables (e.g. datetime format).</td>
</tr>
<tr>
<td><code>gen-error.tcl</code></td>
<td>Error codes and messages used by Gen.</td>
</tr>
<tr>
<td><code>loading-module.tcl</code></td>
<td>Code that tries to load packages and then Gen commands.</td>
</tr>
<tr>
<td><code>loading-module-data.tcl</code></td>
<td>Data used to do the loading.</td>
</tr>
<tr>
<td><code>*.tcl</code></td>
<td>Each command has its own source file.</td>
</tr></table>
</td>
</tr>
<tr>
<td><code>/doc</code></td><td>Any other documents (like the manual).</td>
</tr>
<tr>
<td><code>/test</code></td><td>Test suite</td>
</tr>
</table>
<p>Take the path to the install directory you just made and with it add the following line at the bottom of your <code>init.tcl</code> file:</p><p><code>lappend auto_path YOUR_DIR_PATH</code></p>
<p>See <a href="readme.html#C_DEPENDENCIES">DEPENDENCIES</a> for info about what Gen may need.</p>
<p>See <a href="readme.html#C_CONFIGURATION">CONFIGURATION</a> for more info about <code>init.tcl</code>.</p>
<p><i>What to do after you install?</i> You can check out the <a href='readme.html#C_GETTING_STARTED'>Getting Started</a> section of the README. We recommend browsing the <a href='doc/manual-home.html'>manual</a> (or even better, use the .chm file included in your download). Each command reference has at least one example. You can type that directly into your terminal and try out the command.</p>
<p><i>Prefer use to git and clone the repo?</i> There is a repo posted up on <a href="https://github.com/rbrogan/tcl-gen">GitHub</a> for you.</p>
<p><i>How to uninstall?</i> To uninstall you can simply delete the directory. You can also remove the <code>lappend auto_path YOUR_DIR_PATH</code> line from your Tcl init.</p>
<h3><a id="C_CONFIGURATION">&mdash;07| CONFIGURATION</a></h3>
<p>To configure Tcl so it can find Gen:</p>
<p>Take the path to the install directory you just made and with it add the following line at the bottom of your <code>init.tcl</code> file:</p><p><code>lappend auto_path YOUR_DIR_PATH</code>.</p>
<p><i>How to find init.tcl?</i> Here are some locations found for Windows and Linux. Most likely if you use the number of your version then you can find your init.tcl in a similar spot.</p>
<b><code>C:\Tcl\lib\tcl8.5\init.tcl</code></b><br>
<b><code>C:\Tcl\lib\tcl8.6\init.tcl</code></b><br>
<b><code>/usr/share/tcltk/tcl8.4/init.tcl</code></b><br>
<b><code>/usr/share/tcltk/tcl8.5/init.tcl</code></b><br>
<p>Alternatively, do a search for init.tcl starting from the root directory of your installation.</p>
<p>In order to use various commands, you will want to do configuration of certain variables. You can take a look at the following, when you need to use the commands:</p>
<ul>
<li>Database
<ul><li><code><a href="doc/about-configuration-for-database-use.html">doc/about-configuration-for-database-use.html</a></code></li></ul></li>
<li>Date and Time
<ul><li><code><a href="doc/about-date-and-time-commands.html">doc/about-date-and-time-commands.html</a></code></li></ul></li>
<li>FTP
<ul><li><code><a href="doc/about-ftp-use.html">doc/about-ftp-use.html</a></code></li></ul>
</li>
</ul>
<p>
To run the FTP tests, you will also need to do special set up. See <code>test/README-test-ftp.txt</code> or <code>test/README-test-ftp.html</code> for details.
</p>
<h3><a id="C_MANUAL">&mdash;08| MANUAL</a></h3>

<p>
We have a few options. You can see the <a href="http://www.robertbrogan.com/gen/doc/manual-home.html">online manual</a> (which will be the most up-to-date).</p><p>Alternatively, you can use the offline version at <code><a href="doc/manual-home.html">doc/manual-home.html</a></code> or (preferrably) use the compiled HTML Help version at <code><b>doc/gen.chm</b></code>.
</p><p>
</p><p>
</p>
<h3><a id="C_FAQ">&mdash;09| FAQ</a></h3>

<p>
No questions yet. We will put them here as we get them.<br>
</p><p>
Please send questions you have to <span class="email">gen.questions@robertbrogan.com</span> or visit <a href="http://www.robertbrogan.com/gen/feedback.html">http://www.robertbrogan.com/gen/feedback.html</a>.<br>
</p><p>
Also note, you may possibly find the answer to your question in <a href="#C_MANUAL">MANUAL</a>, <a href="#C_TROUBLESHOOTING">TROUBLESHOOTING</a>, or <a href="#C_KNOWN_ISSUES">KNOWN ISSUES</a>.<br>
</p><p>
</p>
<h3><a id="C_PLATFORM_NOTES">&mdash;10| PLATFORM NOTES</a></h3>

<p>
If you have Tcl working for your platform, then the library should work without problem.
</p>
<p>
None of the commands themselves include platform-specifc interactions (i.e. make system calls) beyond occasionally calling another Tcl command that is platform-specific (e.g. in an upcoming release the command <code>Reg2Dict</code> will call the Tcl command <code>registry</code>, which is Windows-specific).
</p>
<h3><a id="C_TROUBLESHOOTING">&mdash;11| TROUBLESHOOTING</a></h3>

<p>
No tips at this time. We will post them here as we get them.<br>
</p><p>
Also note, you may possibly find help in <a href="#C_MANUAL">MANUAL</a>, <a href="#C_FAQ">FAQ</a>, or <a href="#C_KNOWN_ISSUES">KNOWN ISSUES</a>.<br>
</p><p>
</p>
<h3><a id="C_KNOWN_ISSUES">&mdash;12| KNOWN ISSUES</a></h3>

<p>
See the <a href="known-issues.html">local HTML Known Issues page</a> or <a href="http://www.robertbrogan.com/gen/known-issues.html">the online Known Issues page</a>.
</p>
<h3><a id="C_BUG_REPORTING">&mdash;13| BUG REPORTING</a></h3>

<p>
To report a bug, you can visit <a href="http://www.robertbrogan.com/gen/feedback.html">www.robertbrogan.com/gen/feedback.html</a> and use the form there. <br>
</p><p>
Alternatively, you can send an email to&mdash;
</p><p>
<span class="email">gen.bugreport@robertbrogan.com</span>
</p><p>&mdash;and we will try to get back to you ASAP.
</p>
<p>Note that you may also want to check <a href="known-issues.html">the Known Issues page</a> and <a href="latest-fixes.html">the Latest Fixes page</a> to see if your issue has already been reported or perhaps already fixed.</p>
<h3><a id="C_FEEDBACK">&mdash;14| FEEDBACK</a></h3>

<p>
You can visit our feedback page at <a href="http://www.robertbrogan.com/gen/feedback.html">http://www.robertbrogan.com/gen/feedback.html</a>. <br>
</p><p>
Alternatively, you can use your own email client and send an email to one of:<br>
</p><p>
<span class="email">gen.<b>questions</b>@robertbrogan.com</span><br>
<span class="email">gen.<b>comments</b>@robertbrogan.com</span><br>
<span class="email">gen.<b>bugreport</b>@robertbrogan.com</span><br>
<span class="email">gen.<b>wishlist</b>@robertbrogan.com</span><br>
<span class="email">gen.<b>other</b>@robertbrogan.com</span><br>
</p><p>
and we will try to get back to you ASAP.<br>
</p>
<h3><a id="C_TESTING">&mdash;15| TESTING</a></h3>

<p>
You can find tests in the /test directory.
</p>
<p>You will find a <a href='test/README-test.html'>README</a> file there as well, with further details on things like how to run the tests yourself.</p>
<p>
To run the FTP tests, you will also need to do special set up. See <code>test/README-test-ftp.txt</code> or <code>test/README-test-ftp.html</code> for details.
</p>

<h3><a id="C_CONTRIBUTING">&mdash;16| CONTRIBUTING</a></h3>

<p>
Nothing formal has been set up for governing this project, yet.
</p>

<h3><a id="C_UPDATING">&mdash;17| UPDATING</a></h3>

<p>
The latest version can be found at <a href="http://www.robertbrogan.com/gen/download.html">www.robertbrogan.com/gen/download.html</a>.<br>
</p><p><i>Want to receive notifications about changes to Gen?</i> You can subscribe to the announcements mailing list by sending an email to gen-announce-subscribe@robertbrogan.com. (No need for anything in subject or message body.) You will get an email every time we have a new release.</p>
<p>Note that you may want to check out the <a href="policies.html">Policies page</a> to find out how releases are done. You may also want to check out the <a href="roadmap.html">Roadmap page</a> to find out when the next release is coming out.</p>
<h3><a id="C_RECENT_CHANGES">&mdash;18| RECENT CHANGES</a></h3>
<p>
Version 1.18.0 released. You can view a summary of changes in the <a href='news.html'>news</a> page and further details in the <a href='changelog.html'>changelog</a>.
</p>

<h3><a id="C_LICENSE">&mdash;19| LICENSE</a></h3>

<p>
The license is the same as the license for Tcl, for all practical purposes. See the <a href="license.html">license page</a> or LICENSE.txt.
</p>
<h3><a id="C_LEGAL">&mdash;20| LEGAL</a></h3>

<p>
No legal notice at this time (i.e. no use of crypto). See <a href="license.html">LICENSE</a> for information about the license.<br>
</p><p>
</p>
<h3><a id="C_CREDITS">&mdash;21| CREDITS</a></h3>

<p>
Information posted at wiki.tcl.tk has been helpful throughout work on Tcl projects.<br>
</p><p>
</p>
</div>
<div id = "footer">
<p id = "footer-content">General Utilities For Tcl</p>
</div>
</div>
</body>
</html>