mathematical 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9fad17d831541b401f9eda17a2bcac80e41dd490
+  data.tar.gz: da0a7b96a1e43f8cd9a49e5bcf01a83a26881749
+SHA512:
+  metadata.gz: 973f40da8c62e2f7c16df0e846c72252abebb022ae6465e85714ccf3af743642664573980ffc016e308aa07a9c2a2aa04161a3dcfe133bc32b186392abab762d
+  data.tar.gz: c20e0733a2efac5d629104bddecd3bb306ad04f677d2e371bf4d1f90691867eeb5746ebc88bd87a801b8d0e1ec73970726eb74cb6e884b97fd3f37f08a2b0c51

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+/vendor/gems/
+bin/
+ext/blahtexml/Source/extconf.rb
+ext/blahtexml/Source/makefile
+ext/blahtexml/bin-blahtex
+ext/blahtexml/blahtex

data/.gitmodules

@@ -0,0 +1,4 @@
+[submodule "ext/blahtexml"]
+	path = ext/blahtexml
+	url = git@github.com:gvanas/blahtexml.git
+  ignore = dirty

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mathematical.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Garen Torikian
+
+MIT License
+
+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/README.md

@@ -0,0 +1,64 @@
+# Mathematical
+
+Convert mathematical equations to base64 encoded images.
+
+![](https://i.imgur.com/JC7HT32.gif)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mathematical'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mathematical
+
+## Usage
+
+The simplest way to do this is
+
+``` ruby
+Mathematical::Render.new.render(contents)
+```
+
+`contents` should just be a block of text, containing inline or display style math.
+
+## Dependencies
+
+Two dependencies are needed:
+
+* [blahtexml](https://github.com/gvanas/blahtexml). This does all the conversion
+from math to PNG. It's available for OS X (`make blahtex-mac`) and Linux (`make blahtex-linux`).
+* [dvipng](http://sourceforge.net/projects/dvipng/). I'm on a Mac, and could not
+for the life of me figure out how to build this. I ended up downloading [MacTex](https://www.tug.org/mactex/),
+which is a *huge* package. `dvipng` is installed under */usr/texbin/dvipng*.
+
+## Why did you...?
+
+There are a smattering of Ruby, C, and Ruby+C libraries out there for converting
+math equations to a variety of formats. There needs to be a sane way to show math
+equations in the browser. The options are:
+
+* MathML: With browser support for MathML under attack, it's unfortunately not a sustainable
+solution
+* MathJax. While extremely popular, I dislike the "stuttering" effect caused by
+pages loading math. JavaScript shouldn't be used in situations where server-rendering
+is a possibility, in my opinion.
+* SVG: This would be a great choice, but, unfortunately, there are some [security concerns](http://www.hgi.ruhr-uni-bochum.de/media/hgi/veroeffentlichungen/2011/10/19/svgSecurity-ccs11.pdf) [PDF]
+that make me nervous
+* PNG: This is the format which `blahtexml` is capable of outputting. Working
+with a binary format has the downside of requiring it to be *hosted* somewhere.
+
+After considering these choices, I thought that a base64 encoded image made
+the most sense. You get the benefit of browser compatibility without needing
+to serve an image somewhere online.
+
+## Further readings
+
+* ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf - a short math guide
+* http://gva.noekeon.org/blahtexml/blahtexml-0.9-doc.pdf - the blahtex documentation

data/Rakefile

@@ -0,0 +1,45 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'rbconfig'
+require 'fileutils'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => [:test]
+
+namespace :git do
+  namespace :submodules do
+    desc "Initialize git submodules"
+    task :init do
+      system "git submodule init"
+      system "git submodule update"
+    end
+  end
+end
+
+task :makebin do
+  host_os = RbConfig::CONFIG['host_os']
+  Dir.chdir "ext/blahtexml" do
+    case host_os
+    # when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+    #   :windows
+    when /darwin|mac os/
+      `make blahtex-mac`
+      FileUtils.mkdir_p "../../bin/blahtex/macosx/"
+      FileUtils.cp "blahtex", "../../bin/blahtex/macosx/"
+    when /linux/
+      `make blahtex-linux`
+      FileUtils.mkdir_p "../../bin/blahtex/linux/"
+      FileUtils.cp "blahtex", "../../bin/blahtex/linux/"
+    # when /solaris|bsd/
+      # :unix
+    else
+      raise Error, "unknown os: #{host_os.inspect}"
+    end
+  end
+end

data/lib/mathematical.rb

@@ -0,0 +1,8 @@
+require "mathematical/parser"
+require "mathematical/render"
+require "mathematical/version"
+
+module Mathematical
+  # Raised when missing binaries for images rendering.
+  class CommandNotFoundError < Exception; end
+end

data/lib/mathematical/parser.rb

@@ -0,0 +1,30 @@
+module Mathematical
+  class Parser
+    # https://stackoverflow.com/questions/14182879/regex-to-match-latex-equations
+    REGEX = /
+    (?<!\\)    # negative look-behind to make sure start is not escaped
+    (?:       # start non-capture group for all possible match starts
+        # group 1, match dollar signs only
+        # single or double dollar sign enforced by look-arounds
+        ((?<!\$)\${1,2}(?!\$))|
+        # group 2, match escaped parenthesis
+        (\\\()|
+        # group 3, match escaped bracket
+        (\\\[)|
+        # group 4, match begin equation
+        (\\begin\{equation\})
+    )
+    (.*(\g<1>)?.*)  # match everything in between including nested LaTeX equations
+    (?<!\\)  # negative look-behind to make sure end is not escaped
+        # if group 1 was start, match \1
+        (?(1)(?<!\$)\1(?!\$)|
+        # if group 2 was start, escaped parenthesis is end
+        (?(2)\\\)|
+        # if group 3 was start, escaped bracket is end
+        (?(3)\\\]|
+        # otherwise group 4 was start, match end equation
+        \\end\{equation\}
+    )))
+    /x
+  end
+end

data/lib/mathematical/render.rb

@@ -0,0 +1,101 @@
+require 'rbconfig'
+require 'fileutils'
+require 'tmpdir'
+require 'shellwords'
+require 'base64'
+
+module Mathematical
+  class Render
+    DEFAULT_OPTS = {
+      :html_png_resolution => 200
+    }
+
+    def initialize(opts = {})
+      @os ||= (
+        host_os = RbConfig::CONFIG['host_os']
+        case host_os
+        when /darwin|mac os/
+          "macosx"
+        when /linux/
+          "linux"
+        else
+          raise Error, "unknown os: #{host_os.inspect}"
+        end
+      )
+
+      opts = DEFAULT_OPTS.merge(opts)
+      @temp_dir = Dir.mktmpdir
+      @args = [
+              '--png',
+              '--use-preview-package',
+              # '--shell-dvipng',
+              # "'dvipng -D #{Shellwords.shellescape opts[:html_png_resolution].to_s}'",
+             ]
+    end
+
+
+    def render(contents)
+      in_tmpdir do |tmpdir|
+        @args << "--temp-directory #{Shellwords.shellescape tmpdir.first}"
+        @args << "--png-directory #{Shellwords.shellescape tmpdir.first}"
+
+        contents.gsub(Mathematical::Parser::REGEX) do |maths|
+          if maths =~ /^\$(?!\$)/
+            maths = maths[1..-2]
+            type = :inline
+          else
+            type = :display
+          end
+
+          data = run_blahtex(maths, type)
+          if filename = data.match("<md5>(.+?)</md5>")[1]
+            "<img class=\"#{type.to_s}-math\" src=\"data:image/png;base64,#{png_to_base64(File.join(tmpdir, "#{filename}.png"))}\"/>"
+          end
+        end
+      end
+    end
+
+    def run_blahtex(tex, type)
+      raise CommandNotFoundError, "Required commands missing: #{missing_commands.join(', ')} in PATH. (#{ENV['PATH']})" unless missing_commands.empty?
+      @args << '--displaymath' if type == :equation
+
+      IO.popen(["bin/blahtex/#{@os}/blahtex", *@args].join(' '), 'w+') do |blahtex|
+        blahtex.write tex
+        blahtex.close_write
+
+        output = blahtex.read
+        blahtex.close_read
+
+        raise "Error running blahtex" unless $?.success?
+
+        output
+      end
+    end
+
+    def png_to_base64(path)
+      File.open(path, 'r') { |image_file| Base64.encode64(image_file.read).gsub(/\n/, '') }
+    end
+
+private
+
+    # Check toolchain availability and returns array of missing tools
+    def missing_commands
+      commands = []
+      commands << "dvipng" unless can_run?("dvipng -v")
+      commands
+    end
+
+    # Trial command and check if return code is zero
+    def can_run?(command)
+      `#{command} 2>&1`
+      $?.exitstatus.zero?
+    end
+
+    def in_tmpdir
+      path = FileUtils.mkdir_p Dir.tmpdir
+      yield path
+    ensure
+      FileUtils.rm_rf( path )
+    end
+  end
+end

data/lib/mathematical/version.rb

@@ -0,0 +1,3 @@
+module Mathematical
+  VERSION = "0.0.1"
+end

data/mathematical.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mathematical/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mathematical"
+  spec.version       = Mathematical::VERSION
+  spec.authors       = ["Garen Torikian"]
+  spec.email         = ["gjtorikian@gmail.com"]
+  spec.summary       = %q{Turn maths into PNGs.}
+  spec.description   = %q{Turn maths into PNGs.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+end

data/script/bootstrap

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+set -e
+export CC=gcc
+
+echo "==> Installing gem dependencies…"
+bundle check --path vendor/gems 2>&1 > /dev/null || {
+  bundle install --binstubs bin --path vendor/gems --quiet
+}

data/test/mathematical/basic_test.rb

@@ -0,0 +1,9 @@
+require "test_helper"
+require "mathematical"
+
+class Mathematical::BasicTest < Test::Unit::TestCase
+
+  def test_it_has_a_version
+    assert Mathematical::VERSION
+  end
+end

data/test/mathematical/fixtures/after/basic.html

@@ -0,0 +1 @@
+When <img class="inline-math" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAC0AAAAUCAMAAAAusUTNAAAANlBMVEX///8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABHL6OuAAAAEXRSTlMAQKOPaOEsfMNW+dMW7bPx81p55n0AAADiSURBVCgVtVLZAoQgCCSPrM0O//9ndyA1tK235YE4holDoheJL7lbypkailuwl1fD2vAX9zoSuUkne1tRWwF+hh6ifEXtpQtvVbYzg+ozBU5OnvVgrL3PoKhjcozbViiHkvGslpgX2Q98Fg5w9kR/2MS8JEpSWTFPkYyegJZuZhiNWD1R7mQBQ+K4yf+sFZoaGJly8WhkBkQtZ+O2j12aLxx1g5E7jiiR8sItuyoOkZWyhOus4DYpzvpQpikFG18+cMmIB0OmyceO+gSpa11/hWVkvU3o2blTP2P/Sk38En7LF60+BSj8TilKAAAAAElFTkSuQmCC"/>, there are two solutions...

data/test/mathematical/fixtures/before/basic.text

@@ -0,0 +1 @@
+When $a \ne 0$, there are two solutions...

data/test/mathematical/fixtures_test.rb

@@ -0,0 +1,31 @@
+require "test_helper"
+
+class Mathematical::FixturesTest < Test::Unit::TestCase
+
+  Dir['test/mathematical/fixtures/before/*.text'].each do |before|
+    name = before.split('/').last
+
+    define_method "test_#{name}" do
+      source = File.read(before)
+
+      expected_file = before.sub(/before/, "after").sub(/text/, "html")
+      expected = File.read(expected_file).rstrip
+      actual = Mathematical::Render.new.render(source).rstrip
+
+      if source != expected
+        assert(source != actual, "#{name} did not render anything")
+      end
+
+      diff = IO.popen("diff -u - #{expected_file}", 'r+') do |f|
+        f.write actual
+        f.close_write
+        f.read
+      end
+
+      assert expected == actual, <<message
+#{File.basename expected_file}'s contents don't match command output:
+#{diff}
+message
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'bundler/setup'
+require 'mathematical'
+require 'test/unit'

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: mathematical
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Garen Torikian
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Turn maths into PNGs.
+email:
+- gjtorikian@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .gitmodules
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mathematical.rb
+- lib/mathematical/parser.rb
+- lib/mathematical/render.rb
+- lib/mathematical/version.rb
+- mathematical.gemspec
+- script/bootstrap
+- test/mathematical/basic_test.rb
+- test/mathematical/fixtures/after/basic.html
+- test/mathematical/fixtures/before/basic.text
+- test/mathematical/fixtures_test.rb
+- test/test_helper.rb
+homepage: ''
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Turn maths into PNGs.
+test_files:
+- test/mathematical/basic_test.rb
+- test/mathematical/fixtures/after/basic.html
+- test/mathematical/fixtures/before/basic.text
+- test/mathematical/fixtures_test.rb
+- test/test_helper.rb