Some basic examples needed

[tamboril]

Thanks for the work on this library. I really need a few examples of the API in use. The unit tests aren't much help, and the Doxygen doesn't show any usage examples.

For instance, what's unwrapped mean? And am I supposed to just downcast config_value to the proper type in a big switch ?

[Magisus]

The unwrapped method returns the value stored in a config_value as a C++ type, in this case a boost::variant (for info on this type see http://www.boost.org/doc/libs/1_61_0/doc/html/variant.html). This variant can hold any of the following types: boost::blank (used to represent a null or empty value), string, int64_t, double, int, bool, std::vector, std::unordered_map. The vector and unordered_map contain the same type of boost::variant and represent a HOCON list and HOCON object respectively.

What you do with these values is up to you. The best approach is probably to define a static_visitor as described in the boost::variant docs, instead of a switch statement. For an example of such a visitor, see config_value_factory.cc, whose job it is to take these boost::variants and return corresponding config_values (the opposite of the unwrapped methods).

If you need to manipulate config_values without unwrapping them, and need the concrete types, unfortunately you will have to resort to casting. The library code itself does that all over the place. We have tried to keep our structure and public API as consistent as possible with the original Java version of this project, and they have some additional tests and examples you might want to take a look at: https://github.com/typesafehub/config. Bear in mind our port is still a work in progress, so not all features specified there have been completely implemented in the C++ yet.

We definitely plan to get some proper examples written up soon. We are just at the point where we are going to start using this project internally, and as part of that process we will be cleaning up the documentation and public API, as well as fleshing out some examples.

[MikaelSmith]

I basic tutorial on using boost::variant are present at http://www.boost.org/doc/libs/1_61_0/doc/html/variant/tutorial.html#variant.tutorial.basic. You can use boost::get<Type>(v) if you expect a value matching Type; that request will throw an exception if the type stored in v is not Type.

[tamboril]

Thank you both for the explanations (I just saw this). I'm successfully using the library as-is, and I look forward to the merge of the pending pull requests.

[tamboril]

In the way of documentation, here is what I have to do to build cpp-hocon on CentOS 7 with a local Boost 1.61 without touching any system directories.:

• Build Leatherman and install locally:

  cmake \
    -DBOOST_ROOT=~/local/boost \
    -DCMAKE_CXX_FLAGS_RELEASE="-O3 -DNDEBUG -w" \
    -DLEATHERMAN_GETTEXT=OFF \
    -DCMAKE_INSTALL_PREFIX=~/local <leatherman_src_dir>
  

• Build cpp-hocon and install locally:

  cmake \
    -DBOOST_ROOT=~/local/boost \
    -DCMAKE_PREFIX_PATH=~/local \
    -DCMAKE_CXX_FLAGS_RELEASE="-O3 -DNDEBUG -w" \
    -DCMAKE_INSTALL_PREFIX=~/local <cpp-hocon_src_dir>