Merge pull request kaitai-io#285 from kaitai-io/code-snippets-syntax-…

…highlighting

Syntax highlighting of language-specific usage code snippets

_build/build-html

@@ -17,7 +17,7 @@ Pygments.start 'pygments/'
 
 class FormatPagesGenerator
   LANGS = {
-    'index' => {name: 'Overview'},
+    'index' => {name: 'Overview', lexer: 'yaml'},
 
     'cpp_stl' => {name: 'C++/STL', lexer: 'cpp'},
     'csharp' => {name: 'C#', ext: 'cs'},
@@ -62,6 +62,10 @@ class FormatPagesGenerator
     'WTFPL',
   ])
 
+  def code(lang, src)
+    Pygments.highlight(src, :lexer => LANGS[lang][:lexer] || lang)
+  end
+
   def initialize(ksy_dir, target_dir, html_dir)
     @ksy_dir = File.realpath(ksy_dir)
     @target_dir = File.realpath(target_dir)
@@ -145,7 +149,6 @@ class FormatPagesGenerator
         warn "#{file_id}: no license"
       end
 
-      yaml_html = Pygments.highlight(yaml_str, :lexer => 'yaml')
       format_name = get_format_name(meta)
       cur_lang = 'index'
       page_title = format_name + " format spec for Kaitai Struct"
@@ -172,7 +175,6 @@ class FormatPagesGenerator
         begin
           puts "    * reading source file #{out_dir}/#{path}"
           src = File.read("#{out_dir}/#{path}")
-          src = Pygments.highlight(src, :lexer => LANGS[cur_lang][:lexer] || cur_lang)
         rescue Errno::ENOENT
           puts "      ... not found!"
           src = nil

_build/format_base.html.erb

@@ -11,6 +11,6 @@
     <div class="container">
         <h2>Format specification in Kaitai Struct YAML</h2>
 
-        <%= yaml_html %>
+        <%= code cur_lang, yaml_str %>
     </div>
 </section>

_build/format_lang.html.erb

@@ -31,7 +31,7 @@
         </div>
 
         <div class="row">
-            <%= src[:src] %>
+            <%= code cur_lang, src[:src] %>
 
         </div>
         <% } %>

_build/usage_cpp_stl.html.erb

@@ -11,37 +11,60 @@
         </ul>
         <div class="tab-content" style="margin-top: 6px">
             <div role="tabpanel" class="tab-pane active" id="example-local-file">
-<pre><code class="cpp">#include &lt;fstream&gt;
+<%= code cur_lang, <<-CODE
+#include <fstream>
 
-std::ifstream is("path/to/local/file.<%= meta['file-extension'] || meta['id'] %>", std::ifstream::binary);</code></pre>
+std::ifstream is("path/to/local/file.#{meta['file-extension'] || meta['id']}", std::ifstream::binary);
+CODE
+%>
             </div>
             <div role="tabpanel" class="tab-pane" id="example-std-string">
-<pre><code class="cpp">#include &lt;sstream&gt;
+<%= code cur_lang, <<-CODE
+#include <sstream>
 
-std::istringstream is(str);</code></pre>
+std::istringstream is(str);
+CODE
+%>
             </div>
             <div role="tabpanel" class="tab-pane" id="example-char-ptr">
-<pre><code class="cpp">#include &lt;sstream&gt;
+<%= code cur_lang, <<-CODE
+#include <sstream>
 
 const char buf[] = { ... };
 std::string str(buf, sizeof buf);
-std::istringstream is(str);</code></pre>
+std::istringstream is(str);
+CODE
+%>
             </div>
         </div>
 
     </li>
 
     <li>We need to wrap our input stream into Kaitai stream:
 
-<pre><code class="cpp">#include &lt;kaitai/kaitaistream.h&gt;
+<%= code cur_lang, <<-CODE
+#include <kaitai/kaitaistream.h>
 
-kaitai::kstream ks(&amp;is);</code></pre></li>
+kaitai::kstream ks(&is);
+CODE
+%>
+    </li>
 
     <li>And finally, we can invoke the parsing:
-
-<pre><code class="cpp"><%= class_name %> data(&amp;ks);</code></pre></li>
+<%= code cur_lang, <<-CODE
+#{class_name} data(&ks);
+CODE
+%>
+    </li>
 </ol>
 
 <p>After that, one can get various attributes from the structure by invoking getter methods like:</p>
 
