From c365242bdc28a47f5c6ab91bae34c277d1044eb3 Mon Sep 17 00:00:00 2001 From: dcodeIO Date: Mon, 30 Jan 2017 19:29:03 +0100 Subject: [PATCH] Docs: Reference Buffer for BufferReader/Writer, see #668 --- README.md | 48 ++++++++++++++++++++++++++++---------------- cli/pbts.js | 10 +++++---- index.d.ts | 40 +++++++++++++++++++++++++++++++----- src/reader.js | 4 ++-- src/reader_buffer.js | 13 ++++++++++++ src/writer_buffer.js | 14 +++++++++++-- 6 files changed, 99 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 4b0703df9..66a72b303 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ The library supports both reflection-based and code-based use cases: There is a suitable distribution for each of these: -| Build | GZ Size | Downloads | How to require | Description +| | Gzipped | Downloads | How to require | Description |---------|---------|------------------------------|---------------------------------|------------- | full | 18.5kb | [dist][dist-full] | `require("protobufjs")` | All features. Works with everything. | light | 15.5kb | [dist/light][dist-light] | `require("protobufjs/light")` | All features except tokenizer, parser and bundled common types. Works with JSON definitions, pure reflection and static code. @@ -80,6 +80,10 @@ There is a suitable distribution for each of these: In case of doubt you can just use the full library. +[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist +[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light +[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal + Examples -------- @@ -302,7 +306,7 @@ protobuf.load("awesome.proto", function(err, root) { }); ``` -To achieve the same with static code generated by [pbjs](https://github.com/dcodeIO/protobuf.js#command-line), there is the [pbts](https://github.com/dcodeIO/protobuf.js#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well. +To achieve the same with static code generated by [pbjs](#command-line), there is the [pbts](#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well. Let's say you generated your static code to `bundle.js` and its type definitions to `bundle.d.ts`, then you can do: @@ -358,13 +362,15 @@ Consolidates imports and converts between file formats. default Default wrapper supporting both CommonJS and AMD commonjs CommonJS wrapper amd AMD wrapper - es6 ES6 wrapper + es6 ES6 wrapper (implies --es6) -r, --root Specifies an alternative protobuf.roots name. -l, --lint Linter configuration. Defaults to protobuf.js-compatible rules: - eslint-disable block-scoped-var, no-redeclare, no-control-regex + eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins + + --es6 Enables ES6 syntax (const/let instead of var) Proto sources only: @@ -410,7 +416,7 @@ As you might have noticed, `pbjs` is also capable of generating static code. For $> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto ``` -will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`, which then can be used with just the [minimal library][dist-minimal]. +will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`, which then can be used with just the [minimal library](#distributions). **ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code. @@ -421,16 +427,18 @@ Likewise, the `pbts` command line utility can be used to generate TypeScript def ``` Generates TypeScript definitions from annotated JavaScript files. - -n, --name Wraps everything in a module of the specified name. - -o, --out Saves to a file instead of writing to stdout. - -m, --main Whether building the main library without any imports. - -g, --global Name of the global object in browser environments, if any. --no-comments Does not output any JSDoc comments. + Internal flags: + + -n, --name Wraps everything in a module of the specified name. + + -m, --main Whether building the main library without any imports. + usage: pbts [options] file1.js file2.js ... (or) other | pbts [options] - ``` @@ -455,9 +463,9 @@ $> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts - ### On reflection vs. static code -While using .proto files directly requires the [full library][dist-full] respectively pure reflection/JSON the [light library][dist-light], pretty much all code but the relatively short descriptors is shared. +While using .proto files directly requires the [full library](#distributions) respectively pure reflection/JSON the [light library](#distributions), pretty much all code but the relatively short descriptors is shared. -Static code, on the other hand, requires just the [minimal library][dist-minimal], but generates additional, albeit editable, source code without any reflection features. +Static code, on the other hand, requires just the [minimal library](#distributions), but generates additional, albeit editable, source code without any reflection features. There is no significant difference performance-wise as the code generated statically is pretty much the same as generated at runtime and both are largely interchangeable as seen in the previous section. @@ -590,11 +598,17 @@ $> npm run types By default, protobuf.js integrates into your browserify build-process without requiring any optional modules. Hence: -* If you need int64 support, explicitly require the `long` module somewhere in your project. It will be excluded otherwise. -* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) as a reference. +* If you need int64 support, explicitly require the `long` module somewhere in your project as it will be excluded otherwise. This assumes that a global `require` function is present that protobuf.js can call to obtain the long module. -**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) + If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically: -[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist -[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light -[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal + ```js + var Long = ...; + + protobuf.util.Long = Long; + protobuf.configure(); + ``` + +* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) for reference. + +**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) diff --git a/cli/pbts.js b/cli/pbts.js index 66bac6c46..f4cb09b9b 100644 --- a/cli/pbts.js +++ b/cli/pbts.js @@ -45,16 +45,18 @@ exports.main = function(args, callback) { "", chalk.bold.white("Generates TypeScript definitions from annotated JavaScript files."), "", - " -n, --name Wraps everything in a module of the specified name.", - "", " -o, --out Saves to a file instead of writing to stdout.", "", - " -m, --main Whether building the main library without any imports.", - "", " -g, --global Name of the global object in browser environments, if any.", "", " --no-comments Does not output any JSDoc comments.", "", + chalk.bold.gray(" Internal flags:"), + "", + " -n, --name Wraps everything in a module of the specified name.", + "", + " -m, --main Whether building the main library without any imports.", + "", "usage: " + chalk.bold.green("pbts") + " [options] file1.js file2.js ..." + chalk.bold.gray(" (or) ") + "other | " + chalk.bold.green("pbts") + " [options] -" ].join("\n")); if (callback) diff --git a/index.d.ts b/index.d.ts index 6e37989af..d7d9af134 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1174,10 +1174,10 @@ export class Reader { /** * Creates a new reader using the specified buffer. * @function - * @param {Uint8Array} buffer Buffer to read from - * @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader} + * @param {Uint8Array|Buffer} buffer Buffer to read from + * @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader} */ - static create(buffer: Uint8Array): (BufferReader|Reader); + static create(buffer: (Uint8Array|Buffer)): (Reader|BufferReader); /** * Reads a varint as an unsigned 32 bit value. @@ -1314,6 +1314,21 @@ export class BufferReader extends Reader { * @param {Buffer} buffer Buffer to read from */ constructor(buffer: Buffer); + + /** + * Read buffer. + * @name BufferReader#buf + * @type {Buffer} + */ + buf: Buffer; + + /** + * Reads a sequence of bytes preceeded by its length as a varint. + * @name BufferReader#bytes + * @function + * @returns {Buffer} Value read + */ + bytes(): Buffer; } /** @@ -2703,9 +2718,24 @@ export class BufferWriter extends Writer { /** * Allocates a buffer of the specified size. * @param {number} size Buffer size - * @returns {Uint8Array} Buffer + * @returns {Buffer} Buffer */ - static alloc(size: number): Uint8Array; + static alloc(size: number): Buffer; + + /** + * Writes a sequence of bytes. + * @param {Buffer|string} value Buffer or base64 encoded string to write + * @returns {Writer} `this` + */ + bytes(value: (Buffer|string)): Writer; + + /** + * Finishes the write operation. + * @name BufferWriter#finish + * @function + * @returns {Buffer} Finished buffer + */ + finish(): Buffer; } /** diff --git a/src/reader.js b/src/reader.js index 758aebb43..0bceceac2 100644 --- a/src/reader.js +++ b/src/reader.js @@ -43,8 +43,8 @@ function Reader(buffer) { /** * Creates a new reader using the specified buffer. * @function - * @param {Uint8Array} buffer Buffer to read from - * @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader} + * @param {Uint8Array|Buffer} buffer Buffer to read from + * @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader} */ Reader.create = util.Buffer ? function create_buffer_setup(buffer) { diff --git a/src/reader_buffer.js b/src/reader_buffer.js index adbd4a7fd..95189014f 100644 --- a/src/reader_buffer.js +++ b/src/reader_buffer.js @@ -16,6 +16,12 @@ var util = require("./util/minimal"); */ function BufferReader(buffer) { Reader.call(this, buffer); + + /** + * Read buffer. + * @name BufferReader#buf + * @type {Buffer} + */ } /* istanbul ignore else */ @@ -29,3 +35,10 @@ BufferReader.prototype.string = function read_string_buffer() { var len = this.uint32(); // modifies pos return this.buf.utf8Slice(this.pos, this.pos = Math.min(this.pos + len, this.len)); }; + +/** + * Reads a sequence of bytes preceeded by its length as a varint. + * @name BufferReader#bytes + * @function + * @returns {Buffer} Value read + */ diff --git a/src/writer_buffer.js b/src/writer_buffer.js index 41e7c6330..5ba0ab27b 100644 --- a/src/writer_buffer.js +++ b/src/writer_buffer.js @@ -22,7 +22,7 @@ function BufferWriter() { /** * Allocates a buffer of the specified size. * @param {number} size Buffer size - * @returns {Uint8Array} Buffer + * @returns {Buffer} Buffer */ BufferWriter.alloc = function alloc_buffer(size) { return (BufferWriter.alloc = util._Buffer_allocUnsafe)(size); @@ -42,7 +42,9 @@ var writeBytesBuffer = Buffer && Buffer.prototype instanceof Uint8Array && Buffe }; /** - * @override + * Writes a sequence of bytes. + * @param {Buffer|string} value Buffer or base64 encoded string to write + * @returns {Writer} `this` */ BufferWriter.prototype.bytes = function write_bytes_buffer(value) { if (util.isString(value)) @@ -71,3 +73,11 @@ BufferWriter.prototype.string = function write_string_buffer(value) { this.push(writeStringBuffer, len, value); return this; }; + + +/** + * Finishes the write operation. + * @name BufferWriter#finish + * @function + * @returns {Buffer} Finished buffer + */