BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-07-01 17:33:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

TypeScript/JavaScript docs improvements (#5984)

Browse Source 
* use correct language formatter for TypeScript examples

* fixes typo in JS/TS copied from PHP (apparently)

the variables are not named with a prefixed `$`

* fixes bizarre line breaks in markdown examples

* fixes snake case typo to fit JS/TS conventions

* makes example of Uint8Array usage explicit

* removes random extra lines between language blocks

* adds simple example for writing to file in node

* typo: flabuffers => flatbuffers

* adds (previously missing) code blocks to TypeScript code block

* adds context about where `monster_generated` comes from

to the uninitiated, a bit of help like this is welcome
This commit is contained in:
Dimitri Mitropoulos
2020-06-18 13:23:32 -04:00
committed by GitHub
parent 2e57d80b13
commit 9abb2ec2cc
1 changed files with 47 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/source/Tutorial.md
View File

@@ -281,7 +281,6 @@ See [flatcc build instructions](https://github.com/dvidelabs/flatcc#building).
Please be aware of the difference between `flatc` and `flatcc` tools. Please be aware of the difference between `flatc` and `flatcc` tools.
<br> <br>
</div> </div>
<div class="language-cpp"> <div class="language-cpp">
~~~{.sh} ~~~{.sh}
cd flatbuffers/samples cd flatbuffers/samples
@@ -453,9 +452,11 @@ The first step is to import/include the library, generated files, etc.
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.ts}
// note: import flatbuffers with your desired import method // note: import flatbuffers with your desired import method
import { MyGame } from './monster_generated'; import { MyGame } from './monster_generated';
~~~
</div> </div>
<div class="language-php"> <div class="language-php">
~~~{.php} ~~~{.php}
@@ -534,7 +535,6 @@ The first step is to import/include the library, generated files, etc.
Weapon, WeaponArgs}; Weapon, WeaponArgs};
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
/** /**
@@ -771,7 +771,7 @@ our `orc` Monster, let's create some `Weapon`s: a `Sword` and an `Axe`.
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.js} ~~~{.ts}
let weaponOne = builder.createString('Sword'); let weaponOne = builder.createString('Sword');
let weaponTwo = builder.createString('Axe'); let weaponTwo = builder.createString('Axe');
@@ -910,7 +910,6 @@ our `orc` Monster, let's create some `Weapon`s: a `Sword` and an `Axe`.
}); });
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let weapon1Name = builder.create(string: "Sword") let weapon1Name = builder.create(string: "Sword")
@@ -1032,7 +1031,7 @@ traversal. This is generally easy to do on any tree structures.
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.js} ~~~{.ts}
// Serialize a name for our monster, called 'Orc'. // Serialize a name for our monster, called 'Orc'.
let name = builder.createString('Orc'); let name = builder.createString('Orc');
@@ -1420,7 +1419,7 @@ for the `path` field above:
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
// //
let points = builder.createVector(structs: [MyGame.Sample.createVec3(x: 1, y: 2, z: 3), let points = builder.createVector(structs: [MyGame.Sample.createVec3(x: 1, y: 2, z: 3),
MyGame.Sample.createVec3(x: 4, y: 5, z: 6)], MyGame.Sample.createVec3(x: 4, y: 5, z: 6)],
type: Vec3.self) type: Vec3.self)
~~~ ~~~
@@ -1701,7 +1700,7 @@ can serialize the monster itself:
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let orc = Monster.createMonster(builder, let orc = Monster.createMonster(builder,
offsetOfPos: pos, offsetOfPos: pos,
hp: 300, hp: 300,
offsetOfName: name, offsetOfName: name,
@@ -1776,7 +1775,6 @@ a bit more flexibility.
ns(Monster_end_as_root(B)); ns(Monster_end_as_root(B));
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let start = Monster.startMonster(builder) let start = Monster.startMonster(builder)
@@ -1913,8 +1911,7 @@ appropriate `finish` method.
// Call `Finish()` to instruct the builder that this monster is complete. // Call `Finish()` to instruct the builder that this monster is complete.
// Note: Regardless of how you created the `orc`, you still need to call // Note: Regardless of how you created the `orc`, you still need to call
// `Finish()` on the `FlatBufferBuilder`. // `Finish()` on the `FlatBufferBuilder`.
builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder, builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder, orc);`.
// orc);`.
~~~ ~~~
</div> </div>
<div class="language-java"> <div class="language-java">
@@ -1950,22 +1947,19 @@ appropriate `finish` method.
<div class="language-javascript"> <div class="language-javascript">
~~~{.js} ~~~{.js}
// Call `finish()` to instruct the builder that this monster is complete. // Call `finish()` to instruct the builder that this monster is complete.
builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, orc);`.
// orc);`.
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.ts} ~~~{.ts}
// Call `finish()` to instruct the builder that this monster is complete. // Call `finish()` to instruct the builder that this monster is complete.
builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, orc);`.
// orc);`.
~~~ ~~~
</div> </div>
<div class="language-php"> <div class="language-php">
~~~{.php} ~~~{.php}
// Call `finish()` to instruct the builder that this monster is complete. // Call `finish()` to instruct the builder that this monster is complete.
$builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer( $builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer($builder, $orc);`.
// $builder, $orc);`.
~~~ ~~~
</div> </div>
<div class="language-c"> <div class="language-c">
@@ -2130,7 +2124,6 @@ like so:
let buf = builder.finished_data(); // Of type `&[u8]` let buf = builder.finished_data(); // Of type `&[u8]`
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
// This must be called after `finish()`. // This must be called after `finish()`.
@@ -2146,6 +2139,19 @@ Now you can write the bytes to a file or send them over the network.
If you transfer a FlatBuffer in text mode, the buffer will be corrupted, If you transfer a FlatBuffer in text mode, the buffer will be corrupted,
which will lead to hard to find problems when you read the buffer. which will lead to hard to find problems when you read the buffer.
<div class="language-javascript">
For example, in Node you can simply do:
~~~{.js}
writeFileSync('monster.bin', buf, 'binary');
~~~
</div>
<div class="language-typescript">
For example, in Node you can simply do:
~~~{.ts}
writeFileSync('monster.bin', buf, 'binary');
~~~
</div>
#### Reading Orc FlatBuffers #### Reading Orc FlatBuffers
Now that we have successfully created an `Orc` FlatBuffer, the monster data can Now that we have successfully created an `Orc` FlatBuffer, the monster data can
@@ -2217,9 +2223,10 @@ before:
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.js} ~~~{.ts}
// note: import flabuffers with your desired import method // note: import flatbuffers with your desired import method
// note: the `./monster_generated.ts` file was previously generated by `flatc` above using the `monster.fbs` schema
import { MyGame } from './monster_generated'; import { MyGame } from './monster_generated';
~~~ ~~~
</div> </div>
@@ -2370,7 +2377,11 @@ won't work.**
</div> </div>
<div class="language-javascript"> <div class="language-javascript">
~~~{.js} ~~~{.js}
var bytes = /* the data you just read, in an object of type "Uint8Array" */ // the data you just read, as a `Uint8Array`
// Note that the example here uses `readFileSync` from the built-in `fs` module,
// but other methods for accessing the file contents will also work.
var bytes = new Uint8Array(readFileSync('./monsterdata.bin'));
var buf = new flatbuffers.ByteBuffer(bytes); var buf = new flatbuffers.ByteBuffer(bytes);
// Get an accessor to the root object inside the buffer. // Get an accessor to the root object inside the buffer.
@@ -2379,7 +2390,11 @@ won't work.**
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.ts} ~~~{.ts}
let bytes = /* the data you just read, in an object of type "Uint8Array" */ // the data you just read, as a `Uint8Array`.
// Note that the example here uses `readFileSync` from the built-in `fs` module,
// but other methods for accessing the file contents will also work.
let bytes = new Uint8Array(readFileSync('./monsterdata.bin'));
let buf = new flatbuffers.ByteBuffer(bytes); let buf = new flatbuffers.ByteBuffer(bytes);
// Get an accessor to the root object inside the buffer. // Get an accessor to the root object inside the buffer.
@@ -2439,7 +2454,6 @@ myGame.Monster monster = new myGame.Monster(data);
let monster = get_root_as_monster(buf); let monster = get_root_as_monster(buf);
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
// create a ByteBuffer(:) from an [UInt8] or Data() // create a ByteBuffer(:) from an [UInt8] or Data()
@@ -2499,16 +2513,16 @@ accessors for all non-`deprecated` fields. For example:
</div> </div>
<div class="language-javascript"> <div class="language-javascript">
~~~{.js} ~~~{.js}
var hp = $monster.hp(); var hp = monster.hp();
var mana = $monster.mana(); var mana = monster.mana();
var name = $monster.name(); var name = monster.name();
~~~ ~~~
</div> </div>
<div class="language-typescript"> <div class="language-typescript">
~~~{.ts} ~~~{.ts}
let hp = $monster.hp(); let hp = monster.hp();
let mana = $monster.mana(); let mana = monster.mana();
let name = $monster.name(); let name = monster.name();
~~~ ~~~
</div> </div>
<div class="language-php"> <div class="language-php">
@@ -2556,7 +2570,6 @@ accessors for all non-`deprecated` fields. For example:
let name = monster.name(); let name = monster.name();
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let hp = monster.hp let hp = monster.hp
@@ -2689,7 +2702,6 @@ To access sub-objects, in the case of our `pos`, which is a `Vec3`:
let z = pos.z(); let z = pos.z();
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let pos = monster.pos let pos = monster.pos
@@ -2798,7 +2810,6 @@ FlatBuffers `vector`.
let third_item = inv[2]; let third_item = inv[2];
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
// Get a the count of objects in the vector // Get a the count of objects in the vector
@@ -3034,8 +3045,8 @@ We can access the type to dynamically cast the data as needed (since the
var unionType = monster.equippedType(); var unionType = monster.equippedType();
if (unionType == MyGame.Sample.Equipment.Weapon) { if (unionType == MyGame.Sample.Equipment.Weapon) {
var weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe' var weaponName = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe'
var weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5 var weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
} }
~~~ ~~~
</div> </div>
@@ -3044,8 +3055,8 @@ We can access the type to dynamically cast the data as needed (since the
let unionType = monster.equippedType(); let unionType = monster.equippedType();
if (unionType == MyGame.Sample.Equipment.Weapon) { if (unionType == MyGame.Sample.Equipment.Weapon) {
let weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe' let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe'
let weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5 let weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
} }
~~~ ~~~
</div> </div>
@@ -3121,7 +3132,6 @@ We can access the type to dynamically cast the data as needed (since the
let weapon_damage = equipped.damage(); let weapon_damage = equipped.damage();
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
// Get and check if the monster has an equipped item // Get and check if the monster has an equipped item
@@ -3235,7 +3245,6 @@ mutators like so:
<API for mutating FlatBuffers is not yet available in Rust.> <API for mutating FlatBuffers is not yet available in Rust.>
~~~ ~~~
</div> </div>
<div class="language-swift"> <div class="language-swift">
~~~{.swift} ~~~{.swift}
let monster = Monster.getRootAsMonster(bb: ByteBuffer(bytes: buf)) let monster = Monster.getRootAsMonster(bb: ByteBuffer(bytes: buf))
@@ -3316,7 +3325,7 @@ You can run this file through the `flatc` compiler with the `-b` flag and
our `monster.fbs` schema to produce a FlatBuffer binary file. our `monster.fbs` schema to produce a FlatBuffer binary file.
~~~{.sh} ~~~{.sh}
./../flatc -b monster.fbs monsterdata.json ./../flatc --binary monster.fbs monsterdata.json
~~~ ~~~
The output of this will be a file `monsterdata.bin`, which will contain the The output of this will be a file `monsterdata.bin`, which will contain the