pconfig v1.0 - Aaron D. Marasco <Aaron@Marasco.com> Released 9 May 2001 - http://www.fireparse.com

OVERVIEW

"pconfig" is a perl script to set up... perl scripts! Allows a perl script's configuration information to be included within the script for no need for external files. Controlled by internal comments within the script itself (the target script). The output script is also pconfig compatible (if renamed to .pc) to reconfigure if required. What's the use? Read the HISTORY section below.

HISTORY

I am the author of a few other perl scripts, some GPL, some not. Two of them are designed to (try to) be as fast as possible. This is especially true for net-check since it is designed to be run every fifteen minutes. If these programs were required to read a configuration file, parse it, and then verify the options EVERY TIME THEY RAN, it would end up being some serious wasted processor time.

So I put the configuration in the beginning of the scripts. The data is there with no extra effort.

When I released the first version of fireparse, I got e-mail like crazy. Why? I accidentally left MY e-mail address in there as the report destination! Oops...

So I decided to write pconfig to be an external program that would set up fireparse and handle (some) sanity checking along the way. Figuring it may help other people (that's why fireparse was first released), I made pconfig fairly generic.

FUTURE

It works as much as I need it. So unless other programmers need something more, I think it's pretty much set as far as it needs to.

USE

pconfig works on comments within the original source. It takes in a file with an extension of '.pc' and converts it to a working '.pl' perlscript. It has been tested on the following systems: 5.005_03 built for ppc-linux
v5.6.0 built for MSWin32-x86-multi-thread

A demo file is included (pconfig_ex.pc) that shows some tags. A more involved example is any version of fireparse version 2.4 or beyond.

The comments it looks for are double-hash (##) to begin with. There are four possible lines for it to read: 1. Plain comment - ignored
2. Double-hash description - append to description 3. Double-hash PCONFIG directive - must handle appropriately 4. The actual thing (constant or variable) that is being configured

Plain comments - these are single-hash regular ol' perl comments.
Double-hash description. If the keyword "PCONFIG" doesn't come after the double-hash it is assumed to be a description of whatever variable or constant that is coming up next.
PCONFIG directives - the easiest way to describe these are a quick reference and the included example file. Be sure to read the 'SINGLE' section below.

BEGIN / END

Variables are required to be divided into "blocks." The blocks are delimited by BEGIN and END. Each block must be named on the BEGIN line, and it is optional for the END line (it is ignored - NOT verified!). Anything following the block's name will be displayed to the end user when they are asked if they want to (re)configure that section. Here's an example:
--
#PCONFIG BEGIN NORMAL Main settings, the only section that MOST users need to configure #PCONFIG END
Execution result:
Beginning block named NORMAL
Main settings, the only section that MOST users need to configure Do you want to modify settings within this block? [Y/n] --
Every statement MUST be contained within a block with the exceptions of the BEGINning of a new block or the STOP directive.

STOP

##PCONFIG STOP
Tells pconfig to stop parsing the file and just dump what's left. This is HIGHLY recommended because of the overhead involved in parsing each line.

Within the blocks the following commands are recognized:

ACCEPT / REJECT

##PCONFIG ACCEPT ^\w+\@(\w+\.)+\w+$
#PCONFIG REJECT ^http:\/\/
#PCONFIG REJECT \/$
In my humble opinion, the most powerful aspect of pconfig. The entry is a perl regular expression that can check the data being input. By default, anything is allowed except a totally blank line (which can be overridden by an ACCEPT clause). The order of the parsing is to check all ACCEPTS then all REJECTS. So even if something passes an ACCEPT filter, it can still be later rejected. You can have as many of these for each entry as you'd like. All regular expressions are cleared once the entry has been completed. Don't put any delimiters around the regular expression, that is handled internally.

IGNORE

##PCONFIG IGNORE
The next variable declaration will be ignored. Ignored means that pconfig will not parse it nor prompt the user for a value.

SINGLE

##PCONFIG SINGLE
By default, a variable is surrounded by double-quotes (with an optional 'my' before it). The format is either of these (whitespace can be variable):
my $html_TITLE_val = "Firewall Report"; $variable = "Howdy!;
If there is a "my" before it, it will be retained. The 'SINGLE' flag indicates that the variable has single quotes around it, meaning perl won't parse it later (good for e-mail):
my $mailto = 'aaron@marasco.com';

CONSTANT / CONSTANTNOQ

#PCONFIG CONSTANT
or
#PCONFIG CONSTANTNOQ
Similar to the SINGLE flag, it indicates that the assignment is a constant. "Normal" constants must be written in this manner:
use constant internalnet => '192.168.1.'; with a single quote implied. For no quotes, use CONSTANTNOQ, as shown: use constant verbose => 0;

PREFIX / POSTFIX

#PCONFIG PREFIX --
PCONFIG POSTFIX --
These flags force an input to start with, or end with, a certain string. After the user enters a value, if the PREFIX or POSTFIX are not present, they are automagically added before any ACCEPT or REJECT statements are handled. Here's an example for HTML color code: --
PCONFIG CONSTANT
PCONFIG ACCEPT ^[A-F0-9]{6}$
##PCONFIG PREFIX #
# What color should the table backgrounds be? use constant tablecolor => 'FFFFD0';
--
So the user could enter either 'F0F0F0' or '#F0F0F0' without incident. The PREFIX/POSTFIX are most useful for NAKED entries. The PREFIX and POSTFIX don't need to have escaped sequences (see example in NAKED).

NAKED

#PCONFIG NAKED
A 'NAKED' perl line is not a variable or constant but any other customizable perl line. Here is a complete example, to illustrate:
--
PCONFIG IGNORE
my $date;
#PCONFIG NAKED
#PCONFIG PREFIX chomp($date = `/bin/date + #PCONFIG POSTFIX `);
## Your 'date' formatting. Set the display options like you want from 'man date'. ## Default of %m-%d-%Y is more "American" but also sorts by subject nicer IMHO. ## Only put what goes after the "+". The value you enter is not verified! chomp($date = `/bin/date +%m-%d-%Y`);
-- Output:
Your 'date' formatting. Set the display options like you want from 'man date'. Default of %m-%d-%Y is more "American" but also sorts by subject nicer IMHO. Only put what goes after the "+". The value you enter is not verified!

Current value is: %m-%d-%Y
Change it? [y/N]
--
As you can see, the PREFIX and POSTFIX are pretty much required, unless you want the end user to add semicolons at the end, etc.

REQUIRE

##PCONFIG REQUIRE
When a user runs pconfig, they are asked if they want to configure a specific block or not. If they don't want to, but there are a few extremely important questions, then the REQUIRE tag makes the remainder of the block "un-skippable." Obviously, this kinda harasses the end user, so use it sparingly. You can optionally specify "ONCE" after REQUIRE to have pconfig remove that line from the resulting code.

FINISH_NOTE

##PCONFIG FINISH_NOTE There is very primitive log clean-up stuff for very advanced users, ##PCONFIG FINISH_NOTE but it requires editing the fireparse executable itself. This text (as many lines can be entered as you would like) will be displayed when the pconfig block is ENDded. This is only displayed if the block is executed by the end user (or the block was REQUIREd).

ANNOUNCE

##PCONFIG ANNOUNCE ################################## ##PCONFIG ANNOUNCE # Configuration is complete! #PCONFIG ANNOUNCE ################################## The ANNOUNCE statement is similar to the FINISH_NOTE but is blindly processed and printed regardless of the user's choice in configuring a block. The perfect place would be at the end of the last block.

LICENSE

pconfig is distributed under the GNU GPL v2. The file "LICENSE" is included in the distribution.

DISTRO

If you would like to archive this software on a distributed CD, web site, FTP site, or any other public means, please be so kind as to notify the author. If you are linking to my distribution page, I would appreciate the same.

If you use pconfig for your application, please do not modify the headers or the name, so that people will know the original author and can find the full distribution if they would like to. This file 'README' does NOT need to be included in your distribution.

The recommended way to include it in your tar file is to create a mini-script 'configure' that contains the single line:
./pconfig.pl your-script.pc
since many people are accustomed to typing "./configure" when they see that executable.