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


=head1 NAME

...+furl.cfg

=head1 SYNOPSIS

#                             ::
#\:::::::::::::::::::::::::::::: the FURLING ::::::::::::::::::::::::::::::::::
#                              :                                              :
=head1 FURLING MADARCH

We expose server-side paths and files to client-side browsers by converting
these paths and files into URLs. However, as a purer means of circumventing the
dead-weight of cookies, caches, and other data-inelegances of other CMS systems,
we expose severely altered URLs--which we've named Friendly URLs [FURLs], which
we infuse with our present user-requested flavours, modes, tones, zones, and...

We expose the FURL through a syntax-delimited sequence of "parts". These are:

    [one] a mandatory "host", the fully-qualified host-name
    [two] an optional "path", the host's path, preceded by a <`> tick
  [three] a mandatory "head", the FURL header, declared with <-==>
   [four] an optional "mode", the wanted mode, preceded by a </> comma
   [five] an optional "tone", the wanted tone, preceded by a <:> colon
    [six] an optional "flav", the wanted flav, preceded by a <;> colon
  [seven] an optional "zone", the wanted zone, preceded by a <|> pipe
  [eight] a mandatory "head", the FURL header, declared with <==->

We suppose, then, that you would prefer an example. This is:

 http://arwest.of.avinor/`the`path`to`autumn.is-==/surf:html,gwy+dd|english==-
 {-----------1----------}{----------2---------}{3}{-4-}{--5--}{-6-}{---7--}{8}       

We describe these conventions, below.

=head1 FURLING DISPASSIONS

We allow you parse your URL-ish FURL-strings to and from constituent hashes.
They provide your:

   (
      host => "a string having this FURL's fully-qualified host-name",
      path => "the path or file on the host you wish us to make a page from",
      flav => "the type of the file or page you wish us to make",
      mode => "the type of transformation you wish to perform on this page",
      tone => "the name of the theme you'd like us to print content with",
      zone => "the name of the language or dialect to print content in",
   );

We plead you arrange its path-part in a peculiar fashion, if you pass a path.
We plead you combine the pieces of this path with a *nix </> slash--regardless
of platform, preferences, or hereditary predilection.

We build you your FURL-string by copying the FURL your present user requests
into a local hash, and then over-writing the contents of this hash with your
passed hash.

We find this makes for often pleasant--occasionally unpleasant--side-effects.
Effectively, these are:

   [one] you needn't pass those parts for which the present FURL is fine;
         you needn't pass us a "host", for example, as this FURL's "host" is OK
   [two] you need pass us those parts for which the present FURL is not fine;
         you need pass us your "flav", for example, as this FURL's "flav" is
         often an un-fine default

We find this makes for a pleasant alternative to cookies, caches, and such.

=head1 FURLING CONFESSIONS

We deprecate the lay, every-day URL. It pollutes its space with punctuation and
fallow heaps of value-abbreviations. It obscures its purpose; as such, your
users shall not remember your URLs, nor their minute purpose. It: 

    [one] separates path-name pieces with </> slashes
    [two] separates script-variables with <,> commas
  [three] separates script-variables from their data-values with <=> signs
   [four] separates script-variables from the script-name with a <?> mark

We stiffen at such effrontery. You, who are the castelain of the online keep,
have cause to bristling anger, too. Homepages are a home; URLs, their garden.
They each reflect their denizens. The unkempt homes and gardens breed contempt.

We stiffen at that. Are you kept, and shoddy, are or in your strive?

=head1 FURLING DEVOLUTIONS

We devised the FURL as a circumvention about the banal paths of URLs and URIs.
We surmise that, after befriending your URLs into FURLs, you may not use URLs
at all--anymore.

We recognize but one and one reasons to use a URL over a FURL: URLs unshutter
truth. FURLs direct their friends--your users--into this script that executes
another script that executes another that generates this final scrap of HTML.
Truth? FURLs shadow the truth. They cover the raw structure of server-side
paths, the contents of server-side, raw text files, and scripts that serve the
pages. This is, of course, the FURL raison d'etre.

We recognize that truth and open discourse have their place. At that, we serve
you the "sift"--the flavour opening your paths and files as pages to the users,
who sift as if with FTP.

We recognize, though, that Western truth is property and reeling fences far.

We recognize! Your limbs are yours, and words the limbs by which you tender.
To tend our truths into a product, you privatize, you purchase, and you own.
Words; bought and sold to fend a living wage.

We hate that.

    "But the price paid for this sort of intellectual pacification,
     is the sacrifice of the entire moral courage of the human mind.
     A state of things in which a large portion of the most active
     and inquiring intellects find it advisable to keep the general
     principles and grounds of their convictions within their own
     breasts, and attempt, in what they address to the public, to
     fit as much as they can of their own conclusions to premises
     which they have internally renounced, cannot send forth the
     open, fearless characters, and logical, consistent intellects
     who once adorned the thinking world. The sort of men who can be
     looked for under it, are either mere conformers to commonplace,
     or time-servers for truth, whose arguments on all great subjects
     are meant for their hearers, and are not those which have
     convinced themselves."
     
     John Stuart Mill.
     
=cut

=head

We build the mappings for FURLs, for labeling the parts your users see.

 our $furl_name_for =
    {a => "hash mapping from FURL-parts to printable, pretty strings"};
 our $furl_part_for =
    {a => "hash mapping from printable, pretty strings to FURL-parts"};