-<pre><code class="cpp"><% usage_attrs.each { |attr| %>data.<%= attr[:name] %>() // => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ attr[:name] }() // => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>

_build/usage_csharp.html.erb

@@ -2,13 +2,26 @@
 
 <% class_name = ucc(file_id) %>
 
-<pre><code class="csharp">var data = <%= class_name %>.FromFile("path/to/local/file.<%= meta['file-extension'] || meta['id'] %>");</code></pre>
+<%= code cur_lang, <<-CODE
+var data = #{ class_name }.FromFile("path/to/local/file.#{ meta['file-extension'] || meta['id'] }");
+CODE
+%>
 
 <p>Or parse structure from a byte array:</p>
 
-<pre><code class="csharp">byte[] someArray = new byte[] { ... };
-var data = new <%= class_name %>(new KaitaiStream(someArray));</code></pre>
+<%= code cur_lang, <<-CODE
+byte[] someArray = new byte[] { ... };
+var data = new #{ class_name }(new KaitaiStream(someArray));
+CODE
+%>
 
 <p>After that, one can get various attributes from the structure by accessing properties like:</p>
 
-<pre><code class="csharp"><% usage_attrs.each { |attr| %>data.<%= ucc(attr[:name]) %> // => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ ucc(attr[:name]) } // => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>

_build/usage_java.html.erb

@@ -2,13 +2,26 @@
 
 <% class_name = ucc(file_id) %>
 
-<pre><code class="java"><%= class_name %> data = <%= class_name %>.fromFile("path/to/local/file.<%= meta['file-extension'] || format_name %>");</code></pre>
+<%= code cur_lang, <<-CODE
+#{ class_name } data = #{ class_name }.fromFile("path/to/local/file.#{ meta['file-extension'] || format_name }");
+CODE
+%>
 
 <p>Or parse structure from a byte array:</p>
 
-<pre><code class="java">byte[] someArray = new byte[] { ... };
-<%= class_name %> data = new <%= class_name %>(new ByteBufferKaitaiStream(someArray));</code></pre>
+<%= code cur_lang, <<-CODE
+byte[] someArray = new byte[] { ... };
+#{ class_name } data = new #{ class_name }(new ByteBufferKaitaiStream(someArray));
+CODE
+%>
 
 <p>After that, one can get various attributes from the structure by invoking getter methods like:</p>
 
-<pre><code class="java"><% usage_attrs.each { |attr| %>data.<%= lcc(attr[:name]) %>() // => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ lcc(attr[:name]) }() // => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>

_build/usage_javascript.html.erb

@@ -3,9 +3,19 @@
 
 <p>Parse structure from an ArrayBuffer:</p>
 
-<pre><code class="javascript">var arrayBuffer = ...;
-var data = new <%= class_name %>(new KaitaiStream(arrayBuffer));</code></pre>
+<%= code cur_lang, <<-CODE
+var arrayBuffer = ...;
+var data = new #{ class_name }(new KaitaiStream(arrayBuffer));
+CODE
+%>
 
 <p>After that, one can get various attributes from the structure by accessing fields or properties like:</p>
 
-<pre><code class="javascript"><% usage_attrs.each { |attr| %>data.<%= lcc(attr[:name]) %> // => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ lcc(attr[:name]) } // => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>

_build/usage_python.html.erb

@@ -2,15 +2,28 @@
 
 <% class_name = ucc(file_id) %>
 
-<pre><code class="python">data = <%= class_name %>.from_file("path/to/local/file.<%= meta['file-extension'] || format_name %>")</code></pre>
+<%= code cur_lang, <<-CODE
+data = #{ class_name }.from_file("path/to/local/file.#{ meta['file-extension'] || format_name }")
+CODE
+%>
 
 <p>Or parse structure from a bytes:</p>
 
-<pre><code class="python">from kaitaistruct import KaitaiStream, BytesIO
+<%= code cur_lang, <<-CODE
+from kaitaistruct import KaitaiStream, BytesIO
 
-raw = b"\x00\x01\x02..."
-data = <%= class_name %>(KaitaiStream(BytesIO(raw)))</code></pre>
+raw = b"\\x00\\x01\\x02..."
+data = #{ class_name }(KaitaiStream(BytesIO(raw)))
+CODE
+%>
 
 <p>After that, one can get various attributes from the structure by invoking getter methods like:</p>
 
-<pre><code class="python"><% usage_attrs.each { |attr| %>data.<%= attr[:name] %> # => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ attr[:name] } # => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>

_build/usage_ruby.html.erb

@@ -2,13 +2,26 @@
 
 <% class_name = ucc(file_id) %>
 
-<pre><code class="ruby">data = <%= class_name %>.from_file("path/to/local/file.<%= meta['file-extension'] || format_name %>")</code></pre>
+<%= code cur_lang, <<-CODE
+data = #{ class_name }.from_file("path/to/local/file.#{ meta['file-extension'] || format_name }")
+CODE
+%>
 
 <p>Or parse structure from a string of bytes:</p>
 
-<pre><code class="ruby">bytes = "\x00\x01\x02..."
-data = <%= class_name %>.new(Kaitai::Struct::Stream.new(bytes))</code></pre>
+<%= code cur_lang, <<-CODE
+bytes = "\\x00\\x01\\x02..."
+data = #{ class_name }.new(Kaitai::Struct::Stream.new(bytes))
+CODE
+%>
 
 <p>After that, one can get various attributes from the structure by invoking getter methods like:</p>
 
-<pre><code class="ruby"><% usage_attrs.each { |attr| %>data.<%= attr[:name] %> # => <%= attr[:doc] %><% } %></code></pre>
+<% src_usage_attrs = ""
+usage_attrs.each { |attr|
+    src_usage_attrs += <<-CODE
+data.#{ attr[:name] } # => #{ attr[:doc] }
+    CODE
+}
+%>
+<%= code cur_lang, src_usage_attrs %>