=========================================== Package "Data::Locations" Version 3.0 =========================================== for Perl version 5.000 and higher Copyright (c) 1997 by Steffen Beyer. All rights reserved. This package is free software; you can redistribute and/or modify it under the same terms as Perl itself. What does it do: ---------------- Data::Locations - recursive placeholders in the data you generate "Locations" free you from the need to GENERATE data in the same order in which it will be USED later. They allow you to define insertion points in the middle of your data which you can fill in later, at any time you want! For instance you do not need to write output files in rigidly sequential order anymore using this module. Instead, write the data to locations in the order which is the most appropriate and natural for you! When you're finished, write your data to a file or process it otherwise, purely in memory (faster!). Most important: You can nest these placeholders in any way you want! Potential infinite recursions are detected automatically and refused. This means that you can GENERATE data ONLY ONCE in your program and USE it MANY TIMES at different places, while the data itself is stored in memory only once. Maybe a picture will help to better understand this concept: Think of "locations" as folders (or drawers) containing papers in a sequential order, most of which contain printable text or data, while some may contain the name of another folder (or drawer). When dumping a location to a file, the papers contained in it are printed one after another in the order they were originally stored. When a paper containing the name of another location is encountered, however, the contents of that location are processed before continuing to print the remaining papers of the current location. And so forth, in a recursive descent. Note that you are not confined to dumping locations to a file, you can also process them directly in memory (you can read back the contents of any given location item after item or all at once)! Note further that you may create as many locations with as many embedded locations, as many nesting levels deep as your available memory will permit. Not even Clodsahamp's multidimensionally expanded tree house (see Alan Dean Foster's fantasy novel "Spellsinger" for more details!) can compare with this! :-) Possible applications of this module are for example: - source code generation - web page generation - generating mail messages in mime format - filling in forms - ... Let your fantasy go wild inventing more applications! (And tell me about them!) See the "Tie::Handle(3)" manpage and the example given at the end of the "Data::Locations(3)" manpage for how to tie data locations to file handles in order to further simplify writing data to and reading data from locations. See the "Data::Locations::Shell(3)" manpage for even more ease of use: Use only ONE object reference instead of TWO (one for the location itself and one for the file handle the location has been tied to) which you can use as a file handle AND as a "Data::Locations" object reference, at the same time! Note that this module is fully compatible with "Data::Locations", i.e., if you change all occurrences of "Data::Locations" in your program to "Data::Locations::Shell", your program should work exactly as before - with the added benefit that you don't need to "tie()" your locations to a file handle explicitly anymore in order to be able to use "print $location @items;" and "$item = <$location>;", for instance. Installation: ------------- See the file "INSTALL" in this distribution. Version history: ---------------- See the file "CHANGES" in this distribution. Credits: -------- Many thanks go to Mr. Gero Scholz (now at the Dresdner Bank in Frankfurt, Germany) for writing the "ProMAC" macro processor (some sort of a precursor to Perl in spirit!) and implementing the concept of "locations" there, which inspired me to write this Perl module! Mr. Scholz himself owes his inspiration to the "DELTA" macro processor (a tool largely used during the seventies, as it seems) where a rudimentary version of the concept of "locations" was implemented and where this name ("locations") seems to have been used for the first time. Author's note: -------------- I hope you will find this module beneficial! Share and enjoy! Yours, -- Steffen Beyer http://sb.fluomedia.org/ "There is enough for the need of everyone in this world, but not for the greed of everyone." - Mahatma Gandhi