diff options
author | Kamil Rojewski <krojew@users.noreply.github.com> | 2018-03-23 17:01:39 +0100 |
---|---|---|
committer | Wouter van Oortmerssen <aardappel@gmail.com> | 2018-03-23 09:01:39 -0700 |
commit | cc54963830c4a30eef6ea3c366d478c643cb71d7 (patch) | |
tree | 5deae24e78b07382fa821ce1309b99f87b2a3e3a /docs | |
parent | 79f62ee35383f44f98cf6c61b5cff1a9cd901f2c (diff) | |
download | flatbuffers-cc54963830c4a30eef6ea3c366d478c643cb71d7.tar.gz |
TypeScript docs (#4680)
* Eclipse ignore
* TypeScript support
* Prefixing enums
* Test results
* Merged JS and TS generators
* Fixed AppVeyor build problems
* Fixed more AppVeyor build problems
* Fixed more AppVeyor build problems
* Changed TS flag to options struct
* Storing options by value
* Removed unneeded const
* Re-export support for unions
* Uint support
* Casting bools to numbers for mutation
* TS shell tests
* Reverted generates js test file to original version
* Backing up js tests and properly generating test data
* Not importing flatbuffers for TS test generation
* Not overwriting generated js for tests
* AppVeyor test fixes
* Generating the most strict TS code possible
* Not returning null when creating vectors
* Not returning null from struct contructors
* Vector of unions for ts/js
* Sanity check for languages
* Indentation fix + output test files
* Vectors of unions for php
* Fixes to union vector handling + tests
* Fix for strictPropertyInitialization
* Fix for new aligned operator new for gcc >= 7.1
* Not generating imports/ns prefixes with --gen-all
* TypeScript docs
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/FlatBuffers.md | 2 | ||||
-rw-r--r-- | docs/source/Support.md | 35 | ||||
-rw-r--r-- | docs/source/Tutorial.md | 169 | ||||
-rw-r--r-- | docs/source/TypeScriptUsage.md | 66 | ||||
-rw-r--r-- | docs/source/groups | 3 |
5 files changed, 255 insertions, 20 deletions
diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md index d228bd40..b1239b00 100644 --- a/docs/source/FlatBuffers.md +++ b/docs/source/FlatBuffers.md @@ -4,7 +4,7 @@ FlatBuffers {#flatbuffers_index} # Overview {#flatbuffers_overview} [FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform -serialization library for C++, C#, C, Go, Java, JavaScript, PHP, and Python. +serialization library for C++, C#, C, Go, Java, JavaScript, TypeScript, PHP, and Python. It was originally created at Google for game development and other performance-critical applications. diff --git a/docs/source/Support.md b/docs/source/Support.md index 9833ccdb..e1fc5633 100644 --- a/docs/source/Support.md +++ b/docs/source/Support.md @@ -18,27 +18,28 @@ In general: NOTE: this table is a start, it needs to be extended. -Feature | C++ | Java | C# | Go | Python | JS | C | PHP | Ruby ------------------------------- | ------ | ------ | ------ | ------ | ------ | --------- | ------ | --- | ---- -Codegen for all basic features | Yes | Yes | Yes | Yes | Yes | Yes | Yes | WiP | WiP -JSON parsing | Yes | No | No | No | No | No | Yes | No | No -Simple mutation | Yes | Yes | Yes | Yes | No | No | No | No | No -Reflection | Yes | No | No | No | No | No | Basic | No | No -Buffer verifier | Yes | No | No | No | No | No | Yes | No | No -Testing: basic | Yes | Yes | Yes | Yes | Yes | Yes | Yes | ? | ? -Testing: fuzz | Yes | No | No | Yes | Yes | No | No | ? | ? -Performance: | Superb | Great | Great | Great | Ok | ? | Superb | ? | ? -Platform: Windows | VS2010 | Yes | Yes | ? | ? | ? | VS2010 | ? | ? -Platform: Linux | GCC282 | Yes | ? | Yes | Yes | ? | Yes | ? | ? -Platform: OS X | Xcode4 | ? | ? | ? | Yes | ? | Yes | ? | ? -Platform: Android | NDK10d | Yes | ? | ? | ? | ? | ? | ? | ? -Platform: iOS | ? | ? | ? | ? | ? | ? | ? | ? | ? -Engine: Unity | ? | ? | Yes | ? | ? | ? | ? | ? | ? -Primary authors (github) | gwvo | gwvo | ev*/js*| rw | rw | evanw/ev* | mik* | ch* | rw +Feature | C++ | Java | C# | Go | Python | JS | TS | C | PHP | Ruby +------------------------------ | ------ | ------ | ------ | ------ | ------ | --------- | --------- | ------ | --- | ---- +Codegen for all basic features | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | WiP | WiP +JSON parsing | Yes | No | No | No | No | No | No | Yes | No | No +Simple mutation | Yes | Yes | Yes | Yes | No | No | No | No | No | No +Reflection | Yes | No | No | No | No | No | No | Basic | No | No +Buffer verifier | Yes | No | No | No | No | No | No | Yes | No | No +Testing: basic | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | ? | ? +Testing: fuzz | Yes | No | No | Yes | Yes | No | No | No | ? | ? +Performance: | Superb | Great | Great | Great | Ok | ? | ? | Superb | ? | ? +Platform: Windows | VS2010 | Yes | Yes | ? | ? | ? | Yes | VS2010 | ? | ? +Platform: Linux | GCC282 | Yes | ? | Yes | Yes | ? | Yes | Yes | ? | ? +Platform: OS X | Xcode4 | ? | ? | ? | Yes | ? | Yes | Yes | ? | ? +Platform: Android | NDK10d | Yes | ? | ? | ? | ? | ? | ? | ? | ? +Platform: iOS | ? | ? | ? | ? | ? | ? | ? | ? | ? | ? +Engine: Unity | ? | ? | Yes | ? | ? | ? | ? | ? | ? | ? +Primary authors (github) | gwvo | gwvo | ev*/js*| rw | rw | evanw/ev* | kr | mik* | ch* | rw * ev = evolutional * js = jonsimantov * mik = mikkelfj * ch = chobie + * kr = krojew <br> diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index daa8ee1d..cecfb5a9 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -27,6 +27,7 @@ Please select your desired language for our quest: <input type="radio" name="language" value="go">Go</input> <input type="radio" name="language" value="python">Python</input> <input type="radio" name="language" value="javascript">JavaScript</input> + <input type="radio" name="language" value="typescript">TypeScript</input> <input type="radio" name="language" value="php">PHP</input> <input type="radio" name="language" value="c">C</input> </form> @@ -122,6 +123,9 @@ For your chosen language, please cross-reference with: <div class="language-javascript"> [samplebinary.js](https://github.com/google/flatbuffers/blob/master/samples/samplebinary.js) </div> +<div class="language-typescript"> +<em>none yet</em> +</div> <div class="language-php"> [SampleBinary.php](https://github.com/google/flatbuffers/blob/master/samples/SampleBinary.php) </div> @@ -284,7 +288,13 @@ Please be aware of the difference between `flatc` and `flatcc` tools. <div class="language-javascript"> ~~~{.sh} cd flatbuffers/sample - ./../flatc --javascript samples/monster.fbs + ./../flatc --js samples/monster.fbs +~~~ +</div> +<div class="language-typescript"> +~~~{.sh} + cd flatbuffers/sample + ./../flatc --ts samples/monster.fbs ~~~ </div> <div class="language-php"> @@ -372,6 +382,11 @@ The first step is to import/include the library, generated files, etc. <script src="monster_generated.js"></script> // Generated by `flatc`. ~~~ </div> +<div class="language-typescript"> + // note: import flabuffers with your desired import method + + import { MyGame } from './monster_generated'; +</div> <div class="language-php"> ~~~{.php} // It is recommended that your use PSR autoload when using FlatBuffers in PHP. @@ -454,6 +469,13 @@ which will grow automatically if needed: var builder = new flatbuffers.Builder(1024); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + // Create a `flatbuffer.Builder`, which will be used to create our + // monsters' FlatBuffers. + let builder = new flatbuffers.Builder(1024); +~~~ +</div> <div class="language-php"> ~~~{.php} // Create a `FlatBufferBuilder`, which will be used to create our @@ -566,6 +588,24 @@ our `orc` Monster, lets create some `Weapon`s: a `Sword` and an `Axe`. var axe = MyGame.Sample.Weapon.endWeapon(builder); ~~~ </div> +<div class="language-typescript"> +~~~{.js} + let weaponOne = builder.createString('Sword'); + let weaponTwo = builder.createString('Axe'); + + // Create the first `Weapon` ('Sword'). + MyGame.Sample.Weapon.startWeapon(builder); + MyGame.Sample.Weapon.addName(builder, weaponOne); + MyGame.Sample.Weapon.addDamage(builder, 3); + let sword = MyGame.Sample.Weapon.endWeapon(builder); + + // Create the second `Weapon` ('Axe'). + MyGame.Sample.Weapon.startWeapon(builder); + MyGame.Sample.Weapon.addName(builder, weaponTwo); + MyGame.Sample.Weapon.addDamage(builder, 5); + let axe = MyGame.Sample.Weapon.endWeapon(builder); +~~~ +</div> <div class="language-php"> ~~~{.php} // Create the `Weapon`s using the `createWeapon()` helper function. @@ -684,6 +724,17 @@ traversal. This is generally easy to do on any tree structures. var inv = MyGame.Sample.Monster.createInventoryVector(builder, treasure); ~~~ </div> +<div class="language-typescript"> +~~~{.js} + // Serialize a name for our monster, called 'Orc'. + let name = builder.createString('Orc'); + + // Create a `vector` representing the inventory of the Orc. Each number + // could correspond to an item that can be claimed after he is slain. + let treasure = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + let inv = MyGame.Sample.Monster.createInventoryVector(builder, treasure); +~~~ +</div> <div class="language-php"> ~~~{.php} // Serialize a name for our monster, called "Orc". @@ -787,6 +838,14 @@ offsets. var weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + // Create an array from the two `Weapon`s and pass it to the + // `createWeaponsVector()` method to create a FlatBuffer vector. + let weaps = [sword, axe]; + let weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps); +~~~ +</div> <div class="language-php"> ~~~{.php} // Create an array from the two `Weapon`s and pass it to the @@ -863,6 +922,14 @@ for the `path` field above: var path = builder.endVector(); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + MyGame.Sample.Monster.startPathVector(builder, 2); + MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0); + MyGame.Sample.Vec3.createVec3(builder, 4.0, 5.0, 6.0); + let path = builder.endVector(); +~~~ +</div> <div class="language-php"> ~~~{.php} \MyGame\Example\Monster::StartPathVector($builder, 2); @@ -977,6 +1044,23 @@ can serialize the monster itself: var orc = MyGame.Sample.Monster.endMonster(builder); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + // Create our monster by using `startMonster()` and `endMonster()`. + MyGame.Sample.Monster.startMonster(builder); + MyGame.Sample.Monster.addPos(builder, + MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0)); + MyGame.Sample.Monster.addHp(builder, 300); + MyGame.Sample.Monster.addColor(builder, MyGame.Sample.Color.Red) + MyGame.Sample.Monster.addName(builder, name); + MyGame.Sample.Monster.addInventory(builder, inv); + MyGame.Sample.Monster.addWeapons(builder, weapons); + MyGame.Sample.Monster.addEquippedType(builder, MyGame.Sample.Equipment.Weapon); + MyGame.Sample.Monster.addEquipped(builder, axe); + MyGame.Sample.Monster.addPath(builder, path); + let orc = MyGame.Sample.Monster.endMonster(builder); +~~~ +</div> <div class="language-php"> ~~~{.php} // Create our monster by using `StartMonster()` and `EndMonster()`. @@ -1122,6 +1206,12 @@ Here is a repetition these lines, to help highlight them more clearly: MyGame.Sample.Monster.addEquipped(builder, axe); // Union data ~~~ </div> +<div class="language-typescript"> + ~~~{.ts} + MyGame.Sample.Monster.addEquippedType(builder, MyGame.Sample.Equipment.Weapon); // Union type + MyGame.Sample.Monster.addEquipped(builder, axe); // Union data + ~~~ +</div> <div class="language-php"> ~~~{.php} \MyGame\Sample\Monster::AddEquippedType($builder, \MyGame\Sample\Equipment::Weapon); // Union type @@ -1180,6 +1270,13 @@ appropriate `finish` method. // orc);`. ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + // Call `finish()` to instruct the builder that this monster is complete. + builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, + // orc);`. +~~~ +</div> <div class="language-php"> ~~~{.php} // Call `finish()` to instruct the builder that this monster is complete. @@ -1246,6 +1343,12 @@ like so: var buf = builder.asUint8Array(); // Of type `Uint8Array`. ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + // This must be called after `finish()`. + let buf = builder.asUint8Array(); // Of type `Uint8Array`. +~~~ +</div> <div class="language-php"> ~~~{.php} // This must be called after `finish()`. @@ -1347,6 +1450,13 @@ before: <script src="monster_generated.js"></script> // Generated by `flatc`. ~~~ </div> +<div class="language-typescript"> +~~~{.js} + // note: import flabuffers with your desired import method + + import { MyGame } from './monster_generated'; +~~~ +</div> <div class="language-php"> ~~~{.php} // It is recommended that your use PSR autoload when using FlatBuffers in PHP. @@ -1451,6 +1561,15 @@ won't work** var monster = MyGame.Sample.Monster.getRootAsMonster(buf); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let bytes = /* the data you just read, in an object of type "Uint8Array" */ + let buf = new flatbuffers.ByteBuffer(bytes); + + // Get an accessor to the root object inside the buffer. + let monster = MyGame.Sample.Monster.getRootAsMonster(buf); +~~~ +</div> <div class="language-php"> ~~~{.php} $bytes = /* the data you just read, in a string */ @@ -1518,6 +1637,13 @@ accessors for all non-`deprecated` fields. For example: var name = $monster.name(); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let hp = $monster.hp(); + let mana = $monster.mana(); + let name = $monster.name(); +~~~ +</div> <div class="language-php"> ~~~{.php} $hp = $monster->getHp(); @@ -1593,6 +1719,14 @@ To access sub-objects, in the case of our `pos`, which is a `Vec3`: var z = pos.z(); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let pos = monster.pos(); + let x = pos.x(); + let y = pos.y(); + let z = pos.z(); +~~~ +</div> <div class="language-php"> ~~~{.php} $pos = $monster->getPos(); @@ -1655,6 +1789,12 @@ FlatBuffers `vector`. var thirdItem = monster.inventory(2); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let invLength = monster.inventoryLength(); + let thirdItem = monster.inventory(2); +~~~ +</div> <div class="language-php"> ~~~{.php} $inv_len = $monster->getInventoryLength(); @@ -1720,6 +1860,13 @@ except your need to handle the result as a FlatBuffer `table`: var secondWeaponDamage = monster.weapons(1).damage(); ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let weaponsLength = monster.weaponsLength(); + let secondWeaponName = monster.weapons(1).name(); + let secondWeaponDamage = monster.weapons(1).damage(); +~~~ +</div> <div class="language-php"> ~~~{.php} $weapons_len = $monster->getWeaponsLength(); @@ -1827,6 +1974,16 @@ We can access the type to dynamically cast the data as needed (since the } ~~~ </div> +<div class="language-typescript"> +~~~{.ts} + let unionType = monster.equippedType(); + + if (unionType == MyGame.Sample.Equipment.Weapon) { + let weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe' + let weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5 + } +~~~ +</div> <div class="language-php"> ~~~{.php} $union_type = $monster->getEquippedType(); @@ -1905,7 +2062,12 @@ mutators like so: </div> <div class="language-javascript"> ~~~{.js} - <API for mutating FlatBuffers is not yet support in JavaScript.> + <API for mutating FlatBuffers is not yet supported in JavaScript.> +~~~ +</div> +<div class="language-typescript"> +~~~{.ts} + <API for mutating FlatBuffers is not yet supported in TypeScript.> ~~~ </div> <div class="language-php"> @@ -2019,6 +2181,9 @@ For your chosen language, see: <div class="language-javascript"> [Use in JavaScript](@ref flatbuffers_guide_use_javascript) </div> +<div class="language-typescript"> +[Use in TypeScript](@ref flatbuffers_guide_use_typescript) +</div> <div class="language-php"> [Use in PHP](@ref flatbuffers_guide_use_php) </div> diff --git a/docs/source/TypeScriptUsage.md b/docs/source/TypeScriptUsage.md new file mode 100644 index 00000000..b773fdfd --- /dev/null +++ b/docs/source/TypeScriptUsage.md @@ -0,0 +1,66 @@ +Use in TypeScript {#flatbuffers_guide_use_typescript} +================= + +## Before you get started + +Before diving into the FlatBuffers usage in TypeScript, it should be noted that +the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to +general FlatBuffers usage in all of the supported languages +(including TypeScript). This page is specifically designed to cover the nuances +of FlatBuffers usage in TypeScript. + +You should also have read the [Building](@ref flatbuffers_guide_building) +documentation to build `flatc` and should be familiar with +[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and +[Writing a schema](@ref flatbuffers_guide_writing_schema). + +## FlatBuffers TypeScript library code location + +The code for the FlatBuffers TypeScript library can be found at +`flatbuffers/js` with typings available at @types/flatubffers. + +## Testing the FlatBuffers TypeScript library + +To run the tests, use the [TypeScriptTest.sh](https://github.com/google/ +flatbuffers/blob/master/tests/TypeScriptTest.sh) shell script. + +*Note: The TypeScript test file requires [Node.js](https://nodejs.org/en/).* + +## Using the FlatBuffers TypeScript libary + +*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth +example of how to use FlatBuffers in TypeScript.* + +FlatBuffers supports both reading and writing FlatBuffers in TypeScript. + +To use FlatBuffers in your own code, first generate TypeScript classes from your +schema with the `--ts` option to `flatc`. Then you can include both FlatBuffers +and the generated code to read or write a FlatBuffer. + +For example, here is how you would read a FlatBuffer binary file in TypeScript: +First, include the library and generated code. Then read the file into an +`Uint8Array`. Make a `flatbuffers.ByteBuffer` out of the `Uint8Array`, and pass +the ByteBuffer to the `getRootAsMonster` function. + +~~~{.ts} + // note: import flabuffers with your desired import method + + import { MyGame } from './monster_generated'; + + let data = new Uint8Array(fs.readFileSync('monster.dat')); + let buf = new flatbuffers.ByteBuffer(data); + + let monster = MyGame.Example.Monster.getRootAsMonster(buf); +~~~ + +Now you can access values like this: + +~~~{.ts} + let hp = monster.hp(); + let pos = monster.pos(); +~~~ + +## Text parsing FlatBuffers in TypeScript + +There currently is no support for parsing text (Schema's and JSON) directly +from TypeScript. diff --git a/docs/source/groups b/docs/source/groups index e0d97a7a..c3aea18e 100644 --- a/docs/source/groups +++ b/docs/source/groups @@ -13,6 +13,9 @@ /// @defgroup flatbuffers_javascript_api JavaScript API /// @brief FlatBuffers API for JavaScript +/// @defgroup flatbuffers_typescript_api TypeScript API +/// @brief FlatBuffers API for TypeScript + /// @defgroup flatbuffers_php_api PHP API /// @brief FlatBuffers API for PHP |