{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Enums\n", "\n", "[Relevant portion](https://pybind11.readthedocs.io/en/stable/classes.html?highlight=enum#enumerations-and-internal-types) of the pybind11 manual.\n", "\n", "litgen handles `enum` and `enum class` enums.\n", "\n", "## Classic C enums\n", "\n", "See example below: \n", "\n", "* litgen automatically remove the standard prefix from enum values: `Foo::Foo_a` is exposed as `Foo.a`\n", "* comments about values are preserved in the stub\n", "* litgen automatically handles the enum numbering and outputs the values as a comment in the stub\n", "* if some macro values are used (like `MY_VALUE`), we can set their value\n", "* Computed values are also correctly exposed (see `Foo.d`)" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
// Doc about Foo\n",
       "// On several lines\n",
       "enum Foo\n",
       "{\n",
       "    Foo_a, // This is a\n",
       "\n",
       "    // And this is b and c's comment\n",
       "    Foo_b,\n",
       "    Foo_c = MY_VALUE,\n",
       "\n",
       "    Foo_d = Foo_a | Foo_b + Foo_c, // And a computed value\n",
       "\n",
       "    Foo_e = 4,\n",
       "\n",
       "    Foo_count, // And this is count: by default this member is suppressed\n",
       "};\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
class Foo(enum.Enum):\n",
       "    """ Doc about Foo\n",
       "     On several lines\n",
       "    """\n",
       "    a = enum.auto() # (= 0)  # This is a\n",
       "\n",
       "    # And this is b and c's comment\n",
       "    b = enum.auto() # (= 1)\n",
       "    c = enum.auto() # (= 256)\n",
       "\n",
       "    d = enum.auto() # (= Foo.a | Foo.b + Foo.c)  # And a computed value\n",
       "\n",
       "    e = enum.auto() # (= 4)\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
py::enum_<Foo>(m, "Foo", py::arithmetic(), " Doc about Foo\\n On several lines")\n",
       "    .value("a", Foo_a, "This is a")\n",
       "    .value("b", Foo_b, "")\n",
       "    .value("c", Foo_c, "")\n",
       "    .value("d", Foo_d, "And a computed value")\n",
       "    .value("e", Foo_e, "");\n",
       "
\n", "\n", "
\n", " \n", " \n", " " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "cpp_code = \"\"\"\n", "// Doc about Foo\n", "// On several lines\n", "enum Foo\n", "{\n", " Foo_a, // This is a\n", "\n", " // And this is b and c's comment\n", " Foo_b,\n", " Foo_c = MY_VALUE,\n", "\n", " Foo_d = Foo_a | Foo_b + Foo_c, // And a computed value\n", "\n", " Foo_e = 4,\n", "\n", " Foo_count, // And this is count: by default this member is suppressed\n", "};\n", "\"\"\"\n", "\n", "import litgen\n", "from litgen.demo import litgen_demo\n", "\n", "options = litgen.LitgenOptions()\n", "options.srcmlcpp_options.named_number_macros = {\"MY_VALUE\": 256}\n", "# options.enum_flag_skip_count = False # Uncomment this to generate a definition for Foo::Foo_count\n", "litgen_demo.demo(options, cpp_code)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## C++ enums: enum class\n", "\n", "enum class is also supported, see example below:\n" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
    enum class Foo\n",
       "    {\n",
       "        A,\n",
       "        B,\n",
       "        C = MY_VALUE,\n",
       "        D = A | B + C,\n",
       "        E = 4,\n",
       "        F\n",
       "    };\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
class Foo(enum.Enum):\n",
       "    a = enum.auto() # (= 0)\n",
       "    b = enum.auto() # (= 1)\n",
       "    c = enum.auto() # (= 256)\n",
       "    d = enum.auto() # (= A | B + C)\n",
       "    e = enum.auto() # (= 4)\n",
       "    f = enum.auto() # (= 5)\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
py::enum_<Foo>(m, "Foo", py::arithmetic(), "")\n",
       "    .value("a", Foo::A, "")\n",
       "    .value("b", Foo::B, "")\n",
       "    .value("c", Foo::C, "")\n",
       "    .value("d", Foo::D, "")\n",
       "    .value("e", Foo::E, "")\n",
       "    .value("f", Foo::F, "");\n",
       "
\n", "\n", "
\n", " \n", " \n", " " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "cpp_code = \"\"\"\n", " enum class Foo\n", " {\n", " A,\n", " B,\n", " C = MY_VALUE,\n", " D = A | B + C,\n", " E = 4,\n", " F\n", " };\n", "\"\"\"\n", "\n", "options = litgen.LitgenOptions()\n", "options.srcmlcpp_options.named_number_macros = {\"MY_VALUE\": 256}\n", "litgen_demo.demo(options, cpp_code)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Arithmetic enums\n", "\n", "Use `options.enum_make_arithmetic__regex` to make the enum arithmetic in python, so that it can be converted to a number in python." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
    enum class Foo { A, B, C};\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", " \n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
class Foo(enum.Enum):\n",
       "    a = enum.auto() # (= 0)\n",
       "    b = enum.auto() # (= 1)\n",
       "    c = enum.auto() # (= 2)\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " \n", "
\n", "
\n", "
\n", "\n", "\n", " \n", " \n", "
\n", "
\n", " \n", "
\n", " 
py::enum_<Foo>(m, "Foo", py::arithmetic(), "")\n",
       "    .value("a", Foo::A, "")\n",
       "    .value("b", Foo::B, "")\n",
       "    .value("c", Foo::C, "");\n",
       "
\n", "\n", "
\n", " \n", " \n", " \n", " \n", " " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "cpp_code = \"\"\"\n", " enum class Foo { A, B, C};\n", "\"\"\"\n", "options = litgen.LitgenOptions()\n", "options.enum_make_arithmetic__regex = \"^Foo$\"\n", "litgen_demo.demo(options, cpp_code, show_pydef=True)" ] } ], "metadata": { "kernelspec": { "display_name": "venv311", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.0" } }, "nbformat": 4, "nbformat_minor": 2 }