Add option to put constified enum into module

[tmfink]

Input C/C++ Header

enum my_enum {
    RED,
    GREEN,
    BLUE,
};

Bindgen Invocation

$ bindgen input.h --constified-enum '.*'

Actual Results

/* automatically generated by rust-bindgen */

pub const my_enum_RED: my_enum = 0;
pub const my_enum_GREEN: my_enum = 1;
pub const my_enum_BLUE: my_enum = 2;
pub type my_enum = ::std::os::raw::c_uint;

Expected Results

It would be nice to be able to pass an option like --constified-enum-in-mod 'my_enum' that tells bindgen to put the matching constified enum inside a module:

pub mod my_enum_mod {
    use super::my_enum_type;

    pub const RED: my_enum_type = 0;
    pub const GREEN: my_enum_type = 1;
    pub const BLUE: my_enum_type = 2;
}
pub type my_enum_type = ::std::os::raw::c_uint;

One problem that must be solved is the collision between the type and module name. Some solutions:

1. Add a prefix/suffix to the module and/or type name. In the example, "_type" and "_mod" suffixes were added to the type module name.
   • Advantages:
     • Clearly distinguishes module and type name
   • Disadvantage:
     • Must use a different name when referring the type vs. the module name
2. Put the type definition in the module.
   • Advantage:
     • Both the type and module share the same base name
   • Disadvantage:
     • Both the module and type cannot be imported into the same namespace (because of name collision)
     • It is awkward to refer to the type as my_enum::my_enum.

Solutions shown on play.rust-lang.org

Recommendation

Overall, I prefer appending a suffix to the type and using the original name for the module. This way, you can refer to elements of the module like my_enum::RED. I believe this will overall reduce the amount of typing required, especially since type names can often be elided.

However, this behavior can be controlled with extra options, allowing bindgen users to decide what works best for their situation. The Rust interface to bindgen could also take in callback functions to allow each enum to be handled on a case-by-case basis.

My recommendation on play.rust-lang.org

Background

I'm currently working on the Rust bindings for Capstone, a disassembly library. Because the same register (for some architectures) can have several names, different enum variants (for the register id enums) have the same discriminant value. One example is mips_reg in mips.h.

I have opted to "constify" the register enums. However, in doing so, over 1000 constants are defined in the root of the library, which makes the generated documentation unwieldy.

[fitzgen]

Overall this sounds reasonable to me, and would be nice to have.

We could put the type into the module without calling it the same name as the module, eg something like my_enum::Type:

pub mod my_enum {
    pub Type = ::std::os::raw::c_uint;

    pub const RED: Type = 0;
    pub const GREEN: Type = 1;
    pub const BLUE: Type = 2;
}

I have a weak preference for this form, but maybe I'm overlooking something.

[tmfink]

@fitzgen, you make a good point, but I prefer to keep the type declaration outside of the module (at least by default).

Keeping the type outside is more consistent with bindgen's current behavior. Otherwise, bindgen users would need an extra use statement for each constified enum to avoid referring to the type as my_enum::Type.

However, this is yet another option that could be set by the user. Something like --keep-constified-enum-type-inside-module could work. We should probably give users a choice.

[fitzgen]

would need an extra use statement for each constified enum to avoid referring to the type as my_enum::Type.

I was imagining that is how it would be referred to. Doesn't seem worse than my_enum_type and can't result in a conflicting name if some C/C++ thing we're also generating bindings for also happens to be called my_enum_type.

However, this is yet another option that could be set by the user. Something like --keep-constified-enum-type-inside-module could work. We should probably give users a choice.

The more options we have, the more combinations there are, the more bugs will be latent and hiding. Its good to have options when we need to flip things on/off for correctness issues (eg why constified enums exists in the first place) but I'd like to gently push back on adding options to control all manner of aesthetics.

[tmfink]

That's a good point. I suppose keeping the type inside the module would also make a more clear distinction between normal enums and constified enums. Also, bindgen users can always re-export types outside the module with whatever name they want.

[fitzgen]

This was fixed in #741.