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