diff options
| author | rw <me@rwinslow.com> | 2015-05-15 12:23:10 -0700 |
|---|---|---|
| committer | rw <me@rwinslow.com> | 2015-05-15 12:23:10 -0700 |
| commit | 339376ba670c1675aa63c9c80088264bf584f7d1 (patch) | |
| tree | ae3fcec483c4e9cbc64cc45fd80784e718724b28 /docs | |
| parent | 7a1b77322b07804bf32cbdb34b6cba25b552e825 (diff) | |
| download | flatbuffers-339376ba670c1675aa63c9c80088264bf584f7d1.tar.gz | |
Regenerate Doxygen docs to add Python usage page.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/html/md__java_usage.html | 12 | ||||
| -rw-r--r-- | docs/html/md__python_usage.html | 112 | ||||
| -rw-r--r-- | docs/html/navtree.js | 1 | ||||
| -rw-r--r-- | docs/html/navtreeindex0.js | 9 | ||||
| -rw-r--r-- | docs/html/pages.html | 9 |
5 files changed, 133 insertions, 10 deletions
diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html index fa61ef0c..c67f5692 100644 --- a/docs/html/md__java_usage.html +++ b/docs/html/md__java_usage.html @@ -54,7 +54,7 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');}); </div><!--header--> <div class="contents"> <div class="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. Generate code for Java with the <code>-j</code> option to <code>flatc</code>, or for C# with <code>-n</code> (think .Net).</p> -<p>Note that this document is from the perspective of Java. Code for both languages is generated in the same way, with only very subtle differences, for example any <code>camelCase</code> Java call will be <code>CamelCase</code> in C#.</p> +<p>Note that this document is from the perspective of Java. Code for both languages is generated in the same way, with only minor differences. These differences are <a href="#differences-in-c-sharp">explained in a section below</a>.</p> <p>See <code>javaTest.java</code> for an example. Essentially, you read a FlatBuffer binary file into a <code>byte[]</code>, which you then turn into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p> <div class="fragment"><div class="line">ByteBuffer bb = ByteBuffer.wrap(data);</div> <div class="line">Monster monster = Monster.getRootAsMonster(bb);</div> @@ -100,7 +100,15 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');}); <p>To finish the buffer, call:</p> <div class="fragment"><div class="line">Monster.finishMonsterBuffer(fbb, mon);</div> </div><!-- fragment --><p>The buffer is now ready to be transmitted. It is contained in the <code>ByteBuffer</code> which you can obtain from <code>fbb.dataBuffer()</code>. Importantly, the valid data does not start from offset 0 in this buffer, but from <code>fbb.dataBuffer().position()</code> (this is because the data was built backwards in memory). It ends at <code>fbb.capacity()</code>.</p> -<h2>Text Parsing</h2> +<h2>Differences in C-sharp</h2> +<p>C# code works almost identically to Java, with only a few minor differences. You can see an example of C# code in <code>tests/FlatBuffers.Test/FlatBuffersExampleTests.cs</code>.</p> +<p>First of all, naming follows standard C# style with <code>PascalCasing</code> identifiers, e.g. <code>GetRootAsMyRootType</code>. Also, values (except vectors and unions) are available as properties instead of parameterless accessor methods as in Java. The performance-enhancing methods to which you can pass an already created object are prefixed with <code>Get</code>, e.g.:</p> +<div class="fragment"><div class="line"><span class="comment">// property</span></div> +<div class="line">var pos = monster.Pos;</div> +<div class="line"><span class="comment">// method filling a preconstructed object</span></div> +<div class="line">var preconstructedPos = <span class="keyword">new</span> Vec3();</div> +<div class="line">monster.GetPos(preconstructedPos);</div> +</div><!-- fragment --><h2>Text parsing</h2> <p>There currently is no support for parsing text (Schema's and JSON) directly from Java, though you could use the C++ parser through JNI. Please see the C++ documentation for more on text parsing. </p> </div></div><!-- contents --> </div><!-- doc-content --> diff --git a/docs/html/md__python_usage.html b/docs/html/md__python_usage.html new file mode 100644 index 00000000..63eae508 --- /dev/null +++ b/docs/html/md__python_usage.html @@ -0,0 +1,112 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.8.7"/> +<title>FlatBuffers: Use in Python</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> + $(document).ready(initResizable); + $(window).load(resizeHeight); +</script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td style="padding-left: 0.5em;"> + <div id="projectname">FlatBuffers + </div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.7 --> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +$(document).ready(function(){initNavTree('md__python_usage.html','');}); +</script> +<div id="doc-content"> +<div class="header"> + <div class="headertitle"> +<div class="title">Use in Python </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p>There's experimental support for reading FlatBuffers in Python. Generate code for Python with the <code>-p</code> option to <code>flatc</code>.</p> +<p>See <code>py_test.py</code> for an example. You import the generated code, read a FlatBuffer binary file into a <code>bytearray</code>, which you pass to the <code>GetRootAsMonster</code> function:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> import MyGame.Example <span class="keyword">as</span> example</div> +<div class="line"><a name="l00002"></a><span class="lineno"> 2</span> <span class="keyword">import</span> flatbuffers</div> +<div class="line"><a name="l00003"></a><span class="lineno"> 3</span> </div> +<div class="line"><a name="l00004"></a><span class="lineno"> 4</span> buf = open(<span class="stringliteral">'monster.dat'</span>, <span class="stringliteral">'rb'</span>).read()</div> +<div class="line"><a name="l00005"></a><span class="lineno"> 5</span> buf = bytearray(buf)</div> +<div class="line"><a name="l00006"></a><span class="lineno"> 6</span> monster = example.GetRootAsMonster(buf, 0)</div> +</div><!-- fragment --><p>Now you can access values like this:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> hp = monster.Hp()</div> +<div class="line"><a name="l00002"></a><span class="lineno"> 2</span> pos = monster.Pos()</div> +</div><!-- fragment --><p>To access vectors you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by <code>Length</code> let's you know the number of elements you can access:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> <span class="keywordflow">for</span> i <span class="keywordflow">in</span> xrange(monster.InventoryLength()):</div> +<div class="line"><a name="l00002"></a><span class="lineno"> 2</span>  monster.Inventory(i) <span class="comment"># do something here</span></div> +</div><!-- fragment --><p>You can also construct these buffers in Python using the functions found in the generated code, and the FlatBufferBuilder class:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> builder = flatbuffers.NewBuilder(0)</div> +</div><!-- fragment --><p>Create strings:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> s = builder.CreateString(<span class="stringliteral">"MyMonster"</span>)</div> +</div><!-- fragment --><p>Create a table with a struct contained therein:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> example.MonsterStart(builder)</div> +<div class="line"><a name="l00002"></a><span class="lineno"> 2</span> example.MonsterAddPos(builder, example.CreateVec3(builder, 1.0, 2.0, 3.0, 3.0, 4, 5, 6))</div> +<div class="line"><a name="l00003"></a><span class="lineno"> 3</span> example.MonsterAddHp(builder, 80)</div> +<div class="line"><a name="l00004"></a><span class="lineno"> 4</span> example.MonsterAddName(builder, str)</div> +<div class="line"><a name="l00005"></a><span class="lineno"> 5</span> example.MonsterAddInventory(builder, inv)</div> +<div class="line"><a name="l00006"></a><span class="lineno"> 6</span> example.MonsterAddTest_Type(builder, 1)</div> +<div class="line"><a name="l00007"></a><span class="lineno"> 7</span> example.MonsterAddTest(builder, mon2)</div> +<div class="line"><a name="l00008"></a><span class="lineno"> 8</span> example.MonsterAddTest4(builder, test4s)</div> +<div class="line"><a name="l00009"></a><span class="lineno"> 9</span> mon = example.MonsterEnd(builder)</div> +<div class="line"><a name="l00010"></a><span class="lineno"> 10</span> </div> +<div class="line"><a name="l00011"></a><span class="lineno"> 11</span> final_flatbuffer = bulder.Output()</div> +</div><!-- fragment --><p>Unlike C++, Python does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the <code>Vec3</code> is an inline component of <code>Monster</code>, it has to be created right where it is added, whereas the name and the inventory are not inline, and <b>must</b> be created outside of the table creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field <code>a</code> and a nested struct field <code>b</code> (which has fields <code>c</code> and <code>d</code>), then the arguments will be <code>a</code>, <code>c</code> and <code>d</code>.</p> +<p>Vectors also use this start/end pattern to allow vectors of both scalar types and structs:</p> +<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> example.MonsterStartInventoryVector(builder, 5)</div> +<div class="line"><a name="l00002"></a><span class="lineno"> 2</span> i = 4</div> +<div class="line"><a name="l00003"></a><span class="lineno"> 3</span> <span class="keywordflow">while</span> i >= 0:</div> +<div class="line"><a name="l00004"></a><span class="lineno"> 4</span>  builder.PrependByte(byte(i))</div> +<div class="line"><a name="l00005"></a><span class="lineno"> 5</span>  i -= 1</div> +<div class="line"><a name="l00006"></a><span class="lineno"> 6</span> </div> +<div class="line"><a name="l00007"></a><span class="lineno"> 7</span> inv = builder.EndVector(5)</div> +</div><!-- fragment --><p>The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front. Use the correct <code>Prepend</code> call for the type, or <code>PrependUOffsetT</code> for offsets. You then pass <code>inv</code> to the corresponding <code>Add</code> call when you construct the table containing it afterwards.</p> +<p>There are <code>Prepend</code> functions for all the scalar types. You use <code>PrependUOffset</code> for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate <code>create</code> function in-line, as shown above in the <code>Monster</code> example.</p> +<p>Once you're done constructing a buffer, you call <code>Finish</code> with the root object offset (<code>mon</code> in the example above). Your data now resides in Builder.Bytes. Important to note is that the real data starts at the index indicated by Head(), for Offset() bytes (this is because the buffer is constructed backwards). If you wanted to read the buffer right after creating it (using <code>GetRootAsMonster</code> above), the second argument, instead of <code>0</code> would thus also be <code>Head()</code>.</p> +<h2>Text Parsing</h2> +<p>There currently is no support for parsing text (Schema's and JSON) directly from Python, though you could use the C++ parser through SWIG or ctypes. Please see the C++ documentation for more on text parsing. </p> +</div></div><!-- contents --> +</div><!-- doc-content --> +<!-- Google Analytics --> +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-49880327-7', 'auto'); + ga('send', 'pageview'); +</script> +</body> +</html> diff --git a/docs/html/navtree.js b/docs/html/navtree.js index 608af687..58cf1e6c 100644 --- a/docs/html/navtree.js +++ b/docs/html/navtree.js @@ -7,6 +7,7 @@ var NAVTREE = [ "Use in C++", "md__cpp_usage.html", null ], [ "Use in Go", "md__go_usage.html", null ], [ "Use in Java/C-sharp", "md__java_usage.html", null ], + [ "Use in Python", "md__python_usage.html", null ], [ "Benchmarks", "md__benchmarks.html", null ], [ "FlatBuffers white paper", "md__white_paper.html", null ], [ "FlatBuffer Internals", "md__internals.html", null ], diff --git a/docs/html/navtreeindex0.js b/docs/html/navtreeindex0.js index 7dda4761..92e8403c 100644 --- a/docs/html/navtreeindex0.js +++ b/docs/html/navtreeindex0.js @@ -1,15 +1,16 @@ var NAVTREEINDEX0 = { "index.html":[], -"md__benchmarks.html":[6], +"md__benchmarks.html":[7], "md__building.html":[0], "md__compiler.html":[1], "md__cpp_usage.html":[3], "md__go_usage.html":[4], -"md__grammar.html":[9], -"md__internals.html":[8], +"md__grammar.html":[10], +"md__internals.html":[9], "md__java_usage.html":[5], +"md__python_usage.html":[6], "md__schemas.html":[2], -"md__white_paper.html":[7], +"md__white_paper.html":[8], "pages.html":[] }; diff --git a/docs/html/pages.html b/docs/html/pages.html index 4b2b9928..48122d92 100644 --- a/docs/html/pages.html +++ b/docs/html/pages.html @@ -61,10 +61,11 @@ $(document).ready(function(){initNavTree('pages.html','');}); <tr id="row_3_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__cpp_usage.html" target="_self">Use in C++</a></td><td class="desc"></td></tr> <tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__go_usage.html" target="_self">Use in Go</a></td><td class="desc"></td></tr> <tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__java_usage.html" target="_self">Use in Java/C-sharp</a></td><td class="desc"></td></tr> -<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr> -<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr> -<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr> -<tr id="row_9_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__grammar.html" target="_self">Formal Grammar of the schema language</a></td><td class="desc"></td></tr> +<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__python_usage.html" target="_self">Use in Python</a></td><td class="desc"></td></tr> +<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr> +<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr> +<tr id="row_9_"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr> +<tr id="row_10_" class="even"><td class="entry"><span style="width:16px;display:inline-block;"> </span><a class="el" href="md__grammar.html" target="_self">Formal Grammar of the schema language</a></td><td class="desc"></td></tr> </table> </div><!-- directory --> </div><!-- contents --> |