rubypants 0.2.0 → 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d9822934b5585190847395099959027911beb2f3
+  data.tar.gz: f12b3db11d8f4c77e3c48fadfc6a1360895b4f8e
+SHA512:
+  metadata.gz: 3cdf93d5b4c9bfc7d3343d5b55ca8474955b15f689529db1d639dfba292785db6c99b985c4456ec3c025735344d4ca27b4cc9e5febd70b53825182b95758c5d0
+  data.tar.gz: c9488f204e20f28cd8e7913a8bbda9b0e912c62fd167c873c6d7b24a7a5b9863c015f28f1a9d3c7fbc06bcd2c446da6f3b1c734eb926b23c3c849ff8c3a85b06

data/{README → LICENSE.rdoc}

@@ -1,42 +1,15 @@
-= RubyPants -- SmartyPants ported to Ruby
+= Copyright and License
+
+== Copyright
 
 Ported by Christian Neukirchen <mailto:chneukirchen@gmail.com>
-  Copyright (C) 2004 Christian Neukirchen
+Copyright (C) 2004 Christian Neukirchen
 
-Incooporates ideas, comments and documentation by Chad Miller
-  Copyright (C) 2004 Chad Miller
+Incorporates ideas, comments and documentation by Chad Miller
+Copyright (C) 2004 Chad Miller
 
 Original SmartyPants by John Gruber
-  Copyright (C) 2003 John Gruber
-
-
-== RubyPants
-
-RubyPants is a Ruby port of the smart-quotes library SmartyPants.
-
-The original "SmartyPants" is a free web publishing plug-in for
-Movable Type, Blosxom, and BBEdit that easily translates plain ASCII
-punctuation characters into "smart" typographic punctuation HTML
-entities.
-
-See rubypants.rb for more information.
-
-
-== Incompatibilities
-
-RubyPants uses a different API than SmartyPants; it is compatible to
-Red- and BlueCloth.  Usually, you call RubyPants like this:
-
-  nicehtml = RubyPants.new(uglyhtml, options).to_html
-
-where +options+ is an Array of Integers and/or Symbols (if you don't
-pass any options, RubyPants will use <tt>[2]</tt> as default.)
-
-*Note*:: This is incompatible to SmartyPants, which uses <tt>[1]</tt>
-         for default.
-
-The exact meaning of numbers and symbols is documented at RubyPants#new.
-
+Copyright (C) 2003 John Gruber
 
 == SmartyPants license:
 
@@ -73,10 +46,7 @@ liability, or tort (including negligence or otherwise) arising in
 any way out of the use of this software, even if advised of the
 possibility of such damage.
 
-
-== RubyPants license
-
-Copyright (C) 2004 Christian Neukirchen
+=== RubyPants license
 
 RubyPants is a derivative work of SmartyPants and smartypants.py.
 
@@ -104,11 +74,3 @@ caused and on any theory of liability, whether in contract, strict
 liability, or tort (including negligence or otherwise) arising in
 any way out of the use of this software, even if advised of the
 possibility of such damage.
-
-
-== Links
-
-John Gruber:: http://daringfireball.net
-SmartyPants:: http://daringfireball.net/projects/smartypants
-Chad Miller:: http://web.chad.org
-Christian Neukirchen:: http://kronavita.de/chris

data/README.rdoc

