parse signatures of functions with pointers into CSV files to be filled out

[wchristian]

And another branch not intended for direct merging.

I wrote a script that parses badp-XS-sigs-numptr.pl and creates batch files, by feature, with sets of functions and their arguments. One line per function argument. CSV format. Columns are:

res_type  func_name  pointer_depth  type  arg_name  array_size  inout  width  notes

Fields to be filled contain ???. array_size is used very rarely for args declared with [x], where INF means it was just []. type is the full list of type parameters since there are some things in there like const void *const *. pointer_depth is simply a counter incremented for every * in the type list. inout should be in|out|inout. width should be fixed|variable.

Did i miss anything?

[devel-chm]

Looks good. I would suggest additionally:

• Include argument number for each argument
• Unify the numbering with function name as 0, return value is -1, args are 1..n
• The pointer count makes sense as a level of difficulty (I think)
• Breaking out the return/args by line I think we only need a pointer flag 0/1

[wchristian]

I don't understand these, can you please elaborate?

• Unify the numbering with function name as 0, return value is -1, args are 1..n
• Breaking out the return/args by line I think we only need a pointer flag 0/1

[devel-chm]

Here is an example with the GL_ARB_vertex_buffer_object.csv file:

func_name, arg_num, has_ptr, type, arg_name, array_size, inout, width, notes
glBufferDataARB, -1, 0, void, NA, NA, NA, NA, ???
glBufferDataARB, 1, 0, GLenum, target, NA, in, fixed, ???
glBufferDataARB, 2, 0, GLsizeiptrARB, size, NA, in, fixed, ???
glBufferDataARB, 3, 1, "const void *", data, ???, ???, ???
glBufferDataARB, 4, 0, GLenum, usage, NA, in, fixed, ???
glBufferSubDataARB, -1, 0, void, NA, NA, NA, NA, ???
glBufferSubDataARB, 1, 0, GLenum, target, NA, in, fixed, ???
glBufferSubDataARB, 2, 0, GLintptrARB, offset, NA, in, fixed, ???
glBufferSubDataARB, 3, 0, GLsizeiptrARB, size, NA, in, fixed, ???
glBufferSubDataARB, 4, 1, "const void *", data, ???, ???, ???, ???
glDeleteBuffersARB, -1, 0, void, NA, NA, NA, NA, ???
glDeleteBuffersARB, 1, 0, GLsizei, n, NA, in, fixed, ???
glDeleteBuffersARB, 2, 1, "const GLuint *", buffers, ???, ???, ???, ???
glGenBuffersARB, -1, 0, void, NA, NA, NA, NA, ???
glGenBuffersARB, 1, 0, GLsizei, n, NA, in, fixed, ???
glGenBuffersARB, 2, 1, "GLuint *", buffers, ???, ???, ???, ???
glGetBufferParameterivARB, -1, 0, void, NA, NA, NA, NA, ???
glGetBufferParameterivARB, 1, 0, GLenum, target, NA, in, fixed, ???
glGetBufferParameterivARB, 2, 0, GLenum, pname, NA, in, fixed, ???
glGetBufferParameterivARB, 3, 1, "GLint *", params, ???, ???, ???, ???
glGetBufferPointervARB, -1, 0, void, NA, NA, NA, NA, ???
glGetBufferPointervARB, 1, 0, GLenum, target, NA, in, fixed, ???
glGetBufferPointervARB, 2, 0, GLenum, pname, NA, in, fixed, ???
glGetBufferPointervARB, 3, 1, "void * *", params, ???, ???, ???, ???
glGetBufferSubDataARB, -1, 0, void, NA, NA, NA, NA, ???
glGetBufferSubDataARB, 1, 0, GLenum, target, NA, in, fixed, ???
glGetBufferSubDataARB, 2, 0, GLintptrARB, offset, NA, in, fixed, ???
glGetBufferSubDataARB, 3, 0, GLsizeiptrARB, size, NA, in, fixed, ???
glGetBufferSubDataARB, 4, 1, "void *", data, ???, ???, ???, ???
glMapBufferARB, -1, 1, "void *", NA, ???, out, ???, ???
glMapBufferARB, 1, 0, GLenum, target, NA, in, fixed, ???
glMapBufferARB, 2, 0, GLenum, access, NA, in, fixed, ???

[wchristian]

Thanks for the example, that helps a lot!

glDeleteBuffersARB, 1, 0, GLsizei, n, NA, in, fixed, ???

Should non-pointer args have some notes on them too? I'm not sure what should be written there, and intended to use ??? to mark fields that must be filled in, so when handling a file we can just ctrl+f for ??? to jump from one to the next.

Breaking out the return/args by line I think we only need a pointer flag 0/1

The pointer flag was, as you mentioned, for difficulty, however it didn't count the amount of pointer args for a function, but the reference depth on the pointers on the specific argument. E.g. this one is straight-forward:

glGetBufferParameterivARB, 3, 1, "GLint *", params, ???, ???, ???, ???

However this one looks like it could use a marker to point out something more complicated is going on:

glMultiDrawElementsBaseVertex, 3, 2, "const void * const *", indices, ???, ???, ???, ???

Marking this one for warranting more inspection due to being nested pointers does not help you?

NA

Nice, will use that as appropiate then.

However for clarification about the array_size field: As i had the field right now it was used only for arguments that came in this form: argument[] or argument[16]. What, if anything, should be entered in that field for arguments which don't have [] in the signature?

[devel-chm]

On 3/1/2017 17:28, Christian Walde (Mithaldu) wrote: Thanks for the example, that helps a lot! |glDeleteBuffersARB, 1, 0, GLsizei, n, NA, in, fixed, ???| Should non-pointer args have some notes on them too? I'm not sure what should be written there, and intended to use ??? to mark fields that must be filled in, so when handling a file we can just ctrl+f for ??? to jump from one to the next.

The most important about the non-pointer arguments is that they often determine what the pointer argument does such as number of values, data types, ...

Breaking out the return/args by line I think we only need a pointer flag 0/1 The pointer flag was, as you mentioned, for difficulty, however it didn't count the amount of pointer args for a function, but the reference depth on the pointers on the specific argument. E.g. this one is straight-forward: |glGetBufferParameterivARB, 3, 1, "GLint *", params, ???, ???, ???, ???| However this one looks like it could use a marker to point out something more complicated is going on: |glMultiDrawElementsBaseVertex, 3, 2, "const void * const *", indices, ???, ???, ???, ???| Marking this one for warranting more inspection due to being nested pointers does not help you?

OK. How about put it in since while it may not make a difference when a human looks at the breakdown, it could be useful to better characterize groups of functions needing similar interface strategies.

|NA| Nice, will use that as appropiate then. However for clarification about the |array_size| field: As i had the field right now it was used only for arguments that came in this form: argument[] or argument[16]. What, if anything, should be entered in that field for arguments which don't have [] in the signature?

In C there is little difference between an array and a pointer. If you have pointer, number of elements, and data type then they are almost exactly equivalent---at least as far as the generation of XS bindings to the functions.

[wchristian]

Didn't see that feedback until just now, as my internet is quite broken at the moment, tech scheduled for saturday. Will try to get changes in but can't make any promises.

[wchristian]

Alright, adapted the files to your feedback, let me know if there's anything else you'd like to see changed. In the meantime i'm preparing a script to generate the markup for the issue regarding work on these.

[wchristian]

I opened #53 to keep things moving even if you haven't blessed this one yet. Once you're happy with this one, have a read of #53 and edit it as you find appropriate.