<<
Web::Definitions - defines constants in use throughout the Web::Chain project.
use Web::Definitions qw($DF_DESTINATION_RULE);
unless( $name =~ qr/$DF_DESTINATION_RULE/ ) {
die "$name is not a well-formed DF node name";
}
This is a configuration file for the Web::Chain project (which is used for DF work).
The "constants" defined here are now in the form of upper-case variables (see STYLE discussion below).
This module uses a system that automatically adds candidates for export to the EXPORT_OK list. This system exports:
1. all constants
2. all *_RULE (or *_rule) variables (declared with 'our')
3. all UPPERCASE variables (declared with 'our')
The :all tag can be used to import all exports from this file:
use Web::Definitions qw(:all);
though this is not recommended.
It's better to just import the ones you need, chosen from the following:
- $DF_VERSION - project wide version number.
- $DEBUG - project wide debug flag, turns on lots of excessively verbose reporting, all sent to STDERR.
- $DOOM_HOME - home directory of user doom (sometimes this is better than playing with $ENV{'HOME'} because it doesn't change if the script is run as root).
- $DF_LOC - location of DF html in staging area (the finished product)
- $DOOM_THOUGHTS - default source location of DF nodes in progress (rawtext) The alternate name $DF_RAWTEXT is also available.
- $DF_PUSH_RSYNCH_TARGET - rsync target for pushing the entire project directory out to the public site
- $DF_PUSH_SCP_TARGET - target for individual file transfer (via scp, or "rsync *.html" rather than "rsync <dir>").
- $DF_THOUGHTS_TEMP_LOC - bone pile to toss use rawtext files after adding to the df html site.
- $DF_TOPNODE_NAME - standard name for the first node in the linked-list of DF files.
- $DF_BOTNODE_NAME - standard name for the last node in the linked-list of DF files.
- $DF_CONTENTS_NODE_NAME - another standard name for a "special node": a table of contents of all existing nodes in the DF project (this is an automatically generated node).
- $DF_WHATSNEW_NODE_NAME - another standard name for a "special node": this is an inverse chronological change log. Additions to it are generated automatically, but manual annotations are expected.
- $DF_WHATSNEW_NOW_MARKER - a special marker string that should always exist in a comment near the top of WHATSNEW.html. This marker is searched for when automatically adding additions to the file.
- $DF_NEW_NODES_LOG - standard file that new additions to the DF project were once logged to (this practice is being phased out).
- $df_node_name_quantified_pat - this variable is essentially the central definition of what constitutes a valid "doomfiles node" name. These names must be at least three characters long, and typically will be in all UPPER_CASE with underscores as separators though hyphens and numerics are allowed, as well as the lower-case 'c' (which allows names like McCLAUREN). This variable is not exported as is, but is used by a number of regexp rules below which are. Example allowed node name: McCELTIC-AMERICAN_SOUL_7
- $DF_NODE_NAME_RULE - doomfiles node name pattern, without any pinning at the beginning or end (with '^' or '$'). This is the regexp rule equivalent of $df_node_name_quantified_pat.
- $DF_NODE_NAME_PINNED_RULE - doomfiles node name pattern, pinned at both ends (used for verifying that a string contains a valid node name and nothing else).
- $DF_DESTINATION_RULE - doomfiles node name pattern, pinned at the beginning of the string via '^'. Used to extract a node name from a body of text when it is up against the left margin, the right side is pinned with zero-width lookahead for \s and/or $, the eol. This right side pinning is better than simple greedy matching, because it avoids a minor problem with false positives. In the case of "FALSE*NAMES", it should not capture "FALSE", but instead report that it doesn't see a valid match there.
- $DF_GENERAL_NAME_RULE - A simple, very liberal rule, matches both links and destination labels
- $doomfiles_thoughts_node_separator_pat - detects a line that consists of a bar equal signs beginning in the first column, ('==='). This is used in the "rawtext" doomfiles format to indicate the end of a node. Used by the $DF_END_RULE below.
- $DF_THOUGHTS_LINK_RULE - Tries to identify links embedded in the rawtext source files (sometimes called "Thoughts") without getting confused by incidental use of uppercase strings in the text. Doomfile-style links are distinguished by the whitespace that surrounds them, roughly, at least two spaces before and behind, where the end of the line (and possibly the beginning?) can be thought of as a chunk of virtual spaces. (Getting this to work right on all corner cases is a a suprisingly difficult problem.) This version is a quickie that has bugs in identifying a link near the end of the line without trailing spaces. It keeps things simple by capturing leading and trailing spaces as well as the link, using it in a s/// requires building a replacement version with $1 $2 $3.
- $DF_EMBEDDED_LINK_SINGLE_CAPTURE_RULE - Tries to identify links embedded in the rawtext source files (sometimes called without getting confused by incidental use of uppercase strings in the text. Doomfile-style links are distinguished by the whitespace that surrounds them, roughly at least two spaces before and behind, where the end of the line (and possibly the beginning?) can be thought of as a chunk of virtual spaces. (Getting this to work right on all corner cases is a a suprisingly difficult problem: I'm willing to compromise on the left hand boundary, and say "no links allowed without at least two spaces from the left margin", but getting the right side to work right could be a problem.) This is much like $DF_THOUGHTS_LINK_RULE, except that this version is an attempt at capturing *only* the link itself to $1, using zero-width patterns to identify the whitespace. Also, this pattern is intended to more cases.
- $DF_EXTRACT_NEXT_NODE_RULE, $DF_EXTRACT_PREV_NODE_RULE, $DF_EXTRACT_BODY_RULE - These rules are used to scrape the "next node" and "previous node" and the main body of content out of the finished DF html files.
- $DF_EXTRACT_TITLE_RULE, $DF_EXTRACT_H1_RULE - These are patterns to extract <TITLE> and <H1> strings, out of finished DF html files.
- $DF_THOUGHTS_NODE_HEADER_RULE - Using this in a qr//msg should extract all the new doomfiles nodes in a Rawtext (aka 'Thoughts') file. (Currently not used).
(1) Avoid creating a lot of built-up definitions to be exported. E.g. something like this isn't a good idea:
our $DF_TOPNODE = $DF_LOC . '/' . $DF_TOPNODE_NAME . '.html';
Because code that uses this $DF_TOPNODE can't be tested very well. It will always access the live location $DF_LOC. Better to do this sort of build-up in the code that uses these definitions, where $DF_LOC can be replaced by a debug location on the fly.
(2) Use names like "*_pat" for strings that contain regular expressions, and "*_RULE" for actual regexp objects created with qr{}. Export all "*_RULE"s automatically.
(3) Actually, this module automatically exports all variables with names all in uppercase. Using uppercase variables as (pseudo) constants lessens the chance of collision with other variables. And it makes the exports visually resemble constants even though they're not.
Perl constants have little going for them: their only real advantage is the compiler can optimize them to inlines.
Well, there's also the fact that they're constant and putting a value into that kind of straight-jacket might help prevent a shoot-yourself-in-the-foot problem, but unlike most such things in perl, there is no easy way to escape the straight-jacket later if you really need to. There is no: {no strict 'constants' ... }
It's an odd thought, but it isn't really unusual to want to temporarily change a "constant" e.g. over-ride a project-level $DEBUG flag, setting it temporarily just for the current module.
Also on the negative side, constants don't really interpolate, not even if you try fugly tricks like:
print "My constant: &CONSTANT() \n";
Though, if you want to get even fuglier, you can do this:
print "My constant: @{[ CONSTANT ]} \n";
Why use perl at all if you're going to, uh, constantly do things like this:
print "My constant: " . CONSTANT . "\n";
So: I've stopped using (and exporting) constants.
Project Documentation
Joseph Brenner, <doom@kzsu.stanford.edu>
Copyright (C) 2004 by Joseph Brenner
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.
None reported... yet.
<<