@@ -0,0 +1,119 @@
+= RubyPants: SmartyPants for Ruby
+
+{<img src="https://img.shields.io/gem/v/rubypants.png?style=plastic">}[https://rubygems.org/gems/rubypants]
+
+== Synopsis
+
+RubyPants is a Ruby port of the smart-quotes library SmartyPants.
+
+The original "SmartyPants" is a free web publishing plug-in for
+Movable Type, Blosxom, and BBEdit that easily translates plain ASCII
+punctuation characters into "smart" typographic punctuation HTML
+entities.
+
+
+== Description
+
+RubyPants can perform the following transformations:
+
+* Straight quotes (<tt>"</tt> and <tt>'</tt>) into "curly" quote
+  HTML entities
+* Backticks-style quotes (<tt>``like this''</tt>) into "curly" quote
+  HTML entities
+* Dashes (<tt>--</tt> and <tt>---</tt>) into en- and em-dash
+  entities
+* Three consecutive dots (<tt>...</tt> or <tt>. . .</tt>) into an
+  ellipsis entity
+
+This means you can write, edit, and save your posts using plain old
+ASCII straight quotes, plain dashes, and plain dots, but your
+published posts (and final HTML output) will appear with smart
+quotes, em-dashes, and proper ellipses.
+
+RubyPants does not modify characters within <tt><pre></tt>,
+<tt><code></tt>, <tt><kbd></tt>, <tt><math></tt>, <tt><style></tt> or
+<tt><script></tt> tag blocks. Typically, these tags are used to
+display text where smart quotes and other "smart punctuation" would
+not be appropriate, such as source code or example markup.
+
+
+== Installation
+
+  gem install rubypants
+
+Or, in your application's Gemfile:
+
+  gem 'rubypants'
+
+
+== Example of Usage
+
+  RubyPants.new("String with 'dumb' quotes.").to_html
+
+For additional options, consult the documention in
+<tt>lib/rubypants/core.rb</tt>.
+
+
+== Backslash Escapes
+
+If you need to use literal straight quotes (or plain hyphens and
+periods), RubyPants accepts the following backslash escape sequences
+to force non-smart punctuation. It does so by transforming the
+escape sequence into a decimal-encoded HTML entity:
+
+  \\    \"    \'    \.    \-    \`
+
+This is useful, for example, when you want to use straight quotes as
+foot and inch marks: 6'2" tall; a 17" iMac.  (Use <tt>6\'2\"</tt>
+resp. <tt>17\"</tt>.)
+
+
+== Algorithmic Shortcomings
+
+One situation in which quotes will get curled the wrong way is when
+apostrophes are used at the start of leading contractions. For
+example:
+
+  'Twas the night before Christmas.
+
+In the case above, RubyPants will turn the apostrophe into an
+opening single-quote, when in fact it should be a closing one. I
+don't think this problem can be solved in the general case--every
+word processor I've tried gets this wrong as well. In such cases,
+it's best to use the proper HTML entity for closing single-quotes
+("<tt>&#8217;</tt>") by hand.
+
+
+== Bugs
+
+To file bug reports or feature requests, please create an issue in this gem's
+GitHub repository.
+
+If the bug involves quotes being curled the wrong way, please send
+example text to illustrate.
+
+
+== Authors
+
+John Gruber did all of the hard work of writing this software in
+Perl for Movable Type and almost all of this useful documentation.
+Chad Miller ported it to Python to use with Pyblosxom.
+
+Christian Neukirchen provided the Ruby port, as a general-purpose
+library that follows the *Cloth API.
+
+Jeremy McNevin posted this code to GitHub ages ago, but has recently
+been trying to improve it where possible.
+
+Aron Griffis made jekyll-pants[https://github.com/scampersand/jekyll-pants]
+which depends on RubyPants, and consequently jumped in to help out with
+issues and pull requests.
+
+
+== Links
+
+John Gruber :: http://daringfireball.net
+SmartyPants :: http://daringfireball.net/projects/smartypants
+Chad Miller :: http://web.chad.org
+Christian Neukirchen :: http://kronavita.de/chris
+Aron Griffis :: https://arongriffis.com

data/Rakefile

@@ -1,84 +1,7 @@
-# Rakefile for rubypants  -*-ruby-*-
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
-
-
 desc "Run all the tests"
 task :default => [:test]
 
-desc "Do predistribution stuff"
-task :predist => [:doc]
-
-
 desc "Run all the tests"
 task :test do
-  ruby 'test_rubypants.rb'
-end
-
-desc "Make an archive as .tar.gz"
-task :dist => :test do
-  system "darcs dist -d rubypants#{get_darcs_tree_version}"
-end
-
-
-desc "Generate RDoc documentation"
-Rake::RDocTask.new(:doc) do |rdoc|
-  rdoc.options << '--line-numbers --inline-source --all'
-  rdoc.rdoc_files.include 'README'
-  rdoc.rdoc_files.include 'rubypants.rb'
-end
-
-
-spec = Gem::Specification.new do |s|
-  s.name = 'rubypants'
-  s.version = '0.2.0'
-  s.summary = "RubyPants is a Ruby port of the smart-quotes library SmartyPants."
-  s.description = <<-EOF
-RubyPants is a Ruby port of the smart-quotes library SmartyPants.
-
-The original "SmartyPants" is a free web publishing plug-in for
-Movable Type, Blosxom, and BBEdit that easily translates plain ASCII
-punctuation characters into "smart" typographic punctuation HTML
-entities.
-  EOF
-  s.files = FileList['**/*rb', 'README', 'Rakefile'].to_a
-  s.test_file = "test_rubypants.rb"
-  s.extra_rdoc_files = ["README"]
-  s.rdoc_options = ["--main", "README"]
-  s.rdoc_options.concat ['--line-numbers', '--inline-source', '--all']
-  s.rdoc_options.concat ['--exclude',  'test_rubypants.rb']
-  s.require_path = '.'
-  s.author = "Christian Neukirchen"
-  s.email = "chneukirchen@gmail.com"
-  s.homepage = "http://www.kronavita.de/chris/blog/projects/rubypants.html"
-end
-
-Rake::GemPackageTask.new(spec) do |pkg|
-end
-
-
-# Helper to retrieve the "revision number" of the darcs tree.
-def get_darcs_tree_version
-  return ""  unless File.directory? "_darcs"
-
-  changes = `darcs changes`
-  count = 0
-  tag = "0.0"
-  
-  changes.each("\n\n") { |change|
-    head, title, desc = change.split("\n", 3)
-    
-    if title =~ /^  \*/
-      # Normal change.
-      count += 1
-    elsif title =~ /tagged (.*)/
-      # Tag.  We look for these.
-      tag = $1
-      break
-    else
-      warn "Unparsable change: #{change}"
-    end
-  }
-
-  "-" + tag + "." + count.to_s
+  ruby 'test/rubypants_test.rb'
 end

data/lib/rubypants.rb

@@ -0,0 +1,2 @@
+require_relative 'rubypants/core'
+require_relative 'rubypants/version'

data/lib/rubypants/core.rb

@@ -0,0 +1,374 @@
+class RubyPants < String
+
+  # Create a new RubyPants instance with the text in +string+.
+  #
+  # Allowed elements in the options array:
+  #
+  # 0  :: do nothing
+  # 1  :: enable all, using only em-dash shortcuts
+  # 2  :: enable all, using old school en- and em-dash shortcuts (*default*)
+  # 3  :: enable all, using inverted old school en and em-dash shortcuts
+  # -1 :: stupefy (translate HTML entities to their ASCII-counterparts)
+  #
+  # If you don't like any of these defaults, you can pass symbols to change
+  # RubyPants' behavior:
+  #
+  # <tt>:quotes</tt>        :: quotes
+  # <tt>:backticks</tt>     :: backtick quotes (``double'' only)
+  # <tt>:allbackticks</tt>  :: backtick quotes (``double'' and `single')
+  # <tt>:dashes</tt>        :: dashes
+  # <tt>:oldschool</tt>     :: old school dashes
+  # <tt>:inverted</tt>      :: inverted old school dashes
+  # <tt>:ellipses</tt>      :: ellipses
+  # <tt>:convertquotes</tt> :: convert <tt>&quot;</tt> entities to
+  #                            <tt>"</tt>
+  # <tt>:stupefy</tt>       :: translate RubyPants HTML entities
+  #                            to their ASCII counterparts.
+  #
+  # In addition, you can customize the HTML entities that will be injected by
+  # passing in a hash for the final argument.  The defaults for these entities
+  # are as follows:
+  #
+  # <tt>:single_left_quote</tt>  :: <tt>&#8216;</tt>
+  # <tt>:double_left_quote</tt>  :: <tt>&#8220;</tt>
+  # <tt>:single_right_quote</tt> :: <tt>&#8217;</tt>
+  # <tt>:double_right_quote</tt> :: <tt>&#8221;</tt>
+  # <tt>:em_dash</tt>            :: <tt>&#8212;</tt>
+  # <tt>:en_dash</tt>            :: <tt>&#8211;</tt>
+  # <tt>:ellipsis</tt>           :: <tt>&#8230;</tt>
+  # <tt>:html_quote</tt>         :: <tt>&quot; </tt>
+  #
+  def initialize(string, options=[2], entities = {})
+    super string
+
+    @options = [*options]
+    @entities = default_entities.update(entities)
+  end
+
+  # Apply SmartyPants transformations.
+  def to_html
+    do_quotes = do_backticks = do_dashes = do_ellipses = do_stupify = nil
+    convert_quotes = false
+
+    if @options.include?(0)
+      # Do nothing.
+      return self
+    elsif @options.include?(1)
+      # Do everything, turn all options on.
+      do_quotes = do_backticks = do_ellipses = true
+      do_dashes = :normal
+    elsif @options.include?(2)
+      # Do everything, turn all options on, use old school dash shorthand.
+      do_quotes = do_backticks = do_ellipses = true
+      do_dashes = :oldschool
+    elsif @options.include?(3)
+      # Do everything, turn all options on, use inverted old school
+      # dash shorthand.
+      do_quotes = do_backticks = do_ellipses = true
+      do_dashes = :inverted
+    elsif @options.include?(-1)
+      do_stupefy = true
+    else
+      do_quotes      = @options.include?(:quotes)
+      do_backticks   = @options.include?(:backticks)
+      do_backticks   = :both if @options.include?(:allbackticks)
+      do_dashes      = :normal if @options.include?(:dashes)
+      do_dashes      = :oldschool if @options.include?(:oldschool)
+      do_dashes      = :inverted if @options.include?(:inverted)
+      do_ellipses    = @options.include?(:ellipses)
+      convert_quotes = @options.include?(:convertquotes)
+      do_stupefy     = @options.include?(:stupefy)
+    end
+
+    # Parse the HTML
+    tokens = tokenize
+
+    # Keep track of when we're inside <pre> or <code> tags.
+    in_pre = false
+
+    # Here is the result stored in.
+    result = ""
+
+    # This is a cheat, used to get some context for one-character
+    # tokens that consist of just a quote char. What we do is remember
+    # the last character of the previous text token, to use as context
+    # to curl single- character quote tokens correctly.
+    prev_token_last_char = nil
+
+    tokens.each do |token|
+      if token.first == :tag
+        result << token[1]
+        if token[1] =~ %r!<(/?)(?:pre|code|kbd|script|style|math)[\s>]!
+          in_pre = ($1 != "/")  # Opening or closing tag?
+        end
+      else
+        t = token[1]
+
+        # Remember last char of this token before processing.
+        last_char = t[-1].chr
+
+        unless in_pre
+          t = process_escapes t
+
+          t.gsub!(/&quot;/, '"')  if convert_quotes
+
+          if do_dashes
+            t = educate_dashes t            if do_dashes == :normal
+            t = educate_dashes_oldschool t  if do_dashes == :oldschool
+            t = educate_dashes_inverted t   if do_dashes == :inverted
+          end
+
+          t = educate_ellipses t  if do_ellipses
+
+          # Note: backticks need to be processed before quotes.
+          if do_backticks
+            t = educate_backticks t
+            t = educate_single_backticks t  if do_backticks == :both
+          end
+
+          if do_quotes
+            if t == "'"
+              # Special case: single-character ' token
+              if prev_token_last_char =~ /\S/
+                t = entity(:single_right_quote)
+              else
+                t = entity(:single_left_quote)
+              end
+            elsif t == '"'
+              # Special case: single-character " token
+              if prev_token_last_char =~ /\S/
+                t = entity(:double_right_quote)
+              else
+                t = entity(:double_left_quote)
+              end
+            else
+              # Normal case:
+              t = educate_quotes t
+            end
+          end
+
+          t = stupefy_entities t  if do_stupefy
+        end
+
+        prev_token_last_char = last_char
+        result << t
+      end
+    end
+
+    # Done
+    result
+  end
+
+  protected
+
+  # Return the string, with after processing the following backslash
+  # escape sequences. This is useful if you want to force a "dumb" quote
+  # or other character to appear.
+  #
+  # Escaped are:
+  #      \\    \"    \'    \.    \-    \`
+  #
+  def process_escapes(str)
+    str.
+      gsub('\\\\', '&#92;').
+      gsub('\"',   '&#34;').
+      gsub("\\\'", '&#39;').
+      gsub('\.',   '&#46;').
+      gsub('\-',   '&#45;').
+      gsub('\`',   '&#96;')
+  end
+
+  # The string, with each instance of "<tt>--</tt>" translated to an
+  # em-dash HTML entity.
+  #
+  def educate_dashes(str)
+    str.
+      gsub(/--/, entity(:em_dash))
+  end
+
+  # The string, with each instance of "<tt>--</tt>" translated to an
+  # en-dash HTML entity, and each "<tt>---</tt>" translated to an
+  # em-dash HTML entity.
+  #
+  def educate_dashes_oldschool(str)
+    str.
+      gsub(/---/, entity(:em_dash)).
+      gsub(/--/,  entity(:en_dash))
+  end
+
+  # Return the string, with each instance of "<tt>--</tt>" translated
+  # to an em-dash HTML entity, and each "<tt>---</tt>" translated to
+  # an en-dash HTML entity. Two reasons why: First, unlike the en- and
+  # em-dash syntax supported by +educate_dashes_oldschool+, it's
+  # compatible with existing entries written before SmartyPants 1.1,
+  # back when "<tt>--</tt>" was only used for em-dashes.  Second,
+  # em-dashes are more common than en-dashes, and so it sort of makes
+  # sense that the shortcut should be shorter to type. (Thanks to
+  # Aaron Swartz for the idea.)
+  #
+  def educate_dashes_inverted(str)
+    str.
+      gsub(/---/, entity(:en_dash)).
+      gsub(/--/,  entity(:em_dash))
+  end
+
+  # Return the string, with each instance of "<tt>...</tt>" translated
+  # to an ellipsis HTML entity. Also converts the case where there are
+  # spaces between the dots.
+  #
+  def educate_ellipses(str)
+    str.
+      gsub('...',   entity(:ellipsis)).
+      gsub('. . .', entity(:ellipsis))
+  end
+
+  # Return the string, with "<tt>``backticks''</tt>"-style single quotes
+  # translated into HTML curly quote entities.
+  #
+  def educate_backticks(str)
+    str.
+      gsub("``", entity(:double_left_quote)).
+      gsub("''", entity(:double_right_quote))
+  end
+
+  # Return the string, with "<tt>`backticks'</tt>"-style single quotes
+  # translated into HTML curly quote entities.
+  #
+  def educate_single_backticks(str)
+    str.
+      gsub("`", entity(:single_left_quote)).
+      gsub("'", entity(:single_right_quote))
+  end
+
+  # Return the string, with "educated" curly quote HTML entities.
+  #
+  def educate_quotes(str)
+    punct_class = '[!"#\$\%\'()*+,\-.\/:;<=>?\@\[\\\\\]\^_`{|}~]'
+
+    str = str.dup
+
+    # Special case if the very first character is a quote followed by
+    # punctuation at a non-word-break. Close the quotes by brute
+    # force:
+    str.gsub!(/^'(?=#{punct_class}\B)/,
+              entity(:single_right_quote))
+    str.gsub!(/^"(?=#{punct_class}\B)/,
+              entity(:double_right_quote))
+
+    # Special case for double sets of quotes, e.g.:
+    #   <p>He said, "'Quoted' words in a larger quote."</p>
+    str.gsub!(/"'(?=\w)/,
+              "#{entity(:double_left_quote)}#{entity(:single_left_quote)}")
+    str.gsub!(/'"(?=\w)/,
+              "#{entity(:single_left_quote)}#{entity(:double_left_quote)}")
+
+    # Special case for decade abbreviations (the '80s):
+    str.gsub!(/'(?=\d\ds)/,
+              entity(:single_right_quote))
+
+    close_class = %![^\ \t\r\n\\[\{\(\-]!
+    dec_dashes = "#{entity(:en_dash)}|#{entity(:em_dash)}"
+
+    # Get most opening single quotes:
+    str.gsub!(/([[:space:]]|&nbsp;|--|&[mn]dash;|#{dec_dashes}|&#x201[34];)'(?=\w)/,
+             '\1' + entity(:single_left_quote))
+
+    # Single closing quotes:
+    str.gsub!(/(#{close_class})'/,
+              '\1' + entity(:single_right_quote))
+    str.gsub!(/'(\s|s\b|$)/,
+              entity(:single_right_quote) + '\1')
+
+    # Any remaining single quotes should be opening ones:
+    str.gsub!(/'/,
+              entity(:single_left_quote))
+
+    # Get most opening double quotes:
+    str.gsub!(/([[:space:]]|&nbsp;|--|&[mn]dash;|#{dec_dashes}|&#x201[34];)"(?=\w)/,
+             '\1' + entity(:double_left_quote))
+
+    # Double closing quotes:
+    str.gsub!(/(#{close_class})"/,
+              '\1' + entity(:double_right_quote))
+    str.gsub!(/"(\s|s\b|$)/,
+              entity(:double_right_quote) + '\1')
+
+    # Any remaining quotes should be opening ones:
+    str.gsub!(/"/,
+              entity(:double_left_quote))
+
+    str
+  end
+
+  # Return the string, with each RubyPants HTML entity translated to
+  # its ASCII counterpart.
+  #
+  # Note: This is not reversible (but exactly the same as in SmartyPants)
+  #
+  def stupefy_entities(str)
+    new_str = str.dup
+
+    {
+      :en_dash            => '-',
+      :em_dash            => '--',
+      :single_left_quote  => "'",
+      :single_right_quote => "'",
+      :double_left_quote  => '"',
+      :double_right_quote => '"',
+      :ellipsis           => '...'
+    }.each do |k,v|
+      new_str.gsub!(/#{entity(k)}/, v)
+    end
+
+    new_str
+  end
+
+  # Return an array of the tokens comprising the string. Each token is
+  # either a tag (possibly with nested, tags contained therein, such
+  # as <tt><a href="<MTFoo>"></tt>, or a run of text between
+  # tags. Each element of the array is a two-element array; the first
+  # is either :tag or :text; the second is the actual value.
+  #
+  # Based on the <tt>_tokenize()</tt> subroutine from Brad Choate's
+  # MTRegex plugin.  <http://www.bradchoate.com/past/mtregex.php>
+  #
+  # This is actually the easier variant using tag_soup, as used by
+  # Chad Miller in the Python port of SmartyPants.
+  #
+  def tokenize
+    tag_soup = /([^<]*)(<!--.*?-->|<[^>]*>)/
+
+    tokens = []
+
+    prev_end = 0
+
+    scan(tag_soup) do
+      tokens << [:text, $1]  if $1 != ""
+      tokens << [:tag, $2]
+      prev_end = $~.end(0)
+    end
+
+    if prev_end < size
+      tokens << [:text, self[prev_end..-1]]
+    end
+
+    tokens
+  end
+
+  def default_entities
+    {
+      :single_left_quote  => "&#8216;",
+      :double_left_quote  => "&#8220;",
+      :single_right_quote => "&#8217;",
+      :double_right_quote => "&#8221;",
+      :em_dash            => "&#8212;",
+      :en_dash            => "&#8211;",
+      :ellipsis           => "&#8230;",
+      :html_quote         => "&quot;"
+    }
+  end
+
+  def entity(key)
+    @entities[key]
+  end
+end