Enumeration - String Conversion Script

About

gen_enum_str is a python script included in the github repository of this library. It generates toString and fromString functions for all enumerations.

How it works

The script first searches all enumerations in .hpp files with some regex. It only detects them when using this syntax:

namespace x::y {
    enum NAME {
        ENUM1, ENUM2=4, ENUM3 = 5, ENUM4,
    };
}

The amount of tabs and spaces are irreleveant, but the { brackets must be on the same line as the declaration. Nested namespaces are not supported, you will have to manully edit the generated code if you use them.

After all enumerations were found, it generates toString and fromString declarations in the .hpp file, and the declarations in the according .cpp file. It uses two maps type2name and name2type for the conversion. The maps are contained in structs, which are declared and defined in the source file.

Usage

The script was written for python 3(.10), so you will need to have that installed.

With script installed

Depending on the installation method, it should either be in /usr/bin or /usr/local/bin which should both be in your $PATH. Note that it will not have the .py ending!

If you do want to run the script on ~/c++/src/myheader.hpp, you can simply do:

shell
  gen-enum-str ~/c++/src/myheader.hpp

With script not installed

If you do want to run the script on ~/c++/src/myheader.hpp, with the script itself being located at ~/scripts/gen_enum_str.py, run:

shell
  python3 ~/scripts/gen_enum_str.py ~/c++/src/myheader.hpp

Warning

This script was tested and should not mess anything up, HOWEVER: Do not just run random scripts off the internet on your precious source code without skimming through them first! It is also advisable to have up-to-date backups!

To get help, use:

gen-enum-str --help

output 
 Synposis:           get_enum_str.py <Options>... <file>...
                     get_enum_str.py <Options>... -r <path>...
 -h --help           help
 -r                  recurse: Recurse through given paths process all files.
 -i                  interactive: prompt for every enumeration
 --no-docs           turn off docstring generation
 --docs-no-names     do not list names of enumeration values in docstring
 --docs-no-gen       do not put "generated by gen_enum_str" in docstring
 --no-throw          return empty string/last enum value if the argument for to/fromString is invalid.
                     This would normaly throw gz::InvalidArgument
                     This option does not make the functions noexcept!
 If the generated code produces errors:
 - check that necessary headers are included in the source file:
   - gz-util/string.hpp
   - gz-util/exceptions.hpp (unless you use --no-throw)
 - check the namespaces of the enumerations, the generated code should be in global namespace
   nested namespace are not supported, you will have to correct that if you use them