peisongxiao/yaml-cpp
1
0
Fork 0
mirror of https://github.com/jbeder/yaml-cpp.git synced 2025-09-08 04:11:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Migrating wiki contents from Google Code

Browse Source
This commit is contained in:
Google Code Exporter
2015-03-29 22:55:58 -04:00
commit 174392529c
10 changed files with 1239 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
BreakingChanges.md Normal file
View File

@@ -0,0 +1,39 @@
# The following is a list of breaking changes to yaml-cpp, by version #
# New API #
## 0.5.2 ##
_none_
## 0.5.1 ##
* `Node::clear` was replaced by `Node::reset`, which takes an optional node, similar to smart pointers.
## 0.5.0 ##
Initial version of the new API.
# Old API #
## 0.3.0 ##
_none_
## 0.2.7 ##
* `YAML::Binary` now takes `const unsigned char *` for the binary data (instead of `const char *`).
## 0.2.6 ##
* `Node::GetType()` is now `Node::Type()`, and returns an enum `NodeType::value`, where:
> > ` struct NodeType { enum value { Null, Scalar, Sequence, Map }; }; `
* `Node::GetTag()` is now `Node::Tag()`
* `Node::Identity()` is removed, and `Node::IsAlias()` and `Node::IsReferenced()` have been merged into `Node::IsAliased()`. The reason: there's no reason to distinguish an alias node from its anchor - whichever happens to be emitted first will be the anchor, and the rest will be aliases.
* `Node::Read<T>` is now `Node::to<T>`. This wasn't a documented function, so it shouldn't break anything.
* `Node`'s comparison operators (for example, `operator == (const Node&, const T&)`) have all been removed. These weren't documented either (they were just used for the tests), so this shouldn't break anything either.
* The emitter no longer produces the document start by default - if you want it, you can supply it with the manipulator `YAML::BeginDoc`.
## 0.2.5 ##
This wiki was started with v0.2.5.

16
DeletedBranches.md Normal file
View File

