Permalink
Browse files

initial checkin of yaml project

  • Loading branch information...
1 parent d8778f4 commit 381b6bad7063fd8bed0b7d96bc174e8413550b07 @goertzenator committed May 24, 2012
View
@@ -0,0 +1,11 @@
+.eunit/
+.project
+.settings/
+*.o
+ebin/
+priv/
+
+doc/edoc-info
+doc/*.png
+doc/*.html
+doc/*.css
View
16 LICENSE
@@ -0,0 +1,16 @@
+Libyaml license as per file c_src/libyaml/LICENSE
+Erlang application license:
+
+Copyright (c) 2012, Daniel Goertzen <daniel.goertzen@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
View
168 README.md
@@ -1,4 +1,166 @@
-yaml
-====
+# Erlang YAML Loader
+
+This application loads [YAML](http://en.wikipedia.org/wiki/Yaml) files into Erlang. This implementation supports:
+
+* Anchors and aliases
+* [Merge tags](http://yaml.org/type/merge.html)
+* The tag `!atom` for explicitely tagging values as atoms.
+* An `implicit_atoms` mode to interpret values that look atom-ish as atoms.
+* Customizable schemas via callback modules.
+
+This application embeds the C yaml parser "[libyaml](http://pyyaml.org/wiki/LibYAML)" which is compiled as a NIF.
+
+# Example
+
+###The yaml file...
+
+ # demo1.yaml
+ ---
+ receipt: Oz-Ware Purchase Invoice
+ date: 2007-08-06
+ customer:
+ given: Dorothy
+ family: Gale
+
+ items:
+ - part_no: A4786
+ descrip: Water Bucket (Filled)
+ price: 1.47
+ quantity: 4
+
+ - part_no: E1628
+ descrip: High Heeled "Ruby" Slippers
+ size: 8
+ price: 100.27
+ quantity: 1
+
+ bill_to: &id001
+ street: |
+ 123 Tornado Alley
+ Suite 16
+ city: East Centerville
+ state: KS
+
+ ship_to: *id001
+
+ specialDelivery: >
+ Follow the Yellow Brick
+ Road to the Emerald City.
+ Pay no attention to the
+ man behind the curtain.
+ ...
+
+
+
+###Load command...
+
+ 3> yaml:load_file("test/yaml/demo1.yaml", [implicit_atoms]).
+
+ {ok,[[{customer,[{family,<<"Gale">>},{given,<<"Dorothy">>}]},
+ {items,[[{descrip,<<"Water Bucket (Filled)">>},
+ {price,1.47},
+ {quantity,4},
+ {part_no,<<"A4786">>}],
+ [{descrip,<<"High Heeled \"Ruby\" Slippers">>},
+ {price,100.27},
+ {size,8},
+ {quantity,1},
+ {part_no,<<"E1628">>}]]},
+ {receipt,<<"Oz-Ware Purchase Invoice">>},
+ {date,<<"2007-08-06">>},
+ {specialDelivery,<<"Follow the Yellow Brick Road to the Emerald City. Pay no attention to the ma"...>>},
+ {ship_to,[{street,<<"123 Tornado Alley\nSuite 16\n">>},
+ {state,<<"KS">>},
+ {city,<<"East Centerville">>}]},
+ {bill_to,[{street,<<"123 Tornado Alley\nSuite 16\n">>},
+ {state,<<"KS">>},
+ {city,<<"East Centerville">>}]}]]}
+
+
+# Installation
+
+### Download
+Download the code...
+
+ $ git clone git@github.com:goertzenator/yaml.git
+
+### Compile
+Build the source and documentation and run tests with...
+
+ $ cd yaml
+ $ rebar compile doc eunit
+
+The NIF module spews a few warnings. This is okay.
+
+Play with it..
+
+ $ export ERL_LIBS=$(pwd)
+ $ erl
+ Erlang R15B01 (erts-5.9.1) [source] [64-bit] [smp:3:3] [async-threads:0] [kernel-poll:false]
+
+ Eshell V5.9.1 (abort with ^G)
+ 1> yaml:load_file("test/yaml/demo1.yaml").
+ {ok,[[{<<"specialDelivery">>,
+ <<"Follow the Yellow Brick Road to the Emerald City. Pay no attention to the man behind the cur"...>>},
+ {<<"items">>, ...
+
+
+
+# Schemas
+
+Tag resolution and value construction are implemented in *schema callback modules*. This application includes 4 different schema callback modules, and others can be implemented if different behavior is required.
+
+The included schemas are:
+
+* `yaml_schema_failsafe`
+* `yaml_schema_json`
+* `yaml_schema_core`
+* `yaml_schame_erlang` (default)
+
+The schema is selected with the `schema` option, for example:
+
+ 4> yaml:load_file("test/yaml/demo1.yaml", [{schema, yaml_schema_core}]).
+ {ok,[[{<<"specialDelivery">>, ...
+
+
+
+`failsafe` and `json` are defined by the yaml spec. They are of limited use, however the schema modules can be instructive if you want to write your own.
+
+The `core` schema (defined by the yaml spec) has most of waht you need to make good use of yaml. The `erlang` schema extends core with [merge](http://yaml.org/type/merge.html) and atom support.
+
+To explicitely tag a value as an atom, use the `!atom` tag, for example:
+
+ - !atom an_atom
+ - !atom yet another atom
+
+To turn on implicit atom detection for untagged values, use the erlang schema and pass in the `implicit_atoms` options, for example:
+
+ 5> yaml:load_file("test/yaml/demo1.yaml", [implicit_atoms]).
+
+The following yaml fragment illustrates which values will be recognized as atoms:
+
+ - "not an atom"
+ - not an atom
+ - 'an atom'
+ - an_atom
+ - anatom
+ - aNA_t@OM@_
+ - Not_an_atom
+ - Notanatom
+ - "not_an_atom"
+
+
+## Custom Schemas
+
+See the behavior documenation for yaml_schema and the 4 schemas included in this application.
+
+# Tips
+
+If you are using erlide, I recommend the eclipse yaml editor [yedit](http://code.google.com/p/yedit/).
+
+# Limitations
+
+* This app does not emit yaml.
+* This app may stumble on enormous yaml files because the entire file, event stream, and constructed documents must fit in memory at once. Also, a scheduler may be stuck in a NIF call for a while when parsing a very large yaml file.
+
-libyaml-based yaml loader for Erlang
View
@@ -0,0 +1,19 @@
+Copyright (c) 2006 Kirill Simonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
View
@@ -0,0 +1,27 @@
+LibYAML - A C library for parsing and emitting YAML.
+
+To build and install the library, run:
+$ ./configure
+$ make
+# make install
+
+If you checked the source code from the Subversion repository, run
+$ ./bootstrap
+$ ./configure
+$ make
+# make install
+
+For more information, check the LibYAML homepage:
+'http://pyyaml.org/wiki/LibYAML'.
+
+Post your questions and opinions to the YAML-Core mailing list:
+'http://lists.sourceforge.net/lists/listinfo/yaml-core'.
+
+Submit bug reports and feature requests to the LibYAML bug tracker:
+'http://pyyaml.org/newticket?component=libyaml'.
+
+LibYAML is written by Kirill Simonov <xi@resolvent.net>. It is released
+under the MIT license. See the file LICENSE for more details.
+
+This project is developed for Python Software Foundation as a part of
+Google Summer of Code under the mentorship of Clark Evans.
Oops, something went wrong.

0 comments on commit 381b6ba

Please sign in to comment.