tablerize 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e70970cea20a8c6ee05fe6ed66d56f69389d40cd
+  data.tar.gz: 577fb09939cf9995bef8886dd81f1ef9ffc46f9d
+SHA512:
+  metadata.gz: 08fbcc9174c61c2b4c09bf6dab052f8106b34b01f991f4f27d73cb75654e4c6652e96b59e5d6919becc136e1d26076758413a0dbebdb5968bb9cac68e4f8acfd
+  data.tar.gz: b6bc1783e850f6a49317cc5a84625fe87b1f0b1213a9eaf60d97920590e8819742e8a764ead5e6ce3186eb18b475fe26001790d6b4dc31fc7ab418b82c21dc9b

data/.gitignore

@@ -0,0 +1 @@
+/tablerize-*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=documentation
+--tty

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+script: rspec
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 IFTTT Inc
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Makefile

@@ -0,0 +1,15 @@
+GEM_NAME := tablerize
+
+all:
+	gem build $(GEM_NAME).gemspec
+
+install: all
+	gem install $(GEM_NAME)
+
+uninstall:
+	gem uninstall $(GEM_NAME)
+
+clean:
+	rm -fv -- $(GEM_NAME)-*.gem
+
+.PHONY: all install clean

data/README.md

@@ -0,0 +1,264 @@
+Tablerize
+=========
+
+Tablerize is a format for writing tables using YAML/JSON-compatible data
+structures, and Ruby code to convert it to HTML.
+
+
+## Usage
+
+To install
+
+```shell
+cd tablerize
+make install
+# or (soon)
+gem install tablerize
+```
+
+You can use it in Ruby...
+
+```ruby
+require 'tablerize'
+puts Tablerize.load_file(path).to_html
+# or
+puts Tablerize.load(yaml_string).to_html
+# or
+puts Tablerize.make_table(object_from_yaml_or_json).to_html
+```
+
+...or from the command line
+
+```shell
+tablerize path/to/yaml-table.yml [...]
+```
+
+
+## Why?
+
+Markdown is easy on the eyes. It helps you write formatted documents in plain
+text in a way that is meaningful even without rendering. One thing that [the
+original Markdown specification] doesn't support is tables. But many authors
+writing in Markdown want to write tables, so Markdown libraries have come up
+with various but similar ways of representing tables in Markdown.
+
+[the original Markdown specification]: http://daringfireball.net/projects/markdown/syntax
+
+Tables exist to help you line things up. But these Markdown tables force you to
+either line things up yourself, or deal with the unreadable results. Here's some
+a table from the [Markdown Cheatsheet]:
+
+[Markdown Cheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
+
+```
+| Tables        | Are           | Cool  |
+| ------------- |:-------------:| -----:|
+| col 3 is      | right-aligned | $1600 |
+| col 2 is      | centered      |   $12 |
+| zebra stripes | are neat      |    $1 |
+```
+
+This is pretty readable, but unless you know exactly what the table looks like
+beforehand, lining everything up takes a lot of time! But that's okay, you don't
+_actually_ need to do that, you can just have this mess instead:
+
+```
+Markdown | Less | Pretty
+--- | --- | ---
+*Still* | `renders` | **nicely**
+1 | 2 | 3
+```
+
+Why is this less pretty? Because, while tables exist to organize data, the data
+looks pretty disorganized here. This goes against the concept of having raw
+Markdown be readable!
+
+Depending what Markdown library you're using, the examples above might not even
+render. Many flavors of Markdown tables exist, and accept table syntax in
+varying degrees of leniency. Not only does this make writing tables even harder
+("which Markdown library am I using and does it support table feature X?"), but
+it suggests that these these libraries are just making concessions with the
+constraints of representing a table in this way. Tables take data, something
+that should be computer-readable, and make them human-readable. Unrendered
+Markdown tables, sadly, usually are neither.
+
+Oh, and with this traditional syntax, you can pretty much forget about nesting
+tables.
+
+
+## So what's Tablerize?
+
+**Tablerize** attempts to solve these problems. In its purest form, it is a
+specification of a _human-readable representation of tables in YAML/JSON-
+compatible data_. Since YAML is human-readable, so can Tablerize. This project
+also includes a Ruby library and command-line tool to convert this YAML- based
+format into HTML tables. It can be run with:
+
+```shell
+tablerize path/to/yaml-table.yml [...]
+```
+
+A complementary project, [kramdown-tablerize], allows embedding of YAML
+tables into [kramdown] Markdown documents.
+
+[kramdown]: http://kramdown.gettalong.org/
+[kramdown-tablerize]: https://github.com/IFTTT/kramdown-tablerize
+
+
+## Format
+
+Here's example: Searching for "statistics" on Google news, I come across [a
+Forbes article] with a neat little table I want to type up. Let's try it now
+([examples/example-1.yml]):
+
+[a Forbes article]: http://www.forbes.com/sites/gregorymcneal/2014/06/27/nsa-releases-new-statistical-details-about-surveillance/
+[examples/example-1.yml]: examples/example-1.yml
+
+```yaml
+class: [statistics-table, nsa-surveillance-details]
+
+cols:
+- name: authority
+- name: num_orders
+- name: num_targets
+
+data:
+- class: table-header
+  authority: Legal Authority
+  num_orders: Annual Number of Orders
+  num_targets: Estimated Number of Targets Affected
+- authority: |
+              __FISA Orders__  
+              Based on probable cause
+              (Title I and III of FISA, Sections 703 and 704 of FISA)
+  num_orders: "1,167 orders"
+  num_targets: "1,144"
+- authority: |
+              __Section 702__  
+              of FISA
+  num_orders: "1 order"
+  num_targets: "89,138"
+- authority: |
+              __FISA Pen Register/Trap and Trace__  
+              (Title IV of FISA)
+  num_orders: "131 orders"
+  num_targets: "319"
+```
+
+Here's what it looks like as HTML, using a common Markdown stylesheet ("GitHub"
+on Mou/Macdown):
+
+![screenshot](https://cloud.githubusercontent.com/assets/1570168/5449994/b09875c8-84b3-11e4-9a6a-b489a391d221.png)
+
+Here's an example that illustrates some of the more advanced features of
+Tablerize ([examples/example-2.yml]):
+
+[examples/example-2.yml]: examples/example-2.yml
+
+```yaml
+class: [http-spec-exchange, another-class] # this line is optional
+
+cols: # column specifications and ordering
+- name: k # is used to identify the column below
+  class: http-key # is applied to each cell (td) in the column
+- name: v
+  class: http-value
+
+data: # data, by row
+- v: GET # v corresponds to cols.1.name above
+  k: Method # k corresponds to cols.0.name above
+- k: Parameters # the order of the columns in data doesn't matter
+  v:
+    # nest tables by nesting another YAML dictionary, in the same format
+    class: http-spec-params
+
+    cols:
+    - name: k
+    - name: v
+
+    data:
+    - k: '`client_id`' # backticks must be quoted!
+      v: |
+        A client ID for your service as set in your configuration.
+        
+        a new line, wow! Let's see regular Markdown tables do that...
+    # <p>...</p> gets inserted only if there are multiple paragraphs
+    - k: '`type`'
+      v: '`code`'
+    - k: '`state`'
+      v: An anti-forgery token provided by the API.
+    - k: redirect_uri
+      v: '`https://example.com/api/{{your_service}}/authorize`'
+```
+
+With the right CSS, it becomes this:
+
+![screenshot](https://cloud.githubusercontent.com/assets/1570168/3435774/15108594-0099-11e4-8175-d820206c471e.png)
+
+
+## Tips & Caveats
+
+  - YAML tip: Backticks `` ` `` and some other characters need to be quoted
+    because they have special meaing in YAML or are otherwise not allowed to be
+    unquoted by YAML. Other suspicious characters include commas `,`, ampersands
+    `&`, and asterisks `*` and have been implicated in similar crimes. If
+    readability isn't an issue and there's been a syntax error spree in your
+    area, you can go ahead and quote every string just be safe.
+
+  - Don't use `class` as a column name, since it is used for classes. Unless you
+    really want to. In which case you can. But it still will be used for
+    classes.
+
+  - Auto column classes: As a convenience, if a table has a class `my-table` and
+    a column is named `column-1`, then all the cells in the column will have the
+    class `my-table-column-1`. This only happens for the first table class
+    listed. If you don't want this to happen, make the first table class `null`;
+    it will be ignored and columns will not have automatically-generated
+    classes.
+
+
+## The Road Ahead
+
+  - Support using representing two-column tables as key and value. YAML doesn't
+    support ordered dictionaries, so this will be done by looking at the only
+    key- value pair inside each dictionary in a list:
+
+    ```yaml
+    data:
+    - wake up: done
+    - brush teeth: done
+    - eat breakfast: not done
+    ```
+
+  - Allow HTML attributes to be placed anywhere classes currently can.
+
+  - Allow arbitrary HTML _and_ tables as siblings together inside cells. This
+    will probably be implemented by recursively calling [kramdown-yaml-
+    tablerize], if installed.
+
+  - Allow empty cells to be created by simply not including keys or making keys
+    with no value (represented as `null`/`nil`/`None`). Possibly add a "strict
+    mode" setting that causes these to error instead.
+
+  - Support `thead` and `tfoot`. Perhaps add support `tbody`, which will be a
+    synonym for `data`.
+
+  -  For simple tables, allow outputting to Markdown, for GitHub and other sites
+     that don't allow HTML in Markdown.
+
+  - [textmate/yaml.tmbundle], the YAML syntax highlighter used by TextMate,
+    Sublime Text, and GitHub isn't perfect. Fix the plugin and use the
+    examples in this README as test cases. _Update: GitHub now highlights the
+    YAML in this file almost correctly, but [textmate/yaml.tmbundle] doesn't
+    seem to be updated. GitHub's probably using something else to do syntax
+    highlighting._
+
+[textmate/yaml.tmbundle]: https://github.com/textmate/yaml.tmbundle
+
+## Credit
+
+**Tablerize** was originally designed and written by [@szhu] at [@IFTTT].
+
+[rfc1459/kramdown-gist]: https://github.com/rfc1459/kramdown-gist
+[@szhu]: https://github.com/szhu
+[@IFTTT]: https://github.com/IFTTT

data/bin/tablerize

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# Command-line interface to the tablerize gem.
+
+if ARGV.empty?
+  $stderr.puts "usage: #{$PROGRAM_NAME} path/to/yaml-table.yml [...]"
+  exit 1
+end
+
+begin
+  require_relative '../lib/tablerize'
+rescue LoadError
+  require 'tablerize'
+end
+
+ARGV.each do |path|
+  puts Tablerize.load_file(path).to_html
+end

data/examples/example-1.html

@@ -0,0 +1,9 @@
+<table class="statistics-table nsa-surveillance-details"><tbody>
+<tr class="table-header"><td class="statistics-table-authority">Legal Authority</td><td class="statistics-table-num_orders">Annual Number of Orders</td><td class="statistics-table-num_targets">Estimated Number of Targets Affected</td></tr>
+<tr><td class="statistics-table-authority"><strong>FISA Orders</strong><br />
+Based on probable cause (Title I and III of FISA, Sections 703 and 704 of FISA)</td><td class="statistics-table-num_orders">1,167 orders</td><td class="statistics-table-num_targets">1,144</td></tr>
+<tr><td class="statistics-table-authority"><strong>Section 702</strong><br />
+of FISA</td><td class="statistics-table-num_orders">1 order</td><td class="statistics-table-num_targets">89,138</td></tr>
+<tr><td class="statistics-table-authority"><strong>FISA Pen Register/Trap and Trace</strong><br />
+(Title IV of FISA)</td><td class="statistics-table-num_orders">131 orders</td><td class="statistics-table-num_targets">319</td></tr>
+</tbody></table>

data/examples/example-1.yml

@@ -0,0 +1,27 @@
+class: [statistics-table, nsa-surveillance-details]
+
+cols:
+- name: authority
+- name: num_orders
+- name: num_targets
+
+data:
+- class: table-header
+  authority: Legal Authority
+  num_orders: Annual Number of Orders
+  num_targets: Estimated Number of Targets Affected
+- authority: |
+              __FISA Orders__  
+              Based on probable cause (Title I and III of FISA, Sections 703 and 704 of FISA)
+  num_orders: "1,167 orders"
+  num_targets: "1,144"
+- authority: |
+              __Section 702__  
+              of FISA
+  num_orders: "1 order"
+  num_targets: "89,138"
+- authority: |
+              __FISA Pen Register/Trap and Trace__  
+              (Title IV of FISA)
+  num_orders: "131 orders"
+  num_targets: "319"

data/examples/example-2.html

@@ -0,0 +1,13 @@
+<table class="http-spec-exchange another-class"><tbody>
+<tr><td class="http-key http-spec-exchange-k">Method</td><td class="http-value http-spec-exchange-v">GET</td></tr>
+<tr><td class="http-key http-spec-exchange-k">Parameters</td><td class="http-value http-spec-exchange-v">
+<table class="http-spec-params"><tbody>
+<tr><td class="http-spec-params-k"><code>client_id</code></td><td class="http-spec-params-v"><p>A client ID for your service as set in your configuration.</p>
+
+<p>a new line, wow! Let’s see regular Markdown tables do that…</p></td></tr>
+<tr><td class="http-spec-params-k"><code>type</code></td><td class="http-spec-params-v"><code>code</code></td></tr>
+<tr><td class="http-spec-params-k"><code>state</code></td><td class="http-spec-params-v">An anti-forgery token provided by the API.</td></tr>
+<tr><td class="http-spec-params-k">redirect_uri</td><td class="http-spec-params-v"><code>https://example.com/api/{{your_service}}/authorize</code></td></tr>
+</tbody></table>
+</td></tr>
+</tbody></table>

data/examples/example-2.yml

@@ -0,0 +1,33 @@
+class: [http-spec-exchange, another-class] # this line is optional
+
+cols: # column specifications and ordering
+- name: k # is used to identify the column below
+  class: http-key # is applied to each cell (td) in the column
+- name: v
+  class: http-value
+
+data: # data, by row
+- v: GET # v corresponds to cols.1.name above
+  k: Method # k corresponds to cols.0.name above
+- k: Parameters # the order of the columns in data doesn't matter
+  v:
+    # nest tables by nesting another YAML dictionary, in the same format
+    class: http-spec-params
+
+    cols:
+    - name: k
+    - name: v
+
+    data:
+    - k: '`client_id`' # backticks must be quoted!
+      v: |
+        A client ID for your service as set in your configuration.
+        
+        a new line, wow! Let's see regular Markdown tables do that...
+    # <p>...</p> gets inserted only if there are multiple paragraphs
+    - k: '`type`'
+      v: '`code`'
+    - k: '`state`'
+      v: An anti-forgery token provided by the API.
+    - k: redirect_uri
+      v: '`https://example.com/api/{{your_service}}/authorize`'

data/lib/tablerize/html_element.rb

@@ -0,0 +1,67 @@
+require 'erb'
+
+module Tablerize
+  class HtmlElement
+  end
+
+  # A RawHtmlElement represents arbitrary HTML.
+  class RawHtmlElement < HtmlElement
+    attr_reader :html
+    alias_method :to_html, :html
+
+    def initialize(html)
+      @html = html
+    end
+  end
+  NEWLINE = RawHtmlElement.new("\n")
+
+  # A StructuredHtmlElement represents HTML tags enclosing an array of
+  # HtmlElements.
+  class StructuredHtmlElement < HtmlElement
+    attr_accessor :tag
+    attr_reader :attrs, :classes, :children
+
+    def initialize(tag, opts = {})
+      @tag = tag
+      @attrs = {}
+      @classes = []
+      @children = []
+      add_class opts[:class] unless opts[:class].nil?
+      @attrs.update opts[:attrs] unless opts[:attrs].nil?
+    end
+
+    def add_class(classes)
+      if classes.respond_to? :each
+        classes.each do |klass|
+          add_single_class klass
+        end
+      else
+        add_single_class classes
+      end
+    end
+
+    def to_html
+      "<#{tag}#{attrs_html(@attrs)}>#{inner_html}</#{tag}>"
+    end
+
+    private
+
+    def add_single_class(klass)
+      return if klass.nil? || klass.empty?
+      return if @classes.include? klass
+      @classes << klass
+    end
+
+    def attrs_html(attrs)
+      out =  %( class="#{ERB::Util.h @classes.join(' ')}")  if @classes.length > 0
+      attrs.each do |attr, value|
+        out << %( #{attr}="#{h value}")
+      end
+      out
+    end
+
+    def inner_html
+      @children.map(&:to_html).join('')
+    end
+  end
+end

data/lib/tablerize/version.rb

@@ -0,0 +1,3 @@
+module Tablerize
+  VERSION = "1.0.1"
+end

data/lib/tablerize.rb

@@ -0,0 +1,71 @@
+require_relative 'tablerize/version'
+require_relative 'tablerize/html_element'
+
+require 'yaml'
+
+module Tablerize
+  # Tablerizes a YAML file, returning a Tablerize::HtmlElement.
+  def self.load_file(path)
+    data = YAML.load_file path
+    make_table(data)
+  end
+
+  # Tablerizes a YAML string, returning a Tablerize::HtmlElement.
+  def self.load(content)
+    data = YAML.load content
+    make_table(data)
+  end
+
+  # Tablerizes an object, returning a Tablerize::HtmlElement.
+  def self.make_table(data)
+    table = StructuredHtmlElement.new('table', class: data['class'])
+    tbody = StructuredHtmlElement.new('tbody')
+    tbody.children << NEWLINE
+    cols = data['cols']
+    data['data'].each do |row|
+      tr = StructuredHtmlElement.new('tr', class: row['class'])
+      cols.each do |col|
+        td = StructuredHtmlElement.new('td', class: col['class'])
+        col_key = col['name']
+        if (col_class_prefix = table.classes[0])
+          td.add_class "#{col_class_prefix}-#{col_key}"
+        end
+        cell = row[col_key]
+        if cell.is_a?(Hash)
+          td.children << NEWLINE
+          td.children << make_table(cell)
+          td.children << NEWLINE
+        else
+          td.children << RawHtmlElement.new(markdown_strip cell)
+        end
+        tr.children << td
+      end
+      tbody.children << tr
+      tbody.children << NEWLINE
+    end
+    table.children << tbody
+    table
+  end
+
+  private
+
+  # This method can easily be replaced to use any other Markdown library.
+  # As of now, you'll have to manually modify this method.
+  def self.markdown(text)
+    require 'kramdown'
+    Kramdown::Document.new(text).to_html.strip
+  end
+
+  # Process markdown removing <p>...</p> from one-liners.
+  def self.markdown_strip(text)
+    html = markdown text
+    p_start = '<p>'
+    p_end = '</p>'
+    if html.start_with?(p_start) && html.end_with?(p_end) &&
+       html.scan(p_start).count == 1 && html.scan(p_end).count == 1
+      html[3...-4]
+    else
+      html
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/tablerize'

data/spec/tablerize_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Tablerize do
+  ['example-1', 'example-2'].each do |test_name|
+    context test_name do
+      reference_result = File.read "examples/#{test_name}.html"
+
+      it "should be correctly converted via load_file" do
+        test_result = Tablerize.load_file("examples/#{test_name}.yml").to_html
+        expect(test_result.chomp).to eq(reference_result.chomp)
+      end
+
+      it "should be correctly converted via load" do
+        test_result = Tablerize.load(File.read "examples/#{test_name}.yml").to_html
+        expect(test_result.chomp).to eq(reference_result.chomp)
+      end
+    end
+  end
+end

data/tablerize.gemspec

@@ -0,0 +1,22 @@
+require './lib/tablerize/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'tablerize'
+  gem.summary       = 'Convert YAML to HTML tables.'
+  gem.description   = <<-END
+      Tablerize converts YAML to HTML tables. Say goodbye to aligning tables
+      in Markdown.
+    END
+
+  gem.version       = Tablerize::VERSION
+
+  gem.homepage      = 'https://github.com/IFTTT/tablerize'
+  gem.authors       = ['Sean Zhu']
+  gem.email         = 'opensource+tablerize@szhu.me'
+  gem.license       = 'MIT'
+
+  gem.add_dependency 'kramdown', '~> 1.2', '>= 1.2.0'
+  gem.executables   = ['tablerize']
+  gem.files         = `git ls-files`.split
+  gem.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: tablerize
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Sean Zhu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+description: |2
+        Tablerize converts YAML to HTML tables. Say goodbye to aligning tables
+        in Markdown.
+email: opensource+tablerize@szhu.me
+executables:
+- tablerize
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- LICENSE
+- Makefile
+- README.md
+- bin/tablerize
+- examples/example-1.html
+- examples/example-1.yml
+- examples/example-2.html
+- examples/example-2.yml
+- lib/tablerize.rb
+- lib/tablerize/html_element.rb
+- lib/tablerize/version.rb
+- spec/spec_helper.rb
+- spec/tablerize_spec.rb
+- tablerize.gemspec
+homepage: https://github.com/IFTTT/tablerize
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Convert YAML to HTML tables.
+test_files: []