| = 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.2'''. |
| |
| Download links: |
| |
| * '''source''': http://www.assembla.com/spaces/snakeyaml/trac_mercurial_tool |
| * '''JAR package''': http://snakeyamlrepo.appspot.com/repository/SnakeYAML/SnakeYAML/1.2/SnakeYAML-1.2.jar |
| * '''ZIP archive''': http://www.assembla.com/spaces/snakeyaml/documents/aHaHLImW0r3R86eJe5afGb/download/SnakeYAML-all-1.2.zip |
| * '''Repository''': http://snakeyamlrepo.appspot.com/ |
| |
| Browse 1.2 reports: |
| |
| * '''Maven generated report''': http://snakeyamlrepo.appspot.com/releases/1.2/site/index.html |
| * '''Project's report''': http://snakeyamlrepo.appspot.com/releases/1.2/site/project-reports.html |
| * '''Javadocs''': http://snakeyamlrepo.appspot.com/releases/1.2/site/apidocs/index.html |
| * '''Changes report''': http://snakeyamlrepo.appspot.com/releases/1.2/site/changes-report.html |
| * '''Maven generated report''': http://snakeyamlrepo.appspot.com/releases/1.2/site/index.html |
| * '''Test coverage report''': http://snakeyamlrepo.appspot.com/releases/1.2/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.2</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 == |
| |
| '''(in Mecrurial)''' |
| * Fix [http://trac-hg.assembla.com/snakeyaml/ticket/40 ticket #40]: java.sql.Timestamp was not handled properly (thanks to Magne) |
| |
| '''1.2 (2009-04-27)''' |
| * add [http://trac-hg.assembla.com/snakeyaml/wiki/Documentation#LowLevelAPI info for low-level API] |
| * Add 'Yaml.parse()' method which return Events to support low level YAML processing |
| * Add 'Yaml.compose()' methods which return Nodes |
| * Rename `LineBreak`.LINUX to `LineBreak`.UNIX |
| * Refactor: rename enums in `DumperOptions` to make the names consistent |
| * Add possibility to parse all scalars as Strings |
| * Respect `DumperOptions` with a custom Representer |
| * Represent TAB as '\t' instead of '(9' in an error message |
| |
| '''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]. |
| |
| == 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. |