Parsing Configurations in C++

When parsing configurations in C++ tools, the configurations get usually converted into rofi::configuration::RofiWorld. For this, tools can use the parsing function rofi::parsing::parseRofiWorld() or rofi::parsing::parseRofiWorldSeq().

For the other conversion, tools can use rofi::parsing::writeRofiWorld() or rofi::parsing::writeRofiWorldSeq().

Note

When parsing you may want to check whether the configuration is empty or whether the configuration is fixed in space.

If you want to allow for not fixed configurations and be able to prepare them (without regards to the real position), you can use rofi::parsing::fixateRofiWorld().

Also don’t forget to validate the configuration if needed.

Helper Functions

inline auto rofi::parsing::parseJson(std::istream &istr) -> atoms::Result<nlohmann::json>

Calls nlohmann::json::parse, but returns atoms::Result instead of throwing.

Returns an error if parsing throws an exception.

Parameters: istr – input stream
Returns: parsed json

template<typename T> auto rofi::parsing::getFromJson(const nlohmann::json &json) -> atoms::Result<T>

Calls nlohmann::json::get, but returns atoms::Result instead of throwing.

Returns an error if converting throws an exception.

Template Parameters: T – value type to be returned
Parameters: json – input json
Returns: converted value

Helper RofiWorld Functions

inline void rofi::parsing::fixateRofiWorld(rofi::configuration::RofiWorld &world)

Fixates given world in space using a RigidJoint between (0, 0, 0) and first body of first module.

Assumes the world modules is not empty.

Parameters: world – rofi world to be fixated in space

inline auto rofi::parsing::toSharedAndValidate(rofi::configuration::RofiWorld rofiWorld) -> atoms::Result<std::shared_ptr<rofi::configuration::RofiWorld>>

Converts rofiWorld to std::shared_ptr and validates the world.

Returns an error if rofiWorld is not valid.

Note

Expected use with atoms::Result::and_then.

Note

Uses std::shared_ptr because moving rofi::configuration::RofiWorld unprepares it.

Parameters: rofiWorld – input rofi world
Returns: the validated rofiWorld inside a std::shared_ptr

inline auto rofi::parsing::validateRofiWorldSeq(std::span<rofi::configuration::RofiWorld> rofiWorldSeq) -> atoms::Result<std::monostate>

Validates rofi worlds in rofiWorldSeq .

Returns an error if any world in rofiWorldSeq is not valid.

Parameters: rofiWorldSeq – input rofi world sequence

inline auto rofi::parsing::validatedRofiWorldSeq(std::vector<rofi::configuration::RofiWorld> rofiWorldSeq) -> atoms::Result<std::vector<rofi::configuration::RofiWorld>>

Validates rofi worlds in rofiWorldSeq .

Returns an error if any world in rofiWorldSeq is not valid.

Note

Expected use with atoms::Result::and_then.

Parameters: rofiWorldSeq – input rofi world sequence
Returns: validated rofiWorldSeq

Conversion Functions

inline auto rofi::parsing::getRofiWorldFromJson(const nlohmann::json &json) -> atoms::Result<rofi::configuration::RofiWorld>

Calls rofi::configuration::serialization::fromJSON, but returns atoms::Result instead of throwing.

Returns an error if converting throws an exception.

Parameters: json – input json
Returns: converted rofi world

inline auto rofi::parsing::getRofiWorldSeqFromJson(const nlohmann::json &json) -> atoms::Result<std::vector<rofi::configuration::RofiWorld>>

Converts nlohmann::json to rofi world sequence.

Returns an error if converting throws an exception.

Parameters: json – input json
Returns: converted rofi world sequence

inline auto rofi::parsing::convertRofiWorldSeqToJson(std::span<const rofi::configuration::RofiWorld> rofiWorldSeq) -> nlohmann::json

Converts rofi world sequence to nlohmann::json.

Parameters: rofiWorldSeq – input rofi world sequence
Returns: converted json

template<typename Callback, typename WorldT = std::invoke_result_t<Callback, const rofi::configuration::RofiWorld>::value_type> auto rofi::parsing::convertFromRofiWorldSeq(std::span<const rofi::configuration::RofiWorld> rofiWorldSeq, Callback convertCallback) -> atoms::Result<std::vector<WorldT>>

Converts rofiWorldSeq to a sequence of new worlds.

Uses convertCallback for conversion to WorldT . Returns an error if any call to convertCallback fails including information about the position of the failed world.

Note

Behaves as transform and collect on atoms::Result and also includes info about which conversion failed.

Parameters

rofiWorldSeq – input rofi world sequence
convertCallback – callback for converting rofi world to new world

Returns

converted sequence of new worlds

template<typename WorldT, typename Callback> auto rofi::parsing::convertToRofiWorldSeq(std::span<const WorldT> worldSeq, Callback convertCallback) -> atoms::Result<std::vector<rofi::configuration::RofiWorld>>

Converts worldSeq to a rofi world sequence.

Uses convertCallback for conversion to rofi world. Returns an error if any call to convertCallback fails including information about the position of the failed world.

Note

Behaves as transform and collect on atoms::Result and also includes info about which conversion failed.

Parameters

worldSeq – input world sequence
convertCallback – callback for converting world to rofi world

Returns

converted rofi world sequence

inline auto rofi::parsing::parseOldCfgFormat(std::istream &istr, bool fixate) -> atoms::Result<rofi::configuration::RofiWorld>

Parses rofi world from given istr .

Assumes that the input is in old (Viki) format. Returns an error if the format is incorrect.

Parameters

istr – input stream containing the rofi world
fixate – whether to fixate the world after parsing

Returns

the parsed rofi world

Multi-Format Conversions

enum class rofi::parsing::RofiWorldFormat

Values:

enumerator Old

enumerator Json

enumerator Voxel

inline auto rofi::parsing::parseRofiWorld(std::istream &istr, RofiWorldFormat worldFormat, bool fixateByOne = false) -> atoms::Result<rofi::configuration::RofiWorld>

Parses rofi world from given istr .

Parses the input according to worldFormat . If the world is in old format, fixates the world. Returns an error if the format is incorrect.

Parameters

istr – input stream containing the rofi world
worldFormat – format of input world

Returns

the parsed rofi world

inline auto rofi::parsing::writeRofiWorld(std::ostream &ostr, const rofi::configuration::RofiWorld &rofiWorld, RofiWorldFormat worldFormat) -> atoms::Result<std::monostate>

Writes rofi world to given ostr in the format specified by worldFormat .

Returns an error if the format is incorrect or if the old format is specified.

Parameters

istr – input stream containing the rofi world
worldFormat – format of input world

Returns

the parsed rofi world

inline auto rofi::parsing::parseRofiWorldSeq(std::istream &istr, RofiWorldFormat worldFormat, bool fixateByOne = false) -> atoms::Result<std::vector<rofi::configuration::RofiWorld>>

Parses rofi world sequence from given istr .

Parses the input according to worldFormat . Returns an error if the format is incorrect.

Parameters

istr – input stream containing the rofi world sequence
worldFormat – format of input world sequence

Returns

the parsed rofi world sequence

inline auto rofi::parsing::writeRofiWorldSeq(std::ostream &ostr, std::span<const rofi::configuration::RofiWorld> rofiWorldSeq, RofiWorldFormat worldFormat) -> atoms::Result<std::monostate>

Writes rofi world sequence to given ostr in the format specified by worldFormat .

Returns an error if the format is incorrect or if the old format is specified.

Parameters

istr – input stream containing the rofi world sequence
worldFormat – format of input world sequence

Returns

the parsed rofi world sequence