@@ -0,0 +1,16 @@
# List of deleted branches #
| **Location** | **Description** | **Revision Deleted** |
|:-------------|:----------------|:---------------------|
| /branches/node-refactoring | Push all memory ownership to the root node and remove the `Content` helper classes | [r451](https://code.google.com/p/yaml-cpp/source/detail?r=451) |
| /branches/jbeder-event-api | Procedural event API (like libyaml) | [r389](https://code.google.com/p/yaml-cpp/source/detail?r=389) |
| /branches/tags | Proper tag parsing | [r403](https://code.google.com/p/yaml-cpp/source/detail?r=403) |
| /branches/emitter | The emitter | [r404](https://code.google.com/p/yaml-cpp/source/detail?r=404) |
| /branches/aliases | Access to aliases | [r405](https://code.google.com/p/yaml-cpp/source/detail?r=405) |
| /branches/event-api | Graph builder API, abandoned in favor of /branches/graphbuilder-api | [r389](https://code.google.com/p/yaml-cpp/source/detail?r=389) |
| /branches/other-tags | Tag-by-kind and local tags | [r397](https://code.google.com/p/yaml-cpp/source/detail?r=397) |
| /branches/utf | UTF-8, UTF-16, and UTF-32 reading functionality | [r187](https://code.google.com/p/yaml-cpp/source/detail?r=187) |
| /branches/emitting-unicode | Emitting UTF-8 encoded scalar values and options for emitting ASCII only | [r279](https://code.google.com/p/yaml-cpp/source/detail?r=279) |
| /branches/improved-cloning | One way to better handle cloning aliased nodes | [r342](https://code.google.com/p/yaml-cpp/source/detail?r=342) |
| /branches/graphbuilder-api | An extension of the event API that handles some object management | [r407](https://code.google.com/p/yaml-cpp/source/detail?r=407) |
| /branches/make-debuggable | Tweaks to CMakeLists.txt to simplify debugging with g++ | [r423](https://code.google.com/p/yaml-cpp/source/detail?r=423) |

390
HowShouldWeGenerateYAML.md Normal file
View File

@@ -0,0 +1,390 @@
### Note: this page is no longer relevant since yaml-cpp now includes an emitter. I'm leaving it here for future reference, though, but it will no longer be updated. ###
# Introduction #
Currently, yaml-cpp is just a YAML parser with an emitter that simply parrots back a pre-parsed YAML document. It would be nice to be able to generate YAML documents (and then write them), but I'm not convinced what an ideal API would look like for this.
The purpose of this document is to compile a list of possible ways to generate YAML documents. Please leave comments critiquing the solutions, or providing your own. The idea (at the moment) is **not** to write the actual behind-the-scenes code, but rather to describe an API, and so to write samples of what a user of this API would write.
I'll be updating this wiki based on the comments that people leave. Also, if you like, indicate whether or not such an API would be useful to you.
# Copy/Assignment Method #
This method uses the copy constructors, assignment operators, and STL-like member functions for generating the content, and then the (existing) operator << to write it.
```
// basic scalars
YAML::Node scalar = "Hello World";
YAML::Node number = 52;
// sequence
YAML::Node sequence;
sequence.push_back(scalar);
sequence.push_back(number);
// map
YAML::Node price;
price["monitor"] = 250;
price["RAM (1GB)"] = 70;
price["some random sequence"] = sequence;
```
Potential problems:
* How to generate anchors/aliases
* How to generate directives
* How to indicate inline sequences and maps
# Writer Method #
(thanks to Vadim Zeitlin)
```
using namespace std;
// just an example custom scalar type
struct Date { int d, m, y; };
ostream& operaot<<ostream& s, const Date& d)
{
// this implementation suffers from many problems, it's
// just an example and shouldn't be really used like this
s << d.year << '-' << d.month << '-' << d.day;
}
// an example struct type
struct Person { string name; int age };
YAML::Writer w(cout); // or any other ostream
w.SetIndent(4); // example of setting options
w.SetCompactMaps(false); // choose
// -
// key: value
// rather than (default)
// - key: value
// style
// text after "=> " below indicates the expected output
// this may or may not be done by default, but in any case we need
// to have it to allow outputting multiple documents in the same
// stream
w.StartDocument(); // => "---"
w.Comment("Generated automatically, don't modify");
// => # Generated automatically, don't modify
// each entry may or may not be named
w.Scalar(17); // => "- 17"
w.Name("Age").Scalar(17); // => "Age: 18"
// but usually a convenient shortcut will be used:
w.Scalar("Age", 18); // exactly the same as above
// we could be even cuter and overload operator() to allow writing
w("Age", 18);
// but I'm not sure if this is not going to be too confusing
// appropriate scalar format should be auto-detected:
w.Scalar("Version", 1.0); // => Version: 1.0
w.Scalar("Name", "Foo"); // => Name: Foo
// (notice absence of quoting)
w.Scalar("Desc", "One\nTwo"); // => Desc: "One\nTwo"
w.Scalar("Author", "A \"YAML\" Hacker"); // => Author: 'A "YAML" Hacker'
w.Scalar("Comment",
"very long multiline string which wouldn't fit on a single"
"line"); // => Comment: >
// very long multiline
// string which wouldn't fit
// on a single line
// but some of them can't be auto-detected and, in any case, it
// should be possible to override by using flags
w.Scalar("Logo", "A\n B\n C", // => Logo: |
YAML::Block); // A
// B
// C
w.Scalar("Sign", "--", YAML::SingleQuote);// => Sign: '--'
// some scalar types may need special handling
// this uses default format, maybe there should be a global
// option to choose it
w.Scalar("Latest", true); // => Latest: y
// this special method allows to specify the format to use
w.Bool("Latest", true, YAML::LongBool); // => Latest: yes
w.Bool("Latest", true, YAML::OnOffBool | YAML::UpperCase); // => Latest: ON
// it's also probably better to have separate named methods for
// integer options
w.Scalar("Mode", 0755); // => Mode: 493
w.Oct("Mode", 0755); // => Mode: 0755
w.Hex("Mode", 0755); // => Mode: 0x1ed
// ... although we could also have flags for it, e.g.
w.Scalar("Max", 256, YAML::Hex); // => Max: 0x100
// using NULL is not going to work (C++0x nullptr would...) so we
// need a special method for this
w.Null("Extra"); // => Extra: ~
// custom types may be used provided they overload operator<<()
w.Scalar("Created", Date(2008, 9, 7)); // => Created: 2008-09-07
// structs are more complicated: we can't output them without some
// help so the user code must provide specialization of YAMLFields
// template for any custom type it wants to serialize
template <>
struct YAMLFields<Person> {
typedef void (*Writer)(YAML::WriteName&, const Person&);
static void WriteName(YAML::Writer& w, const Person& p) {
w.Scalar("name", p.name);
}
static void WriteAge(YAML::Writer& w, const Person& p) {
w.Scalar("age", p.age);
}
// this method must return a NULL-terminated array of
// functions writing individual fields, YAML::Writer will
// call them in turn
static Writer *GetWriters() {
static const Writer writers[] = {
&WriteName, &WriteAge, NULL
};
return writers;
}
// TODO: I'd like to do something similar for reading
// instead of doing it manually
};
// then this works (and chooses the inline style for short strings)
w.Map("Me", Person("VZ", 77)); // => Me: { name: VZ, age: 77 }
// maybe there should be some simpler API for ad-hoc maps output,
// although this is not going to work for saving arrays of structs
YAML::Map map;
map["name"] = "VZ";
map["age"] = 66;
w.Map(map);
// arrays are pretty straightforward as they simply delegate to
// the handling of their individual elements
// any iterators are supported and best format is auto-detected
int primes[] = { 2, 3, 5, 7, 11 };
w.Seq("Primes", primes, primes + sizeof(primes)/sizeof(primes[0]));
// => Primes: [ 2, 3, 5, 7, 11 ]
// format can be overridden
w.Seq("Primes", primes, primes + sizeof(primes)/sizeof(primes[0]),
YAML::Block); // => Primes:
// - 2
// - 3
// - 5
// - 7
// - 11
// custom types are also supported, of course, and there is a
// convenient wrapper for containers which frees you from using
// begin() and end() in the most common case
vector<Person> folks;
folks.push_back(Person("me", 10));
folks.push_back(Person("you", 100));
w.Seq("we", folks); // => we:
// - name: me
// age: 10
// - name: you
// age: 100
// this may or may not be done by default
w.EndDocument(); // => ...
```
# Stream method #
This is a combination of the above Writer method and STL ostream manipulators.
The simple case:
```
YAML::Emitter out;
out << "Hello, World!";
out.WriteToFile("out.yaml");
// Hello, World!
std::ofstream fout("other.yaml");
out.WriteToStream(fout);
// same thing
```
A simple list:
```
YAML::Emitter out;
out << YAML::BeginSeq;
out << "eggs";
out << "bread";
out << "milk";
out << YAML::EndSeq; // if we omit this, should we a) throw or b) assume it's there?
// - eggs
// - bread
// - milk
```
A simple map:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "name"; // should we instead have a one-off method for creating a key/value pair?
out << YAML::Value << "Ryan Braun";
out << YAML::Key << "position";
out << YAML::Value << "3B";
out << YAML::EndMap;
// name: Ryan Braun
// position: 3B
```
Examples can be mixed:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "name";
out << YAML::Value << "Barack Obama";
out << YAML::Key << "children";
out << YAML::Value << YAML::BeginSeq << "Sasha" << "Malia" << YAML::EndSeq;
out << YAML::EndMap;
// name: Barack Obama
// children:
// - Sasha
// - Malia
```
Output format can be modified using manipulators:
```
YAML::Emitter out;
out << YAML::Literal << "A\n B\n C";
// |
// A
// B
// C
```
```
YAML::Emitter out;
out << YAML::Flow;
out << YAML::BeginSeq << 2 << 3 << 5 << 7 << 11 < YAML::EndSeq;
// [2, 3, 5, 7, 11]
```
We can also have comments:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "method";
out << YAML::Value << "least squares";
out << YAML::Comment("should we change this method?");
out << YAML::EndMap;
// method: least squares # should we change this method?
```
And aliases/anchors:
```
YAML::Emitter out;
out << YAML::BeginSeq;
out << YAML::Anchor("fred");
out << YAML::BeginMap;
out << YAML::Key << "name" << YAML::Value << "Fred";
out << YAML::Key << "age" << YAML::Value << "42";
out << YAML::EndMap;
out << YAML::Alias("fred");
out << YAML::EndSeq;
// - &fred
// name: Fred
// age: 42
// - *fred
```
As usual, we can overload `operator <<`:
```
struct Vec3 { int x; int y; int z; };
YAML::Emitter& operator << (YAML::Emitter& out, const Vec3& v) {
out << YAML::Flow;
out << YAML::BeginSeq << v.x << v.y << v.z << YAML:EndSeq;
return out;
}
```
We'll provide overloads for STL vectors (and lists and sets and any container with an iterator and a dereferencable value?)
```
YAML::Emitter out;
std::vector <int> values;
values.push_back(3);
values.push_back(5);
out << values;
// - 3
// - 5
```
... and maps:
```
YAML::Emitter out;
std::map <std::string, int> ages;
ages["Daniel"] = 26;
ages["Jesse"] = 24;
out << ages;
// Daniel: 26
// Jesse: 24
```
All manipulators affect **only** the next item in the stream they all have global setters that can be **locally** changed using a manipulator:
```
YAML::Emitter out;
out.SetIndent(4);
out.SetMapStyle(YAML::Flow);
```
List of string manipulators:
```
YAML::Auto; // auto-detect - try for no quotes, but put double quotes if necessary
YAML::SingleQuoted;
YAML::DoubleQuoted;
YAML::Literal;
```
List of bool manipulators:
```
YAML::YesNoBool; // yes, no
YAML::TrueFalseBool; // true, false
YAML::OnOffBool; // on, off
YAML::UpperCase; // TRUE, N
YAML::LowerCase; // f, yes
YAML::CamelCase; // No, Off
YAML::LongBool; // yes, On
YAML::ShortBool; // y, t
```
List of int manipulators:
```
YAML::Dec;
YAML::Hex;
YAML::Oct;
```
List of sequence manipulators:
```
YAML::Flow;
YAML::Block;
```
List of map manipulators:
```
YAML::Flow;
YAML::Block;
YAML::Auto; // auto-detect key - try for simple key, but make it a long key if necessary
YAML::LongKey;
```
Note about sequence/map manipulators: they're the same locally, but they have different global flag setters (which take the same parameters)
List of misc manipulators:
```
YAML::Null;
YAML::NewLine; // print a blank line
```
List of comment manipulators:
```
YAML::Comment;
YAML::Indent(int n); // number of spaces to indent a comment after a value
YAML::PostIndent(int n); // number of spaces to indent the actual text of a comment after the '#' sign
// e.g., with Indent(3) and PostIndent(2):
// Hello # this is a comment
```

205
HowToEmitYAML.md Normal file
View File

@@ -0,0 +1,205 @@
## Contents ##
# Basic Emitting #
The model for emitting YAML is `std::ostream` manipulators. A `YAML::Emitter` objects acts as an output stream, and its output can be retrieved through the `c_str()` function (as in `std::string`). For a simple example:
```
#include "yaml-cpp/yaml.h"
int main()
{
YAML::Emitter out;
out << "Hello, World!";
std::cout << "Here's the output YAML:\n" << out.c_str(); // prints "Hello, World!"
return 0;
}
```
# Simple Lists and Maps #
A `YAML::Emitter` object acts as a state machine, and we use manipulators to move it between states. Here's a simple sequence:
```
YAML::Emitter out;
out << YAML::BeginSeq;
out << "eggs";
out << "bread";
out << "milk";
out << YAML::EndSeq;
```
produces
```
- eggs
- bread
- milk
```
A simple map:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "name";
out << YAML::Value << "Ryan Braun";
out << YAML::Key << "position";
out << YAML::Value << "LF";
out << YAML::EndMap;
```
produces
```
name: Ryan Braun
position: LF
```
These elements can, of course, be nested:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "name";
out << YAML::Value << "Barack Obama";
out << YAML::Key << "children";
out << YAML::Value << YAML::BeginSeq << "Sasha" << "Malia" << YAML::EndSeq;
out << YAML::EndMap;
```
produces
```
name: Barack Obama
children:
- Sasha
- Malia
```
# Using Manipulators #
To deviate from standard formatting, you can use manipulators to modify the output format. For example,
```
YAML::Emitter out;
out << YAML::Literal << "A\n B\n C";
```
produces
```
|
A
B
C
```
and
```
YAML::Emitter out;
out << YAML::Flow;
out << YAML::BeginSeq << 2 << 3 << 5 << 7 << 11 < YAML::EndSeq;
```
produces
```
[2, 3, 5, 7, 11]
```
Comments act like manipulators:
```
YAML::Emitter out;
out << YAML::BeginMap;
out << YAML::Key << "method";
out << YAML::Value << "least squares";
out << YAML::Comment("should we change this method?");
out << YAML::EndMap;
```
produces
```
method: least squares # should we change this method?
```
And so do aliases/anchors:
```
YAML::Emitter out;
out << YAML::BeginSeq;
out << YAML::Anchor("fred");
out << YAML::BeginMap;
out << YAML::Key << "name" << YAML::Value << "Fred";
out << YAML::Key << "age" << YAML::Value << "42";
out << YAML::EndMap;
out << YAML::Alias("fred");
out << YAML::EndSeq;
```
produces
```
- &fred
name: Fred
age: 42
- *fred
```
# STL Containers, and Other Overloads #
We overload `operator <<` for `std::vector`, `std::list`, and `std::map`, so you can write stuff like:
```
std::vector <int> squares;
squares.push_back(1);
squares.push_back(4);
squares.push_back(9);
squares.push_back(16);
std::map <std::string, int> ages;
ages["Daniel"] = 26;
ages["Jesse"] = 24;
YAML::Emitter out;
out << YAML::BeginSeq;
out << YAML::Flow << squares;
out << ages;
out << YAML::EndSeq;
```
to produce
```
- [1, 4, 9, 16]
-
Daniel: 26
Jesse: 24
```
Of course, you can overload `operator <<` for your own types:
```
struct Vec3 { int x; int y; int z; };
YAML::Emitter& operator << (YAML::Emitter& out, const Vec3& v) {
out << YAML::Flow;
out << YAML::BeginSeq << v.x << v.y << v.z << YAML::EndSeq;
return out;
}
```
and it'll play nicely with everything else.
# Using Existing Nodes #
We also overload `operator << ` for `YAML::Node`s in both APIs, so you can output existing Nodes. Of course, Nodes in the old API are read-only, so it's tricky to emit them if you want to modify them. So use the new API!
# Output Encoding #
The output is always UTF-8. By default, yaml-cpp will output as much as it can without escaping any characters. If you want to restrict the output to ASCII, use the manipulator `YAML::EscapeNonAscii`:
```
emitter.SetOutputCharset(YAML::EscapeNonAscii);
```
# Lifetime of Manipulators #
Manipulators affect the **next** output item in the stream. If that item is a `BeginSeq` or `BeginMap`, the manipulator lasts until the corresponding `EndSeq` or `EndMap`. (However, within that sequence or map, you can override the manipulator locally, etc.; in effect, there's a "manipulator stack" behind the scenes.)
If you want to permanently change a setting, there are global setters corresponding to each manipulator, e.g.:
```
YAML::Emitter out;
out.SetIndent(4);
out.SetMapStyle(YAML::Flow);
```
# When Something Goes Wrong #
If something goes wrong when you're emitting a document, it must be something like forgetting a `YAML::EndSeq`, or a misplaced `YAML::Key`. In this case, emitting silently fails (no more output is emitted) and an error flag is set. For example:
```
YAML::Emitter out;
assert(out.good());
out << YAML::Key;
assert(!out.good());
std::cout << "Emitter error: " << out.GetLastError() << "\n";
```

265
HowToParseADocument.md Normal file
View File

@@ -0,0 +1,265 @@
_The following describes the old API. For the new API, see the [Tutorial](Tutorial.md)._
## Contents ##
# Basic Parsing #
The parser accepts streams, not file names, so you need to first load the file. Since a YAML file can contain many documents, you can grab them one-by-one. A simple way to parse a YAML file might be:
```
#include <fstream>
#include "yaml-cpp/yaml.h"
int main()
{
std::ifstream fin("test.yaml");
YAML::Parser parser(fin);
YAML::Node doc;
while(parser.GetNextDocument(doc)) {
// ...
}
return 0;
}
```
# Reading From the Document #
Suppose we have a document consisting only of a scalar. We can read that scalar like this:
```
YAML::Node doc; // let's say we've already parsed this document
std::string scalar;
doc >> scalar;
std::cout << "That scalar was: " << scalar << std::endl;
```
How about sequences? Let's say our document now consists only of a sequences of scalars. We can use an iterator:
```
YAML::Node doc; // already parsed
for(YAML::Iterator it=doc.begin();it!=doc.end();++it) {
std::string scalar;
*it >> scalar;
std::cout << "Found scalar: " << scalar << std::endl;
}
```
... or we can just loop through:
```
YAML::Node doc; // already parsed
for(unsigned i=0;i<doc.size();i++) {
std::string scalar;
doc[i] >> scalar;
std::cout << "Found scalar: " << scalar << std::endl;
}
```
And finally maps. For now, let's say our document is a map with all keys/values being scalars. Again, we can iterate:
```
YAML::Node doc; // already parsed
for(YAML::Iterator it=doc.begin();it!=doc.end();++it) {
std::string key, value;
it.first() >> key;
it.second() >> value;
std::cout << "Key: " << key << ", value: " << value << std::endl;
}
```
Note that dereferencing a map iterator is undefined; instead, use the `first` and `second` methods to get the key and value nodes, respectively.
Alternatively, we can pick off the values one-by-one, if we know the keys:
```
YAML::Node doc; // already parsed
std::string name;
doc["name"] >> name;
int age;
doc["age"] >> age;
std::cout << "Found entry with name '" << name << "' and age '" << age << "'\n";
```
One thing to be keep in mind: reading a map by key (as immediately above) requires looping through all entries until we find the right key, which is an O(n) operation. So if you're reading the entire map this way, it'll be O(n^2). For small n, this isn't a big deal, but I wouldn't recommend reading maps with a very large number of entries (>100, say) this way.
## Optional Keys ##
If you try to access a key that doesn't exist, `yaml-cpp` throws an exception (see [HowToParseADocument#When\_Something\_Goes\_Wrong](HowToParseADocument#When_Something_Goes_Wrong.md) When Something Goes Wrong). If you have optional keys, you it's often easier to use `FindValue` instead of `operator[]`:
```
YAML::Node doc; // already parsed
if(const YAML::Node *pName = doc.FindValue("name")) {
std::string name;
*pName >> name;
std::cout << "Key 'name' exists, with value '" << name << "'\n";
} else {
std::cout << "Key 'name' doesn't exist\n";
}
```
# Getting More Complicated #
The above three methods can be combined to read from an arbitrary document. But we can make life a lot easier. Suppose we're reading 3-vectors (i.e., vectors with three components), so we've got a structure looking like this:
```
struct Vec3 {
float x, y, z;
};
```
We can read this in one operation by overloading the extraction (>>) operator:
```
void operator >> (const YAML::Node& node, Vec3& v)
{
node[0] >> v.x;
node[1] >> v.y;
node[2] >> v.z;
}
// now it's a piece of cake to read it
YAML::Node doc; // already parsed
Vec3 v;
doc >> v;
std::cout << "Here's the vector: (" << v.x << ", " << v.y << ", " << v.z << ")\n";
```
# A Complete Example #
Here's a complete example of how to parse a complex YAML file:
`monsters.yaml`
```
- name: Ogre
position: [0, 5, 0]
powers:
- name: Club
damage: 10
- name: Fist
damage: 8
- name: Dragon
position: [1, 0, 10]
powers:
- name: Fire Breath
damage: 25
- name: Claws
damage: 15
- name: Wizard
position: [5, -3, 0]
powers:
- name: Acid Rain
damage: 50
- name: Staff
damage: 3
```
`main.cpp`
```
#include "yaml-cpp/yaml.h"
#include <iostream>
#include <fstream>
#include <string>
#include <vector>
// our data types
struct Vec3 {
float x, y, z;
};
struct Power {
std::string name;
int damage;
};
struct Monster {
std::string name;
Vec3 position;
std::vector <Power> powers;
};
// now the extraction operators for these types
void operator >> (const YAML::Node& node, Vec3& v) {
node[0] >> v.x;
node[1] >> v.y;
node[2] >> v.z;
}
void operator >> (const YAML::Node& node, Power& power) {
node["name"] >> power.name;
node["damage"] >> power.damage;
}
void operator >> (const YAML::Node& node, Monster& monster) {
node["name"] >> monster.name;
node["position"] >> monster.position;
const YAML::Node& powers = node["powers"];
for(unsigned i=0;i<powers.size();i++) {
Power power;
powers[i] >> power;
monster.powers.push_back(power);
}
}
int main()
{
std::ifstream fin("monsters.yaml");
YAML::Parser parser(fin);
YAML::Node doc;
parser.GetNextDocument(doc);
for(unsigned i=0;i<doc.size();i++) {
Monster monster;
doc[i] >> monster;
std::cout << monster.name << "\n";
}
return 0;
}
```
# When Something Goes Wrong #
... we throw an exception (all exceptions are derived from `YAML::Exception`). If there's a parsing exception (i.e., a malformed YAML document), we throw a `YAML::ParserException`:
```
try {
std::ifstream fin("test.yaml");
YAML::Parser parser(fin);
YAML::Node doc;
parser.GetNextDocument(doc);
// do stuff
} catch(YAML::ParserException& e) {
std::cout << e.what() << "\n";
}
```
If you make a programming error (say, trying to read a scalar from a sequence node, or grabbing a key that doesn't exist), we throw some kind of `YAML::RepresentationException`. To prevent this, you can check what kind of node something is:
```
YAML::Node node;
YAML::NodeType::value type = node.Type(); // should be:
// YAML::NodeType::Null
// YAML::NodeType::Scalar
// YAML::NodeType::Sequence
// YAML::NodeType::Map
```
# Note about copying `YAML::Node` #
Currently `YAML::Node` is non-copyable, so you need to do something like
```
const YAML::Node& node = doc["whatever"];
```
This is intended behavior. If you want to copy a node, use the `Clone` function:
```
std::auto_ptr<YAML::Node> pCopy = myOtherNode.Clone();
```
The intent is that if you'd like to keep a `YAML::Node` around for longer than the document will stay in scope, you can clone it and store it as long as you like.

50
ProjectHome.md Normal file
View File

@@ -0,0 +1,50 @@
yaml-cpp is a [YAML](http://www.yaml.org/) parser and emitter in C++ matching the [YAML 1.2 spec](http://www.yaml.org/spec/1.2/spec.html).
To get a feel for how it can be used, see the [Tutorial](http://code.google.com/p/yaml-cpp/wiki/Tutorial). For the old API (version < 0.5.0), see [How To Parse A Document](http://code.google.com/p/yaml-cpp/wiki/HowToParseADocument) or [How to Emit YAML](http://code.google.com/p/yaml-cpp/wiki/HowToEmitYAML).
# Problems? #
If you find a bug, post an [issue](http://code.google.com/p/yaml-cpp/issues/list)! If you have questions about how to use yaml-cpp, please post it on http://stackoverflow.com and tag it `yaml-cpp`.
# Recent Release #
[yaml-cpp 0.5.2](https://yaml-cpp.googlecode.com/archive/release-0.5.2.tar.gz) has been released! This is a bug fix release.
[yaml-cpp 0.3.0](http://yaml-cpp.googlecode.com/files/yaml-cpp-0.3.0.tar.gz) is still available if you want the old API.
**The old API will continue to be supported, and will still receive bugfixes!** The 0.3.x and 0.4.x versions will be old API releases, and 0.5.x and above will all be new API releases.
# How to Build #
yaml-cpp uses [CMake](http://www.cmake.org) to support cross-platform building. The basic steps to build are:
1. Download and install [CMake](http://www.cmake.org) (Resources -> Download).
**Note:** If you don't use the provided installer for your platform, make sure that you add CMake's bin folder to your path.
2. Navigate into the source directory, and type:
```
mkdir build
cd build
```
3. Run CMake. The basic syntax is:
```
cmake [-G generator] [-DBUILD_SHARED_LIBS=ON|OFF] ..
```
* The `generator` is whatever type of build system you'd like to use. To see a full list of generators on your platform, just run `cmake` (with no arguments). For example:
* On Windows, you might use "Visual Studio 9 2008" to generate a Visual Studio 2008 solution
* On OS X, you might use "Xcode" to generate an Xcode project
* On a UNIX-y system, simply omit the option to generate a makefile
* yaml-cpp defaults to building a static library, but you may build a shared library by specifying `-DBUILD_SHARED_LIBS=ON`.
* For more options on customizing the build, see the [CMakeLists.txt](http://code.google.com/p/yaml-cpp/source/browse/CMakeLists.txt) file.
4. Build it!
5. To clean up, just remove the `build` directory.

34
RepositoryGuide.md Normal file
View File

@@ -0,0 +1,34 @@
`yaml-cpp` naturally splits into a "core" library with two "frontend" APIs, and so that's how the code is organized.
## Core ##
```
hg clone https://code.google.com/p/yaml-cpp.core/
```
This provides parsing to the intermediate (and undocumented!) event API, as well as emitting.
## New API ##
```
hg clone https://code.google.com/p/yaml-cpp.new-api/
```
This is an upstream of the `core` repository. It provides the new `YAML::Node` API. See [Tutorial](Tutorial.md) for details on this API.
## Old API ##
```
hg clone https://code.google.com/p/yaml-cpp.old-api/
```
This is an upstream of the `core` repository. It provides the old `YAML::Node` API. See [HowToParseADocument](HowToParseADocument.md) for details on this API.
## Default ##
```
hg clone https://code.google.com/p/yaml-cpp/
```
This is a mirror of the `new-api` repository.

23
StagingBranches.md Normal file
View File

@@ -0,0 +1,23 @@
# Introduction #
Understandably, the yaml-cpp management would like to keep the /trunk in a fairly reasonable state for consumers of the yaml-cpp library. There are, however, occasions that arise where multiple patch branches that do not merge cleanly need to be integrated before they can be combined back into /trunk. In these cases we fall back on staging branches.
# Where Are the Staging Branches? #
Staging branches, like other branches, are found in the project's Subversion repository under the /branches folder. Anonymous access is available at
http://yaml-cpp.googlecode.com/svn/branches. The staging branches have the form _username_-staging.
As of this writing, the only staging branch is http://yaml-cpp.googlecode.com/svn/branches/rtweeks21-staging, but please check the branches link (from the previous paragraph) for the latest information.
# What is in a Staging Branch? #
That is really up to the developer who owns the branch. Staging branches will typically look like a copy of the HEAD of /trunk into which some other branches have been reintegrated. Staging branches are intended to provide an area to prepare a group of (possibly unrelated) changes to go into the trunk.
# How Will the Developers Keep Track of the Merges? #
All Subversion clients starting with version 1.5 add information about merges between branches to appropriate folders in the svn:mergeinfo property. These clients can therefore track (and report) which version have been merged from one branch to another and avoid any attempts to re-merge a revision.
The best way to merge a feature or bug-fix branch into a staging branch (or a staging branch into /trunk) is `svn merge --reintegrate`, which will correctly handle changes from any synchronization merges from /trunk into the development branch. This follows the procedure recommended by the Subversion documentation.

14
Strings.md Normal file
View File

@@ -0,0 +1,14 @@
# Encodings and `yaml-cpp` #
`yaml-cpp` will parse any file as specificed by the [YAML 1.2 spec](http://www.yaml.org/spec/1.2/spec.html#id2570322). Internally, it stores all strings in UTF-8, and representation is done with UTF-8. This means that in
```
std::string str;
node >> str;
```
`str` will be UTF-8. Similarly, if you're accessing a map by string key, you need to pass the key in UTF-8. If your application uses a different encoding, you need to convert to and from UTF-8 to work with `yaml-cpp`. (It's possible we'll add some small conversion functions, but for now it's restricted.)
For convenience, Richard Weeks has kindly provided a google gadget that converts Unicode to a string literal. Just paste in the Unicode:
&lt;wiki:gadget url="http://hosting.gmodules.com/ig/gadgets/file/111180078345548400783/c-style-utf8-encoder.xml"&gt;

203
Tutorial.md Normal file
View File

@@ -0,0 +1,203 @@
# Introduction #
_The following describes the new API. For the old API, see [HowToParseADocument](HowToParseADocument.md) or [HowToEmitYAML](HowToEmitYAML.md)._
A typical example, loading a configuration file, might look like this:
```
YAML::Node config = YAML::LoadFile("config.yaml");
if (config["lastLogin"]) {
std::cout << "Last logged in: " << config["lastLogin"].as<DateTime>() << "\n";
}
const std::string username = config["username"].as<std::string>();
const std::string password = config["password"].as<std::string>();
login(username, password);
config["lastLogin"] = getCurrentDateTime();
std::ofstream fout("config.yaml");
fout << config;
```
# Basic Parsing and Node Editing #
All nodes in a YAML document (including the root) are represented by `YAML::Node`. You can check what kind it is:
```
YAML::Node node = YAML::Load("[1, 2, 3]");
assert(node.Type() == YAML::NodeType::Sequence);
assert(node.IsSequence()); // a shortcut!
```
Collection nodes (sequences and maps) act somewhat like STL vectors and maps:
```
YAML::Node primes = YAML::Load("[2, 3, 5, 7, 11]");
for (std::size_t i=0;i<primes.size();i++) {
std::cout << primes[i].as<int>() << "\n";
}
// or:
for (YAML::const_iterator it=primes.begin();it!=primes.end();++it) {
std::cout << it->as<int>() << "\n";
}
primes.push_back(13);
assert(primes.size() == 6);
```
and
```
YAML::Node lineup = YAML::Load("{1B: Prince Fielder, 2B: Rickie Weeks, LF: Ryan Braun}");
for(YAML::const_iterator it=lineup.begin();it!=lineup.end();++it) {
std::cout << "Playing at " << it->first.as<std::string>() << " is " << it->second.as<std::string>() << "\n";
}
lineup["RF"] = "Corey Hart";
lineup["C"] = "Jonathan Lucroy";
assert(lineup.size() == 5);
```
Querying for keys does **not** create them automatically (this makes handling optional map entries very easy)
```
YAML::Node node = YAML::Load("{name: Brewers, city: Milwaukee}");
if (node["name"]) {
std::cout << node["name"].as<std::string>() << "\n";
}
if (node["mascot"]) {
std::cout << node["mascot"].as<std::string>() << "\n";
}
assert(node.size() == 2); // the previous call didn't create a node
```
If you're not sure what kind of data you're getting, you can query the type of a node:
```
switch (node.Type()) {
case Null: // ...
case Scalar: // ...
case Sequence: // ...
case Map: // ...
case Undefined: // ...
}
```
or ask directly whether it's a particular type, e.g.:
```
if (node.IsSequence()) {
// ...
}
```
# Building Nodes #
You can build `YAML::Node` from scratch:
```
YAML::Node node; // starts out as null
node["key"] = "value"; // it now is a map node
node["seq"].push_back("first element"); // node["seq"] automatically becomes a sequence
node["seq"].push_back("second element");
node["mirror"] = node["seq"][0]; // this creates an alias
node["seq"][0] = "1st element"; // this also changes node["mirror"]
node["mirror"] = "element #1"; // and this changes node["seq"][0] - they're really the "same" node
node["self"] = node; // you can even create self-aliases
node[node["mirror"]] = node["seq"]; // and strange loops :)
```
The above node is now:
```
&1
key: value
&2 seq: [&3 "element #1", second element]
mirror: *3
self: *1
*3 : *2
```
# How Sequences Turn Into Maps #
Sequences can be turned into maps by asking for non-integer keys. For example,
```
YAML::Node node = YAML::Load("[1, 2, 3]");
node[1] = 5; // still a sequence, [1, 5, 3]
node.push_back(-3) // still a sequence, [1, 5, 3, -3]
node["key"] = "value"; // now it's a map! {0: 1, 1: 5, 2: 3, 3: -3, key: value}
```
Indexing a sequence node by an index that's not in its range will _usually_ turn it into a map, but if the index is one past the end of the sequence, then the sequence will grow by one to accommodate it. (That's the **only** exception to this rule.) For example,
```
YAML::Node node = YAML::Load("[1, 2, 3]");
node[3] = 4; // still a sequence, [1, 2, 3, 4]
node[10] = 10; // now it's a map! {0: 1, 1: 2, 2: 3, 3: 4, 10: 10}
```
# Converting To/From Native Data Types #
Yaml-cpp has built-in conversion to and from most built-in data types, as well as `std::vector`, `std::list`, and `std::map`. The following examples demonstrate when those conversions are used:
```
YAML::Node node = YAML::Load("{pi: 3.14159, [0, 1]: integers}");
// this needs the conversion from Node to double
double pi = node["pi"].as<double>();
// this needs the conversion from double to Node
node["e"] = 2.71828;
// this needs the conversion from Node to std::vector<int> (*not* the other way around!)
std::vector<int> v;
v.push_back(0);
v.push_back(1);
std::string str = node[v].as<std::string>();
```
To use yaml-cpp with your own data types, you need to specialize the YAML::convert<> template class. For example, suppose you had a simple `Vec3` class:
```
struct Vec3 { double x, y, z; /* etc - make sure you have overloaded operator== */ };
```
You could write
```
namespace YAML {
template<>
struct convert<Vec3> {
static Node encode(const Vec3& rhs) {
Node node;
node.push_back(rhs.x);
node.push_back(rhs.y);
node.push_back(rhs.z);
return node;
}
static bool decode(const Node& node, Vec3& rhs) {
if(!node.IsSequence() || node.size() != 3) {
return false;
}
rhs.x = node[0].as<double>();
rhs.y = node[1].as<double>();
rhs.z = node[2].as<double>();
return true;
}
};
}
```
Then you could use `Vec3` wherever you could use any other type:
```
YAML::Node node = YAML::Load("start: [1, 3, 0]");
Vec3 v = node["start"].as<Vec3>();
node["end"] = Vec3(2, -1, 0);
```