Including iostream means introducing the static (global) constructors
and destructors for std::cin, std::cerr, and std::cout. That extra
init and fini code is undesirable when those streams are not actually
used.
Instead, we'll use the narrower includes for exactly what's needed,
i.e., <istream> or <ostream>.
Accept Emitter::operator<<(std::string_view).
ABI remains C++11 compatible by exposing new method
Emitter::Write(const char*, size_t).
All affected calls optimized to pass std::string values as pointer + size
tuple into appropriate routines.
Including:
- Remove WORKSPACE and upgrade to MODULE.bazel.
- The integration tests were not included since the directory was misspelled.
- Their header files were not accessible.
Goole Test itself documents the `INSTALL_GTEST` option as something that projects embedding it should set to `OFF`. Leaving it on means that projects downstream from libraries that embed it are likely to encounter conflicting copies. This is particularly annoying because GTest does not maintain anything like a stable API, and so causes builds to fail if include paths pick up an inappropriately installed copy ahead of the one that the code wanted.
Fixes#488
Add dragonbox to compute the required precision to print floating point
numbers. This avoids uglification of floating point numbers that
happen by default via std::stringstream.
Numbers like 34.34 used to be converted to '34.340000000000003' as strings.
With this version they will be converted to the string '34.34'.
This fixes issue https://github.com/jbeder/yaml-cpp/issues/1289
GCC 15 will no longer include it by default, resulting in build
failures in projects that do not explicitly include it.
Error:
src/emitterutils.cpp:221:11: error: 'uint16_t' was not declared in this scope
221 | std::pair<uint16_t, uint16_t> EncodeUTF16SurrogatePair(int codePoint) {
| ^~~~~~~~
src/emitterutils.cpp:13:1: note: 'uint16_t' is defined in header '<cstdint>';
this is probably fixable by adding '#include <cstdint>'
12 | #include "yaml-cpp/null.h"
+++ |+#include <cstdint>
13 | #include "yaml-cpp/ostream_wrapper.h"
Tests pass.
Closes: #1307
See-also: https://gcc.gnu.org/pipermail/gcc-cvs/2024-August/407124.html
See-also: https://bugs.gentoo.org/937412
Signed-off-by: Christopher Fore <csfore@posteo.net>
jekyll/liquid got hung up on `{{"Daniel", 26}, {"Jesse", 24}}`.
The reason is that `{{...}}` are used as variables that are replaced by
there values. In this case we have a YAML object that looks the same.
This issue can be fixed by surrounding the block into `{% raw %}...{%
endraw %}` tags.
This reverts commit 1f5e971f77.
See #1306; the previous commit caused an error with -Wpedantic:
yaml-cpp/include/yaml-cpp/emitterstyle.h:13:2: error: extra ‘;’ [-Wpedantic]
Since the original commit was to resolve warnings, reverting and the OP can produce a new one that fixes this issue.
The CMake format target does not use the correct .clang-format file in
out-of-source builds. This instructs CMake to use the project root as
the working directory for running the clang-format command so that it
finds the .clang-format file.
Since `std::string` has to be dynamically constructed and destructed,
it could be accessed before initialization or after destruction in a
multithreaded context. By using constant c-strings instead, we guarantee
that the array will be valid for the whole lifetime of the program. The
use of `constexpr` also enforces this requirement.
I have run clang-format on the file to format my changes according to
CONTRIBUTING.md.
Protect from regressions due to use of undefined or
implementation-specific behavior when using `std::` containers and smart
pointers.
This only has effect on platforms with the GNU standard C++ library.
Refer to https://gcc.gnu.org/onlinedocs/libstdc++/manual/debug_mode.html.
There is no need to use the embedded gtest code copy in Linux systems, if they already provide the googletest framework system-wide.
Search for it, and fallback to the embedded one if the system one is not detected.
This patch has been also contributed by Simon Quigley <tsimonq2@debian.org>
* CMake: Add option to set the package install dir.
* CMake: Fix generated config.
- `YAML_CPP_SHARED_LIBS_BUILT` should not be set with a `PATH_VAR` as it
would always evaluate to true.
- `YAML_CPP_LIBRARIES` should used the exported target name including
the namespace, but `check_required_components` shouldn't.
- Use `CMAKE_CURRENT_LIST_DIR` to find the target file, instead of a
`PATH_VAR`. Package managers such as vcpkg move CMake configs after
installing.
* CI: Test the generated CMake package.
* CMake: Create add a deprecated yaml-cpp target.
This target is meant to provide compatibility with versions prior to
0.8.0.
* CMake: mark the yaml-cpp target as IMPORTED.
---------
Co-authored-by: Jesse Beder <jbeder+github@gmail.com>
add_custom_target uninstall causes a clash with the same target in rtmidi (https://github.com/thestk/rtmidi).
"add_custom_target cannot create target "uninstall" because another target with the same name already exists. The existing target is a custom target created in source directory"
Adds new option YAML_CPP_DISABLE_UNINSTALL
fixes#1151
---------
Co-authored-by: Megamouse <studienricky89@googlemail.de>
Co-authored-by: Jesse Beder <jbeder+github@gmail.com>
* CI: test with supported C++ standards
let's test with the supported standards for better coverage.
C++23 standard was just out, but the support on the toolchain is
not quite ready yet. so let's leave it for a future change.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
* CI: drop redundant Build step
"Build Tests" is strictly a superset of "Build". in addition to
the library, the former builds the tests also. both these
steps share the same set of command line arguments. by removing
"Build" step, we don't lose anything regarding the test coverage
and information for further investigation if the build fails.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
---------
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
This reverts commit 6262201182.
in 62622011, we wanted address the needs to use the `string_view`
converter in C++98, but that requirement was based on wrong
preconditions. `std::string_view` was introduced in C++17, and
popular standard libraries like libstdc++ and libc++ both provide
`std::string_view` when the source is built with C++17.
furthermore 62622011 is buggy. because it uses `<version>` to tell
the feature set provided by the standard library. but `<version>`
is a part of C++20. so this defeats the purpose of the change of
62622011.
Fixes#1223
* Test(CMake) set NAME and COMMAND in add_test
* (CMake) add enable_testing()
* (CMake) move cmake_dependent_option up, before using them
* (CMake) use YAML_CPP_MAIN_PROJECT in cmake_dependent_option
* (CMake) log values regarding tests
* (CMake) always find CTest, but don't enable tests
* (CMAKE)(temp) fix logging
* (actions) set YAML_CPP_BUILD_TESTS for tests
* (actions) provide YAML_CPP_BUILD_TESTS to ctest
* (actions) set -DYAML_CPP_BUILD_TESTS at build
* (actions) don't fail false
* (actions) build tests in Test step
* (actions) run tests verbose
* (CMake) remove temp logging
* (actions) split building from running tests
* (actions) ctest Debug
* (actions) ctest Debug
* Remove enable_testing
It secures the repo against erroneous or malicious actions from external jobs you call from your workflow. It's specially important for the case they get compromised, for example.
This pull request adds two new exported variables to the CMake config:
YAML_CPP_LIBRARY_DIR - points to the directory containing the built library files
YAML_CPP_SHARED_LIBS_BUILT - boolean value, lets users know whether shared libraries were built or not
On Oracle Solaris the following statement is declared in file /usr/include/sys/regset.h:
#define SS 18 /* only stored on a privilege transition */
Because of this template type name SS is substituted by numeric literal, which results in a compilation error:
error: expected nested-name-specifier before numeric constant
Fixed by renaming template type names.
Co-authored-by: Roman Degtyar <Roman.Degtyar@veeam.com>
The option `YAML_CPP_BUILD_TESTS` currently enables or disables building of tests; but unconditionally the CMake file includes CTest; this PR makes that conditional on the option.
Also, there is no option for enabling formatting, but it does check whether it can find the `clang-format` executable; this PR adds an option (default to true) that skips even looking for the executable if disabled.
After configuring the file `yaml-cpp-config.cmake.in`, the result ends up with
empty variables. (see also the discussion in #774).
Rework this file and the call to `configure_package_config_file` according the
cmake documentation
(https://cmake.org/cmake/help/v3.22/module/CMakePackageConfigHelpers.html?highlight=configure_package_config#command:configure_package_config_file)
to overcome this issue and allow a simple `find_package` after install.
As there was some discussion about the place where to install the
`yaml-cpp-config.cmake` file, e.g. #1055, factor out the install location into
an extra variable to make it easier changing this location in the future.
Also untabify CMakeLists.txt in some places to align with the other code parts in this file.
Add copying of shared library to the output directory with a test binary.
[binary] removed using of non unsigned char as argument at
'std::isspace' function that was provokes undefined behavior.
[.github/workflows/build.yml] enabled run of test at the
'windows-latest' environment.
GNUInstallDirs provided may be absolute paths, in which case appending
to the install prefix is not correct. We can instead use the provided
CMAKE_INSTALL_FULL_* variables, which are precomputed absolute paths.
https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
* Export YAML::detail::node::m_amount
The internal header node/detail/node.h is included by public headers;
YAML::detail::node is implemented in the header itself, and thus it gets
inlined... except for its static m_amount class member, which is
instantiated in the library only. Right now all the symbols of yaml-cpp
are exported (nothing is hidden), so the linker will find node::m_amount
in the yaml-cpp library.
As solution/workaround, explicitly export YAML::detail::node::m_amount.
* CMake: use GenerateExportHeader
Make use of the GenerateExportHeader CMake module to generate the dll.h
header with export macros.
While the produced dll.h is different, the result should be the same,
i.e. nothing changes for yaml-cpp or its users.
* CMake: hide all the symbols by default
Hide all the symbols that are not explicitly exported with YAML_CPP_API.
This way the ABI will be way smaller, and only actually exposing the
public classes/functions.
- Don't eagerly convert key to std::string
- Make const char* keys streamable when exception is thrown
- Don't create a temporary string when comparing a const char* key
For completeness I've implemented escaping for characters outside the
basic multilingual plane, but it doesn't get used (as there's no
EscapeAsAsciiJson emitter option implemented).
Inside of a sequence or map, `YAML::Newline` wouldn't reset the collection state, which would cause behavior like this:
```
nodeA:
k: [{i: 0},
{i:1},
]NodeB:
k: [{i: 0},
{i:1},
]
```
* partially fix clang compilation
Missing header and mistaken algorithm usage.
Also removed it name from range loops. It's not correct.
Signed-off-by: Rosen Penev <rosenp@gmail.com>
* run through clang's -Wrange-loop-analysis
Some range loops should not use references as they need to copy.
Signed-off-by: Rosen Penev <rosenp@gmail.com>
* manual range loop conversions
Signed-off-by: Rosen Penev <rosenp@gmail.com>
Library debug postfix might not be suitable for cross platform project, and usually require extra work of link against prebuilt yaml-cpp.
Generally, Xcode project output library to these directories:
Debug
Release
Debug-iphoneos
Release-iphoneos
Debug-iphonesimulator
Release-iphonesimulator
Another Xcode project usually configured its build setting as follow, and expects library name to be same between Release and Debug
LIBRARY_SEARCH_PATHS=$(CONFIGURATION)$(EFFECT_PLATFORM_NAME)
OTHER_LDFLAGS= $(inherited) -lyaml-cpp
* Copied Tutorial from Google Code wiki.
* Initial Home page
* Copied How To Parse A Document from Google Code wiki
* Updated How To Parse A Document (markdown)
* Updated How To Parse A Document (markdown)
* Updated How To Parse A Document (Old API) (markdown)
* Copied How To Emit YAML from Google Code wiki
* Copied Breaking Changes from Google Code wiki
* Copied Strings from Google Code wiki
* Updated Strings (markdown)
* Updated Home (markdown)
* Fix typo.
* Updated Breaking Changes (markdown)
* Updated How To Parse A Document (Old API) (markdown)
* Updated Breaking Changes (markdown)
* Move wiki content to docs/
* Improve markdown and add colored code syntax
Co-authored-by: Jesse Beder <jbeder+github@gmail.com>
The explicitly defaulted or implemented move constructors and assignment
operators are made "noexcept".
Bugfix:
* src/stream.cpp Stream::Stream() char_traits::int_type intro[4] is
now aggregate-initialized (to zero) to avoid UB.
Minor changes:
* Using std::isinf() and std::signbit() instead of comparing for
equality with infinity.
* src/streamcharsource.h: Added #include "stream.h".
* src/stream.h: Forward declaring "class StreamCharSource".
* Some implicit casting changed into static_cast's.
Signed-off-by: Ted Lyngmo <ted@lyncon.se>
This is in preparation for other patches that will make use of the
macro. The patch also removes #undef:ing the macro after its been
used to not make the header inclusion order critical. Otherwise,
the new header would always have to be the last of the yaml-cpp
headers to be included.
This happens whenever in a macro you use some "if" block, and don't use curly braces {},
as the macro is expanded on a single line, not on several lines. So just add the missing
curly braces to please gcc.
In file included from /remote/users/mlamesch/CloneFromPlatinum/yamlcpp/osp/Yamlcpp/18-0-0-5/include/yaml-cpp/yaml.h:18,
from src/TestYaml.cpp:2:
/remote/users/mlamesch/CloneFromPlatinum/yamlcpp/osp/Yamlcpp/18-0-0-5/include/yaml-cpp/node/convert.h: In static member function static bool YAML::convert<int>::decode(const YAML::Node&, int&):
/remote/users/mlamesch/CloneFromPlatinum/yamlcpp/osp/Yamlcpp/18-0-0-5/include/yaml-cpp/node/convert.h:139:1: error: this if clause does not guard... [-Werror=misleading-indentation]
YAML_DEFINE_CONVERT_STREAMABLE_SIGNED(int);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example of how someone might consume yaml-cpp with bazel:
cc_binary(
name = "example",
srcs = ["example.cc"],
deps = ["@com_github_jbeder_yaml_cpp//:yaml-cpp"],
)
Remove 2.6-isms
Remove 2.8-isms
Bump CMake minimum version to 3.4
Disable some options when used as a subdirectory
Use `CONFIGURE_DEPENDS` with `file(GLOB)` when possible
Backport CMake 3.15's MSVC_RUNTIME_LIBRARY setting.
Set all compile options as generator expressions.
Set all find-package files to be installed to the correct file.
Remove `export(PACKAGE)`, as this has been deprecated.
Remove fat binary support
Remove manual setting of iPhone settings. These should be set by parent
projects.
Remove use of ExternalProject for a local use
Conditionally remove format target unless clang-format is found
* CMake: Prefix options with "YAML" and hide platform-specific options
When including yaml-cpp as a subproject, some option names can conflict with other projects.
(1) Make sure the yaml-cpp options are prefixed with YAML
(2) Hide platform-specific options when possible to avoid cluttering the cmake option list
* Update docs for change from BUILD_SHARED_LIBS to YAML_BUILD_SHARED_LIBS
Setting CMAKE_CXX_STANDARD and CMAKE_CXX_STANDARD_REQUIRED directly is problematic when including yaml-cpp as a subproject.
The proper way is to set these per-target.
Invalid access via operator[] or as<> will now print the offending key, if possible.
For example:
a:
x: 1
y: 2
node["a"]["z"].as<int>()
will say that the key "z" was invalid.
* Add compilation flags: -Wshadow -Weffc++ -pedantic -pedantic-errors
* Delete implicit copy & move constructors & assignment operators
in classes with pointer data members.
* An exception to the above: Add default copy & move constructors &
assignment operators for the Binary class.
* Convert boolean RegEx operators to binary operators.
* Initialize all members in all classes in ctors.
* Let default ctor delegate to the converting ctor in
Binary and RegEx
* Don't change any tests except regex_test (as a result of the change
to binary operators).
Note: https://bugzilla.redhat.com/show_bug.cgi?id=1544675 makes
-Weffc++ report a false positive in "include/yaml-cpp/node/impl.h".
NDK now uses ninja for building but yaml-cpp would emit the “ninja: error: build.ninja:326: bad $-escape (literal $ must be written as $$)” error due to syntax error in the generated build.ninja file. Related issue: https://github.com/jbeder/yaml-cpp/issues/630
The issue is that numbers like
2.01 or 3.01 can not be precisely represented with binary floating point
numbers.
This replaces all occurrences of 'std::numeric_limits<T>::digits10 + 1' with
'std::numeric_limits<T>::max_digits10'.
Background:
Using 'std::numeric_limits<T>::digits10 + 1' is not precise enough.
Converting a 'float' into a 'string' and back to a 'float' will not always
produce the original 'float' value. To guarantee that the 'string'
representation has sufficient precision the value
'std::numeric_limits<T>::max_digits10' has to be used.
* Removed an expression which is always true
* The second expression (ch is space) is removed because the first one contains space 0x20
* nextEmptyLine is always false so it is removed from the expression
Let CMake handle the default optimizations for various configurations. We don't need to override them. In fact, overriding them makes it impossible for users to override them themselves.
Roll-forward of c90c08ccc9 "Revert "Improvements to CMake buildsystem (#563)""
NEW:
* Replace CMAKE_SOURCE_DIR with CMAKE_CURRENT_SOURCE_DIR
Fixes#612 when yaml-cpp is used as a git submodule.
ORIGINAL:
* Move enable_testing() into proper place
* Added CMake's checks for C++11 standards
Raised minimal version of CMake to 3.1, since on old systems there no
decent compilers that supports c++11.
Closes#377.
* Externalize googletest project
Externalize gtest to avoid installation, fixes#539.
* Remove defined cmake_policies
CMP0012 - OLD marked as deprecated for >=cmake-3.1 and will be removed
CMP0015 - does not affect to build process
CMP0042 - already NEW for >=cmake-3.1
Fixes#505
* Fix compiling in Windows MSVC
* Move enable_testing() into proper place
* Added CMake's checks for C++11 standards
Raised minimal version of CMake to 3.1, since on old systems there no
decent compilers that supports c++11.
Closes#377.
* Externalize googletest project
Externalize gtest to avoid installation, fixes#539.
* Remove defined cmake_policies
CMP0012 - OLD marked as deprecated for >=cmake-3.1 and will be removed
CMP0015 - does not affect to build process
CMP0042 - already NEW for >=cmake-3.1
Fixes#505
* Fix compiling in Windows MSVC
@@ -17,9 +17,9 @@ Commit messages should be in the imperative mood, as described in the [Git contr
# Tests
Please verify the tests pass by running the target `tests/run_tests`.
Please verify the tests pass by configuring CMake with `-D YAML_CPP_BUILD_TESTS=ON` and running the target `test/yaml-cpp-tests`.
If you are adding functionality, add tests accordingly.
If you are adding functionality, add tests accordingly. Note that the "spec tests" are reserved for examples directly from the YAML spec, so if you have new examples, put them in other test files.
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).
`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](https://github.com/jbeder/yaml-cpp/wiki/Tutorial) or [How to Emit YAML](https://github.com/jbeder/yaml-cpp/wiki/How-To-Emit-YAML). For the old API (version < 0.5.0), see [How To Parse A Document](https://github.com/jbeder/yaml-cpp/wiki/How-To-Parse-A-Document-(Old-API)).
## Usage
# Problems? #
See [Tutorial](https://github.com/jbeder/yaml-cpp/wiki/Tutorial) and [How to Emit YAML](https://github.com/jbeder/yaml-cpp/wiki/How-To-Emit-YAML) for reference. For the old API (until 0.5.0), see [How To Parse A Document](https://github.com/jbeder/yaml-cpp/wiki/How-To-Parse-A-Document-(Old-API)).
## Any Problems?
If you find a bug, post an [issue](https://github.com/jbeder/yaml-cpp/issues)! If you have questions about how to use yaml-cpp, please post it on http://stackoverflow.com and tag it [`yaml-cpp`](http://stackoverflow.com/questions/tagged/yaml-cpp).
# How to Build #
## How to Build
yaml-cpp uses [CMake](http://www.cmake.org) to support cross-platform building. The basic steps to build are:
`yaml-cpp` uses [CMake](http://www.cmake.org) to support cross-platform building. Install [CMake](http://www.cmake.org) _(Resources -> Download)_ before proceeding. 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.
**Note:** If you don't use the provided installer for your platform, make sure that you add CMake's bin folder to your path.
#### 1. Navigate into the source directory, create build folder and run `CMake`:
*`yaml-cpp` builds a static library by default, you may want to build a shared library by specifying `-DYAML_BUILD_SHARED_LIBS=ON`.
*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 12 2013" to generate a Visual Studio 2013 solution or "Visual Studio 14 2015 Win64" to generate a 64-bit Visual Studio 2015 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`.
Note that for `yaml-cpp` unit tests to run successfully, the _GoogleTest_
library also must be built with this flag, i.e. the system one cannot be
used (the _YAML_USE_SYSTEM_GTEST_ CMake option must be _OFF_, which is the
default).
* For more options on customizing the build, see the [CMakeLists.txt](https://github.com/jbeder/yaml-cpp/blob/master/CMakeLists.txt) file.
4. Build it!
#### 2. Build it!
* The command you'll need to run depends on the generator you chose earlier.
5. To clean up, just remove the `build` directory.
**Note:** To clean up, just remove the `build` directory.
# Recent Release #
## How to Integrate it within your project using CMake
[yaml-cpp 0.6.0](https://github.com/jbeder/yaml-cpp/releases/tag/yaml-cpp-0.6.0) has been released! This release requires C++11, and no longer depends on Boost.
[yaml-cpp 0.3.0](https://github.com/jbeder/yaml-cpp/releases/tag/release-0.3.0) 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.
**The old API will stop receiving bugfixes in 2026.** The 0.3.x versions provide the old API, and 0.5.x and above all provide the new API.
# API Documentation
The autogenerated API reference is hosted on [CodeDocs](https://codedocs.xyz/jbeder/yaml-cpp/index.html)
# Third Party Integrations
The following projects are not officially supported:
Security updates are applied only to the latest release.
## Reporting a Vulnerability
If you have discovered a security vulnerability in this project, please report it privately. **Do not disclose it as a public issue.** This gives us time to work with you to fix the issue before public exposure, reducing the chance that the exploit will be used before a patch is released.
Please disclose it at [security advisory](https://github.com/jbeder/yaml-cpp/security/advisories/new).
This project is maintained by a team of volunteers on a reasonable-effort basis. As such, vulnerabilities will be disclosed in a best effort base.
*`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`.
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:
```cpp
#include"yaml-cpp/yaml.h"
intmain()
{
YAML::Emitterout;
out<<"Hello, World!";
std::cout<<"Here's the output YAML:\n"<<out.c_str();// prints "Hello, World!"
return0;
}
```
# 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:
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`:
```cpp
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.:
```cpp
YAML::Emitterout;
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:
_The following describes the old API. For the new API, see the [Tutorial](https://github.com/jbeder/yaml-cpp/wiki/Tutorial)._
## 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
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 [When Something Goes Wrong](https://github.com/jbeder/yaml-cpp/wiki/How-To-Parse-A-Document-(Old-API)#When_Something_Goes_Wrong). If you have optional keys, it's often easier to use `FindValue` instead of `operator[]`:
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:
... 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:
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.
`yaml-cpp` will parse any file as specified 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. It's a Google Gadget, so unfortunately it does not work on GitHub. Patches welcome to port it to a usable format here:
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:
```cpp
switch (node.Type()) {
case Null: // ...
case Scalar: // ...
case Sequence: // ...
case Map: // ...
case Undefined: // ...
}
```
or ask directly whether it's a particular type, e.g.:
```cpp
if (node.IsSequence()) {
// ...
}
```
# Building Nodes #
You can build `YAML::Node` from scratch:
```cpp
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:
```yaml
&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,
```cpp
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,
```cpp
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:
// 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:
```cpp
struct Vec3 { double x, y, z; /* etc - make sure you have overloaded operator== */ };
```
You could write
```cpp
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:
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Salim B
Patrick Diehl
Jeremy Nimmer
Daniel Levin
Jesse Beder
Jesse Beder
IMaloney
Phil Miller
Simon Gene Gottlieb
Reini Urban
Federico Di Pierro
Orgad Shaneh
Cristian Le
Christopher Fore
NameSirius
Josiah VanderZee
Frank Osterfeld
Humberto Dias
dependabot[bot]
Jason Beach
Alejandro-FA
Trompettesib
Alexandre TISSOT
Levi Armstrong
Diogo Teles Sant'Anna
Alex Thiessen
Gianfranco Costamagna
Ezekiel Warren
Pete Lewis
Pierre WendlingandJesse Beder
Alfi Maulana
Paul Jurczak
FireWolf
Daniel Stonier
Kefu Chai
Craig Scott
Ryan
Jelin
Matthijs van der Burgh
Matthijs van der Burgh
James Brown
sfalmo
Derzsi Dániel
stephematician
Baruch
Timo Gurr
rdzehtsiarandRoman Degtyar
Skywol
Igor [hyperxor]
Dr. Andre Vehreschild
SpaceIm
xiaozhuai, Weihang Ding
Felix Schwitzer
Michael Martz
Akash Patel
Sam4uk
Christian Rauch
TheVice
Chen
Pavel Karelin
Ryan Burns
PhilipDeegan
Robert Sebastian Herlim
Michał Janiszewski
João Marcos Bezerra
Pino Toscano
jwindgassen
Snow Pettersen
mjvankampen
jbeach
JBPennington
theamarin
t.t
Kajetan Świerk
Oliver Hamlet
Tom Collins
Raffaello Bertini
Rosen Penev
Josh Soref
Hans-Peter Gygax
Raúl Gutiérrez Segalés
Chen
Ted Lyngmo
Ian Taylor
deflinhec
Martin Delille
Alan Griffiths
Tindy X
Maxim Okhotskiy
Victor Mataré
Romain Deterre
Néstor Subirón
Anton Onishchenko
JeffWegher
Carlos Gomes Martinho
Mike Egger
Romain Geissler @ Amadeus
carmeli-tamir
Isabella Muerte
Rasmus
Andy Maloney
Fatih YAZICI
Jeppe Blicher Tarp
bedapisl
peterchen-cp
caryoscelus
Olli Wang
tt4g
pent0
Alexander Anokhin
Joel Frederico
Lassi Hämäläinen
dand-oss
Florian Eich
Stefan Reinhold
Antony Polukhin
Azamat H. Hackimov
Jesse Beder
Alexander
Alexander Karatarakis
Jiao
Patrick Stotko
Tanki Zhang
maek