README for Nonsense 0.6
=======================
------------
Introduction
------------
Nonsense generates random (and sometimes humorous) text from datafiles and
templates using a very simple, recursive grammar. It's like having a million
monkeys sitting in front of a million typewriters, without having to feed or
clean up after them. From fake Slashdot headlines to absurd college courses to
buzzword bingo cards, Nonsense is a good way to waste time.
Whether this program has any practical applications is open to debate. I use it
to produce the names for characters and places in the fake news articles I
write for Humorix. You might be able to use it as an alternative to fortune(6)
or as a way to add random content to your website.
--------
Examples
--------
Below is a list of the things that Nonsense can output with the datafiles
included in this archive.
For a realistic simulation of the Slashdot homepage:
nonsense -t slashdot.html.template
For a buzzword-enhanced mission statement that only a Pointy Haired Boss
could love:
nonsense -f mission.data
For a PHB-inspired business plan (in HTML):
nonsense -t bizplan.html.template -f mission.data
For a person's name:
nonsense Person
For a long list of random fake email addresses suitable for sending to a
spammer's email harvester:
nonsense FakeEmail -n 1000
For a buzzword bingo card (in HTML) to print out for your next meeting:
nonsense -t bingo.html.template
For a listing of absurd college classes (these might be offensive to
liberal-arts professors):
nonsense -f college.data -n 20
For a listing of political organizations (again, these might be
offensive to certain people):
nonsense OrgPolitical -n 10
For a listing of stupid laws that may or may not really exist:
nonsense -f stupidlaws.data -n 10
For a plausible Linux portal site domain name:
nonsense -f linux.data LinuxDomain
For a list of Open Source programs as they would appear on Freshmeat:
nonsense -f linux.data FreshmeatApp
For a realistic .RDF back-end file for the Freshmeat site:
nonsense -f linux.data -t freshmeat.rdf.template
For the resume of a random geek:
nonsense -f resume.data -t resume.html.template
For a news headline:
nonsense -f newspaper.data Headline
For the front page of a newspaper (in HTML):
nonsense -f newspaper.data -t newspaper.html.template
For a cheap replacement for the Unix fortune(6) program:
nonsense -F Fortune
To produce a file containing 100 items suitable for feeding to fortune(6):
nonsense -F FortuneFile -n 100
------------
How it works
------------
In a nutshell, Nonsense reads in "templates" and "datafiles" (boring terms
that I just made up) and uses the magic of Perl and pseudo-random numbers
to spit out something to STDOUT.
A "template" is merely a text file containing "tags" enclosed in {curly
braces}. Nonsense substitutes random text for these tags using a really
crude markup language.
A "datafile" is a text file divided into sections (seperated by a blank
line), each one containing a list of text items (seperated by a newline)
that are randomly selected to fill in the template.
Let's take an example. Say you have this datafile called
"microsoft.data":
-*-
PRODUCT
{MicrosoftName} {ProductName}
MICROSOFTNAME
Microshaft
Microsloth
Macrohard
Mightgosoft
PRODUCTNAME
Windoze 95
Winblows 98
Windows Not Trustworthy
Winslows Y2K
Bob
LookOut!
-*-
Now let's say you enter "nonsense -f microsoft.data product".
No template file is given here, so Nonsense will assume you want to produce
random text from the given "PRODUCT" section. It picks out one line from the
PRODUCT section, which, in this case, must be "{MicrosoftName} {ProductName}".
This line contains markup, which is recursively parsed: Nonsense picks a random
MICROSOFTNAME (say, Microshaft) and a random PRODUCTNAME (say, Bob) to produce
the final output: "Microshaft Bob".
In short, anything in {curly braces} is replaced by one line from the
matching section in the datafile, which is recursively processed.
There's also a few special cases that allow Nonsense to handle more
elaborate situations:
* {#number1-number2} - Nonsense will replace this tag with a random number
between number1 and number2 (inclusive).
* {[item1|item2|item3...} - Nonsense will pick out one item from this list
(each item is seperated by pipe characters). If only one item
is listed, then it will be output 50% of the time (otherwise
nothing is output)
* {@strftime format} - Nonsense will pass the current date/time to
strftime and return the output. So, for instance, {@%A|0|0} would
return the current day of the week.
* {@strftime format|number1|number2} - Same as above, but uses the
date/time that occured X seconds ago, where X is a random number between
number1 and number2. For instance, {@%H:%M|0|86400} would return the
hour:minute anywhere from 0 to 86,400 seconds (1 day) ago. This is
actually more useful than it might first appear...
* {;short perl code segment} - Nonsense will eval the stuff inside the
braces as a short block of Perl code. This is useful for doing
something really complicated that requires the full power of Perl.
However, this is risky since there's no error checking and no "sandbox".
You can disable this behavior with the -e command line switch (or by
hacking the code).
* {\character} - Allows you to embed literal characters that couldn't
otherwise be specified, such as:
{\n} - Newline
{\0} - Null (i.e. nothing)
{\L} - Left brace '{'
{\R} - Right brace '}'
{\###} - ASCII character in decimal
* {variablename=literal text} - Stores the text on the right-hand
side of the equals sign to the specified state variable, without
outputting anything. This is useful for preserving context and is
used, for example, in the Slashdot simulator.
* {variablename:=command} - Similar to above, but evaluates
the command and stores the result into a state variable.
* {$variablename} - Returns the contents of a state variable.
* {command#number1-number2} - Evaluates the command a random number
of times between number1 and number2
-*-
Case is important! {ProductName}, {productname} and {PRODUCTNAME} are
slightly different. If the name is given in lowercase, the substitution
will be converted to all lowercase (i.e. it's fed through Perl's lc
function) -- so, {productname} might produce "macroshaft".
UPPERCASE names specify the opposite; the result is uppercased with uc.
MixedCase names tell Nonsense to leave the case of the result alone (this
is usually what you'll want to use). Finally, if you prepend a name with
a caret ^ (i.e. {^ProductName}), the result is fed through Perl's ucfirst
function, which will capitalize the first character only.
Did you get all of that? Probably not. While Nonsense is written in Perl
(which is by practice a write-only language), you can still probably
understand the code much better than my rambling explanations.
------------------
Command Line Usage
------------------
nonsense [ -f file.data ] [ -t file.template ]
[ -n number ] [ -p ] [ -b bullet string ] [ -e ]
[ -D | -d ] [ command string ]
-f Specify a data file to load in. Use multiple -f parameters
to include additional files. The default.data file is
is always loaded.
-F Load ALL data files (i.e. all files in the current directory
with a .data extension).
-t Use a template file. The markup in this file will be processed
and the result output to STDOUT.
-n Repeat n times.
-p Separate each item with a blank line (i.e. paragraph break)
-b Specify a "bullet" to go in front of each item.
-e Disable direct eval()'s
-d Debug mode (shows each substituation)
-D Verbose debug mode (shows each substitution and the result)
cmd Instead of specifying a template file, you can just specify
string a section to pull out from the data files.
---------
CGI Usage
---------
Thanks to contributions by Fred Hirsch (truehand@darkhart.com), Nonsense
can now be executed as a CGI script.
The included form.html contains an HTML form (along with predefined links) for
use with Nonsense. You'll need to change the tag in this file
to match the CGI directory where you installed the Nonsense code.
Here are the CGI parameters that Nonsense takes:
template=filename
The template to use. If the template has "html" in
its filename, then the output will be of MIME type text/html,
otherwise it will be text/plain.
file=filename
Specify a single datafile to load
allfiles=1
Load all datafiles from the Nonsense directory
cmd=string
A section to pull out of the datafiles (if you don't use a template)
number=integer
Number of iterations
debug=[1|2]
Set the debug level (1=shows each substition, 2=shows
each substitution and its replacement). The debug information
is hidden as an unobtrusive HTML comment.
standalone=1
Outputs a standalone HTML page (i.e. with and

tags)
instead of just a page fragment
spacer=[p|br|nl|literal string]
Specify a string that is output between each iteration
p is "\n

\n"
br is "\n" (the default)
nl is "\n" only
anything else is treated as a literal (with '\n' converted
into a real newline character)
bullet=[ol|ul]
Displays the text as an ordered list (ol) or an unordered
list (ul)
* Examples:
To output a bulleted list of 20 fortune cookies, the URL would
look something like:
nonsense?cmd=FortuneCookie&file=cookie.data&bullet=ul&number=20
To output a newspaper front page:
nonsense?template=newspaper.html.template&file=newspaper.data
------------
CGI Security
------------
Nonsense is not the most secure program around. If you want to use
this program on a public website, please be careful.
* You can change the source code so that the program will ignore all
CGI parameters. This avoids any chance that the user may pass malicious
parameters designed to crash the system or read arbitrary files.
In the source, set the $ignoreparameters variable to 1. Then, change
the hard-coded defaults. If, for example, you want the program to generate
the Slashdot homepage, replace these lines:
my $template = '{Default}';
my $template_meta = '';
With this one:
my($template, $template_meta) = LoadTemplate('slashdot.html.template');
This will load the Slashdot template in to memory directly. Feel free
to change the other defaults as well.
* You can also wrap the program in a server-side include so that the user
doesn't have direct access to it. The program's output will be inserted
into your webpage using only the parameters that you specify.
------------
Contact Info
------------
This program is written by James Baughn,
nonsense@i-want-a-website.com.
Fred Hirsch (truehand@darkhart.com) and Peter Suschlik (peter@zilium.de)
have both submitted code.
Send suggestions, comments, feedback, patches, and new datafiles/templates
to the above address. Direct your hate mail and flames to
devnull@i-want-a-website.com
(C) Copyright 2000-2001. This program and accompanying files are licensed
under the GNU General Public License 2.0 contained in the obligatory
space-wasting COPYING file.
The homepage for Nonsense is at
http://i-want-a-website.com/about-linux/downloads.shtml
----------
Final Word
----------
Have fun!