Proposition for a stable API

[tomaka]

The current API is pretty crappy, so here is my proposition to have a clean API and release some kind of non-work-in-progress version of the gl_generator.

• Hide the registry and generators modules from the outside of the crate.
• Only expose one single function named generate.

As far as I know, nobody has written an external generator yet, so I don't think it's a problem to remove this possibility.

The signature of generate would be like this:

fn generate<W, I>(output: &mut W, generator: GeneratorType, api: Api,
                  version: &str, profile: &str, extensions: I, fallbacks: Fallbacks)
                  -> Result<(), Error>
                  where W: Write, I: IntoIterator, I::Item: AsRef<str>

• The user would no longer need to depend on khronos_api (major point IMO)
• The namespace and XML files would be automatically deducted from the api
• Anything could be passed for extensions, be it a Vec<String> or a &[&str].
• version and profile are still strings as their content are peeked directly at the XML files. Not using an enum means that we won't have to do any modification when a new version of OpenGL is released.

[brendanzab]

Making generators private for now might be reasonable. We can make more of the API public as we see fit in the future.

[brendanzab]

Ah, yes! I see now. Making khronos_api private would be a big win. There's no real need to allow for custom xml strings to be passed to the generators.

[brendanzab]

How about:

impl<Extensions, Extension = String> Registry<Extensions> where
    Extension: AsRef<str>,
    Extensions: IntoIterator<Item = Extension>,
{
    pub fn new(api: Api, version: (u8, u8): &str, profile: Profile, extensions: Extensions, fallbacks: Fallbacks) -> Registry<Extensions>;
    pub fn write_bindings(self, &mut output, generator) -> io::Result<()>;
}

Then:

Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All)
    .write_bindings(&mut output, generators::Global)
    .unwrap();

[brendanzab]

Hmm, seems like @mjkoo is relying on some of the gl_generator::generators functionality in his epoxy-rs crate. Might make sense to get his views on this.

[brendanzab]

@tomaka How happy are you with the current API on master? I would like this to work, but I cant get the type inference to work when no extensions are specified:

impl Registry {
    pub fn new<Exts, Ext = String>(api: Api, version: (u8, u8), profile: Profile, fallbacks: Fallbacks, extensions: Exts) -> Registry where
        Ext: AsRef<str>,
        Exts: IntoIterator<Item = Extension>;

    pub fn write_bindings<W, G>(&self, generator: G, output: &mut W) -> io::Result<()> where
        G: Generator,
        W: io::Write;
}

Might be an issue with combining default type params and trait constraints...

[brendanzab]

The issues with the default type parameters might be related to what @nikomatsakis was talking about in this comment: rust-lang/rfcs#1196 (comment).

One solution, if we really wanted an AsRef bound would be to go back to the builder route, with a with_extensions method.

// no extensions
RegistryBuilder::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All)
    .build()
    .write_bindings(&mut output, generators::Global)
    .unwrap();

// extensions
RegistryBuilder::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All)
    .with_extensions(["GL_ARB_debug_output"])
    .build()
    .write_bindings(&mut output, generators::Global)
    .unwrap();

I reckon that is ugly and confusing though. I think we should just call it a day and accept an AsRef<[&'a str]> for the extension list, like we currently do:

Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, ["GL_ARB_debug_output"])
    .write_bindings(&mut output, generators::Global)
    .unwrap();

[brendanzab]

Craziest idea yet:

Have a build script for gl_generator that parses the xml files, and generates a big enum of the possible extensions!

Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [Extension::GL_ARB_debug_output])

No more stringly typed stuff! It's almost like a hacky form of type providers!

/jokeyjoke