New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for load, loadsync does not correspond with implementation and examples #608

Closed
Crazy-Duck opened this Issue Jan 3, 2017 · 5 comments

Comments

Projects
None yet
2 participants
@Crazy-Duck

Crazy-Duck commented Jan 3, 2017

protobuf.js version: 6.3.1

Going by the API doc, the only load functions available are Root.load and Root.loadSync, who take filename, options and callback as arguments, with options being a ParseOptions object (permitting for example to specify you don't want camelCase conversion). Going by the example and these docs, I expected to be able to do the following:

var Protobuf = require('protobufjs'),
    fs = require("fs");


var folder = fs.readdirSync(__dirname + '/proto'); // folder containing proto files
var schema = Protobuf.loadSync(folder.map(filename => __dirname + '/proto/' + filename), {keepCase: true}); // Produces error

However, when passing an options object, a stacktrace is generated implying that the options object is taken as a Root object on which load is invoked...

Stack trace:

/home/ubuntu/workspace/node_modules/protobufjs/src/index.js:64
    return root.loadSync(filename);
                ^

TypeError: root.loadSync is not a function
    at Object.loadSync (/home/ubuntu/workspace/node_modules/protobufjs/src/index.js:64:17)
    at Object.<anonymous> (/home/ubuntu/workspace/poc_proto.js:6:23)
    at Module._compile (module.js:571:32)

When going through the source, I saw that index.js exports itself undocumented load and loadSync functions, who take a different set of parameters, namely filename, root and callback. These functions check if a root parameter is present and if so invoke load/loadSync on this object, with the given filename and callback as arguments. If no root argument is given, a new Root object is generated and load/loadSync are called on this new object. This leads to the terribly confusing situation where, if you don't want to specify options, you can just follow the example using the exported functions, however, when you want to specify options, you need to first create a Root object yourself and use this object instead (thus effectively re-implementing the exported load/loadSync functions, but this time taking into account the options.

Is this intended behavior of the library? If so, it might be necessary to perhaps modify the docs to make this distinction clear..

@dcodeIO

This comment has been minimized.

Owner

dcodeIO commented Jan 3, 2017

When first implemented, keepCase was meant for pbjs' not recommended --keep-case option. That's why I left it out in the convenience API.

When I think about it, now that IE8 support has been dropped and alternative getter/setter functions are a thing of the past, it's actually not necessary anymore to mark this as not recommended. Will take a look!

@dcodeIO dcodeIO added the enhancement label Jan 3, 2017

dcodeIO added a commit that referenced this issue Jan 3, 2017

@dcodeIO

This comment has been minimized.

Owner

dcodeIO commented Jan 3, 2017

You can now set the keepCase option globally:

protobuf.parse.defaults.keepCase = true;

This affects all load/loadSync functions where/when no ParseOptions are specified. These fall back to use protobuf.parse.defaults.

Note that protobuf.load/loadSync are convenience functions, so I'd like to keep them rather simple.

dcodeIO added a commit that referenced this issue Jan 3, 2017

New: Instead of protobuf.parse.keepCase, fall back to protobuf.parse.…
…defaults holding all possible defaults, see #608
@dcodeIO

This comment has been minimized.

Owner

dcodeIO commented Jan 3, 2017

Changed this to fall back to protobuf.parse.defaults - edited the previous comment accordingly. Also added additional links to the documentation so that this is easier to discover.

@Crazy-Duck

This comment has been minimized.

Crazy-Duck commented Jan 3, 2017

Alright, thanks a lot for the fast response!

@dcodeIO

This comment has been minimized.

Owner

dcodeIO commented Jan 3, 2017

Closing this for now as 6.4.0, which is now released, should solve the issue. Feel free to reopen the issue if necessary.

@dcodeIO dcodeIO closed this Jan 3, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment