#!/usr/bin/env perl
#=--#-============================= the SITE of NAMING
    #                             - this file best read whilst 
#--=#-============================- =------------------------------------------=
package CGI::Madarch;                                   use strict; use warnings;
                                                       use our_package_contents;

=head1 NAME

...+name.cfg - 

=cut

#                             ::
#\:::::::::::::::::::::::::::::: the NAMING :::::::::::::::::::::::::::::::::::
#                              :                                              :
=head1 NAMING FILES

We recommend you name your site's paths and files according to rather arbitrary
convention. Should you care to understand these conventions, you may rename the
files and paths of your site to them, and thereby benefit. These are:

    [one] a mandatory path-name--the absolute path to which this name belongs
    [two] an optional "cardinal", a collating numeral, followed by a <=> sign
  [three] an optional "prenomen", a short descriptive title
   [four] an optional "cognomen", a large description, preceded by a <|> pipe
   [five] an optional file-type--this file-extension--preceded by a <.> dot

We suppose, then, that you would prefer an example. Here, we have three:

           /the/world/about/me/01=always|run_beneath_the_urge/
           /the/world/about/me/12=verify|we_splurge_though_lo/
           /the/world/about/me/77=to_fly|we_surge_to_acids_hi.ergo
           {---------1--------}{2}{--3-}{---------4---------}{-5-}

We describe these conventions, below.

=head1 NAMING CONVENTIONS

We apply the optional "cardinal" as a means of collating this file against its
neighbors. A path-name "spring", for example, collates later than an "autumn",
unless you rename your "spring"--"01.spring".

We allow you conveniently embed whitespace in both the "prenomen" and "cognomen"
by embedding underscores instead, which we convert as we see them--as need be.

We elect the <=>, <|>, and <_> characters as our name-identifiers, as these are
the digital signs which no analogue book, or poetry, or other printed faire may
brook. These <=>, <|>, and <_> characters will not appear in prenomens, cognomens,
or other printed names and words; there can be no damage in their use.

We avoid conflict where we can.

=head1 NAMING DISPASSIONS

We allow you parse flat path- and file-names to and from constituent hashes.
They provide your:

   (
      path    => "this file or path's absolute path-parent",
      prenomen => "this file or path's title",
      cognomen => "this file or path's title-summary",
      cardinal => "this file or path's order-cardinal",
      type    => "this file's type--if a file",
   );

=head1 NAMING CONFESSIONS

We have a string of benefits, and strings of detnaoint. We benefit, by:

   [one] collating path-names
   [two] entitling path-names, without tainting path-name order
 [three] commenting path-names without tainting path-name order or titles
  [four] eliminating the necessity for external meta-data files
   
We do detract! By congealing our meta-data into path- and file-names themselves,
we exacerbate the already common ills of off- and on-line link-breaking. Since
we embed meta-data into names, we cannot change meta-data without moving files;
we break, thereby, their site-internal symbolic-links and external other sites
who link to them.

We do detract. We break the world, when it changes.

=head2 forge_name_syntax

We build the name-syntax--the grammar your site's path-names may adhere to.

01=epistle|to_a_blade`.poem

=cut
BEGIN {
   my $flow = {
      sorts => [ qw(path cardinal prenomen cognomen type) ],
      east => {
         path    => q{/},
         cardinal => q{=},
      },
      west => {
         cognomen => q{|} ,
         type    => q{`.},   # `
      },
      feeds => {
         path    => true,
#        prenomen => true,
      },
      needs => {
         prenomen => true,
      },
   };
   
   sub forge_site_name_settings() {
       forge_flow_for $flow;
   }
   
   sub forge_name_hash_for($) {
      my $name = forge_flow_hash_for $flow => shift;
   
      foreach             my $part qw(cardinal prenomen cognomen) {
         if (defined $name->{$part}) {
                     $name->{$part} =~ tr~_~ ~;
         }
      }
   
      return $name;
   }
   
   sub forge_name_lace_for {
      my $name = forge_call_hash_for \@_;
   
      foreach             my $part qw(cardinal prenomen cognomen) {
         if (defined $name->{$part}) {
                     $name->{$part} =~ tr~ ~_~;
         }
      }
   
      return forge_flow_line_for $flow => $name;
   }
}

#                             ::
#\:::::::::::::::::::::::::::::: the MAIN :::::::::::::::::::::::::::::::::::::
#                              :                                              :
forge_site_name_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
 
=cut