= SnakeYAML =

'''SnakeYAML is a YAML parser and emitter for Java.'''


== Overview ==

[http://yaml.org/ YAML] is a data serialization format designed for human
readability and interaction with scripting languages.

[http://pyyaml.org/wiki/SnakeYAML SnakeYAML] is a YAML parser and emitter for
the Java programming language. SnakeYAML tries to be as close as possible to PyYAML
API allowing documents to be easily exchanged between Python and Java.

SnakeYAML features

 * a '''complete''' [http://yaml.org/spec/current.html YAML 1.1] parser.
   In particular, SnakeYAML can parse all examples from the specification.
 * Unicode support including UTF-8/UTF-16 input/output.
 * high-level API for serializing and deserializing native Java objects.
 * support for all types from the [http://yaml.org/type/index.html YAML types repository].
 * relatively sensible error messages.

Note that SnakeYAML is still young and may have some bugs.

== Requirements ==

SnakeYAML requires Java 5 or higher.


== Download and Installation ==

The current stable release of SnakeYAML: '''1.1'''.

Download links:

 * '''source''': http://www.assembla.com/spaces/snakeyaml/trac_mercurial_tool
 * '''JAR package''': http://snakeyamlrepo.appspot.com/repository/SnakeYAML/SnakeYAML/1.1/SnakeYAML-1.1.jar
 * '''ZIP archive''': http://www.assembla.com/spaces/snakeyaml/documents/ahRjS-eoSr3QBDeJe5aVNr/download/SnakeYAML-all-1.1.zip
 * '''Repository''': http://snakeyamlrepo.appspot.com/
 
Browse 1.1 reports:

 * '''Maven generated report''': http://snakeyamlrepo.appspot.com/releases/1.1/site/index.html
 * '''Project's report''': http://snakeyamlrepo.appspot.com/releases/1.1/site/project-reports.html
 * '''Javadocs''': http://snakeyamlrepo.appspot.com/releases/1.1/site/apidocs/index.html
 * '''Changes report''': http://snakeyamlrepo.appspot.com/releases/1.1/site/changes-report.html
 * '''Maven generated report''': http://snakeyamlrepo.appspot.com/releases/1.1/site/index.html
 * '''Test coverage report''': http://snakeyamlrepo.appspot.com/releases/1.1/site/cobertura/index.html

Maven 2 configuration:

Repository definition (in settings.xml) 
{{{
<repositories>
  ...
  <repository>
    <id>snakeyaml</id>
    <name>SnakeYAML repository</name>
    <url>http://snakeyamlrepo.appspot.com/repository</url>
  </repository>
  ...
</repositories>
}}}

Dependency definition (in pom.xml)
{{{
<dependencies>
  ...
  <dependency>
    <groupId>SnakeYAML</groupId>
    <artifactId>SnakeYAML</artifactId>
    <version>1.1</version>
  </dependency>
  ...
</dependencies>
}}}

== Documentation ==

''Loading:''
{{{
Yaml yaml = new Yaml();
Object obj = yaml.load("a: 1\nb: 2\nc:\n  - aaa\n  - bbb");
System.out.println(obj);

{b=2, c=[aaa, bbb], a=1}
}}}
''Dumping:''
{{{

Map<String, String> map = new HashMap<String, String>();
map.put("name", "Pushkin");
Yaml yaml = new Yaml();
String output = yaml.dump(map);
System.out.println(output);

--- 
name: Pushkin
}}}

For more details, please check [wiki:Documentation SnakeYAML Documentation].


== History ==
'''1.1 (2009-03-14)'''
 * Test coverage reached 98%
 * byte[] is used for type `binary`
 * Better Spring support: the root `JavaBean` class can be specified as a String
 * Performance: fix a bug with expanding Regular Expressions (thanks to Christophe Desguez)
 * Fix ticket #4: java.sql.Date was not handled properly (thanks to Christophe Desguez)
 * Introduce `Enums` in `DumperOptions`
 * Minor refactoring and bug fixes
 * Add [/snakeyaml/wiki/Documentation#Threading Threads] and 
 [/snakeyaml/wiki/Documentation#Spring Spring] sections to the wiki documentation
 
'''1.0.1 (2009-02-18)'''
 * Proper `Enum` [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#Enum support] (thanks to James Nissel)
 * Minor performance improvement
 * Fix minor issues in `DumperOptions`
 
'''1.0 (2009-02-06)'''
 * Use `LinkedHashMap` to respect the order where it is required (`ScannerImpl`.java and Emitter.java)
 * The mailing list is renamed to `snakeyaml-core` to avoid a name conflict in `Google` `AppEngine`
 
'''1.0rc2 (2009-01-22)'''
 * Add [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#JavaBeans JavaBeans section] to the wiki
 * Provide possibility to define/eliminate the root tag for `JavaBeans`
 * Arrays as `JavaBens` properties are properly supported
 * Do not emit redundant tags for `JavaBeans`
 * Respect public fields in `JavaBeans`

'''1.0rc1 (2009-01-16)'''
 * Implement [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#Typesafecollections type safe List and Map] 
 as a property of a custom Java class
 * Remove Java 6 dependencies
 
'''0.91 (2009-01-14)'''
 * Support [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#Shortcuts shortcut tags] for custom classes
 * Import canonical scanner and parser from PyYAML
 
'''0.9 (2009-01-12)'''
 * Minor changes
 * Add possibility [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#Providingthetopleveltype to provide] the top level type
 * Fix a bug in Emitter when writing folded scalars
   
'''0.8 (2009-01-07)'''
 * Add possibility to use java.io.Reader as input
 * Import changes from [http://pyyaml.org/wiki/PyYAML#History PyYAML 3.07/3.08]
 * Use global tags (with !!) to load/dump Java custom classes
 * Fix parsing Long.MIN_VALUE
 * When constructing integers try to create the first in the following order: 
   Integer -> Long -> `BigInteger`

'''0.7 (2008-12-20)'''
 * Improve test coverage

'''0.6 (2008-12-17)'''
 * Add more examples to the documentation
 * Public interface is using Iterator instead of Iterable
 * Sort names when `JavaBeans` are represented
 * defaultFlowStyle for Dumper is configurable in `DumperOptions`

'''0.5 (2008-12-12)'''
 * Add possibility to define an implicit resolver
 * Add possibility to define an explicit constructor
 * Java objects can be constructed from mapping (javabean), from sequence (constructor),
   from scalar (constructor)
 * fix omap and pairs tags
 * Implement possibility to define a custom List or Map implementation
 * Implement possibility to define a custom Representer
 * Support arrays of reference types
 * Import latest changes from PyYAML (after 3.06 was released)
 * Fix Node identity to avoid aliases for simple types - [1, 1]
 * Recursive objects can be represented (but not yet constructed)
 * Binary is represented back as String
 * Fix: 'null' can be a key in a map
 * Fix: 'set' type works

'''0.4 (2008-11-11)'''
 * Fix a deviation with PyYAML in method scanBlockScalar().
   Fix a bug in [https://jvyaml.dev.java.net/ JvYaml] that the trailing '\n' in a 
   block scalar was removed
 * Restore from PyYAML the way the keys are parsed. (Restored methods are
   stalePossibleSimpleKeys() and removePossibleSimpleKey().)
   Fix issue http://code.google.com/p/jvyamlb/issues/detail?id=6
 * Change public interface. Rename YAML to Yaml. Remove all static methods from Yaml.
   Factory and configuration must be injected at the constructor. 
   Yaml loadAll() and dumpAll() methods work with Iterable instead of List.
   This way is closer to PyYAML API
 * Reader as in PyYAML is implemented. BOM is properly supported. Fix a known [http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4508058 bug] in Java
 * Fix issue: https://jvyaml.dev.java.net/issues/show_bug.cgi?id=11
 * Respect Unicode characters.
   Fix issue: https://jvyaml.dev.java.net/issues/show_bug.cgi?id=10
 * Respect sign for float.
   Fix issue: https://jvyaml.dev.java.net/issues/show_bug.cgi?id=13
 * Binary data is represented as [http://java.sun.com/javase/6/docs/api/java/nio/ByteBuffer.html ByteBuffer]
 * When parsed, a timestamp in the canonical form (i.e, 2001-12-15T02:59:43.1Z) is
   interpreted as if it is in the default time zone.
   Fix issue: https://jvyaml.dev.java.net/issues/show_bug.cgi?id=7 
 * Restore Mark from PyYAML to show a snippet of YAML in case of invalid data
 * Reformat the source files and provide formatter for Eclipse
 * Mavenize the project and apply Maven standard folder structure
 * Import [https://jvyaml.dev.java.net JvYaml] source from CVS to Mercurial

== Development and bug reports ==

You may check out the SnakeYAML source code from
[http://hg.assembla.com/snakeyaml SnakeYAML Mercurial repository].

You may also 
[http://trac-hg.assembla.com/snakeyaml/browser browse] the SnakeYAML source code.

If you find a bug in SnakeYAML, please
[http://trac-hg.assembla.com/snakeyaml/newticket file a bug report].
You may review open bugs through
[http://trac-hg.assembla.com/snakeyaml/report/1 the list of open tickets].

You may discuss SnakeYAML at
[http://groups.google.com/group/snakeyaml-core the mailing list].

== TODO ==
 * proper `enum` support 
 
== Known bugs ==
 * Recursive objects are not fully supported. Dumping works but loading does not.

== Author and copyright ==

The SnakeYAML is developed by Andrey Somov and it is based on [http://pyyaml.org/wiki/PyYAML PyYAML] 
module written by [mailto:xi@resolvent.net Kirill Simonov].

SnakeYAML is released under the MIT license.