From: Moritz Bunkus Date: Fri, 12 Oct 2007 11:13:14 +0000 (+0000) Subject: Dokumentation der Perl-Module von Drittanbietern in eigenes Verzeichnis verschoben. X-Git-Tag: release-2.6.0beta1~469 X-Git-Url: http://wagnertech.de/git?a=commitdiff_plain;h=dec4d40fe9f54c53c52d836ddd6a3153bcee0b13;p=kivitendo-erp.git Dokumentation der Perl-Module von Drittanbietern in eigenes Verzeichnis verschoben. --- diff --git a/doc/modules/LICENSE.CGI-Ajax b/doc/modules/LICENSE.CGI-Ajax new file mode 100644 index 000000000..9d0305b3f --- /dev/null +++ b/doc/modules/LICENSE.CGI-Ajax @@ -0,0 +1,383 @@ +Terms of Perl itself + +a) the GNU General Public License as published by the Free + Software Foundation; either version 1, or (at your option) any + later version, or +b) the "Artistic License" + +--------------------------------------------------------------------------- + +The General Public License (GPL) +Version 2, June 1991 + +Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, +Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute +verbatim copies of this license document, but changing it is not allowed. + +Preamble + +The licenses for most software are designed to take away your freedom to share +and change it. By contrast, the GNU General Public License is intended to +guarantee your freedom to share and change free software--to make sure the +software is free for all its users. This General Public License applies to most of +the Free Software Foundation's software and to any other program whose +authors commit to using it. (Some other Free Software Foundation software is +covered by the GNU Library General Public License instead.) You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, not price. Our +General Public Licenses are designed to make sure that you have the freedom +to distribute copies of free software (and charge for this service if you wish), that +you receive source code or can get it if you want it, that you can change the +software or use pieces of it in new free programs; and that you know you can do +these things. + +To protect your rights, we need to make restrictions that forbid anyone to deny +you these rights or to ask you to surrender the rights. These restrictions +translate to certain responsibilities for you if you distribute copies of the +software, or if you modify it. + +For example, if you distribute copies of such a program, whether gratis or for a +fee, you must give the recipients all the rights that you have. You must make +sure that they, too, receive or can get the source code. And you must show +them these terms so they know their rights. + +We protect your rights with two steps: (1) copyright the software, and (2) offer +you this license which gives you legal permission to copy, distribute and/or +modify the software. + +Also, for each author's protection and ours, we want to make certain that +everyone understands that there is no warranty for this free software. If the +software is modified by someone else and passed on, we want its recipients to +know that what they have is not the original, so that any problems introduced by +others will not reflect on the original authors' reputations. + +Finally, any free program is threatened constantly by software patents. We wish +to avoid the danger that redistributors of a free program will individually obtain +patent licenses, in effect making the program proprietary. To prevent this, we +have made it clear that any patent must be licensed for everyone's free use or +not licensed at all. + +The precise terms and conditions for copying, distribution and modification +follow. + +GNU GENERAL PUBLIC LICENSE +TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +MODIFICATION + +0. This License applies to any program or other work which contains a notice +placed by the copyright holder saying it may be distributed under the terms of +this General Public License. The "Program", below, refers to any such program +or work, and a "work based on the Program" means either the Program or any +derivative work under copyright law: that is to say, a work containing the +Program or a portion of it, either verbatim or with modifications and/or translated +into another language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not covered by +this License; they are outside its scope. The act of running the Program is not +restricted, and the output from the Program is covered only if its contents +constitute a work based on the Program (independent of having been made by +running the Program). Whether that is true depends on what the Program does. + +1. You may copy and distribute verbatim copies of the Program's source code as +you receive it, in any medium, provided that you conspicuously and appropriately +publish on each copy an appropriate copyright notice and disclaimer of warranty; +keep intact all the notices that refer to this License and to the absence of any +warranty; and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and you may at +your option offer warranty protection in exchange for a fee. + +2. You may modify your copy or copies of the Program or any portion of it, thus +forming a work based on the Program, and copy and distribute such +modifications or work under the terms of Section 1 above, provided that you also +meet all of these conditions: + +a) You must cause the modified files to carry prominent notices stating that you +changed the files and the date of any change. + +b) You must cause any work that you distribute or publish, that in whole or in +part contains or is derived from the Program or any part thereof, to be licensed +as a whole at no charge to all third parties under the terms of this License. + +c) If the modified program normally reads commands interactively when run, you +must cause it, when started running for such interactive use in the most ordinary +way, to print or display an announcement including an appropriate copyright +notice and a notice that there is no warranty (or else, saying that you provide a +warranty) and that users may redistribute the program under these conditions, +and telling the user how to view a copy of this License. (Exception: if the +Program itself is interactive but does not normally print such an announcement, +your work based on the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If identifiable +sections of that work are not derived from the Program, and can be reasonably +considered independent and separate works in themselves, then this License, +and its terms, do not apply to those sections when you distribute them as +separate works. But when you distribute the same sections as part of a whole +which is a work based on the Program, the distribution of the whole must be on +the terms of this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest your rights to +work written entirely by you; rather, the intent is to exercise the right to control +the distribution of derivative or collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program with the +Program (or with a work based on the Program) on a volume of a storage or +distribution medium does not bring the other work under the scope of this +License. + +3. You may copy and distribute the Program (or a work based on it, under +Section 2) in object code or executable form under the terms of Sections 1 and 2 +above provided that you also do one of the following: + +a) Accompany it with the complete corresponding machine-readable source +code, which must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange; or, + +b) Accompany it with a written offer, valid for at least three years, to give any +third party, for a charge no more than your cost of physically performing source +distribution, a complete machine-readable copy of the corresponding source +code, to be distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +c) Accompany it with the information you received as to the offer to distribute +corresponding source code. (This alternative is allowed only for noncommercial +distribution and only if you received the program in object code or executable +form with such an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for making +modifications to it. For an executable work, complete source code means all the +source code for all modules it contains, plus any associated interface definition +files, plus the scripts used to control compilation and installation of the +executable. However, as a special exception, the source code distributed need +not include anything that is normally distributed (in either source or binary form) +with the major components (compiler, kernel, and so on) of the operating system +on which the executable runs, unless that component itself accompanies the +executable. + +If distribution of executable or object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the source +code from the same place counts as distribution of the source code, even though +third parties are not compelled to copy the source along with the object code. + +4. You may not copy, modify, sublicense, or distribute the Program except as +expressly provided under this License. Any attempt otherwise to copy, modify, +sublicense or distribute the Program is void, and will automatically terminate +your rights under this License. However, parties who have received copies, or +rights, from you under this License will not have their licenses terminated so long +as such parties remain in full compliance. + +5. You are not required to accept this License, since you have not signed it. +However, nothing else grants you permission to modify or distribute the Program +or its derivative works. These actions are prohibited by law if you do not accept +this License. Therefore, by modifying or distributing the Program (or any work +based on the Program), you indicate your acceptance of this License to do so, +and all its terms and conditions for copying, distributing or modifying the +Program or works based on it. + +6. Each time you redistribute the Program (or any work based on the Program), +the recipient automatically receives a license from the original licensor to copy, +distribute or modify the Program subject to these terms and conditions. You +may not impose any further restrictions on the recipients' exercise of the rights +granted herein. You are not responsible for enforcing compliance by third parties +to this License. + +7. If, as a consequence of a court judgment or allegation of patent infringement +or for any other reason (not limited to patent issues), conditions are imposed on +you (whether by court order, agreement or otherwise) that contradict the +conditions of this License, they do not excuse you from the conditions of this +License. If you cannot distribute so as to satisfy simultaneously your obligations +under this License and any other pertinent obligations, then as a consequence +you may not distribute the Program at all. For example, if a patent license would +not permit royalty-free redistribution of the Program by all those who receive +copies directly or indirectly through you, then the only way you could satisfy +both it and this License would be to refrain entirely from distribution of the +Program. + +If any portion of this section is held invalid or unenforceable under any particular +circumstance, the balance of the section is intended to apply and the section as +a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any patents or other +property right claims or to contest validity of any such claims; this section has +the sole purpose of protecting the integrity of the free software distribution +system, which is implemented by public license practices. Many people have +made generous contributions to the wide range of software distributed through +that system in reliance on consistent application of that system; it is up to the +author/donor to decide if he or she is willing to distribute software through any +other system and a licensee cannot impose that choice. + +This section is intended to make thoroughly clear what is believed to be a +consequence of the rest of this License. + +8. If the distribution and/or use of the Program is restricted in certain countries +either by patents or by copyrighted interfaces, the original copyright holder who +places the Program under this License may add an explicit geographical +distribution limitation excluding those countries, so that distribution is permitted +only in or among countries not thus excluded. In such case, this License +incorporates the limitation as if written in the body of this License. + +9. The Free Software Foundation may publish revised and/or new versions of the +General Public License from time to time. Such new versions will be similar in +spirit to the present version, but may differ in detail to address new problems or +concerns. + +Each version is given a distinguishing version number. If the Program specifies a +version number of this License which applies to it and "any later version", you +have the option of following the terms and conditions either of that version or of +any later version published by the Free Software Foundation. If the Program does +not specify a version number of this License, you may choose any version ever +published by the Free Software Foundation. + +10. If you wish to incorporate parts of the Program into other free programs +whose distribution conditions are different, write to the author to ask for +permission. For software which is copyrighted by the Free Software Foundation, +write to the Free Software Foundation; we sometimes make exceptions for this. +Our decision will be guided by the two goals of preserving the free status of all +derivatives of our free software and of promoting the sharing and reuse of +software generally. + +NO WARRANTY + +11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS +NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE +COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM +"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR +IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, +YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED +TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY +WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS +PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM +(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY +OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS +BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +END OF TERMS AND CONDITIONS + + +--------------------------------------------------------------------------- + +The Artistic License + +Preamble + +The intent of this document is to state the conditions under which a Package +may be copied, such that the Copyright Holder maintains some semblance of +artistic control over the development of the package, while giving the users of the +package the right to use and distribute the Package in a more-or-less customary +fashion, plus the right to make reasonable modifications. + +Definitions: + +- "Package" refers to the collection of files distributed by the Copyright + Holder, and derivatives of that collection of files created through textual + modification. +- "Standard Version" refers to such a Package if it has not been modified, + or has been modified in accordance with the wishes of the Copyright + Holder. +- "Copyright Holder" is whoever is named in the copyright or copyrights for + the package. +- "You" is you, if you're thinking about copying or distributing this Package. +- "Reasonable copying fee" is whatever you can justify on the basis of + media cost, duplication charges, time of people involved, and so on. (You + will not be required to justify it to the Copyright Holder, but only to the + computing community at large as a market that must bear the fee.) +- "Freely Available" means that no fee is charged for the item itself, though + there may be fees involved in handling the item. It also means that + recipients of the item may redistribute it under the same conditions they + received it. + +1. You may make and give away verbatim copies of the source form of the +Standard Version of this Package without restriction, provided that you duplicate +all of the original copyright notices and associated disclaimers. + +2. You may apply bug fixes, portability fixes and other modifications derived from +the Public Domain or from the Copyright Holder. A Package modified in such a +way shall still be considered the Standard Version. + +3. You may otherwise modify your copy of this Package in any way, provided +that you insert a prominent notice in each changed file stating how and when +you changed that file, and provided that you do at least ONE of the following: + + a) place your modifications in the Public Domain or otherwise + make them Freely Available, such as by posting said modifications + to Usenet or an equivalent medium, or placing the modifications on + a major archive site such as ftp.uu.net, or by allowing the + Copyright Holder to include your modifications in the Standard + Version of the Package. + + b) use the modified Package only within your corporation or + organization. + + c) rename any non-standard executables so the names do not + conflict with standard executables, which must also be provided, + and provide a separate manual page for each non-standard + executable that clearly documents how it differs from the Standard + Version. + + d) make other distribution arrangements with the Copyright Holder. + +4. You may distribute the programs of this Package in object code or executable +form, provided that you do at least ONE of the following: + + a) distribute a Standard Version of the executables and library + files, together with instructions (in the manual page or equivalent) + on where to get the Standard Version. + + b) accompany the distribution with the machine-readable source of + the Package with your modifications. + + c) accompany any non-standard executables with their + corresponding Standard Version executables, giving the + non-standard executables non-standard names, and clearly + documenting the differences in manual pages (or equivalent), + together with instructions on where to get the Standard Version. + + d) make other distribution arrangements with the Copyright Holder. + +5. You may charge a reasonable copying fee for any distribution of this Package. +You may charge any fee you choose for support of this Package. You may not +charge a fee for this Package itself. However, you may distribute this Package in +aggregate with other (possibly commercial) programs as part of a larger +(possibly commercial) software distribution provided that you do not advertise +this Package as a product of your own. + +6. The scripts and library files supplied as input to or produced as output from +the programs of this Package do not automatically fall under the copyright of this +Package, but belong to whomever generated them, and may be sold +commercially, and may be aggregated with this Package. + +7. C or perl subroutines supplied by you and linked into this Package shall not +be considered part of this Package. + +8. Aggregation of this Package with a commercial distribution is always permitted +provided that the use of this Package is embedded; that is, when no overt attempt +is made to make this Package's interfaces visible to the end user of the +commercial distribution. Such use shall not be construed as a distribution of +this Package. + +9. The name of the Copyright Holder may not be used to endorse or promote +products derived from this software without specific prior written permission. + +10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR +PURPOSE. + +The End + + diff --git a/doc/modules/README.CGI-Ajax b/doc/modules/README.CGI-Ajax new file mode 100644 index 000000000..1af8860c6 --- /dev/null +++ b/doc/modules/README.CGI-Ajax @@ -0,0 +1,41 @@ +pod2text CGI::Perljax.pm > README + +CGI::Perljax + +Perljax - a perl-specific system for writing AJAX- or +DHTML-based web applications. + + +Perljax provides a unique mechanism for using perl code +asynchronously from javascript using AJAX to access user-written +perl functions/methods. Perljax unburdens the user from having to +write any javascript, except for having to associate an exported +method with a document-defined event (such as onClick, onKeyUp, +etc). Only in the more advanced implementations of a exported perl +method would a user need to write custom javascript. Perljax supports +methods that return single results, or multiple results to the web +page. No other projects that we know of are like Perljax for the +following reasons: 1. Perljax is targeted specifically for perl +development. 2. Perljax shields the user from having to write any +javascript at all (unless they want to). 3. The URL for the HTTP GET +request is automatically generated based on HTML layout and events, +and the page is then dynamically updated. 4. Perljax is not part +of a Content Management System, or some other larger project. + + +INSTALL + +perl Makefile.PL +make +make test +make install + +*If you are on a windows box you should use 'nmake' rather than 'make'. + +Installation will place Perljax into the system perl @INC path, but it +is important that you make sure mod_perl uses this path (which is +mod_perl's default behavior, and also assuming you use mod_perl, and +not just run perl as a CGI). + +Example scripts are provided in the source script directory, and can +also be seen on the project's website, http://www.perljax.us. diff --git a/doc/modules/README.YAML b/doc/modules/README.YAML new file mode 100644 index 000000000..0fbb2fd09 --- /dev/null +++ b/doc/modules/README.YAML @@ -0,0 +1,611 @@ +NAME + YAML - YAML Ain't Markup Language (tm) + +SYNOPSIS + use YAML; + + # Load a YAML stream of 3 YAML documents into Perl data structures. + my ($hashref, $arrayref, $string) = Load(<<'...'); + --- + name: ingy + age: old + weight: heavy + # I should comment that I also like pink, but don't tell anybody. + favorite colors: + - red + - green + - blue + --- + - Clark Evans + - Oren Ben-Kiki + - Ingy döt Net + --- > + You probably think YAML stands for "Yet Another Markup Language". It + ain't! YAML is really a data serialization language. But if you want + to think of it as a markup, that's OK with me. A lot of people try + to use XML as a serialization format. + + "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!" + ... + + # Dump the Perl data structures back into YAML. + print Dump($string, $arrayref, $hashref); + + # YAML::Dump is used the same way you'd use Data::Dumper::Dumper + use Data::Dumper; + print Dumper($string, $arrayref, $hashref); + +DESCRIPTION + The YAML.pm module implements a YAML Loader and Dumper based on the YAML + 1.0 specification. + + YAML is a generic data serialization language that is optimized for + human readability. It can be used to express the data structures of most + modern programming languages. (Including Perl!!!) + + For information on the YAML syntax, please refer to the YAML + specification. + +WHY YAML IS COOL + YAML is readable for people. + It makes clear sense out of complex data structures. You should find + that YAML is an exceptional data dumping tool. Structure is shown + through indentation, YAML supports recursive data, and hash keys are + sorted by default. In addition, YAML supports several styles of + scalar formatting for different types of data. + + YAML is editable. + YAML was designed from the ground up to be an excellent syntax for + configuration files. Almost all programs need configuration files, + so why invent a new syntax for each one? And why subject users to + the complexities of XML or native Perl code? + + YAML is multilingual. + Yes, YAML supports Unicode. But I'm actually referring to + programming languages. YAML was designed to meet the serialization + needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was + also designed to be interoperable between those languages. That + means YAML serializations produced by Perl can be processed by + Python. + + YAML is taint safe. + Using modules like Data::Dumper for serialization is fine as long as + you can be sure that nobody can tamper with your data files or + transmissions. That's because you need to use Perl's "eval()" + built-in to deserialize the data. Somebody could add a snippet of + Perl to erase your files. + + YAML's parser does not need to eval anything. + + YAML is full featured. + YAML can accurately serialize all of the common Perl data structures + and deserialize them again without losing data relationships. + Although it is not 100% perfect (no serializer is or can be + perfect), it fares as well as the popular current modules: + Data::Dumper, Storable, XML::Dumper and Data::Denter. + + YAML.pm also has the ability to handle code (subroutine) references + and typeglobs. (Still experimental) These features are not found in + Perl's other serialization modules. + + YAML is extensible. + The YAML language has been designed to be flexible enough to solve + it's own problems. The markup itself has 3 basic construct which + resemble Perl's hash, array and scalar. By default, these map to + their Perl equivalents. But each YAML node also supports a tagging + mechanism (type system) which can cause that node to be interpreted + in a completely different manner. That's how YAML can support object + serialization and oddball structures like Perl's typeglob. + +YAML IMPLEMENTATIONS IN PERL + This module, YAML.pm, is really just the interface module for YAML + modules written in Perl. The basic interface for YAML consists of two + functions: "Dump" and "Load". The real work is done by the modules + YAML::Dumper and YAML::Loader. + + Different YAML module distributions can be created by subclassing + YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple + consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple. + + Why would there be more than one implementation of YAML? Well, despite + YAML's offering of being a simple data format, YAML is actually very + deep and complex. Implementing the entirety of the YAML specification is + a daunting task. + + For this reason I am currently working on 3 different YAML + implementations. + + YAML + The main YAML distribution will keeping evolving to support the + entire YAML specification in pure Perl. This may not be the fastest + or most stable module though. Currently, YAML.pm has lots of known + bugs. It is mostly a great tool for dumping Perl data structures to + a readable form. + + YAML::Lite + The point of YAML::Lite is to strip YAML down to the 90% that people + use most and offer that in a small, fast, stable, pure Perl form. + YAML::Lite will simply die when it is asked to do something it + can't. + + YAML::Syck + "libsyck" is the C based YAML processing library used by the Ruby + programming language (and also Python, PHP and Pugs). YAML::Syck is + the Perl binding to "libsyck". It should be very fast, but may have + problems of its own. It will also require C compilation. + + NOTE: Audrey Tang has actually completed this module and it works + great and is 10 times faster than YAML.pm. + + In the future, there will likely be even more YAML modules. Remember, + people other than Ingy are allowed to write YAML modules! + +FUNCTIONAL USAGE + YAML is completely OO under the hood. Still it exports a few useful top + level functions so that it is dead simple to use. These functions just + do the OO stuff for you. If you want direct access to the OO API see the + documentation for YAML::Dumper and YAML::Loader. + + Exported Functions + The following functions are exported by YAML.pm by default. The reason + they are exported is so that YAML works much like Data::Dumper. If you + don't want functions to be imported, just use YAML with an empty import + list: + + use YAML (); + + Dump(list-of-Perl-data-structures) + Turn Perl data into YAML. This function works very much like + Data::Dumper::Dumper(). It takes a list of Perl data strucures and + dumps them into a serialized form. It returns a string containing + the YAML stream. The structures can be references or plain scalars. + + Load(string-containing-a-YAML-stream) + Turn YAML into Perl data. This is the opposite of Dump. Just like + Storable's thaw() function or the eval() function in relation to + Data::Dumper. It parses a string containing a valid YAML stream into + a list of Perl data structures. + + Exportable Functions + These functions are not exported by default but you can request them in + an import list like this: + + use YAML qw'freeze thaw Bless'; + + freeze() and thaw() + Aliases to Dump() and Load() for Storable fans. This will also allow + YAML.pm to be plugged directly into modules like POE.pm, that use + the freeze/thaw API for internal serialization. + + DumpFile(filepath, list) + Writes the YAML stream to a file instead of just returning a string. + + LoadFile(filepath) + Reads the YAML stream from a file instead of a string. + + Bless(perl-node, [yaml-node | class-name]) + Associate a normal Perl node, with a yaml node. A yaml node is an + object tied to the YAML::Node class. The second argument is either a + yaml node that you've already created or a class (package) name that + supports a yaml_dump() function. A yaml_dump() function should take + a perl node and return a yaml node. If no second argument is + provided, Bless will create a yaml node. This node is not returned, + but can be retrieved with the Blessed() function. + + Here's an example of how to use Bless. Say you have a hash + containing three keys, but you only want to dump two of them. + Furthermore the keys must be dumped in a certain order. Here's how + you do that: + + use YAML qw(Dump Bless); + $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'}; + print Dump $hash; + Bless($hash)->keys(['banana', 'apple']); + print Dump $hash; + + produces: + + --- + apple: good + banana: bad + cauliflower: ugly + --- + banana: bad + apple: good + + Bless returns the tied part of a yaml-node, so that you can call the + YAML::Node methods. This is the same thing that YAML::Node::ynode() + returns. So another way to do the above example is: + + use YAML qw(Dump Bless); + use YAML::Node; + $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'}; + print Dump $hash; + Bless($hash); + $ynode = ynode(Blessed($hash)); + $ynode->keys(['banana', 'apple']); + print Dump $hash; + + Note that Blessing a Perl data structure does not change it anyway. + The extra information is stored separately and looked up by the + Blessed node's memory address. + + Blessed(perl-node) + Returns the yaml node that a particular perl node is associated with + (see above). Returns undef if the node is not (YAML) Blessed. + +GLOBAL OPTIONS + YAML options are set using a group of global variables in the YAML + namespace. This is similar to how Data::Dumper works. + + For example, to change the indentation width, do something like: + + local $YAML::Indent = 3; + + The current options are: + + DumperClass + You can override which module/class YAML uses for Dumping data. + + LoaderClass + You can override which module/class YAML uses for Loading data. + + Indent + This is the number of space characters to use for each indentation + level when doing a Dump(). The default is 2. + + By the way, YAML can use any number of characters for indentation at + any level. So if you are editing YAML by hand feel free to do it + anyway that looks pleasing to you; just be consistent for a given + level. + + SortKeys + Default is 1. (true) + + Tells YAML.pm whether or not to sort hash keys when storing a + document. + + YAML::Node objects can have their own sort order, which is usually + what you want. To override the YAML::Node order and sort the keys + anyway, set SortKeys to 2. + + Stringify + Default is 0. (false) + + Objects with string overloading should honor the overloading and + dump the stringification of themselves, rather than the actual + object's guts. + + UseHeader + Default is 1. (true) + + This tells YAML.pm whether to use a separator string for a Dump + operation. This only applies to the first document in a stream. + Subsequent documents must have a YAML header by definition. + + UseVersion + Default is 0. (false) + + Tells YAML.pm whether to include the YAML version on the + separator/header. + + --- %YAML:1.0 + + AnchorPrefix + Default is ''. + + Anchor names are normally numeric. YAML.pm simply starts with '1' + and increases by one for each new anchor. This option allows you to + specify a string to be prepended to each anchor number. + + UseCode + Setting the UseCode option is a shortcut to set both the DumpCode + and LoadCode options at once. Setting UseCode to '1' tells YAML.pm + to dump Perl code references as Perl (using B::Deparse) and to load + them back into memory using eval(). The reason this has to be an + option is that using eval() to parse untrusted code is, well, + untrustworthy. + + DumpCode + Determines if and how YAML.pm should serialize Perl code references. + By default YAML.pm will dump code references as dummy placeholders + (much like Data::Dumper). If DumpCode is set to '1' or 'deparse', + code references will be dumped as actual Perl code. + + DumpCode can also be set to a subroutine reference so that you can + write your own serializing routine. YAML.pm passes you the code ref. + You pass back the serialization (as a string) and a format + indicator. The format indicator is a simple string like: 'deparse' + or 'bytecode'. + + LoadCode + LoadCode is the opposite of DumpCode. It tells YAML if and how to + deserialize code references. When set to '1' or 'deparse' it will + use "eval()". Since this is potentially risky, only use this option + if you know where your YAML has been. + + LoadCode can also be set to a subroutine reference so that you can + write your own deserializing routine. YAML.pm passes the + serialization (as a string) and a format indicator. You pass back + the code reference. + + UseBlock + YAML.pm uses heuristics to guess which scalar style is best for a + given node. Sometimes you'll want all multiline scalars to use the + 'block' style. If so, set this option to 1. + + NOTE: YAML's block style is akin to Perl's here-document. + + UseFold + If you want to force YAML to use the 'folded' style for all + multiline scalars, then set $UseFold to 1. + + NOTE: YAML's folded style is akin to the way HTML folds text, except + smarter. + + UseAliases + YAML has an alias mechanism such that any given structure in memory + gets serialized once. Any other references to that structure are + serialized only as alias markers. This is how YAML can serialize + duplicate and recursive structures. + + Sometimes, when you KNOW that your data is nonrecursive in nature, + you may want to serialize such that every node is expressed in full. + (ie as a copy of the original). Setting $YAML::UseAliases to 0 will + allow you to do this. This also may result in faster processing + because the lookup overhead is by bypassed. + + THIS OPTION CAN BE DANGEROUS. *If* your data is recursive, this + option *will* cause Dump() to run in an endless loop, chewing up + your computers memory. You have been warned. + + CompressSeries + Default is 1. + + Compresses the formatting of arrays of hashes: + + - + foo: bar + - + bar: foo + + becomes: + + - foo: bar + - bar: foo + + Since this output is usually more desirable, this option is turned + on by default. + +YAML TERMINOLOGY + YAML is a full featured data serialization language, and thus has its + own terminology. + + It is important to remember that although YAML is heavily influenced by + Perl and Python, it is a language in its own right, not merely just a + representation of Perl structures. + + YAML has three constructs that are conspicuously similar to Perl's hash, + array, and scalar. They are called mapping, sequence, and string + respectively. By default, they do what you would expect. But each + instance may have an explicit or implicit tag (type) that makes it + behave differently. In this manner, YAML can be extended to represent + Perl's Glob or Python's tuple, or Ruby's Bigint. + + stream + A YAML stream is the full sequence of unicode characters that a YAML + parser would read or a YAML emitter would write. A stream may + contain one or more YAML documents separated by YAML headers. + + --- + a: mapping + foo: bar + --- + - a + - sequence + + document + A YAML document is an independent data structure representation + within a stream. It is a top level node. Each document in a YAML + stream must begin with a YAML header line. Actually the header is + optional on the first document. + + --- + This: top level mapping + is: + - a + - YAML + - document + + header + A YAML header is a line that begins a YAML document. It consists of + three dashes, possibly followed by more info. Another purpose of the + header line is that it serves as a place to put top level tag and + anchor information. + + --- !recursive-sequence &001 + - * 001 + - * 001 + + node + A YAML node is the representation of a particular data stucture. + Nodes may contain other nodes. (In Perl terms, nodes are like + scalars. Strings, arrayrefs and hashrefs. But this refers to the + serialized format, not the in-memory structure.) + + tag This is similar to a type. It indicates how a particular YAML node + serialization should be transferred into or out of memory. For + instance a Foo::Bar object would use the tag 'perl/Foo::Bar': + + - !perl/Foo::Bar + foo: 42 + bar: stool + + collection + A collection is the generic term for a YAML data grouping. YAML has + two types of collections: mappings and sequences. (Similar to hashes + and arrays) + + mapping + A mapping is a YAML collection defined by unordered key/value pairs + with unique keys. By default YAML mappings are loaded into Perl + hashes. + + a mapping: + foo: bar + two: times two is 4 + + sequence + A sequence is a YAML collection defined by an ordered list of + elements. By default YAML sequences are loaded into Perl arrays. + + a sequence: + - one bourbon + - one scotch + - one beer + + scalar + A scalar is a YAML node that is a single value. By default YAML + scalars are loaded into Perl scalars. + + a scalar key: a scalar value + + YAML has many styles for representing scalars. This is important + because varying data will have varying formatting requirements to + retain the optimum human readability. + + plain scalar + A plain sclar is unquoted. All plain scalars are automatic + candidates for "implicit tagging". This means that their tag may be + determined automatically by examination. The typical uses for this + are plain alpha strings, integers, real numbers, dates, times and + currency. + + - a plain string + - -42 + - 3.1415 + - 12:34 + - 123 this is an error + + single quoted scalar + This is similar to Perl's use of single quotes. It means no escaping + except for single quotes which are escaped by using two adjacent + single quotes. + + - 'When I say ''\n'' I mean "backslash en"' + + double quoted scalar + This is similar to Perl's use of double quotes. Character escaping + can be used. + + - "This scalar\nhas two lines, and a bell -->\a" + + folded scalar + This is a multiline scalar which begins on the next line. It is + indicated by a single right angle bracket. It is unescaped like the + single quoted scalar. Line folding is also performed. + + - > + This is a multiline scalar which begins on + the next line. It is indicated by a single + carat. It is unescaped like the single + quoted scalar. Line folding is also + performed. + + block scalar + This final multiline form is akin to Perl's here-document except + that (as in all YAML data) scope is indicated by indentation. + Therefore, no ending marker is required. The data is verbatim. No + line folding. + + - | + QTY DESC PRICE TOTAL + --- ---- ----- ----- + 1 Foo Fighters $19.95 $19.95 + 2 Bar Belles $29.95 $59.90 + + parser + A YAML processor has four stages: parse, load, dump, emit. + + A parser parses a YAML stream. YAML.pm's Load() function contains a + parser. + + loader + The other half of the Load() function is a loader. This takes the + information from the parser and loads it into a Perl data structure. + + dumper + The Dump() function consists of a dumper and an emitter. The dumper + walks through each Perl data structure and gives info to the + emitter. + + emitter + The emitter takes info from the dumper and turns it into a YAML + stream. + + NOTE: In YAML.pm the parser/loader and the dumper/emitter code are + currently very closely tied together. In the future they may be + broken into separate stages. + + For more information please refer to the immensely helpful YAML + specification available at . + +ysh - The YAML Shell + The YAML distribution ships with a script called 'ysh', the YAML shell. + ysh provides a simple, interactive way to play with YAML. If you type in + Perl code, it displays the result in YAML. If you type in YAML it turns + it into Perl code. + + To run ysh, (assuming you installed it along with YAML.pm) simply type: + + ysh [options] + + Please read the "ysh" documentation for the full details. There are lots + of options. + +BUGS & DEFICIENCIES + If you find a bug in YAML, please try to recreate it in the YAML Shell + with logging turned on ('ysh -L'). When you have successfully reproduced + the bug, please mail the LOG file to the author (ingy@cpan.org). + + WARNING: This is still *ALPHA* code. Well, most of this code has been + around for years... + + BIGGER WARNING: YAML.pm has been slow in the making, but I am committed + to having top notch YAML tools in the Perl world. The YAML team is close + to finalizing the YAML 1.1 spec. This version of YAML.pm is based off of + a very old pre 1.0 spec. In actuality there isn't a ton of difference, + and this YAML.pm is still fairly useful. Things will get much better in + the future. + +RESOURCES + is the mailing + list. This is where the language is discussed and designed. + + is the official YAML website. + + is the YAML 1.0 specification. + + is the official YAML wiki. + +SEE ALSO + See YAML::Syck. Fast! + +AUTHOR + Ingy döt Net + + is resonsible for YAML.pm. + + The YAML serialization language is the result of years of collaboration + between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others + have added help along the way. + +COPYRIGHT + Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright + (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved. + + This program is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + + See + diff --git a/modules/fallback/CGI/LICENSE b/modules/fallback/CGI/LICENSE deleted file mode 100644 index 9d0305b3f..000000000 --- a/modules/fallback/CGI/LICENSE +++ /dev/null @@ -1,383 +0,0 @@ -Terms of Perl itself - -a) the GNU General Public License as published by the Free - Software Foundation; either version 1, or (at your option) any - later version, or -b) the "Artistic License" - ---------------------------------------------------------------------------- - -The General Public License (GPL) -Version 2, June 1991 - -Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, -Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute -verbatim copies of this license document, but changing it is not allowed. - -Preamble - -The licenses for most software are designed to take away your freedom to share -and change it. By contrast, the GNU General Public License is intended to -guarantee your freedom to share and change free software--to make sure the -software is free for all its users. This General Public License applies to most of -the Free Software Foundation's software and to any other program whose -authors commit to using it. (Some other Free Software Foundation software is -covered by the GNU Library General Public License instead.) You can apply it to -your programs, too. - -When we speak of free software, we are referring to freedom, not price. Our -General Public Licenses are designed to make sure that you have the freedom -to distribute copies of free software (and charge for this service if you wish), that -you receive source code or can get it if you want it, that you can change the -software or use pieces of it in new free programs; and that you know you can do -these things. - -To protect your rights, we need to make restrictions that forbid anyone to deny -you these rights or to ask you to surrender the rights. These restrictions -translate to certain responsibilities for you if you distribute copies of the -software, or if you modify it. - -For example, if you distribute copies of such a program, whether gratis or for a -fee, you must give the recipients all the rights that you have. You must make -sure that they, too, receive or can get the source code. And you must show -them these terms so they know their rights. - -We protect your rights with two steps: (1) copyright the software, and (2) offer -you this license which gives you legal permission to copy, distribute and/or -modify the software. - -Also, for each author's protection and ours, we want to make certain that -everyone understands that there is no warranty for this free software. If the -software is modified by someone else and passed on, we want its recipients to -know that what they have is not the original, so that any problems introduced by -others will not reflect on the original authors' reputations. - -Finally, any free program is threatened constantly by software patents. We wish -to avoid the danger that redistributors of a free program will individually obtain -patent licenses, in effect making the program proprietary. To prevent this, we -have made it clear that any patent must be licensed for everyone's free use or -not licensed at all. - -The precise terms and conditions for copying, distribution and modification -follow. - -GNU GENERAL PUBLIC LICENSE -TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND -MODIFICATION - -0. This License applies to any program or other work which contains a notice -placed by the copyright holder saying it may be distributed under the terms of -this General Public License. The "Program", below, refers to any such program -or work, and a "work based on the Program" means either the Program or any -derivative work under copyright law: that is to say, a work containing the -Program or a portion of it, either verbatim or with modifications and/or translated -into another language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not covered by -this License; they are outside its scope. The act of running the Program is not -restricted, and the output from the Program is covered only if its contents -constitute a work based on the Program (independent of having been made by -running the Program). Whether that is true depends on what the Program does. - -1. You may copy and distribute verbatim copies of the Program's source code as -you receive it, in any medium, provided that you conspicuously and appropriately -publish on each copy an appropriate copyright notice and disclaimer of warranty; -keep intact all the notices that refer to this License and to the absence of any -warranty; and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and you may at -your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Program or any portion of it, thus -forming a work based on the Program, and copy and distribute such -modifications or work under the terms of Section 1 above, provided that you also -meet all of these conditions: - -a) You must cause the modified files to carry prominent notices stating that you -changed the files and the date of any change. - -b) You must cause any work that you distribute or publish, that in whole or in -part contains or is derived from the Program or any part thereof, to be licensed -as a whole at no charge to all third parties under the terms of this License. - -c) If the modified program normally reads commands interactively when run, you -must cause it, when started running for such interactive use in the most ordinary -way, to print or display an announcement including an appropriate copyright -notice and a notice that there is no warranty (or else, saying that you provide a -warranty) and that users may redistribute the program under these conditions, -and telling the user how to view a copy of this License. (Exception: if the -Program itself is interactive but does not normally print such an announcement, -your work based on the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If identifiable -sections of that work are not derived from the Program, and can be reasonably -considered independent and separate works in themselves, then this License, -and its terms, do not apply to those sections when you distribute them as -separate works. But when you distribute the same sections as part of a whole -which is a work based on the Program, the distribution of the whole must be on -the terms of this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest your rights to -work written entirely by you; rather, the intent is to exercise the right to control -the distribution of derivative or collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program with the -Program (or with a work based on the Program) on a volume of a storage or -distribution medium does not bring the other work under the scope of this -License. - -3. You may copy and distribute the Program (or a work based on it, under -Section 2) in object code or executable form under the terms of Sections 1 and 2 -above provided that you also do one of the following: - -a) Accompany it with the complete corresponding machine-readable source -code, which must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange; or, - -b) Accompany it with a written offer, valid for at least three years, to give any -third party, for a charge no more than your cost of physically performing source -distribution, a complete machine-readable copy of the corresponding source -code, to be distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -c) Accompany it with the information you received as to the offer to distribute -corresponding source code. (This alternative is allowed only for noncommercial -distribution and only if you received the program in object code or executable -form with such an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for making -modifications to it. For an executable work, complete source code means all the -source code for all modules it contains, plus any associated interface definition -files, plus the scripts used to control compilation and installation of the -executable. However, as a special exception, the source code distributed need -not include anything that is normally distributed (in either source or binary form) -with the major components (compiler, kernel, and so on) of the operating system -on which the executable runs, unless that component itself accompanies the -executable. - -If distribution of executable or object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the source -code from the same place counts as distribution of the source code, even though -third parties are not compelled to copy the source along with the object code. - -4. You may not copy, modify, sublicense, or distribute the Program except as -expressly provided under this License. Any attempt otherwise to copy, modify, -sublicense or distribute the Program is void, and will automatically terminate -your rights under this License. However, parties who have received copies, or -rights, from you under this License will not have their licenses terminated so long -as such parties remain in full compliance. - -5. You are not required to accept this License, since you have not signed it. -However, nothing else grants you permission to modify or distribute the Program -or its derivative works. These actions are prohibited by law if you do not accept -this License. Therefore, by modifying or distributing the Program (or any work -based on the Program), you indicate your acceptance of this License to do so, -and all its terms and conditions for copying, distributing or modifying the -Program or works based on it. - -6. Each time you redistribute the Program (or any work based on the Program), -the recipient automatically receives a license from the original licensor to copy, -distribute or modify the Program subject to these terms and conditions. You -may not impose any further restrictions on the recipients' exercise of the rights -granted herein. You are not responsible for enforcing compliance by third parties -to this License. - -7. If, as a consequence of a court judgment or allegation of patent infringement -or for any other reason (not limited to patent issues), conditions are imposed on -you (whether by court order, agreement or otherwise) that contradict the -conditions of this License, they do not excuse you from the conditions of this -License. If you cannot distribute so as to satisfy simultaneously your obligations -under this License and any other pertinent obligations, then as a consequence -you may not distribute the Program at all. For example, if a patent license would -not permit royalty-free redistribution of the Program by all those who receive -copies directly or indirectly through you, then the only way you could satisfy -both it and this License would be to refrain entirely from distribution of the -Program. - -If any portion of this section is held invalid or unenforceable under any particular -circumstance, the balance of the section is intended to apply and the section as -a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any patents or other -property right claims or to contest validity of any such claims; this section has -the sole purpose of protecting the integrity of the free software distribution -system, which is implemented by public license practices. Many people have -made generous contributions to the wide range of software distributed through -that system in reliance on consistent application of that system; it is up to the -author/donor to decide if he or she is willing to distribute software through any -other system and a licensee cannot impose that choice. - -This section is intended to make thoroughly clear what is believed to be a -consequence of the rest of this License. - -8. If the distribution and/or use of the Program is restricted in certain countries -either by patents or by copyrighted interfaces, the original copyright holder who -places the Program under this License may add an explicit geographical -distribution limitation excluding those countries, so that distribution is permitted -only in or among countries not thus excluded. In such case, this License -incorporates the limitation as if written in the body of this License. - -9. The Free Software Foundation may publish revised and/or new versions of the -General Public License from time to time. Such new versions will be similar in -spirit to the present version, but may differ in detail to address new problems or -concerns. - -Each version is given a distinguishing version number. If the Program specifies a -version number of this License which applies to it and "any later version", you -have the option of following the terms and conditions either of that version or of -any later version published by the Free Software Foundation. If the Program does -not specify a version number of this License, you may choose any version ever -published by the Free Software Foundation. - -10. If you wish to incorporate parts of the Program into other free programs -whose distribution conditions are different, write to the author to ask for -permission. For software which is copyrighted by the Free Software Foundation, -write to the Free Software Foundation; we sometimes make exceptions for this. -Our decision will be guided by the two goals of preserving the free status of all -derivatives of our free software and of promoting the sharing and reuse of -software generally. - -NO WARRANTY - -11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS -NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE -COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM -"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR -IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE -ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, -YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED -TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY -WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS -PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM -(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY -OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS -BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -END OF TERMS AND CONDITIONS - - ---------------------------------------------------------------------------- - -The Artistic License - -Preamble - -The intent of this document is to state the conditions under which a Package -may be copied, such that the Copyright Holder maintains some semblance of -artistic control over the development of the package, while giving the users of the -package the right to use and distribute the Package in a more-or-less customary -fashion, plus the right to make reasonable modifications. - -Definitions: - -- "Package" refers to the collection of files distributed by the Copyright - Holder, and derivatives of that collection of files created through textual - modification. -- "Standard Version" refers to such a Package if it has not been modified, - or has been modified in accordance with the wishes of the Copyright - Holder. -- "Copyright Holder" is whoever is named in the copyright or copyrights for - the package. -- "You" is you, if you're thinking about copying or distributing this Package. -- "Reasonable copying fee" is whatever you can justify on the basis of - media cost, duplication charges, time of people involved, and so on. (You - will not be required to justify it to the Copyright Holder, but only to the - computing community at large as a market that must bear the fee.) -- "Freely Available" means that no fee is charged for the item itself, though - there may be fees involved in handling the item. It also means that - recipients of the item may redistribute it under the same conditions they - received it. - -1. You may make and give away verbatim copies of the source form of the -Standard Version of this Package without restriction, provided that you duplicate -all of the original copyright notices and associated disclaimers. - -2. You may apply bug fixes, portability fixes and other modifications derived from -the Public Domain or from the Copyright Holder. A Package modified in such a -way shall still be considered the Standard Version. - -3. You may otherwise modify your copy of this Package in any way, provided -that you insert a prominent notice in each changed file stating how and when -you changed that file, and provided that you do at least ONE of the following: - - a) place your modifications in the Public Domain or otherwise - make them Freely Available, such as by posting said modifications - to Usenet or an equivalent medium, or placing the modifications on - a major archive site such as ftp.uu.net, or by allowing the - Copyright Holder to include your modifications in the Standard - Version of the Package. - - b) use the modified Package only within your corporation or - organization. - - c) rename any non-standard executables so the names do not - conflict with standard executables, which must also be provided, - and provide a separate manual page for each non-standard - executable that clearly documents how it differs from the Standard - Version. - - d) make other distribution arrangements with the Copyright Holder. - -4. You may distribute the programs of this Package in object code or executable -form, provided that you do at least ONE of the following: - - a) distribute a Standard Version of the executables and library - files, together with instructions (in the manual page or equivalent) - on where to get the Standard Version. - - b) accompany the distribution with the machine-readable source of - the Package with your modifications. - - c) accompany any non-standard executables with their - corresponding Standard Version executables, giving the - non-standard executables non-standard names, and clearly - documenting the differences in manual pages (or equivalent), - together with instructions on where to get the Standard Version. - - d) make other distribution arrangements with the Copyright Holder. - -5. You may charge a reasonable copying fee for any distribution of this Package. -You may charge any fee you choose for support of this Package. You may not -charge a fee for this Package itself. However, you may distribute this Package in -aggregate with other (possibly commercial) programs as part of a larger -(possibly commercial) software distribution provided that you do not advertise -this Package as a product of your own. - -6. The scripts and library files supplied as input to or produced as output from -the programs of this Package do not automatically fall under the copyright of this -Package, but belong to whomever generated them, and may be sold -commercially, and may be aggregated with this Package. - -7. C or perl subroutines supplied by you and linked into this Package shall not -be considered part of this Package. - -8. Aggregation of this Package with a commercial distribution is always permitted -provided that the use of this Package is embedded; that is, when no overt attempt -is made to make this Package's interfaces visible to the end user of the -commercial distribution. Such use shall not be construed as a distribution of -this Package. - -9. The name of the Copyright Holder may not be used to endorse or promote -products derived from this software without specific prior written permission. - -10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR -PURPOSE. - -The End - - diff --git a/modules/fallback/CGI/README b/modules/fallback/CGI/README deleted file mode 100644 index 1af8860c6..000000000 --- a/modules/fallback/CGI/README +++ /dev/null @@ -1,41 +0,0 @@ -pod2text CGI::Perljax.pm > README - -CGI::Perljax - -Perljax - a perl-specific system for writing AJAX- or -DHTML-based web applications. - - -Perljax provides a unique mechanism for using perl code -asynchronously from javascript using AJAX to access user-written -perl functions/methods. Perljax unburdens the user from having to -write any javascript, except for having to associate an exported -method with a document-defined event (such as onClick, onKeyUp, -etc). Only in the more advanced implementations of a exported perl -method would a user need to write custom javascript. Perljax supports -methods that return single results, or multiple results to the web -page. No other projects that we know of are like Perljax for the -following reasons: 1. Perljax is targeted specifically for perl -development. 2. Perljax shields the user from having to write any -javascript at all (unless they want to). 3. The URL for the HTTP GET -request is automatically generated based on HTML layout and events, -and the page is then dynamically updated. 4. Perljax is not part -of a Content Management System, or some other larger project. - - -INSTALL - -perl Makefile.PL -make -make test -make install - -*If you are on a windows box you should use 'nmake' rather than 'make'. - -Installation will place Perljax into the system perl @INC path, but it -is important that you make sure mod_perl uses this path (which is -mod_perl's default behavior, and also assuming you use mod_perl, and -not just run perl as a CGI). - -Example scripts are provided in the source script directory, and can -also be seen on the project's website, http://www.perljax.us. diff --git a/modules/override/README b/modules/override/README deleted file mode 100644 index 0fbb2fd09..000000000 --- a/modules/override/README +++ /dev/null @@ -1,611 +0,0 @@ -NAME - YAML - YAML Ain't Markup Language (tm) - -SYNOPSIS - use YAML; - - # Load a YAML stream of 3 YAML documents into Perl data structures. - my ($hashref, $arrayref, $string) = Load(<<'...'); - --- - name: ingy - age: old - weight: heavy - # I should comment that I also like pink, but don't tell anybody. - favorite colors: - - red - - green - - blue - --- - - Clark Evans - - Oren Ben-Kiki - - Ingy döt Net - --- > - You probably think YAML stands for "Yet Another Markup Language". It - ain't! YAML is really a data serialization language. But if you want - to think of it as a markup, that's OK with me. A lot of people try - to use XML as a serialization format. - - "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!" - ... - - # Dump the Perl data structures back into YAML. - print Dump($string, $arrayref, $hashref); - - # YAML::Dump is used the same way you'd use Data::Dumper::Dumper - use Data::Dumper; - print Dumper($string, $arrayref, $hashref); - -DESCRIPTION - The YAML.pm module implements a YAML Loader and Dumper based on the YAML - 1.0 specification. - - YAML is a generic data serialization language that is optimized for - human readability. It can be used to express the data structures of most - modern programming languages. (Including Perl!!!) - - For information on the YAML syntax, please refer to the YAML - specification. - -WHY YAML IS COOL - YAML is readable for people. - It makes clear sense out of complex data structures. You should find - that YAML is an exceptional data dumping tool. Structure is shown - through indentation, YAML supports recursive data, and hash keys are - sorted by default. In addition, YAML supports several styles of - scalar formatting for different types of data. - - YAML is editable. - YAML was designed from the ground up to be an excellent syntax for - configuration files. Almost all programs need configuration files, - so why invent a new syntax for each one? And why subject users to - the complexities of XML or native Perl code? - - YAML is multilingual. - Yes, YAML supports Unicode. But I'm actually referring to - programming languages. YAML was designed to meet the serialization - needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was - also designed to be interoperable between those languages. That - means YAML serializations produced by Perl can be processed by - Python. - - YAML is taint safe. - Using modules like Data::Dumper for serialization is fine as long as - you can be sure that nobody can tamper with your data files or - transmissions. That's because you need to use Perl's "eval()" - built-in to deserialize the data. Somebody could add a snippet of - Perl to erase your files. - - YAML's parser does not need to eval anything. - - YAML is full featured. - YAML can accurately serialize all of the common Perl data structures - and deserialize them again without losing data relationships. - Although it is not 100% perfect (no serializer is or can be - perfect), it fares as well as the popular current modules: - Data::Dumper, Storable, XML::Dumper and Data::Denter. - - YAML.pm also has the ability to handle code (subroutine) references - and typeglobs. (Still experimental) These features are not found in - Perl's other serialization modules. - - YAML is extensible. - The YAML language has been designed to be flexible enough to solve - it's own problems. The markup itself has 3 basic construct which - resemble Perl's hash, array and scalar. By default, these map to - their Perl equivalents. But each YAML node also supports a tagging - mechanism (type system) which can cause that node to be interpreted - in a completely different manner. That's how YAML can support object - serialization and oddball structures like Perl's typeglob. - -YAML IMPLEMENTATIONS IN PERL - This module, YAML.pm, is really just the interface module for YAML - modules written in Perl. The basic interface for YAML consists of two - functions: "Dump" and "Load". The real work is done by the modules - YAML::Dumper and YAML::Loader. - - Different YAML module distributions can be created by subclassing - YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple - consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple. - - Why would there be more than one implementation of YAML? Well, despite - YAML's offering of being a simple data format, YAML is actually very - deep and complex. Implementing the entirety of the YAML specification is - a daunting task. - - For this reason I am currently working on 3 different YAML - implementations. - - YAML - The main YAML distribution will keeping evolving to support the - entire YAML specification in pure Perl. This may not be the fastest - or most stable module though. Currently, YAML.pm has lots of known - bugs. It is mostly a great tool for dumping Perl data structures to - a readable form. - - YAML::Lite - The point of YAML::Lite is to strip YAML down to the 90% that people - use most and offer that in a small, fast, stable, pure Perl form. - YAML::Lite will simply die when it is asked to do something it - can't. - - YAML::Syck - "libsyck" is the C based YAML processing library used by the Ruby - programming language (and also Python, PHP and Pugs). YAML::Syck is - the Perl binding to "libsyck". It should be very fast, but may have - problems of its own. It will also require C compilation. - - NOTE: Audrey Tang has actually completed this module and it works - great and is 10 times faster than YAML.pm. - - In the future, there will likely be even more YAML modules. Remember, - people other than Ingy are allowed to write YAML modules! - -FUNCTIONAL USAGE - YAML is completely OO under the hood. Still it exports a few useful top - level functions so that it is dead simple to use. These functions just - do the OO stuff for you. If you want direct access to the OO API see the - documentation for YAML::Dumper and YAML::Loader. - - Exported Functions - The following functions are exported by YAML.pm by default. The reason - they are exported is so that YAML works much like Data::Dumper. If you - don't want functions to be imported, just use YAML with an empty import - list: - - use YAML (); - - Dump(list-of-Perl-data-structures) - Turn Perl data into YAML. This function works very much like - Data::Dumper::Dumper(). It takes a list of Perl data strucures and - dumps them into a serialized form. It returns a string containing - the YAML stream. The structures can be references or plain scalars. - - Load(string-containing-a-YAML-stream) - Turn YAML into Perl data. This is the opposite of Dump. Just like - Storable's thaw() function or the eval() function in relation to - Data::Dumper. It parses a string containing a valid YAML stream into - a list of Perl data structures. - - Exportable Functions - These functions are not exported by default but you can request them in - an import list like this: - - use YAML qw'freeze thaw Bless'; - - freeze() and thaw() - Aliases to Dump() and Load() for Storable fans. This will also allow - YAML.pm to be plugged directly into modules like POE.pm, that use - the freeze/thaw API for internal serialization. - - DumpFile(filepath, list) - Writes the YAML stream to a file instead of just returning a string. - - LoadFile(filepath) - Reads the YAML stream from a file instead of a string. - - Bless(perl-node, [yaml-node | class-name]) - Associate a normal Perl node, with a yaml node. A yaml node is an - object tied to the YAML::Node class. The second argument is either a - yaml node that you've already created or a class (package) name that - supports a yaml_dump() function. A yaml_dump() function should take - a perl node and return a yaml node. If no second argument is - provided, Bless will create a yaml node. This node is not returned, - but can be retrieved with the Blessed() function. - - Here's an example of how to use Bless. Say you have a hash - containing three keys, but you only want to dump two of them. - Furthermore the keys must be dumped in a certain order. Here's how - you do that: - - use YAML qw(Dump Bless); - $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'}; - print Dump $hash; - Bless($hash)->keys(['banana', 'apple']); - print Dump $hash; - - produces: - - --- - apple: good - banana: bad - cauliflower: ugly - --- - banana: bad - apple: good - - Bless returns the tied part of a yaml-node, so that you can call the - YAML::Node methods. This is the same thing that YAML::Node::ynode() - returns. So another way to do the above example is: - - use YAML qw(Dump Bless); - use YAML::Node; - $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'}; - print Dump $hash; - Bless($hash); - $ynode = ynode(Blessed($hash)); - $ynode->keys(['banana', 'apple']); - print Dump $hash; - - Note that Blessing a Perl data structure does not change it anyway. - The extra information is stored separately and looked up by the - Blessed node's memory address. - - Blessed(perl-node) - Returns the yaml node that a particular perl node is associated with - (see above). Returns undef if the node is not (YAML) Blessed. - -GLOBAL OPTIONS - YAML options are set using a group of global variables in the YAML - namespace. This is similar to how Data::Dumper works. - - For example, to change the indentation width, do something like: - - local $YAML::Indent = 3; - - The current options are: - - DumperClass - You can override which module/class YAML uses for Dumping data. - - LoaderClass - You can override which module/class YAML uses for Loading data. - - Indent - This is the number of space characters to use for each indentation - level when doing a Dump(). The default is 2. - - By the way, YAML can use any number of characters for indentation at - any level. So if you are editing YAML by hand feel free to do it - anyway that looks pleasing to you; just be consistent for a given - level. - - SortKeys - Default is 1. (true) - - Tells YAML.pm whether or not to sort hash keys when storing a - document. - - YAML::Node objects can have their own sort order, which is usually - what you want. To override the YAML::Node order and sort the keys - anyway, set SortKeys to 2. - - Stringify - Default is 0. (false) - - Objects with string overloading should honor the overloading and - dump the stringification of themselves, rather than the actual - object's guts. - - UseHeader - Default is 1. (true) - - This tells YAML.pm whether to use a separator string for a Dump - operation. This only applies to the first document in a stream. - Subsequent documents must have a YAML header by definition. - - UseVersion - Default is 0. (false) - - Tells YAML.pm whether to include the YAML version on the - separator/header. - - --- %YAML:1.0 - - AnchorPrefix - Default is ''. - - Anchor names are normally numeric. YAML.pm simply starts with '1' - and increases by one for each new anchor. This option allows you to - specify a string to be prepended to each anchor number. - - UseCode - Setting the UseCode option is a shortcut to set both the DumpCode - and LoadCode options at once. Setting UseCode to '1' tells YAML.pm - to dump Perl code references as Perl (using B::Deparse) and to load - them back into memory using eval(). The reason this has to be an - option is that using eval() to parse untrusted code is, well, - untrustworthy. - - DumpCode - Determines if and how YAML.pm should serialize Perl code references. - By default YAML.pm will dump code references as dummy placeholders - (much like Data::Dumper). If DumpCode is set to '1' or 'deparse', - code references will be dumped as actual Perl code. - - DumpCode can also be set to a subroutine reference so that you can - write your own serializing routine. YAML.pm passes you the code ref. - You pass back the serialization (as a string) and a format - indicator. The format indicator is a simple string like: 'deparse' - or 'bytecode'. - - LoadCode - LoadCode is the opposite of DumpCode. It tells YAML if and how to - deserialize code references. When set to '1' or 'deparse' it will - use "eval()". Since this is potentially risky, only use this option - if you know where your YAML has been. - - LoadCode can also be set to a subroutine reference so that you can - write your own deserializing routine. YAML.pm passes the - serialization (as a string) and a format indicator. You pass back - the code reference. - - UseBlock - YAML.pm uses heuristics to guess which scalar style is best for a - given node. Sometimes you'll want all multiline scalars to use the - 'block' style. If so, set this option to 1. - - NOTE: YAML's block style is akin to Perl's here-document. - - UseFold - If you want to force YAML to use the 'folded' style for all - multiline scalars, then set $UseFold to 1. - - NOTE: YAML's folded style is akin to the way HTML folds text, except - smarter. - - UseAliases - YAML has an alias mechanism such that any given structure in memory - gets serialized once. Any other references to that structure are - serialized only as alias markers. This is how YAML can serialize - duplicate and recursive structures. - - Sometimes, when you KNOW that your data is nonrecursive in nature, - you may want to serialize such that every node is expressed in full. - (ie as a copy of the original). Setting $YAML::UseAliases to 0 will - allow you to do this. This also may result in faster processing - because the lookup overhead is by bypassed. - - THIS OPTION CAN BE DANGEROUS. *If* your data is recursive, this - option *will* cause Dump() to run in an endless loop, chewing up - your computers memory. You have been warned. - - CompressSeries - Default is 1. - - Compresses the formatting of arrays of hashes: - - - - foo: bar - - - bar: foo - - becomes: - - - foo: bar - - bar: foo - - Since this output is usually more desirable, this option is turned - on by default. - -YAML TERMINOLOGY - YAML is a full featured data serialization language, and thus has its - own terminology. - - It is important to remember that although YAML is heavily influenced by - Perl and Python, it is a language in its own right, not merely just a - representation of Perl structures. - - YAML has three constructs that are conspicuously similar to Perl's hash, - array, and scalar. They are called mapping, sequence, and string - respectively. By default, they do what you would expect. But each - instance may have an explicit or implicit tag (type) that makes it - behave differently. In this manner, YAML can be extended to represent - Perl's Glob or Python's tuple, or Ruby's Bigint. - - stream - A YAML stream is the full sequence of unicode characters that a YAML - parser would read or a YAML emitter would write. A stream may - contain one or more YAML documents separated by YAML headers. - - --- - a: mapping - foo: bar - --- - - a - - sequence - - document - A YAML document is an independent data structure representation - within a stream. It is a top level node. Each document in a YAML - stream must begin with a YAML header line. Actually the header is - optional on the first document. - - --- - This: top level mapping - is: - - a - - YAML - - document - - header - A YAML header is a line that begins a YAML document. It consists of - three dashes, possibly followed by more info. Another purpose of the - header line is that it serves as a place to put top level tag and - anchor information. - - --- !recursive-sequence &001 - - * 001 - - * 001 - - node - A YAML node is the representation of a particular data stucture. - Nodes may contain other nodes. (In Perl terms, nodes are like - scalars. Strings, arrayrefs and hashrefs. But this refers to the - serialized format, not the in-memory structure.) - - tag This is similar to a type. It indicates how a particular YAML node - serialization should be transferred into or out of memory. For - instance a Foo::Bar object would use the tag 'perl/Foo::Bar': - - - !perl/Foo::Bar - foo: 42 - bar: stool - - collection - A collection is the generic term for a YAML data grouping. YAML has - two types of collections: mappings and sequences. (Similar to hashes - and arrays) - - mapping - A mapping is a YAML collection defined by unordered key/value pairs - with unique keys. By default YAML mappings are loaded into Perl - hashes. - - a mapping: - foo: bar - two: times two is 4 - - sequence - A sequence is a YAML collection defined by an ordered list of - elements. By default YAML sequences are loaded into Perl arrays. - - a sequence: - - one bourbon - - one scotch - - one beer - - scalar - A scalar is a YAML node that is a single value. By default YAML - scalars are loaded into Perl scalars. - - a scalar key: a scalar value - - YAML has many styles for representing scalars. This is important - because varying data will have varying formatting requirements to - retain the optimum human readability. - - plain scalar - A plain sclar is unquoted. All plain scalars are automatic - candidates for "implicit tagging". This means that their tag may be - determined automatically by examination. The typical uses for this - are plain alpha strings, integers, real numbers, dates, times and - currency. - - - a plain string - - -42 - - 3.1415 - - 12:34 - - 123 this is an error - - single quoted scalar - This is similar to Perl's use of single quotes. It means no escaping - except for single quotes which are escaped by using two adjacent - single quotes. - - - 'When I say ''\n'' I mean "backslash en"' - - double quoted scalar - This is similar to Perl's use of double quotes. Character escaping - can be used. - - - "This scalar\nhas two lines, and a bell -->\a" - - folded scalar - This is a multiline scalar which begins on the next line. It is - indicated by a single right angle bracket. It is unescaped like the - single quoted scalar. Line folding is also performed. - - - > - This is a multiline scalar which begins on - the next line. It is indicated by a single - carat. It is unescaped like the single - quoted scalar. Line folding is also - performed. - - block scalar - This final multiline form is akin to Perl's here-document except - that (as in all YAML data) scope is indicated by indentation. - Therefore, no ending marker is required. The data is verbatim. No - line folding. - - - | - QTY DESC PRICE TOTAL - --- ---- ----- ----- - 1 Foo Fighters $19.95 $19.95 - 2 Bar Belles $29.95 $59.90 - - parser - A YAML processor has four stages: parse, load, dump, emit. - - A parser parses a YAML stream. YAML.pm's Load() function contains a - parser. - - loader - The other half of the Load() function is a loader. This takes the - information from the parser and loads it into a Perl data structure. - - dumper - The Dump() function consists of a dumper and an emitter. The dumper - walks through each Perl data structure and gives info to the - emitter. - - emitter - The emitter takes info from the dumper and turns it into a YAML - stream. - - NOTE: In YAML.pm the parser/loader and the dumper/emitter code are - currently very closely tied together. In the future they may be - broken into separate stages. - - For more information please refer to the immensely helpful YAML - specification available at . - -ysh - The YAML Shell - The YAML distribution ships with a script called 'ysh', the YAML shell. - ysh provides a simple, interactive way to play with YAML. If you type in - Perl code, it displays the result in YAML. If you type in YAML it turns - it into Perl code. - - To run ysh, (assuming you installed it along with YAML.pm) simply type: - - ysh [options] - - Please read the "ysh" documentation for the full details. There are lots - of options. - -BUGS & DEFICIENCIES - If you find a bug in YAML, please try to recreate it in the YAML Shell - with logging turned on ('ysh -L'). When you have successfully reproduced - the bug, please mail the LOG file to the author (ingy@cpan.org). - - WARNING: This is still *ALPHA* code. Well, most of this code has been - around for years... - - BIGGER WARNING: YAML.pm has been slow in the making, but I am committed - to having top notch YAML tools in the Perl world. The YAML team is close - to finalizing the YAML 1.1 spec. This version of YAML.pm is based off of - a very old pre 1.0 spec. In actuality there isn't a ton of difference, - and this YAML.pm is still fairly useful. Things will get much better in - the future. - -RESOURCES - is the mailing - list. This is where the language is discussed and designed. - - is the official YAML website. - - is the YAML 1.0 specification. - - is the official YAML wiki. - -SEE ALSO - See YAML::Syck. Fast! - -AUTHOR - Ingy döt Net - - is resonsible for YAML.pm. - - The YAML serialization language is the result of years of collaboration - between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others - have added help along the way. - -COPYRIGHT - Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright - (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved. - - This program is free software; you can redistribute it and/or modify it - under the same terms as Perl itself. - - See -