#!/usr/bin/env perl #=--#-============================= the APHELION # - this file best read whilst orbiting on on #--=#-============================- =-----------------------------------------= package CGI::Madarch; use strict; use warnings; use our_package_contents; =head1 NAME madarch ----- A renewable content-management system. A cyclic, groweable, scaleable system. A generator of systematic wide-worlds. madarch.cfg - A script configuring site-wide Madarch settings. =head1 SYNOPSIS We supply the web-home to which we are installed with: [one] dynamic generation [the new world] [two] RDF site summaries [RSS] [three] cascading-style sheets [CSS] [four] YAML Ain't Markup Language [YAML] [five] implicit URL-link verification [validation] [six] implicit language localization [zones] [seven] explicit content-types [flavours] [eight] explicit theme styling [tones] [nine] install-less installation [wigi!] [ten] industrial-strength speed [wigi!!] =head1 OBSOLETION In supplying your home its web of fey, we obsolete the following fell technologies: [one] the Apache mod_rewrite module [two] the Perl CGI module [two] the Perl CGI::Carp module [three] the Perl YAML module [four] the Perl File::Find module [five] the Perl HTTP::Request module [six] the Perl MIME::Type[s] module[s] [seven] the Perl XML::RSS module =head1 DESCRIPTION We generate every page dynamically--as the client requests them. We generate every page dynamically. Customarily, your clients get each page as linked ".html" that you've uploaded. We deprecate that custom! The client retrieves no ".html" files, with us; no-o. Oh--instead, they give a path whose files produce ".html" files, run-time. Run! These files are scripts, converting raw-data into ".html", and YAML data-files, through which a script converts its raw-data-- to ".html", or ".rss", or other flavours of the day. Customarily, your clients get each page. Do the grim thing: dispense with custom. =head1 INSTALLATION We recommend you first retrieve our latest distribution from: http://bcurry.gomen.org/`arwest-=:pack=- We recommend you then unpackage the downloading package into: the top-path of your server-side world-readable HTML path [or] one sub-path of this server-side world-readable HTML path We recommend you lastly execute our unpackaged top-level script from a browser. We recommend this, as, on initial execution, this script automatically builds: [one] an ".htaccess" file, whose presence hides ours from browsers' URLs [two] a local "temp", into which we write Madarch-specific temporary data [three] and spurious other needful files and paths We recommend you drive your browser to: http://${host_name}/${pack_path}/arwest/${this_name} Where: [one] ${host_name} is the name of your host [two] ${pack_path} is the path to which you unpackaged Madarch [three] ${this_name} is the name of this script Which, for some "minna.gomen.org" and the first version of Madarch, might be: http://minna.gomen.org/arwest/arwest-adain.cfg =head1 UPGRADE We recommend you not upgrade unless expressly needs an option of the upgrade. We abide, in general, by the axim that: If it ain't broke, don't fix it. We recommend you not upgrade! We refactor Madarch often. This is not necessarily a reflection of our supposed fondness for extreme-programming [XP], but moreso a reflection of our foibles: work-a-holic perfectionism. You should not expect one revision of Madarch to necessarily resemble its antecedents; and, indeed, they rarely shall. By the need to renew, we need--inevitably--to break with rules. You should, as such, expect our revisions to brutally break your site; for we are not a turn-key solution nor adhere we to that want. We allow you, if you must, to upgrade as follows: [one] install Madarch as above [two] manually merge arwest-${old_version}.cfg into arwest-${new_version}.cfg [two] manually rename or copy old-version flavour, mode, or tone scripts that you have made into some new-version equivalents =head1 CUSTOMIZATION We afford you a heavy set of stuff to customize Madarch, and thus the site. These are: [one] redefining script-name syntax [two] redefining path-name syntax [three] redefining FURL syntax [four] renaming our scripts, files, and paths [five] defining additional MIME-type, zone-name, and sink-call mappings [six] leeching additional Perl CPAN modules [ ] creating a symbolic-link to your Perl installed-modules path [ ] creating a Perl script for generating your site's entry-page [ ] creating new flavours--for MIME-types your site dynamically generates [ ] creating new flavour-modes, for sharing content between content-views [ ] creating new flavour-tones, for styling content =head1 COMPLETION We advise that, when customizing your installation, you avoid file- and path- name and -permission inconsistencies. Un-packaging Madarch is effortless; but, customizing all's un-packaged is not. It needs a working, or willing to work, comprehension of our: [one] Perl [two] HTML [three] CSS We expect that, when complete, your server-side path-structure will resemble: > ls -al ~myself/public_html/ total 332 -rw-r--r-- 1 myself nobody 7969 Oct 18 03:15 .cgi -rw-r--r-- 1 myself nobody 1576 Oct 20 06:17 .htaccess lrwxr-xr-x 1 myself nobody 23 Oct 12 01:25 .perl -> ~myself/.perl drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 arwest drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 blog-entries drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 book-rambles drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 link-friends drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 tmp drwxr-xr-x 2 myself nobody 512 Oct 20 06:41 work-resumes > ls -al ~myself/public_html/arwest total 452 -rw-r--r-- 1 myself nobody 60479 Sep 20 10:27 arwest-adain.cfg -rwxr-xr-x 1 myself nobody 60479 Sep 20 10:27 arwest-adain.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:file.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,sift.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,surf.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,gwy+dd.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,gwy+dd.css -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,mosaik.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:html,mosaik.css -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:pack.cgi -rw-r--r-- 1 myself nobody 63500 Sep 19 11:55 arwest-adain:rss.cgi drwxr-xr-x 2 myself nobody 63500 Sep 19 11:55 arwest-adain;util > ls -al ~myself/public_html/arwest-adain\;util total 160 drwxr-xr-x 2 myself nobody 512 Oct 21 05:09 YAML -rw-r--r-- 1 myself nobody 48279 Oct 21 05:00 YAML.pm -rw-r--r-- 1 myself nobody 24864 Oct 21 05:00 YAML.pod -rwxr-xr-x 1 myself nobody 30 Oct 20 09:24 mu =head1 DISCUSSION We explain the above files and paths, thusly: [.cgi] is the Perl script producing the HTML for your site's entry-level page [.htaccess] is the Apache configuration redirecting users to an Madarch script [.perl] is a symbolic-link from your Perl installed-modules path to your site is the path produced by un-packaging Madarch into ~myself/public_html is the script configuring Madarch is the script interfacing Madarch with the CGI environment [ qw(an array reference having the order of parts) ], easter => {a => "hash mapping left-associative parts to separators"}, wester => {a => "hash mapping right-associative parts to separators"}, filler => {a => "hash mapping purely-punctuative parts to punctuation"}, musher => {a => "hash substituting characters of one sort for another"}, feeder => {a => "hash telling which parts greedily consume characters"}, needer => {a => "hash telling which parts must match--must be present"}, defer => {a => "subroutine defaulting all unmatched parts"}, shell => {a => "hash mapping internal part-names to printable names"}, ); We cannot explain it fully enough; but, we can expose some full examples of it. In the examples that follow, we denote: [one] left-associative parts, with an L [two] right-associative parts with an R [three] purely-punctuative parts with a P [four] greedy (.*)?-style parts with a P [five] matching-necessary parts with a P These are: http://harvest.of.sleep/ `lacks`zest -= /inscribed ;in :my |rest =- {---------------------GR}{L---------}{NP}{L--------}{L-}{L-}{L---}{NP} /our/isle/is_a_deadened/ ireland -dreaming ;of_tips_of_white .cgi {---------------------GR}{L-----}{L-------}{L---------------}{L--} We build such formal grammars, dully, as follows: =head2 forge_site_syntaxes We build all syntaxes. =cut sub forge_site_settings() { forge_site_settings_for_mime(); forge_site_settings_for_code(); } =head2 forge_mime_types We build the mapping from W3C-style MIME-type to Madarch-ish flavour-name. =head3 details We name our flavours, typically, from the file-extension of the file-names of the files with which they print their content. We recognize, however, that the sleeping world dreams no stuff of flavours. Theirs are the MIME-type dreams, for the MIME-type is, after all, file-name independent, and therefore harcroakr--though cumbersome--stuff to work with. We encourage, happily, your improvement of this hash. Adjust it as you like, to suite the MIME-types that you like--or simply e-mail us, and we shall do it, to permanence. =cut sub forge_site_settings_for_mime() { $mime_type_for = { rss => 'application/rss+xml' , bz2 => 'application/x-bzip2' , tbz2 => 'application/x-bzip2' , gzip => 'application/x-gzip' , gz => 'application/x-gzip' , tgz => 'application/x-gzip' , cgi => 'application/x-perl' , pl => 'application/x-perl' , pm => 'application/x-perl' , rar => 'application/x-rar-compressed' , tar => 'application/x-tar' , zip => 'application/zip' , mid => 'audio/midi' , midi => 'audio/midi' , txt => 'text/plain' , text => 'text/plain' , css => 'text/css' , htm => 'text/html' , html => 'text/html' , yml => 'text/x-yaml' , yaml => 'text/x-yaml' , link => 'text/x-yaml' , note => 'text/x-yaml' , poem => 'text/x-yaml' } ; $mime_type_for->{'tar.bz2'} = 'application/x-bzip2'; $mime_type_for->{'tar.gz' } = 'application/x-gzip' ; $mime_type_for->{binary} = 'text/binary'; } # :: #\:::::::::::::::::::::::::::::: the CODING ::::::::::::::::::::::::::::::::::: # : : =head1 RENAMING MADARCH We distribute Madarch as a set of files whose names follow our arbitrary naming conventions. If you care to understand these conventions, then you may rename the files the Madarch distribution has. These are: [one] a mandatory "path", the absolute path-name under which it strides [two] a mandatory "name", our package-name--typically "arwest" [three] a mandatory "make", the version-name, preceded by a <-> dash [four] an optional "flav", the flavour-name, preceded by a <;> colon [five] an optional "mode", the content-name, preceded by a <,> comma [six] an optional "tone", the theme's name, preceded by a <:> quote [seven] a mandatory "type", the type of file, preceded by a <.> dot We suppose, then, that you would prefer an example. Here, we have two: /arwest/arwest-adain;html,surf.cgi /arwest/arwest-adain;html:mosaik.cgi {---1--}{--2-}{--3-}{-4-}{-5-}{-7} {---1--}{--2-}{--3-}{-4-}{--6--}{-7} We allow you rename your external files as you see! When, however, you do, we plead you rename our internal, corresponding variable, as well. For example, we build your FURLs on the basis that your HTML-flavour is simply named "html"; when you rename "arwest-adain:html.cgi" to "arwest-adain:hypertextual.cgi", we must ask you also rename our $html_name variable to the "hypertextual" string. We describe these conventions, below. =head1 CODING DISPASSIONS We allow you parse the absolute script-names to and from constituent hashes. They provide your: ( path => "the script's path-name", name => "the script's package-name", make => "the script's version-name", flav => "the script's flavour-name", mode => "the script's content-name", tone => "the script's stylist-name", type => "the script's extension", ); We build you your script-name by: [one] copying the FURL this user requests into a hash [two] over-writing its contents with the present hash of script-name parts [three] over-writing its contents with your passed hash We find this makes for often pleasant--occasionally unpleasant--side-effects. Effectively, these resemble those of "FURLING DISPASSIONS", above. =head1 CODING CONFESSIONS We use renaming to effect a semblance of version-control. By embedding version- names in names, we effectively: [one] allow you install or upgrade several versions within one path without worry of overwriting old or existing versions [two] allow you upgrade into a conflicting version in a timely way, without worry of plunging your site into new-version down-time =head1 CODING NAMES We define the name as, merely, our one-word title. We define our name, by default, as an "arwest". When you rename it, we ask you further rename your install-path from "arwest" to this new name. However, this is all. You need change no Perl variables, at all. =head1 CODING MAKES We define the version as a word synopsizing this release of Madarch. We define our version, for the first release, as example, to "adain". In Welsh, this is a pinion-wing; however, you may not agree with Welsh. Certainly, the British do not. Hence, you may rename it, as you like. Indeed, we apply our version-name so infrequently that you need change little else, if you do re- name versions. Off you go, little one! =head1 CODING TYPES We define the type as the file-extension suffixing our default files. We ask you not change the file-extensions; and, in any advent, there's little benefit in that. =head1 CODING FILES We supply you a slim Perl-script for batch-renaming files, using s///-style regular expressions--rather than the customary glob-style "mv *.e *.gads" command expressions. We name it, simply, mu. You may find it by our utils. =head2 forge_code_syntax We build the code-syntax--the grammar our installed script-names adhere to. =cut BEGIN { my $code_hash_for = { }; my $flow = { sorts => [ qw(home name make flav mode tone ward leaf type) ], east => { home => q{/}, }, west => { flav => q{;}, mode => q{,}, tone => q{:}, ward => q{+}, leaf => q{^}, type => q{.}, }, feeds => { home => true, }, needs => { name => true, type => true, }, }; sub forge_site_settings_for_code() { forge_flow_for $flow; } sub forge_code_hash_for($) { my $line = shift; if (not $code_hash_for->{$line}) { $code_hash_for->{$line} = forge_flow_hash_for $flow => $line; #print "tail_script=" . $code_lace_for->[tail_script] . "\n"; if ( $code_lace_for->[tail_script]->{name} ne $line ) { stuff_code_hash_for($code_hash_for->{$line}); } } $code_hash_for->{$line} } sub forge_code_lace_for { my $hash = forge_call_hash_for \@_; my $line = forge_flow_line_for $flow => stuff_code_hash_for($hash); $code_hash_for->{$line} = $hash; $line } =head2 stuff_code_hash_for We apply our code-defaults to the code-hash whose reference you pass. =cut sub stuff_code_hash_for($) { my $code = forge_call_hash_for \@_; my $this_code = forge_code_hash_for $code_lace_for->[tail_script]->{name}; $code->{home} ||= $this_code->{home}; $code->{name} ||= $this_code->{name}; $code->{ward} ||= $this_code->{ward}; $code->{flav} = $this_code->{flav} if not exists $code->{flav}; $code->{mode} = $this_code->{mode} if not exists $code->{mode}; $code->{tone} = $this_code->{tone} if not exists $code->{tone}; $code->{leaf} = $this_code->{leaf} if not exists $code->{leaf}; $code->{type} = $this_code->{type} if not exists $code->{type}; if ($code->{flav} && ( $code->{flav} eq 'file' || $code->{flav} eq 'pack' ) ) { delete $code->{mode}; delete $code->{tone}; } $code } } # :: #\:::::::::::::::::::::::::::::: the MAIN ::::::::::::::::::::::::::::::::::::: # : : forge_site_settings; 1 __END__ =head1 COPYRIGHT AND LICENSE The information below applies to everything in this distribution, except where noted. Copyright 1980-2005 by B.W.Curry. http://bcurry.gomen.org This file is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This file is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this file; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. =head1 SEE ALSO links -g bcurry.gomen.org & =head1 AUTHOR bcurry at freeshell dot org =head1 ADDING FILES We recommend--though not insist, naturally--that you add the following files: [one] "arwest.html.my.cgi" to your top-path, to generate your site-wide HTML headers, footers, and such; see "arwest.html.gwy+dd.cgi" as example [two] "arwest.html.my.css" to your top-path, to style up your generated HTML headers, and other content; see "arwest.html.gwy+dd.css" as example [three] "index.html.cgi" for every path--top-level or not--in which you'd like us to generate an HTML page; please see "index.html.cgi" as example [five] "index.rss.cgi", for every path [top-level or not] in which you'd like us to generate one RSS feed; please see "index.rss.cgi", as example We suggest you insulate Madarch from the remainder of your site. We suggest, in other words, that you shift the "arwest-" files that you have installed, or shortly will, into their own path--and that you name this path as you have named the "prenomen" for these files. Having done the naming properly, you should see your path- and file-names and -permissions resembling these: our @note_list = qw(the result of "split"-ing $this_furl{note} on "!"-marks); our $note_path = "the result of "join"-ing @note_list with "/"-slashes); We signify an open schema. If you prefer your scheme's in the sandbox of privatized-property, we hope and vent you'll look for other script-stuff. Permittivity is the thing; you could learn to share, a bit. Learn; live; levity. =head1 LOCATING MODULi We insist that Perl locate its modules with the following search order: [one] in "$HOME/.perl/lib", your server-side user-local Perl library [two] in the default server-side system-wide drwxr-xr-x Perl library-- typically "/usr/lib/perl/${perl.version}/". =head1 RENAMING THE PARTERS We define your name-parters as the characters separating, and delineating, the various parts of our installed file-names. We "part" the "prenomen" from its "version", as example, through the <-> comma character. We permit you alter parters as follows: [one] first, adjust our "forge_script_name_grammar" sub, below [two] then, rename your installed script file-names accordingly We recognize that our default name-grammar resembles our default FURL-grammar. However, any resemblances are purely coincidental, and likely the function of laziness. In truth, the grammars with which we parse we parse apart names and FURLs are entirely separate--and changes in one have no bearing on the other. Were adjusting the FURL-grammar to adjust the name-grammar, in a dependent fashion, then you would need rename your files after every fine adjustment of the FURL-syntax. Clearly, this is in poor and bad taste. Clearly, this is all somewhat perplexing. So be it. =head3 details We admit! The "head" and "tail" FURL-parts are strictly synctactic sugar. Pleasant, but purely ASCII-aesthetic bits of psuedo-maybe-art. Therefore, then, we don't need them; if you don't want them, please simply set them empty... We do not delegate to our typical "forge_parser_into_syntax" subroutine, as we cannot; our syntax does not entirely agree with what this subroutine gives. We lack commonality. # Match our optional, extraneous ASCII lead-in string $pattern .= "\^" . ($$dividers{head} ? quotemeta($$dividers{head}) . "?" : ""); # Match our optional, extraneous ASCII lead-out string $pattern .= ($$dividers{tail} ? quotemeta($$dividers{tail}) . "?" : ""); # Brush the hash-header to the head of this string, if defined # $line .= ($furl_dividers{head} ? $furl_dividers{head} : ""); # Brush the hash-tailer to the tail of this string, if defined # $line .= ($furl_dividers{tail} ? $furl_dividers{tail} : ""); # Parse the FURL-string's server-name into our hash # $furl =~ s~$(http\:\/\/.*?\/)~~; # $$hash{host} = $1; # Generate the regular expression for parsing apart such path-names $name_syntax{parser} = qr~^ (.*$$name_syntax{dividers}{cardinal})? # [one] an optional cardinal (.*?) # [two] a mandatory prenomen ($$name_syntax{dividers}{cognomen}.*)? # [three] an optional cognomen $~x; =head1 FURLING FORMATS We permit you customize this syntax, if you like, by custom-changing the definition of the following subroutine. This is: =head1 FURLING DEFAULTS We allow FURLs to leave any or all their parts unspecified. When unspecified, we default these parts, as is sensible, as follows: [one] the default "host" is $ENV{SERVER_NAME}; this is the name Apache sends [two] the default "path" is ""; this defaults root-requests to the root page [four] the default "flav" is "html", HTML: a scheme for mis-information [five] the default "tone" is "gwy+dd", tree: an Madarch theme for HTML [five] the default "tone" is "gwy+dd", tree: an Madarch theme for HTML [six] the default "zone" is "en", English: the common tongue We permit you customize the defaults, if you like, by custom-changing the definition of the following subroutine. This is: our $html_name = "the name we print when referring to our html flavour"; our $rss_name = "the name we print when referring to our rss flavour"; our $file_name = "the name we print when referring to our file flavour"; our $pack_name = "the name we print when referring to our pack flavour"; our $surf_name = "the name we print when referring to our surf mode"; our $sift_name = "the name we print when referring to our sift mode"; our $test_name = "the name we print when referring to our test mode"; our $gwy-dd_name = "the name we print when referring to our surf tone"; our $mosaik_name = "the name we print when referring to our sift tone"; We allow you rename the can think of several reasons to rename--the most noticeable of which is that it permits a mien of version control. You might rename to "arwest-00.cgi", when installing v0.000 of us; you might thus protect your v0.000 installation from over-writing on update, or re-installation, or permit your conditionally selecting one from amongst several installations. We begin, then, with a definition. Your flavour is the tasteful type of file which you--the user--have requested we generate for you. This is one artful means of theming a site, or otherwise altering the content it provide its users, since the flavour needs no artless cookies, inedible JavaScript, or noxious similar DSGXHTML hacks to serve the theme-selection. We'll define a flavour as [more or likely less] also analogous to the W3C's "Content-type" MIME-types, some of which resemble: [one] text/html, your commonplace HTML document [two] text/xml, those commonplace XML documents [three] application/octet-stream, a non-text binary or executed file [four] application/rss+xml, an XML document declaring some RSS feed We implement several flavours, on your behalf. These are: [one] the HTML pages that "arwest.html.cgi" generates [two] the path-lists that "arwest.path.cgi" produces [three] the RSS feed, which "arwest.rss.cgi" engenders =head2 FLAVOURING TO TASTE We permit that you select between flavours by appending the ":html" or ":rss" suffix [as desired] to any otherwise-valid URL; when un-specified, we assume you'd like the customary HTML. If, for example, you specify the following: http://bcurry.gomen.org/-=,.blog http://bcurry.gomen.org/-=,.blog: http://bcurry.gomen.org/-=,.blog:html then you've requested we render this blog in HTML. If instead you specify: http://bcurry.gomen.org/-=,.blog:rss then you've requested we render this blog as, instead, an RSS XML-feed. We define several flavours, by default, which you may find amongst our stuff; traditionally, these are the file-download, path-or-file-archive-then-download, HTML-page, and RSS-feed flavours. We labour, in our routine, to penultimately generate a regular expression resembling this: qr~^ (.*) # the mandatory host-name, followed by $$furl_dividers{wall}? # an optional back-slash separator $$furl_dividers{head}? # an optional-extraneous header ($$furl_dividers{path}.*?)? # an optional path-name specifier ($$furl_dividers{flav}.*?)? # an optional content-type specifier ($$furl_dividers{mode}.*?)? # an optional content-type generator ($$furl_dividers{tone}.*?)? # an optional thematic identifier ($$furl_dividers{zone}.*?)? # an optional language identifier $$furl_dividers{tail}? # and optional-extraneous tailer $ ~x; # with e[x]tensive comments =pod gzip => 'gzip' . ' --fast' . ' --recursive' . ' --quiet' . ' --to-stdout <$source_files> > <$target_file>.gz', arraying => [ qw(prenomen cognomen cardinal path type) ], =head flow string lamina mucosa sheath shroud moeity metier scalar kindor =head1 MAPPING MADARCH We build you a few hashes, whose contents are fairly constant through our life. We welcome--and encourage--you change their contents to suite the inconstancies in modern, site-specific life. We build you these hashes, that we may correlate our internally, overly naive string-constants with your externally, real-world-useable string necessities. We customarily apply these external strings for pragmatic ends--such as printing-to-page, or printing-to-file, or executing-files-from. And, likewise, we customarily apply these internal strings to simplistic uses--often, simply passing them about without the care of having to prettily format them. We build you the following subroutines, to assist in the mapping. These are: =cut