README

   1 #
   2 #    S P Y C
   3 #      a simple php yaml class
   4 #   v0.3
   5 #
   6 # Load this README!
   7 # >> $readme = Spyc::YAMLLoad('README');
   8 #
   9 --- %YAML:1.1
  10 title: Spyc -- a Simple PHP YAML Class
  11 version: 0.3
  12 author: [chris wanstrath, chris@ozmm.org]
  13 websites: [http://www.yaml.org, http://spyc.sourceforge.net]
  14 license: [MIT License, http://www.opensource.org/licenses/mit-license.php]
  15 copyright: (c) 2005-2006 Chris Wanstrath
  16 tested on: [php 4.3.11, php 5.0.4]
  17
  18 installation: >
  19   Copy spyc.php to a directory you can
  20   access with your YAML-ready PHP script.
  21
  22   That's it!
  23
  24 about: >
  25   From www.yaml.org:
  26
  27   "YAML(tm) (rhymes with 'camel') is a human-friendly, cross language,
  28   Unicode based data serialization language designed around the common
  29   native data structures of agile programming languages. It is broadly
  30   useful for programming needs ranging from configuration files to
  31   Internet messaging to object persistence to data auditing. Together
  32   with the Unicode standard for characters, the YAML specification provides
  33   all the information necessary to understand YAML Version 1.1 and to
  34   creating programs that process YAML information.
  35
  36   YAML(tm) is a balance of the following design goals:
  37     - YAML documents are very readable by humans.
  38     - YAML interacts well with scripting languages.
  39     - YAML uses host languages' native data structures.
  40     - YAML has a consistent information model.
  41     - YAML enables stream-based processing.
  42     - YAML is expressive and extensible.
  43     - YAML is easy to implement."
  44
  45   YAML makes a lot of sense.  It's easy to use, easy to learn, and cool.
  46   As the lucky stiff named why once said, "YAML is a beacon of light."
  47
  48   If you're new to YAML, may we suggest YAML In Five Minutes:
  49     - http://yaml.kwiki.org/?YamlInFiveMinutes
  50
  51   If you don't have five minutes, realize that this README is a completely
  52   valid YAML document.  Dig in, load this or any YAML file into an array
  53   with Spyc and see how easy it is to translate friendly text into usable
  54   data.
  55
  56   The purpose of Spyc is to provide a pure PHP alternative to Syck, a
  57   simple API for loading and dumping YAML documents, a YAML loader which
  58   understands a usable subset of the YAML spec, and to further spread
  59   the glory of YAML to the PHP masses.
  60
  61   If you're at all hesitant ("usable subset of YAML?!"), navigate
  62   http://yaml.org/start.html.  Spyc completely understands the YAML
  63   document shown there, a document which has features way beyond the
  64   scope of what normal config files might require.  Try it for yourself,
  65   and then start enjoying the peace of mind YAML brings to your life.
  66
  67 meat and a few potatoes:
  68   - concept: Loading a YAML document into PHP
  69     brief: >
  70       $yaml will become an array of all the data in wicked.yaml
  71     code: |
  72
  73       include('spyc.php');
  74
  75       $yaml = Spyc::YAMLLoad('wicked.yaml');
  76
  77   - concept: Loading a YAML string into PHP
  78     brief: >
  79       $array will look like this:
  80         array('A YAML','document in a','string')
  81     code: |
  82
  83       include('spyc.php');
  84
  85       $yaml  = '- A YAML\n- document in a\n- string.';
  86       $array = Spyc::YAMLLoad($yaml);
  87
  88   - concept: Dumping a PHP array to YAML
  89     brief: >
  90       $yaml will become a string of a YAML document created from
  91       $array.
  92     code: |
  93
  94       include('spyc.php');
  95
  96       $array['name']  = 'chris';
  97       $array['sport'] = 'curbing';
  98
  99       $yaml = Spyc::YAMLDump($array);
 100
 101 prior art:
 102   - who: [Brian Ingerson, Clark Evans, Oren Ben-Kiki]
 103     why?: >
 104       The YAML spec is really a piece of work, and these guys
 105       did a great job on it.  A simple and elegant language like
 106       YAML was a long time coming and it's refreshing to know
 107       such able minded individuals took the task to heart and
 108       executed it with cunning and strength.  In addition to
 109       their various noteworthy contributions to YAML parsers
 110       and related projects, YAML.pm's README is a treasure trove
 111       of information for knowledge seekers.  Thanks, guys.
 112
 113   - who: why the lucky stiff
 114     why?: >
 115       As the author of Syck, the code used in Ruby for the language's
 116       YAML class and methods, why is indirectly (directly?) responsible
 117       for my first exposure to YAML (as a config file in a Ruby web-app)
 118       and the countless hours I spent playing with this sheik new data
 119       format afterwards.  Syck's README is a YAML file and thus the
 120       inspiration for this file and, even, this very piece of software.
 121
 122   - who: Steve Howell
 123     why?: >
 124       Python's YAML implementation.  PyYAML's README file is also YAML,
 125       so it too inspired the YAML format of this README file.
 126
 127   - who: [Rasmus Lerdorf, Zeev Suraski, Andi Gutmans, et al]
 128     why?: >
 129       PHP is great at what it does best.  It's also paid a lot of my bills.
 130       Thanks.
 131
 132 bugs:
 133   report: >
 134     Please see Spyc's Sourceforge project page for information on reporting bugs.
 135   speed: >
 136     This implementation was not designed for speed.  Rather, it
 137     was designed for those who need a pure PHP implementation of
 138     a YAML parser and who are not overly concerned with performance.
 139     If you want speed, check out Syck.
 140   depth: >
 141     This parser is by no means a comprehensive YAML parser.  For supported
 142     features and future plans, check the website.
 143   unicode: >
 144     YAML is supposed to be unicode, but for now we're just using ASCII.
 145     PHP has crappy unicode support but who knows what the future holds.
 146
 147 resources:
 148   - http://www.yaml.org
 149   - http://www.yaml.org/spec/
 150   - http://yaml.kwiki.org/?YamlInFiveMinutes
 151   - http://www.whytheluckystiff.net/syck/
 152   - http://yaml4r.sourceforge.net/cookbook/
 153   - http://www.sourceforge.net/projects/spyc/
 154   - http://spyc.sourceforge.net/
 155
 156 thanks:
 157   - Adam Wood
 158   - Daniel Ferreira
 159   - Aaron Jensen
 160   - Mike Thornton
 161   - Fabien Potencier
 162   - Mustafa Kumas