1README for Nonsense 0.6 2======================= 3 4------------ 5Introduction 6------------ 7 8Nonsense generates random (and sometimes humorous) text from datafiles and 9templates using a very simple, recursive grammar. It's like having a million 10monkeys sitting in front of a million typewriters, without having to feed or 11clean up after them. From fake Slashdot headlines to absurd college courses to 12buzzword bingo cards, Nonsense is a good way to waste time. 13 14Whether this program has any practical applications is open to debate. I use it 15to produce the names for characters and places in the fake news articles I 16write for Humorix. You might be able to use it as an alternative to fortune(6) 17or as a way to add random content to your website. 18 19 20-------- 21Examples 22-------- 23 24Below is a list of the things that Nonsense can output with the datafiles 25included in this archive. 26 27For a realistic simulation of the Slashdot homepage: 28 29 nonsense -t slashdot.html.template 30 31For a buzzword-enhanced mission statement that only a Pointy Haired Boss 32could love: 33 34 nonsense -f mission.data 35 36For a PHB-inspired business plan (in HTML): 37 38 nonsense -t bizplan.html.template -f mission.data 39 40For a person's name: 41 42 nonsense Person 43 44For a long list of random fake email addresses suitable for sending to a 45spammer's email harvester: 46 47 nonsense FakeEmail -n 1000 48 49For a buzzword bingo card (in HTML) to print out for your next meeting: 50 51 nonsense -t bingo.html.template 52 53For a listing of absurd college classes (these might be offensive to 54liberal-arts professors): 55 56 nonsense -f college.data -n 20 57 58For a listing of political organizations (again, these might be 59offensive to certain people): 60 61 nonsense OrgPolitical -n 10 62 63For a listing of stupid laws that may or may not really exist: 64 65 nonsense -f stupidlaws.data -n 10 66 67For a plausible Linux portal site domain name: 68 69 nonsense -f linux.data LinuxDomain 70 71For a list of Open Source programs as they would appear on Freshmeat: 72 73 nonsense -f linux.data FreshmeatApp 74 75For a realistic .RDF back-end file for the Freshmeat site: 76 77 nonsense -f linux.data -t freshmeat.rdf.template 78 79For the resume of a random geek: 80 81 nonsense -f resume.data -t resume.html.template 82 83For a news headline: 84 85 nonsense -f newspaper.data Headline 86 87For the front page of a newspaper (in HTML): 88 89 nonsense -f newspaper.data -t newspaper.html.template 90 91For a cheap replacement for the Unix fortune(6) program: 92 93 nonsense -F Fortune 94 95To produce a file containing 100 items suitable for feeding to fortune(6): 96 97 nonsense -F FortuneFile -n 100 98 99 100------------ 101How it works 102------------ 103 104In a nutshell, Nonsense reads in "templates" and "datafiles" (boring terms 105that I just made up) and uses the magic of Perl and pseudo-random numbers 106to spit out something to STDOUT. 107 108A "template" is merely a text file containing "tags" enclosed in {curly 109braces}. Nonsense substitutes random text for these tags using a really 110crude markup language. 111 112A "datafile" is a text file divided into sections (seperated by a blank 113line), each one containing a list of text items (seperated by a newline) 114that are randomly selected to fill in the template. 115 116Let's take an example. Say you have this datafile called 117"microsoft.data": 118 119-*- 120 121PRODUCT 122{MicrosoftName} {ProductName} 123 124MICROSOFTNAME 125Microshaft 126Microsloth 127Macrohard 128Mightgosoft 129 130PRODUCTNAME 131Windoze 95 132Winblows 98 133Windows Not Trustworthy 134Winslows Y2K 135Bob 136LookOut! 137 138-*- 139 140Now let's say you enter "nonsense -f microsoft.data product". 141 142No template file is given here, so Nonsense will assume you want to produce 143random text from the given "PRODUCT" section. It picks out one line from the 144PRODUCT section, which, in this case, must be "{MicrosoftName} {ProductName}". 145This line contains markup, which is recursively parsed: Nonsense picks a random 146MICROSOFTNAME (say, Microshaft) and a random PRODUCTNAME (say, Bob) to produce 147the final output: "Microshaft Bob". 148 149In short, anything in {curly braces} is replaced by one line from the 150matching section in the datafile, which is recursively processed. 151 152There's also a few special cases that allow Nonsense to handle more 153elaborate situations: 154 155* {#number1-number2} - Nonsense will replace this tag with a random number 156 between number1 and number2 (inclusive). 157 158* {[item1|item2|item3...} - Nonsense will pick out one item from this list 159 (each item is seperated by pipe characters). If only one item 160 is listed, then it will be output 50% of the time (otherwise 161 nothing is output) 162 163* {@strftime format} - Nonsense will pass the current date/time to 164 strftime and return the output. So, for instance, {@%A|0|0} would 165 return the current day of the week. 166 167* {@strftime format|number1|number2} - Same as above, but uses the 168 date/time that occured X seconds ago, where X is a random number between 169 number1 and number2. For instance, {@%H:%M|0|86400} would return the 170 hour:minute anywhere from 0 to 86,400 seconds (1 day) ago. This is 171 actually more useful than it might first appear... 172 173* {;short perl code segment} - Nonsense will eval the stuff inside the 174 braces as a short block of Perl code. This is useful for doing 175 something really complicated that requires the full power of Perl. 176 However, this is risky since there's no error checking and no "sandbox". 177 You can disable this behavior with the -e command line switch (or by 178 hacking the code). 179 180* {\character} - Allows you to embed literal characters that couldn't 181 otherwise be specified, such as: 182 183 {\n} - Newline 184 {\0} - Null (i.e. nothing) 185 {\L} - Left brace '{' 186 {\R} - Right brace '}' 187 {\###} - ASCII character in decimal 188 189* {variablename=literal text} - Stores the text on the right-hand 190 side of the equals sign to the specified state variable, without 191 outputting anything. This is useful for preserving context and is 192 used, for example, in the Slashdot simulator. 193 194* {variablename:=command} - Similar to above, but evaluates 195 the command and stores the result into a state variable. 196 197* {$variablename} - Returns the contents of a state variable. 198 199* {command#number1-number2} - Evaluates the command a random number 200 of times between number1 and number2 201 202-*- 203 204Case is important! {ProductName}, {productname} and {PRODUCTNAME} are 205slightly different. If the name is given in lowercase, the substitution 206will be converted to all lowercase (i.e. it's fed through Perl's lc 207function) -- so, {productname} might produce "macroshaft". 208 209UPPERCASE names specify the opposite; the result is uppercased with uc. 210MixedCase names tell Nonsense to leave the case of the result alone (this 211is usually what you'll want to use). Finally, if you prepend a name with 212a caret ^ (i.e. {^ProductName}), the result is fed through Perl's ucfirst 213function, which will capitalize the first character only. 214 215Did you get all of that? Probably not. While Nonsense is written in Perl 216(which is by practice a write-only language), you can still probably 217understand the code much better than my rambling explanations. 218 219 220------------------ 221Command Line Usage 222------------------ 223 224 nonsense [ -f file.data ] [ -t file.template ] 225 [ -n number ] [ -p ] [ -b bullet string ] [ -e ] 226 [ -D | -d ] [ command string ] 227 228 -f Specify a data file to load in. Use multiple -f parameters 229 to include additional files. The default.data file is 230 is always loaded. 231 -F Load ALL data files (i.e. all files in the current directory 232 with a .data extension). 233 234 -t Use a template file. The markup in this file will be processed 235 and the result output to STDOUT. 236 237 -n Repeat n times. 238 -p Separate each item with a blank line (i.e. paragraph break) 239 -b Specify a "bullet" to go in front of each item. 240 241 -e Disable direct eval()'s 242 243 -d Debug mode (shows each substituation) 244 -D Verbose debug mode (shows each substitution and the result) 245 246cmd Instead of specifying a template file, you can just specify 247string a section to pull out from the data files. 248 249 250--------- 251CGI Usage 252--------- 253 254Thanks to contributions by Fred Hirsch (truehand@darkhart.com), Nonsense 255can now be executed as a CGI script. 256 257The included form.html contains an HTML form (along with predefined links) for 258use with Nonsense. You'll need to change the <BASE HREF=""> tag in this file 259to match the CGI directory where you installed the Nonsense code. 260 261Here are the CGI parameters that Nonsense takes: 262 263 template=filename 264 The template to use. If the template has "html" in 265 its filename, then the output will be of MIME type text/html, 266 otherwise it will be text/plain. 267 268 file=filename 269 Specify a single datafile to load 270 271 allfiles=1 272 Load all datafiles from the Nonsense directory 273 274 cmd=string 275 A section to pull out of the datafiles (if you don't use a template) 276 277 number=integer 278 Number of iterations 279 280 debug=[1|2] 281 Set the debug level (1=shows each substition, 2=shows 282 each substitution and its replacement). The debug information 283 is hidden as an unobtrusive HTML comment. 284 285 standalone=1 286 Outputs a standalone HTML page (i.e. with <HTML> and <BODY> tags) 287 instead of just a page fragment 288 289 spacer=[p|br|nl|literal string] 290 Specify a string that is output between each iteration 291 p is "\n<P>\n" 292 br is "<BR>\n" (the default) 293 nl is "\n" only 294 anything else is treated as a literal (with '\n' converted 295 into a real newline character) 296 297 bullet=[ol|ul] 298 Displays the text as an ordered list (ol) or an unordered 299 list (ul) 300 301* Examples: 302 303To output a bulleted list of 20 fortune cookies, the URL would 304look something like: 305 306 nonsense?cmd=FortuneCookie&file=cookie.data&bullet=ul&number=20 307 308To output a newspaper front page: 309 310 nonsense?template=newspaper.html.template&file=newspaper.data 311 312------------ 313CGI Security 314------------ 315 316Nonsense is not the most secure program around. If you want to use 317this program on a public website, please be careful. 318 319* You can change the source code so that the program will ignore all 320 CGI parameters. This avoids any chance that the user may pass malicious 321 parameters designed to crash the system or read arbitrary files. 322 323 In the source, set the $ignoreparameters variable to 1. Then, change 324 the hard-coded defaults. If, for example, you want the program to generate 325 the Slashdot homepage, replace these lines: 326 327 my $template = '{Default}'; 328 my $template_meta = ''; 329 330 With this one: 331 332 my($template, $template_meta) = LoadTemplate('slashdot.html.template'); 333 334 This will load the Slashdot template in to memory directly. Feel free 335 to change the other defaults as well. 336 337* You can also wrap the program in a server-side include so that the user 338 doesn't have direct access to it. The program's output will be inserted 339 into your webpage using only the parameters that you specify. 340 341 342------------ 343Contact Info 344------------ 345 346This program is written by James Baughn, 347nonsense@i-want-a-website.com. 348 349Fred Hirsch (truehand@darkhart.com) and Peter Suschlik (peter@zilium.de) 350have both submitted code. 351 352Send suggestions, comments, feedback, patches, and new datafiles/templates 353to the above address. Direct your hate mail and flames to 354devnull@i-want-a-website.com 355 356(C) Copyright 2000-2001. This program and accompanying files are licensed 357under the GNU General Public License 2.0 contained in the obligatory 358space-wasting COPYING file. 359 360The homepage for Nonsense is at 361http://i-want-a-website.com/about-linux/downloads.shtml 362 363---------- 364Final Word 365---------- 366 367Have fun! 368