diff --git a/tconfpy.3 b/tconfpy.3 index 247c6b3..b98b929 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -20,130 +20,32 @@ of configuration file parsing and validation, while providing your users a rich set of configuration features. +.SH DOCUMENT ORGANIZATION -.SH INSTALLATION -There are three ways to install \*(TC depending on your preferences -and type of system. In each of these installation methods you must be -logged in with root authority on Unix-like systems or as the -Administrator on Win32 systems. +This document is divided into 4 major sections: -.SS Preparation - Getting And Extracting The Package +.B PROGRAMMING USING THE \*(TC API +discusses how to call the configuration file parser, the options +available when doing this, and what the parser returns. This is +the "Programmer's View" of the module and provides in-depth +descriptions of the API, data structures, and options available to +the programmer. +.B CONFIGURATION LANGUAGE REFERENCE +describes the syntax and semantics of the configuration language +recognized by \*(TC. This is the "User's View" of the package, but +both programmers and people writing configuration files will find this +helpful. -For the first two installation methods, you must first download the -latest release from: +.B ADVANCED TOPICS +describes some ways to combine the various \*(TC features to +do some fairly nifty things. -.nf - http://www.tundraware.com/Software/tconfpy/ -.fi - -Then unpack the contents by issuing the following command: - -.nf - tar -xzvf py-tconfpy-X.XXX.tar.gz (where X.XXX is the version number) -.fi - -Win32 users who do not have tar installed on their system can find -a Windows version of the program at: - -.nf - http://unxutils.sourceforge.net/ -.fi - - -.SS Install Method #1 - All Systems (Semi-Automated) - - -Enter the directory created in the unpacking step above. Then issue -the following command: - -.nf - python setup.py install -.fi - -This will install the \*(TC module and compile it. - -You will manually have to copy the 'test-tc.py' program to a directory -somewhere in your executable path. Similarly, copy the documentation -files to locations appropriate for your system. - - -.SS Install Method #2 - All Systems (Manual) - - -Enter the directory created in the unpacking step above. Then, -manually copy the tconfpy.py file to a directory somewhere in your -PYTHONPATH. The recommended location for Unix-like systems is: - -.nf - .../pythonX.Y/site-packages -.fi - -For Win32 systems, the recommended location is: - -.nf - ...\\PythonX.Y\\lib\\site-packages -.fi - -Where X.Y is the Python release number. - - -You can pre-compile the \*(TC module by starting Python interactively -and then issuing the command: - -.nf - import tconfpy -.fi - -Manually copy the 'test-tc.py' program to a directory -somewhere in your executable path. Copy the documentation -files to locations appropriate for your system. - - -.SS Install Method #3 - FreeBSD Only (Fully-Automated) - - -Make sure you are logged in as root, then: - -.nf - cd /usr/ports/devel/py-tconfpy - make install -.fi - -This is a fully-automated install that puts both code and -documentation where it belongs. After this command has completed -you'll find the license agreement and all the documentation (in the -various formats) in: - -.nf - /usr/local/share/doc/py-tconfpy -.fi - -The 'man' pages will have been properly installed so either of these -commands will work: - -.nf - man tconfpy - man test-tc -.fi - -.SS Bundling \*(TC With Your Own Programs - - -If you write a program that depends on \*(TC you'll need to ensure -that the end-users have it installed on their systems. There are two -ways to do this: - -1) Tell them to download and install the package as described above. - This is not recommended since you cannot rely on the technical - ability of end users to do this correctly. - -2) Just include 'tconfpy.py' in your program distribution directory. - This ensures that the module is available to your program - regardless of what the end-user system has installed. - - +.B INSTALLATION +explains how to install this package on various platforms. This +information can also be found in the \'READ-1ST.txt\' file distributed +with the package. .SH PROGRAMMING USING THE \*(TC API @@ -153,13 +55,39 @@ options available when doing so, and what the parser returns to the calling program. +One small note is in order here. As a matter of coding style and +brevity, the code examples here assume the following Python import +syntax: + +.nf +from tconfpy import * +.fi + +If you prefer the more pedestrian: + +.nf +import tconfpy +.fi + +you will have to prepend all references to a \*(TC object with +\'tconfpy.\'. So \'retval=ParseConfig(...\' becomes +\'retval = tconfpy.ParseConfig(...\' and so on. + .SS API Overview The \*(TC API consists of a single call. Only the configuration file to be processed is a required parameter, all the others are optional and default as described below: .nf -.B retval = ParseConfig(cfgfile, InitialSymTbl={}, AllowNewVars=True, AllowNewNamespaces=True, Debug=False, LiteralVars=False) +from tconfpy import * + +retval = ParseConfig(cfgfile, + InitialSymTbl={}, + AllowNewVars=True, + AllowNewNamespaces=True, + Debug=False, + LiteralVars=False + ) where: @@ -167,9 +95,9 @@ The the name of a file containing configuration information .B InitialSymTbl - A pre-populated symbol table. Defaults to an empty symbol table. As - described below, this must contain valid \'VarDescriptor\' entries - for each symbol in the table. + A pre-populated symbol table (a Python dictionary). Defaults to + an empty symbol table. As described below, this must contain + valid \'VarDescriptor\' entries for each symbol in the table. .B AllowNewVars Allow the user to create new variables in the configuration @@ -554,6 +482,133 @@ .SS Enforcing Mandatory Configurations +.SS Iterative Parsing + + +.SH INSTALLATION +There are three ways to install \*(TC depending on your preferences +and type of system. In each of these installation methods you must be +logged in with root authority on Unix-like systems or as the +Administrator on Win32 systems. + + +.SS Preparation - Getting And Extracting The Package + + +For the first two installation methods, you must first download the +latest release from: + +.nf + http://www.tundraware.com/Software/tconfpy/ +.fi + +Then unpack the contents by issuing the following command: + +.nf + tar -xzvf py-tconfpy-X.XXX.tar.gz (where X.XXX is the version number) +.fi + +Win32 users who do not have tar installed on their system can find +a Windows version of the program at: + +.nf + http://unxutils.sourceforge.net/ +.fi + + +.SS Install Method #1 - All Systems (Semi-Automated) + + +Enter the directory created in the unpacking step above. Then issue +the following command: + +.nf + python setup.py install +.fi + +This will install the \*(TC module and compile it. + +You will manually have to copy the 'test-tc.py' program to a directory +somewhere in your executable path. Similarly, copy the documentation +files to locations appropriate for your system. + + +.SS Install Method #2 - All Systems (Manual) + + +Enter the directory created in the unpacking step above. Then, +manually copy the tconfpy.py file to a directory somewhere in your +PYTHONPATH. The recommended location for Unix-like systems is: + +.nf + .../pythonX.Y/site-packages +.fi + +For Win32 systems, the recommended location is: + +.nf + ...\\PythonX.Y\\lib\\site-packages +.fi + +Where X.Y is the Python release number. + + +You can pre-compile the \*(TC module by starting Python interactively +and then issuing the command: + +.nf + import tconfpy +.fi + +Manually copy the 'test-tc.py' program to a directory +somewhere in your executable path. Copy the documentation +files to locations appropriate for your system. + + +.SS Install Method #3 - FreeBSD Only (Fully-Automated) + + +Make sure you are logged in as root, then: + +.nf + cd /usr/ports/devel/py-tconfpy + make install +.fi + +This is a fully-automated install that puts both code and +documentation where it belongs. After this command has completed +you'll find the license agreement and all the documentation (in the +various formats) in: + +.nf + /usr/local/share/doc/py-tconfpy +.fi + +The 'man' pages will have been properly installed so either of these +commands will work: + +.nf + man tconfpy + man test-tc +.fi + +.SS Bundling \*(TC With Your Own Programs + + +If you write a program that depends on \*(TC you'll need to ensure +that the end-users have it installed on their systems. There are two +ways to do this: + +1) Tell them to download and install the package as described above. + This is not recommended since you cannot rely on the technical + ability of end users to do this correctly. + +2) Just include 'tconfpy.py' in your program distribution directory. + This ensures that the module is available to your program + regardless of what the end-user system has installed. + + + .SH OTHER