blob: a89b7ac82a0c650fd61eed13f703548c627c5b62 [file] [log] [blame]
= SnakeYAML =
'''SnakeYAML is a YAML parser and emitter for Java.'''
== Overview ==
[ YAML] is a data serialization format designed for human
readability and interaction with scripting languages.
[ 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''' [ 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 [ 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''':
* '''JAR package''':
* '''ZIP archive''':
* '''Repository''':
Browse 1.1 reports:
* '''Maven generated report''':
* '''Project's report''':
* '''Javadocs''':
* '''Changes report''':
* '''Maven generated report''':
* '''Test coverage report''':
Maven 2 configuration:
Repository definition (in settings.xml)
<name>SnakeYAML repository</name>
Dependency definition (in pom.xml)
== Documentation ==
Yaml yaml = new Yaml();
Object obj = yaml.load("a: 1\nb: 2\nc:\n - aaa\n - bbb");
{b=2, c=[aaa, bbb], a=1}
Map<String, String> map = new HashMap<String, String>();
map.put("name", "Pushkin");
Yaml yaml = new Yaml();
String output = yaml.dump(map);
name: Pushkin
For more details, please check [wiki:Documentation SnakeYAML Documentation].
== History ==
'''1.1.1 (in Mercurial)'''
* 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` [ 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
* The mailing list is renamed to `snakeyaml-core` to avoid a name conflict in `Google` `AppEngine`
'''1.0rc2 (2009-01-22)'''
* Add [ 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 [ type safe List and Map]
as a property of a custom Java class
* Remove Java 6 dependencies
'''0.91 (2009-01-14)'''
* Support [ shortcut tags] for custom classes
* Import canonical scanner and parser from PyYAML
'''0.9 (2009-01-12)'''
* Minor changes
* Add possibility [ to provide] the top level type
* Fix a bug in Emitter when writing folded scalars
'''0.8 (2009-01-07)'''
* Add possibility to use as input
* Import changes from [ 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 [ 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
* 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 [ bug] in Java
* Fix issue:
* Respect Unicode characters.
Fix issue:
* Respect sign for float.
Fix issue:
* Binary data is represented as [ 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:
* 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 [ JvYaml] source from CVS to Mercurial
== Development and bug reports ==
You may check out the SnakeYAML source code from
[ SnakeYAML Mercurial repository].
You may also
[ browse] the SnakeYAML source code.
If you find a bug in SnakeYAML, please
[ file a bug report].
You may review open bugs through
[ the list of open tickets].
You may discuss SnakeYAML at
[ 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 [ PyYAML]
module written by [ Kirill Simonov].
SnakeYAML is released under the MIT license.