[Arjen Markus] (27 november 2003) This page is intended to hold (the draft version of) a Tcl user/programmer guide. I feel something like that is needed, as it will concentrate information that is now scattered all over the place in one single document - information that is needed by unexperienced programmers and is tough to find, due to the scattering. ---- ''Idea for a tutorial/user guide'' * Use the script to find files * Describe in detail how to do it: why use procedures? * Describe options to implement it: - by running the command on each file in turn - by having it return a list of files * Describe in detail how to deploy the script! * Second example: polynomials (ah maths!) - Similar set-up Subjects/aspects - just a reminder: * GUI for finding files * #! magic * associations under Windows * tclkit and console * MacOSX: how to work on that platform? * difference between application and library - info script trick * Start menu under Windows * Typical installation under UNIX * Environment variables * Version numbers: Tcl, own application * package require Tk * version number and patchlevel Tcl/Tk * wrapping in general '''How to make a Tcl application''' '''1. Introduction''' Books on programming languages generally focus on the syntax and semantics of the language. They seldom explain in detail how to make an actual application, that is, a program or set of programs that you can give to a user and that he or she can start using then. Partly the reason is that many programmers already have some knowledge of how to do that (but how did they learn that in the first place?). Partly, especially for compiled languages (C, Fortran, Java, ...), the reason is that this is very platform-dependent. You can consult the manual for your compiler to find out what the command is for compiling a single source file, what options it supports. Such things are generally found in the programmer's guide. The situation is different for an interpreted language like Tcl. As there is no compiler in the sense of a separate program that you need to run, the source code for your Tcl program is all that is needed: this is the application. Well, if that were the full story, this guide could stop here. Of course it is not as simple as that. So you give your code to the unexpecting user. What then? How is he or she supposed to know how to start it? Or for that matter, if you know the basics of the language, but you do not have much (or any) experience with it, how do you as a programmer start? This guide intends to help out: I will describe a few small applications from the beginning (the idea) to the end (the actual, deliverable application). By describing them in detail, I hope you will learn the following: * Basic programming skills in Tcl (if you do not have them already) * How to design a (small) application * How to organise your source code (use of main code, procedures, what to do with several source files, how script libraries work) * How to create a deliverable application (for various platforms) '''2. Experimenting via the "shells"''' Tcl/Tk comes with two standard interpreter programs, tclsh and wish and though you can make your own programs using the Tcl/Tk libraries, we will concentrate on these two: * tclsh is a program that executes Tcl scripts and can be used interactively to run Tcl commands * wish is a very similar program but it offers the Tk package right from the start. When run interactively, it sets up the main window for you, called "." With a term from UNIX these programs are called "shells". So from now on we will use that term, whenever convenient. (Note: while it is fairly easy to make your own Tcl/Tk shell or to make a program that uses the Tcl/Tk libraries, this is not covered in this user guide. We refer to TIP #66 and ... for more details) If you just start tclsh, you get a so-called prompt (% by default). You can type any commands you like at the prompt: % puts "Hello, world!" Hello, world! These commands are executed and the result is printed. This is a great environment for testing commands that you are not certain about. Say, you want to experiment with [[string map]] (which can replace "substrings" by other strings in a larger string - easier to use than the regular expressions): % # Convert the lowercase vowels into the uppercase equivalents % set line "abcdefg" % string map {a A e E i I o O u U} $line AbcdEfg If you want to start your scripts (in an interactive environment), use the [[source]] command: % source myscript.tcl and the script will be loaded and run. A more direct way is to give the name of the script file as a command-line argument (for Windows users: open a DOS-box first): Under Windows: d:\> tclsh myscript.tcl Under UNIX/Linux: /users/me> tclsh myscript.tcl Under MacOSX: ???? '''3. Finding files''' The first program we are going to write (or perhaps ''develop'' is a better term, as we are going to write several versions, from simple to sophisticated), deals with the following question: ''Given a directory, find all the files in that directory and in any directories below that, that fulfill some condition'' (the condition could be: the file name ends in ".tcl", the file is older than 10 days, the file is larger than 100 kB, etc.) Further requirements: * It should run under Windows, UNIX/Linux, MacOSX (well, all common platforms supported by Tcl) * The condition must be given via the command-line (as one of a set of possibilities) * We do not need a GUI (yet), we just want a list of names printed or actions performed * It should be possible to just say: findfiles "*.tcl" older 10 (that is: it can be run as any ordinary system command, dir or ls for example) What Tcl commands do we need? At least: * ''glob'' - this gets us a list of files matching some pattern ("*.tcl" for instance) * ''file'' - this allows us to get all kinds of properties of the files (like the time of creation) and to manipulate file names, should that be necessary * ''cd'' - this allows us to change directory (we can "descend" the directory tree) (and then of course things like if and puts, but these are so basic, they belong to the language. Strictly speaking they are not a part of the ''definition'' of Tcl! But let us not get too side-tracked here) A very first version: '''4. Adding a GUI''' '''5. A library example''' '''6. Platform issues''' '''References''' ---- Bob Clark - cover some of the tcl library please, and for readers expecting object orientation (presumably most of them), a treatment of snit (and/or others) would be very useful. At least point out libraries like http and ftp as a wealth of wheels that don't need reinvention. [AM] Noted! ---- [[ [Category Tutorial] ]]