=cut
BEGIN {
    my $flow = {
      sorts => [ qw(host path head plug mode flav tone zone tail flag) ],
      east => {
         host => q{/},
         flag => q[}],
      },
      west => {
         path => q{'},   # '
         head => q{-==},
         mode => q{/},
         flav => q{:},
         tone => q{;},
         zone => q{|},
         tail => q{==-},
         flag => q[{to-],
      },
      feeds => {
         host => true,
         path => true,
      },
      needs => {
         host => true,
         path => true,
         head => true,
         tail => true,
      },
   };

   my $furl_name_for = {
      flav => {
         file => 'file'
      ,  html => 'html'
      ,  pack => 'pack'
      ,  rss  => 'rss'
      },
      mode => {
         sift => 'sift'
      ,  surf => 'surf'
      ,  test => 'test'
      },
      tone => {
         gwy_dd => 'gwy+dd'
      ,  mosaik => 'mosaik'
      , '0_9x'  => '0.9x'
      , '1_0'   => '1.0'
      },
      zone => {
         en => 'english'
      ,  ja => 'japanese'
      },
   };
   my $furl_part_for = evert_hashes_for hash => $furl_name_for;

=head2 forge_furl_syntax

We build the FURL-syntax--the grammar our Friendly URLs adhere to.

=cut
   sub forge_site_furl_settings() {
       forge_flow_for $flow;       
#print "everting produces======== english->$furl_part_for->{zone}->{english}\n";
   }

   sub forge_furl_hash_for($) {
       my $line = shift;
#FIX BWC: generalize this for all the 'needs' elements?
      if ($line =~ m~^http\:\/\/.*?\/$~ox) {
          $line .=
            $flow->{west}->{path}
          . $flow->{west}->{head}
          . $flow->{west}->{tail}
          ;
      }
   
      my $furl = forge_flow_hash_for $flow => $line;

           remap_vals_for(hash => $furl, with => $furl_part_for);
      split_furl_path_for(        $furl);
      split_furl_data_for(plug => $furl);
      split_furl_data_for(flag => $furl);
      stuff_furl_hash_for(        $furl);

#foreach my $part ( @{$flow->{sorts}} ) {
#   print "$part is defined to $furl->{$part}\n" if defined $furl->{$part};
#}

#print "forged furl hash for $line with $flow->{reads} ============ ";
#print " $_=$furl->{$_}" foreach keys %$furl;;
#print "\n";

      $furl
   }
   
   sub forge_furl_lace_for {
      my $furl = forge_call_hash_for \@_;
   
      stuff_furl_hash_for(        $furl);
      unite_furl_data_for(flag => $furl);
      unite_furl_data_for(plug => $furl);
      unite_furl_path_for(        $furl);
           remap_vals_for(hash => $furl, with => $furl_name_for);
   
      forge_flow_line_for $flow => $furl
   }

=head2 stuff_furl_hash_for

We apply our FURL-defaults to the FURL-hash whose reference you pass.

=cut
   sub stuff_furl_hash_for($) {
         my $furl = shift;
            $this_furl ||= $furl;     
   
      $furl->{host} ||= $this_furl->{host};
      $furl->{path} ||= $this_furl->{path};
      $furl->{head} ||= $this_furl->{head};
      $furl->{plug} ||= $this_furl->{plug} || { };
      $furl->{flav} ||= $this_furl->{flav} || 'html';
      $furl->{zone} ||= $this_furl->{zone} || $best_zones->[first_listed];
      $furl->{tail} ||= $this_furl->{tail};
      $furl->{flag} ||= $this_furl->{flag} || { };
   
      if    ($furl->{flav} eq 'html') {
             $furl->{mode} ||= $this_furl->{mode} || 'surf';
             $furl->{tone} ||= $this_furl->{tone} || 'gwy_dd';
      }
      elsif ($furl->{flav} eq 'rss') {
      delete $furl->{mode};
             $furl->{tone} ||= '0_9x';
      }
      elsif ($furl->{flav} eq 'file' ||
             $furl->{flav} eq 'pack') {
             delete $furl->{mode};
             delete $furl->{tone};
      }
      else {
         croak 'We cannot stuff the FURL to ' .
           "@$furl->{@{$flow->{sorts}}}, since"
         . " [We do not recognize its $furl->{flav} flavour].\n"
         ;
      }
   }

   sub split_furl_path_for($) {
      my $furl = shift;
   
      $furl->{path} =~ s~\Q$flow->{west}->{path}\E~/~go;
      $furl->{path} =
         $nave_path
      . ($furl->{path} ? '/' . $furl->{path}
                       : '')
      ;
   }
   
   sub unite_furl_path_for($) {
      my $furl = shift;
   
      $furl->{path} =~ s~^\Q$nave_path\E\/*~~o;
      $furl->{path} =~ s~\/~$flow->{west}->{path}~go;
   }

   sub split_furl_data_for($$) {
      my $part = shift;
      my $furl = shift;
   
      if (
           $furl->{$part}
      && %{$furl->{$part}}
      ) {
         $furl->{$part} = forge_data_hash_for(
            line      => $furl->{$part},
            splitting => {
               pairs_from_pairs_with => qr~\,~,
               keys_from_values_with => qr~\=~,
            },
         )
      }
      else {
         undef $furl->{$part}
      }
   }
   
   sub unite_furl_data_for($$) {
      my $part = shift;
      my $furl = shift;
   
      if (
           $furl->{$part}
      && %{$furl->{$part}}
      ) {
         $furl->{$part} = forge_data_line_for(
            hash    => $furl->{$part},
            joining => {
               pairs_to_pairs_with => q~,~,
               keys_to_values_with => q~=~,
            },
         )
      }
      else {
         undef $furl->{$part}
      }
   }
}

#                             ::
#\:::::::::::::::::::::::::::::: the MAIN :::::::::::::::::::::::::::::::::::::
#                              :                                              :
forge_site_furl_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