BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-04 20:48:59 +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.
<br>
</div>
<div class="language-cpp">
~~~{.sh}
cd flatbuffers/samples
@@ -453,9 +452,11 @@ The first step is to import/include the library, generated files, etc.
~~~
</div>
<div class="language-typescript">
~~~{.ts}
// note: import flatbuffers with your desired import method
import { MyGame } from './monster_generated';
~~~
</div>
<div class="language-php">
~~~{.php}
@@ -534,7 +535,6 @@ The first step is to import/include the library, generated files, etc.
Weapon, WeaponArgs};
~~~
</div>
<div class="language-swift">
~~~{.swift}
/**
@@ -771,7 +771,7 @@ our `orc` Monster, let's create some `Weapon`s: a `Sword` and an `Axe`.
~~~
</div>
<div class="language-typescript">
~~~{.js}
~~~{.ts}
let weaponOne = builder.createString('Sword');
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 class="language-swift">
~~~{.swift}
let weapon1Name = builder.create(string: "Sword")
@@ -1032,7 +1031,7 @@ traversal. This is generally easy to do on any tree structures.
~~~
</div>
<div class="language-typescript">
~~~{.js}
~~~{.ts}
// Serialize a name for our monster, called 'Orc'.
let name = builder.createString('Orc');
@@ -1420,7 +1419,7 @@ for the `path` field above:
<div class="language-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)],
type: Vec3.self)
~~~
@@ -1701,7 +1700,7 @@ can serialize the monster itself:
</div>
<div class="language-swift">
~~~{.swift}
let orc = Monster.createMonster(builder,
let orc = Monster.createMonster(builder,
offsetOfPos: pos,
hp: 300,
offsetOfName: name,
@@ -1776,7 +1775,6 @@ a bit more flexibility.
ns(Monster_end_as_root(B));
~~~
</div>
<div class="language-swift">
~~~{.swift}
let start = Monster.startMonster(builder)
@@ -1913,8 +1911,7 @@ appropriate `finish` method.
// Call `Finish()` to instruct the builder that this monster is complete.
// Note: Regardless of how you created the `orc`, you still need to call
// `Finish()` on the `FlatBufferBuilder`.
builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder,
// orc);`.
builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder, orc);`.
~~~
</div>
<div class="language-java">
@@ -1950,22 +1947,19 @@ appropriate `finish` method.
<div class="language-javascript">
~~~{.js}
// Call `finish()` to instruct the builder that this monster is complete.
builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder,
// orc);`.
builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, 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);`.
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.
$builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer(
// $builder, $orc);`.
$builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer($builder, $orc);`.
~~~
</div>
<div class="language-c">
@@ -2130,7 +2124,6 @@ like so:
let buf = builder.finished_data(); // Of type `&[u8]`
~~~
</div>
<div class="language-swift">
~~~{.swift}
// 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,
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
Now that we have successfully created an `Orc` FlatBuffer, the monster data can
@@ -2217,9 +2223,10 @@ before:
~~~
</div>
<div class="language-typescript">
~~~{.js}
// note: import flabuffers with your desired import method
~~~{.ts}
// 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';
~~~
</div>
@@ -2370,7 +2377,11 @@ won't work.**
</div>
<div class="language-javascript">
~~~{.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);
// Get an accessor to the root object inside the buffer.
@@ -2379,7 +2390,11 @@ won't work.**
</div>
<div class="language-typescript">
~~~{.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);
// 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);
~~~
</div>
<div class="language-swift">
~~~{.swift}
// create a ByteBuffer(:) from an [UInt8] or Data()
@@ -2499,16 +2513,16 @@ accessors for all non-`deprecated` fields. For example:
</div>
<div class="language-javascript">
~~~{.js}
var hp = $monster.hp();
var mana = $monster.mana();
var name = $monster.name();
var hp = monster.hp();
var mana = monster.mana();
var name = monster.name();
~~~
</div>
<div class="language-typescript">
~~~{.ts}
let hp = $monster.hp();
let mana = $monster.mana();
let name = $monster.name();
let hp = monster.hp();
let mana = monster.mana();
let name = monster.name();
~~~
</div>
<div class="language-php">
@@ -2556,7 +2570,6 @@ accessors for all non-`deprecated` fields. For example:
let name = monster.name();
~~~
</div>
<div class="language-swift">
~~~{.swift}
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();
~~~
</div>
<div class="language-swift">
~~~{.swift}
let pos = monster.pos
@@ -2798,7 +2810,6 @@ FlatBuffers `vector`.
let third_item = inv[2];
~~~
</div>
<div class="language-swift">
~~~{.swift}
// 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();
if (unionType == MyGame.Sample.Equipment.Weapon) {
var weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe'
var weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
var weaponName = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe'
var weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
}
~~~
</div>
@@ -3044,8 +3055,8 @@ We can access the type to dynamically cast the data as needed (since the
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
let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name(); // 'Axe'
let weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
}
~~~
</div>
@@ -3121,7 +3132,6 @@ We can access the type to dynamically cast the data as needed (since the
let weapon_damage = equipped.damage();
~~~
</div>
<div class="language-swift">
~~~{.swift}
// 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.>
~~~
</div>
<div class="language-swift">
~~~{.swift}
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.
~~~{.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