sundawg_premailer 0.0.1

data/CHANGELOG.rdoc

@@ -0,0 +1,62 @@
+= Premailer CHANGELOG
+
+== Version NEXT
+* strip @import rules from local CSS until CssParser is updated
+* copy related CSS attributes to HTML (inspired by http://github.com/peterbe/premailer/commit/c4f2634a99fc5005011ffde54ae0336ea1497ef5)
+* ignore spaces around links in HREFs
+
+== Version 1.5.4
+* new bin/premailer script
+* added missing htmlentities depenency to gemspec (thanks to http://github.com/usefulthink )
+* fixed handling of unspecified <link> media types
+
+== Version 1.5.3
+ * improved plaintext conversion
+
+== Version 1.5.2
+ * released to GitHub
+ * fixed handling of mailto links
+ * various minor updates
+
+== Version 1.5.1
+ * bugfix (http://code.google.com/p/premailer/issues/detail?id=1 and http://code.google.com/p/premailer/issues/detail?id=2) thanks to Russell Norris 
+ * bugfix (http://code.google.com/p/premailer/issues/detail?id=4) thanks to Dave Holmes 
+
+== Version 1.5.0
+ * preview release of Ruby gem
+
+== Version 1.4
+ * incremental parsing improvements
+ * respect <tt>@media</tt> rule (http://www.w3.org/TR/CSS21/media.html#at-media-rule)
+ * better quote escaping
+
+== Version 1.3
+ * separate CSS parser into its own library
+ * handle <tt>background: red url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mP4%2F58BAAT%2FAf9jgNErAAAAAElFTkSuQmCC);</tt>
+ * preserve <tt>:hover</tt> etc... in head styles
+
+== Version 1.2
+ * respect <tt>LINK</tt> media types
+ * better style folding
+ * incremental parsing improvements
+
+== Version 1.1
+ * proper calculation of selector specificity per CSS 2.1 spec
+ * support for <tt>@import</tt>
+ * preliminary support for shorthand CSS properties (<tt>margin</tt>, <tt>padding</tt>)
+ * preliminary separation of CSS parser
+
+== Version 1.0
+ * ported web interface to eRuby
+ * incremental parsing improvements
+
+== Version 0.9
+ * initial proof-of-concept
+ * PHP web version
+
+== TODO: Future
+ * complete shorthand properties support (<tt>border-width</tt>, <tt>font</tt>, <tt>background</tt>)
+ * UTF-8 and other charsets (test page: http://kianga.kcore.de/2004/09/21/utf8_test)
+ * make warnings for <tt>border</tt> match <tt>border-left</tt>, etc...
+ * Integrate CSS validator
+ * Remove unused classes and IDs

data/LICENSE.rdoc

@@ -0,0 +1,42 @@
+= Premailer License
+
+Copyright (c) 2007-09 Alex Dunae
+
+Premailer is copyrighted free software by Alex Dunae (http://dunae.ca/).
+You can redistribute it and/or modify it under the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to the internet or an equivalent medium, or by 
+	  allowing the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may modify and include the part of the software into any other
+     software (possibly commercial) as long as clear acknowledgement and 
+     a link back to the original software (http://code.dunae.ca/premailer.web/)
+     is provided.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/Manifest

@@ -0,0 +1,26 @@
+CHANGELOG.rdoc
+LICENSE.rdoc
+Manifest
+README.rdoc
+Rakefile
+bin/premailer
+bin/trollop.rb
+init.rb
+lib/premailer.rb
+lib/premailer/html_to_plain_text.rb
+lib/premailer/premailer.rb
+misc/client_support.yaml
+premailer.gemspec
+tests/files/base.html
+tests/files/contact_bg.png
+tests/files/dialect.png
+tests/files/dots_end.png
+tests/files/dots_h.gif
+tests/files/import.css
+tests/files/inc/2009-placeholder.png
+tests/files/noimport.css
+tests/files/styles.css
+tests/test_helper.rb
+tests/test_html_to_plain_text.rb
+tests/test_link_resolver.rb
+tests/test_premailer.rb

data/README.rdoc

@@ -0,0 +1,37 @@
+= Premailer (Sundawg Fork) README
+
+This a small modification to the outstanding gem provided by Alex Dunae.
+
+http://code.dunae.ca/premailer.web/
+
+Please visit the premailer github page for the authoritative guide on how to use premailer:
+
+http://github.com/alexdunae/premailer/
+
+This project was forked on February 8th, 2010 from version 1.5.4.
+
+= Instructions Specific To This Version
+
+This version was created to provide an easier way to perform in-memory css-inlining given a String with HTML content. This was added to provide better integration with existing ActionMailer functionality.
+
+To use premailer with your existing HTML emails, you must change your Action Mailer action as so:
+
+  def hello_world(params)
+    content = Premailer.new(render_message("hello_world.text.html.erb", params), :in_memory => true).to_inline_css
+    subject       "Hello World"
+    recipients    "somebody@somewhere.com" 
+    from          "somebody@sundawg.net" 
+    sent_on       Time.now.utc
+    content_type  "text/html"
+    body          content
+  end
+
+Calling render_message will execute your view template with whatever arguments and models you require for the view to render properly. The additional argument, is :in_memory => true so that premailer does not attempt to perform HTTP GET or load from local disk your view template. Once you have premailer instantiated, you can then call the standard to_inline_css so that your email sends HTML email with the CSS attributes properly in element style attributes.
+
+= Additional Changes
+
+Added echoe gem to help build, package, and install locally this project as a gem.
+
+= Disclaimer
+
+Along with any disclaimer provided with the original software, I have not fully tested to make sure all original functionality continues to work as is.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'fileutils'
+require 'lib/premailer'
+require 'echoe'
+
+desc 'Default: parse a URL.'
+task :default => [:inline]
+
+desc 'Parse a URL and write out the output.'
+task :inline do
+  url = ENV['url']
+  output = ENV['output']
+  
+  if !url or url.empty? or !output or output.empty?
+    puts 'Usage: rake inline url=http://example.com/ output=output.html'
+    exit
+  end
+
+  premailer = Premailer.new(url, :warn_level => Premailer::Warnings::SAFE)
+  fout = File.open(output, "w")
+  fout.puts premailer.to_inline_css
+  fout.close
+
+  puts "Succesfully parsed '#{url}' into '#{output}'"
+  puts premailer.warnings.length.to_s + ' CSS warnings were found'
+end
+
+task :text do
+  url = ENV['url']
+  output = ENV['output']
+  
+  if !url or url.empty? or !output or output.empty?
+    puts 'Usage: rake text url=http://example.com/ output=output.txt'
+    exit
+  end
+
+  premailer = Premailer.new(url, :warn_level => Premailer::Warnings::SAFE)
+  fout = File.open(output, "w")
+  fout.puts premailer.to_plain_text
+  fout.close
+  
+  puts "Succesfully parsed '#{url}' into '#{output}'"
+end
+
+Echoe.new('sundawg_premailer', '0.0.1') do |p|
+  p.description    = "Fork of premailer project to accomodate in memory HTML (http://premailer.dialect.ca/)."
+  p.url            = "http://github.com/SunDawg/premailer"
+  p.author         = "Christopher Sun"
+  p.email          = "christopher.sun@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+  p.runtime_dependencies = ['hpricot >=0.6', 'css_parser >=1.0.0', 'text-reform >=0.2.0', 'htmlentities >=4.0.0']
+end

data/bin/premailer

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+#
+# = Premailer
+require 'trollop'
+require File.join(File.dirname(__FILE__), '../lib/premailer')
+
+opts = Trollop::options do
+  version "Premailer #{Premailer::VERSION} (c) 2008-2009 Alex Dunae"
+  banner <<-EOS
+Improve the rendering of HTML emails by making CSS inline, converting links and warning about unsupported code.
+
+Usage:
+  premailer [options] inputfile [outputfile] [warningsfile]
+
+Example
+  premailer http://example.com/
+  premailer http://example.com/ out.html out.txt warnings.txt
+  premailer --base-url=http://example.com/ src.html out.html
+
+Options:
+EOS
+  opt :base_url, "Manually set the base URL, useful for local files", :type => String
+  opt :query_string, "Query string to append to links", :type => String, :short => 'q'
+  opt :line_length, "Length of lines when creating plaintext version", :type => :int, :default => 65, :short => 'l'
+  opt :remove_classes, "Remove classes from the HTML document?", :default => false
+  opt :css, "Manually specify css stylesheets", :type => String, :multi => true
+  opt :verbose, '', :default => false, :short => 'v'
+end
+
+inputfile    = ARGV.shift
+outfile      = ARGV.shift
+txtfile      = ARGV.shift
+warningsfile = ARGV.shift
+
+Trollop::die "inputfile is missing" if inputfile.nil?
+
+premailer_opts = {
+  :base_url => opts[:base_url],
+  :query_string => opts[:query_string],
+  :show_warnings => opts[:show_warnings] ? Premailer::Warnings::SAFE : Premailer::Warnings::NONE,
+  :line_length => opts[:line_length],
+  :remove_classes => opts[:remove_classes],
+  :css => opts[:css]
+}
+
+premailer = Premailer.new(inputfile, premailer_opts)
+
+# html output
+if outfile
+  fout = File.open(outfile, 'w')
+  fout.puts premailer.to_inline_css
+  fout.close
+else
+  p premailer.to_inline_css
+  exit
+end
+
+# plaintext output
+if txtfile
+  fout = File.open(txtfile, 'w')
+  fout.puts premailer.to_plain_text
+  fout.close
+end
+
+# warnings output
+if warningsfile
+  fout = File.open(warningsfile, 'w')
+  premailer.warnings.each do |w|
+    fout.puts "- #{w[:message]} (#{w[:level]}) may not render properly in #{w[:clients]}"
+  end
+  fout.close
+end

data/bin/trollop.rb

@@ -0,0 +1,739 @@
+## lib/trollop.rb -- trollop command-line processing library
+## Author::    William Morgan (mailto: wmorgan-trollop@masanjin.net)
+## Copyright:: Copyright 2007 William Morgan
+## License::   GNU GPL version 2
+
+require 'date'
+
+module Trollop
+
+VERSION = "1.15"
+
+## Thrown by Parser in the event of a commandline error. Not needed if
+## you're using the Trollop::options entry.
+class CommandlineError < StandardError; end
+  
+## Thrown by Parser if the user passes in '-h' or '--help'. Handled
+## automatically by Trollop#options.
+class HelpNeeded < StandardError; end
+
+## Thrown by Parser if the user passes in '-h' or '--version'. Handled
+## automatically by Trollop#options.
+class VersionNeeded < StandardError; end
+
+## Regex for floating point numbers
+FLOAT_RE = /^-?((\d+(\.\d+)?)|(\.\d+))$/
+
+## Regex for parameters
+PARAM_RE = /^-(-|\.$|[^\d\.])/
+
+## The commandline parser. In typical usage, the methods in this class
+## will be handled internally by Trollop::options. In this case, only the
+## #opt, #banner and #version, #depends, and #conflicts methods will
+## typically be called.
+##
+## If it's necessary to instantiate this class (for more complicated
+## argument-parsing situations), be sure to call #parse to actually
+## produce the output hash.
+class Parser
+
+  ## The set of values that indicate a flag option when passed as the
+  ## +:type+ parameter of #opt.
+  FLAG_TYPES = [:flag, :bool, :boolean]
+
+  ## The set of values that indicate a single-parameter (normal) option when
+  ## passed as the +:type+ parameter of #opt.
+  ##
+  ## A value of +io+ corresponds to a readable IO resource, including
+  ## a filename, URI, or the strings 'stdin' or '-'.
+  SINGLE_ARG_TYPES = [:int, :integer, :string, :double, :float, :io, :date]
+
+  ## The set of values that indicate a multiple-parameter option (i.e., that
+  ## takes multiple space-separated values on the commandline) when passed as
+  ## the +:type+ parameter of #opt.
+  MULTI_ARG_TYPES = [:ints, :integers, :strings, :doubles, :floats, :ios, :dates]
+
+  ## The complete set of legal values for the +:type+ parameter of #opt.
+  TYPES = FLAG_TYPES + SINGLE_ARG_TYPES + MULTI_ARG_TYPES
+
+  INVALID_SHORT_ARG_REGEX = /[\d-]/ #:nodoc:
+
+  ## The values from the commandline that were not interpreted by #parse.
+  attr_reader :leftovers
+
+  ## The complete configuration hashes for each option. (Mainly useful
+  ## for testing.)
+  attr_reader :specs
+
+  ## Initializes the parser, and instance-evaluates any block given.
+  def initialize *a, &b
+    @version = nil
+    @leftovers = []
+    @specs = {}
+    @long = {}
+    @short = {}
+    @order = []
+    @constraints = []
+    @stop_words = []
+    @stop_on_unknown = false
+
+    #instance_eval(&b) if b # can't take arguments
+    cloaker(&b).bind(self).call(*a) if b
+  end
+
+  ## Define an option. +name+ is the option name, a unique identifier
+  ## for the option that you will use internally, which should be a
+  ## symbol or a string. +desc+ is a string description which will be
+  ## displayed in help messages.
+  ##
+  ## Takes the following optional arguments:
+  ##
+  ## [+:long+] Specify the long form of the argument, i.e. the form with two dashes. If unspecified, will be automatically derived based on the argument name by turning the +name+ option into a string, and replacing any _'s by -'s.
+  ## [+:short+] Specify the short form of the argument, i.e. the form with one dash. If unspecified, will be automatically derived from +name+.
+  ## [+:type+] Require that the argument take a parameter or parameters of type +type+. For a single parameter, the value can be a member of +SINGLE_ARG_TYPES+, or a corresponding Ruby class (e.g. +Integer+ for +:int+). For multiple-argument parameters, the value can be any member of +MULTI_ARG_TYPES+ constant. If unset, the default argument type is +:flag+, meaning that the argument does not take a parameter. The specification of +:type+ is not necessary if a +:default+ is given.
+  ## [+:default+] Set the default value for an argument. Without a default value, the hash returned by #parse (and thus Trollop::options) will have a +nil+ value for this key unless the argument is given on the commandline. The argument type is derived automatically from the class of the default value given, so specifying a +:type+ is not necessary if a +:default+ is given. (But see below for an important caveat when +:multi+: is specified too.) If the argument is a flag, and the default is set to +true+, then if it is specified on the the commandline the value will be +false+.
+  ## [+:required+] If set to +true+, the argument must be provided on the commandline.
+  ## [+:multi+] If set to +true+, allows multiple occurrences of the option on the commandline. Otherwise, only a single instance of the option is allowed. (Note that this is different from taking multiple parameters. See below.)
+  ##
+  ## Note that there are two types of argument multiplicity: an argument
+  ## can take multiple values, e.g. "--arg 1 2 3". An argument can also
+  ## be allowed to occur multiple times, e.g. "--arg 1 --arg 2".
+  ##
+  ## Arguments that take multiple values should have a +:type+ parameter
+  ## drawn from +MULTI_ARG_TYPES+ (e.g. +:strings+), or a +:default:+
+  ## value of an array of the correct type (e.g. [String]). The
+  ## value of this argument will be an array of the parameters on the
+  ## commandline.
+  ##
+  ## Arguments that can occur multiple times should be marked with
+  ## +:multi+ => +true+. The value of this argument will also be an array.
+  ## In contrast with regular non-multi options, if not specified on
+  ## the commandline, the default value will be [], not nil.
+  ##
+  ## These two attributes can be combined (e.g. +:type+ => +:strings+,
+  ## +:multi+ => +true+), in which case the value of the argument will be
+  ## an array of arrays.
+  ##
+  ## There's one ambiguous case to be aware of: when +:multi+: is true and a
+  ## +:default+ is set to an array (of something), it's ambiguous whether this
+  ## is a multi-value argument as well as a multi-occurrence argument.
+  ## In thise case, Trollop assumes that it's not a multi-value argument.
+  ## If you want a multi-value, multi-occurrence argument with a default
+  ## value, you must specify +:type+ as well.
+
+  def opt name, desc="", opts={}
+    raise ArgumentError, "you already have an argument named '#{name}'" if @specs.member? name
+
+    ## fill in :type
+    opts[:type] = # normalize
+      case opts[:type]
+      when :boolean, :bool; :flag
+      when :integer; :int
+      when :integers; :ints
+      when :double; :float
+      when :doubles; :floats
+      when Class
+        case opts[:type].name
+        when 'TrueClass', 'FalseClass'; :flag
+        when 'String'; :string
+        when 'Integer'; :int
+        when 'Float'; :float
+        when 'IO'; :io
+        when 'Date'; :date
+        else
+          raise ArgumentError, "unsupported argument type '#{opts[:type].class.name}'"
+        end
+      when nil; nil
+      else
+        raise ArgumentError, "unsupported argument type '#{opts[:type]}'" unless TYPES.include?(opts[:type])
+        opts[:type]
+      end
+
+    ## for options with :multi => true, an array default doesn't imply
+    ## a multi-valued argument. for that you have to specify a :type
+    ## as well. (this is how we disambiguate an ambiguous situation;
+    ## see the docs for Parser#opt for details.)
+    disambiguated_default =
+      if opts[:multi] && opts[:default].is_a?(Array) && !opts[:type]
+        opts[:default].first
+      else
+        opts[:default]
+      end
+
+    type_from_default =
+      case disambiguated_default
+      when Integer; :int
+      when Numeric; :float
+      when TrueClass, FalseClass; :flag
+      when String; :string
+      when IO; :io
+      when Date; :date
+      when Array
+        if opts[:default].empty?
+          raise ArgumentError, "multiple argument type cannot be deduced from an empty array for '#{opts[:default][0].class.name}'"
+        end
+        case opts[:default][0]    # the first element determines the types
+        when Integer; :ints
+        when Numeric; :floats
+        when String; :strings
+        when IO; :ios
+        when Date; :dates
+        else
+          raise ArgumentError, "unsupported multiple argument type '#{opts[:default][0].class.name}'"
+        end
+      when nil; nil
+      else
+        raise ArgumentError, "unsupported argument type '#{opts[:default].class.name}'"
+      end
+
+    raise ArgumentError, ":type specification and default type don't match (default type is #{type_from_default})" if opts[:type] && type_from_default && opts[:type] != type_from_default
+
+    opts[:type] = opts[:type] || type_from_default || :flag
+
+    ## fill in :long
+    opts[:long] = opts[:long] ? opts[:long].to_s : name.to_s.gsub("_", "-")
+    opts[:long] =
+      case opts[:long]
+      when /^--([^-].*)$/
+        $1
+      when /^[^-]/
+        opts[:long]
+      else
+        raise ArgumentError, "invalid long option name #{opts[:long].inspect}"
+      end
+    raise ArgumentError, "long option name #{opts[:long].inspect} is already taken; please specify a (different) :long" if @long[opts[:long]]
+
+    ## fill in :short
+    opts[:short] = opts[:short].to_s if opts[:short] unless opts[:short] == :none
+    opts[:short] = case opts[:short]
+      when /^-(.)$/; $1
+      when nil, :none, /^.$/; opts[:short]
+      else raise ArgumentError, "invalid short option name '#{opts[:short].inspect}'"
+    end
+
+    if opts[:short]
+      raise ArgumentError, "short option name #{opts[:short].inspect} is already taken; please specify a (different) :short" if @short[opts[:short]]
+      raise ArgumentError, "a short option name can't be a number or a dash" if opts[:short] =~ INVALID_SHORT_ARG_REGEX
+    end
+
+    ## fill in :default for flags
+    opts[:default] = false if opts[:type] == :flag && opts[:default].nil?
+
+    ## autobox :default for :multi (multi-occurrence) arguments
+    opts[:default] = [opts[:default]] if opts[:default] && opts[:multi] && !opts[:default].is_a?(Array)
+
+    ## fill in :multi
+    opts[:multi] ||= false
+
+    opts[:desc] ||= desc
+    @long[opts[:long]] = name
+    @short[opts[:short]] = name if opts[:short] && opts[:short] != :none
+    @specs[name] = opts
+    @order << [:opt, name]
+  end
+
+  ## Sets the version string. If set, the user can request the version
+  ## on the commandline. Should probably be of the form "<program name>
+  ## <version number>".
+  def version s=nil; @version = s if s; @version end
+
+  ## Adds text to the help display. Can be interspersed with calls to
+  ## #opt to build a multi-section help page.
+  def banner s; @order << [:text, s] end
+  alias :text :banner
+
+  ## Marks two (or more!) options as requiring each other. Only handles
+  ## undirected (i.e., mutual) dependencies. Directed dependencies are
+  ## better modeled with Trollop::die.
+  def depends *syms
+    syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
+    @constraints << [:depends, syms]
+  end
+  
+  ## Marks two (or more!) options as conflicting.
+  def conflicts *syms
+    syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
+    @constraints << [:conflicts, syms]
+  end
+
+  ## Defines a set of words which cause parsing to terminate when
+  ## encountered, such that any options to the left of the word are
+  ## parsed as usual, and options to the right of the word are left
+  ## intact.
+  ##
+  ## A typical use case would be for subcommand support, where these
+  ## would be set to the list of subcommands. A subsequent Trollop
+  ## invocation would then be used to parse subcommand options, after
+  ## shifting the subcommand off of ARGV.
+  def stop_on *words
+    @stop_words = [*words].flatten
+  end
+
+  ## Similar to #stop_on, but stops on any unknown word when encountered
+  ## (unless it is a parameter for an argument). This is useful for
+  ## cases where you don't know the set of subcommands ahead of time,
+  ## i.e., without first parsing the global options.
+  def stop_on_unknown
+    @stop_on_unknown = true
+  end
+
+  ## Parses the commandline. Typically called by Trollop::options.
+  def parse cmdline=ARGV
+    vals = {}
+    required = {}
+
+    opt :version, "Print version and exit" if @version unless @specs[:version] || @long["version"]
+    opt :help, "Show this message" unless @specs[:help] || @long["help"]
+
+    @specs.each do |sym, opts|
+      required[sym] = true if opts[:required]
+      vals[sym] = opts[:default]
+      vals[sym] = [] if opts[:multi] && !opts[:default] # multi arguments default to [], not nil
+    end
+
+    resolve_default_short_options
+
+    ## resolve symbols
+    given_args = {}
+    @leftovers = each_arg cmdline do |arg, params|
+      sym = case arg
+      when /^-([^-])$/
+        @short[$1]
+      when /^--([^-]\S*)$/
+        @long[$1]
+      else
+        raise CommandlineError, "invalid argument syntax: '#{arg}'"
+      end
+      raise CommandlineError, "unknown argument '#{arg}'" unless sym
+
+      if given_args.include?(sym) && !@specs[sym][:multi]
+        raise CommandlineError, "option '#{arg}' specified multiple times"
+      end
+
+      given_args[sym] ||= {}
+
+      given_args[sym][:arg] = arg
+      given_args[sym][:params] ||= []
+
+      # The block returns the number of parameters taken.
+      num_params_taken = 0
+
+      unless params.nil?
+        if SINGLE_ARG_TYPES.include?(@specs[sym][:type])
+          given_args[sym][:params] << params[0, 1]  # take the first parameter
+          num_params_taken = 1
+        elsif MULTI_ARG_TYPES.include?(@specs[sym][:type])
+          given_args[sym][:params] << params        # take all the parameters
+          num_params_taken = params.size
+        end
+      end
+
+      num_params_taken
+    end
+
+    ## check for version and help args
+    raise VersionNeeded if given_args.include? :version
+    raise HelpNeeded if given_args.include? :help
+
+    ## check constraint satisfaction
+    @constraints.each do |type, syms|
+      constraint_sym = syms.find { |sym| given_args[sym] }
+      next unless constraint_sym
+
+      case type
+      when :depends
+        syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym][:long]} requires --#{@specs[sym][:long]}" unless given_args.include? sym }
+      when :conflicts
+        syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym][:long]} conflicts with --#{@specs[sym][:long]}" if given_args.include?(sym) && (sym != constraint_sym) }
+      end
+    end
+
+    required.each do |sym, val|
+      raise CommandlineError, "option '#{sym}' must be specified" unless given_args.include? sym
+    end
+
+    ## parse parameters
+    given_args.each do |sym, given_data|
+      arg = given_data[:arg]
+      params = given_data[:params]
+
+      opts = @specs[sym]
+      raise CommandlineError, "option '#{arg}' needs a parameter" if params.empty? && opts[:type] != :flag
+
+      vals["#{sym}_given".intern] = true # mark argument as specified on the commandline
+
+      case opts[:type]
+      when :flag
+        vals[sym] = !opts[:default]
+      when :int, :ints
+        vals[sym] = params.map { |pg| pg.map { |p| parse_integer_parameter p, arg } }
+      when :float, :floats
+        vals[sym] = params.map { |pg| pg.map { |p| parse_float_parameter p, arg } }
+      when :string, :strings
+        vals[sym] = params.map { |pg| pg.map { |p| p.to_s } }
+      when :io, :ios
+        vals[sym] = params.map { |pg| pg.map { |p| parse_io_parameter p, arg } }
+      when :date, :dates
+        vals[sym] = params.map { |pg| pg.map { |p| parse_date_parameter p, arg } }
+      end
+
+      if SINGLE_ARG_TYPES.include?(opts[:type])
+        unless opts[:multi]       # single parameter
+          vals[sym] = vals[sym][0][0]
+        else                      # multiple options, each with a single parameter
+          vals[sym] = vals[sym].map { |p| p[0] }
+        end
+      elsif MULTI_ARG_TYPES.include?(opts[:type]) && !opts[:multi]
+        vals[sym] = vals[sym][0]  # single option, with multiple parameters
+      end
+      # else: multiple options, with multiple parameters
+    end
+
+    ## allow openstruct-style accessors
+    class << vals
+      def method_missing(m, *args)
+        self[m] || self[m.to_s]
+      end
+    end
+    vals
+  end
+
+  def parse_date_parameter param, arg #:nodoc:
+    begin
+      begin
+        time = Chronic.parse(param)
+      rescue NameError
+        # chronic is not available
+      end
+      time ? Date.new(time.year, time.month, time.day) : Date.parse(param)
+    rescue ArgumentError => e
+      raise CommandlineError, "option '#{arg}' needs a date"
+    end
+  end
+
+  ## Print the help message to +stream+.
+  def educate stream=$stdout
+    width # just calculate it now; otherwise we have to be careful not to
+          # call this unless the cursor's at the beginning of a line.
+
+    left = {}
+    @specs.each do |name, spec| 
+      left[name] = "--#{spec[:long]}" +
+        (spec[:short] && spec[:short] != :none ? ", -#{spec[:short]}" : "") +
+        case spec[:type]
+        when :flag; ""
+        when :int; " <i>"
+        when :ints; " <i+>"
+        when :string; " <s>"
+        when :strings; " <s+>"
+        when :float; " <f>"
+        when :floats; " <f+>"
+        when :io; " <filename/uri>"
+        when :ios; " <filename/uri+>"
+        when :date; " <date>"
+        when :dates; " <date+>"
+        end
+    end
+
+    leftcol_width = left.values.map { |s| s.length }.max || 0
+    rightcol_start = leftcol_width + 6 # spaces
+
+    unless @order.size > 0 && @order.first.first == :text
+      stream.puts "#@version\n" if @version
+      stream.puts "Options:"
+    end
+
+    @order.each do |what, opt|
+      if what == :text
+        stream.puts wrap(opt)
+        next
+      end
+
+      spec = @specs[opt]
+      stream.printf "  %#{leftcol_width}s:   ", left[opt]
+      desc = spec[:desc] + begin
+        default_s = case spec[:default]
+        when $stdout; "<stdout>"
+        when $stdin; "<stdin>"
+        when $stderr; "<stderr>"
+        when Array
+          spec[:default].join(", ")
+        else
+          spec[:default].to_s
+        end
+
+        if spec[:default]
+          if spec[:desc] =~ /\.$/
+            " (Default: #{default_s})"
+          else
+            " (default: #{default_s})"
+          end
+        else
+          ""
+        end
+      end
+      stream.puts wrap(desc, :width => width - rightcol_start - 1, :prefix => rightcol_start)
+    end
+  end
+
+  def width #:nodoc:
+    @width ||= if $stdout.tty?
+      begin
+        require 'curses'
+        Curses::init_screen
+        x = Curses::cols
+        Curses::close_screen
+        x
+      rescue Exception
+        80
+      end
+    else
+      80
+    end
+  end
+
+  def wrap str, opts={} # :nodoc:
+    if str == ""
+      [""]
+    else
+      str.split("\n").map { |s| wrap_line s, opts }.flatten
+    end
+  end
+
+private
+
+  ## yield successive arg, parameter pairs
+  def each_arg args
+    remains = []
+    i = 0
+
+    until i >= args.length
+      if @stop_words.member? args[i]
+        remains += args[i .. -1]
+        return remains
+      end
+      case args[i]
+      when /^--$/ # arg terminator
+        remains += args[(i + 1) .. -1]
+        return remains
+      when /^--(\S+?)=(.*)$/ # long argument with equals
+        yield "--#{$1}", [$2]
+        i += 1
+      when /^--(\S+)$/ # long argument
+        params = collect_argument_parameters(args, i + 1)
+        unless params.empty?
+          num_params_taken = yield args[i], params
+          unless num_params_taken
+            if @stop_on_unknown
+              remains += args[i + 1 .. -1]
+              return remains
+            else
+              remains += params
+            end
+          end
+          i += 1 + num_params_taken
+        else # long argument no parameter
+          yield args[i], nil
+          i += 1
+        end
+      when /^-(\S+)$/ # one or more short arguments
+        shortargs = $1.split(//)
+        shortargs.each_with_index do |a, j|
+          if j == (shortargs.length - 1)
+            params = collect_argument_parameters(args, i + 1)
+            unless params.empty?
+              num_params_taken = yield "-#{a}", params
+              unless num_params_taken
+                if @stop_on_unknown
+                  remains += args[i + 1 .. -1]
+                  return remains
+                else
+                  remains += params
+                end
+              end
+              i += 1 + num_params_taken
+            else # argument no parameter
+              yield "-#{a}", nil
+              i += 1
+            end
+          else
+            yield "-#{a}", nil
+          end
+        end
+      else
+        if @stop_on_unknown
+          remains += args[i .. -1]
+          return remains
+        else
+          remains << args[i]
+          i += 1
+        end
+      end
+    end
+
+    remains
+  end
+
+  def parse_integer_parameter param, arg
+    raise CommandlineError, "option '#{arg}' needs an integer" unless param =~ /^\d+$/
+    param.to_i
+  end
+
+  def parse_float_parameter param, arg
+    raise CommandlineError, "option '#{arg}' needs a floating-point number" unless param =~ FLOAT_RE
+    param.to_f
+  end
+
+  def parse_io_parameter param, arg
+    case param
+    when /^(stdin|-)$/i; $stdin
+    else
+      require 'open-uri'
+      begin
+        open param
+      rescue SystemCallError => e
+        raise CommandlineError, "file or url for option '#{arg}' cannot be opened: #{e.message}"
+      end
+    end
+  end
+
+  def collect_argument_parameters args, start_at
+    params = []
+    pos = start_at
+    while args[pos] && args[pos] !~ PARAM_RE && !@stop_words.member?(args[pos]) do
+      params << args[pos]
+      pos += 1
+    end
+    params
+  end
+
+  def resolve_default_short_options
+    @order.each do |type, name|
+      next unless type == :opt
+      opts = @specs[name]
+      next if opts[:short]
+
+      c = opts[:long].split(//).find { |d| d !~ INVALID_SHORT_ARG_REGEX && !@short.member?(d) }
+      if c # found a character to use
+        opts[:short] = c
+        @short[c] = name
+      end
+    end
+  end
+
+  def wrap_line str, opts={}
+    prefix = opts[:prefix] || 0
+    width = opts[:width] || (self.width - 1)
+    start = 0
+    ret = []
+    until start > str.length
+      nextt = 
+        if start + width >= str.length
+          str.length
+        else
+          x = str.rindex(/\s/, start + width)
+          x = str.index(/\s/, start) if x && x < start
+          x || str.length
+        end
+      ret << (ret.empty? ? "" : " " * prefix) + str[start ... nextt]
+      start = nextt + 1
+    end
+    ret
+  end
+
+  ## instance_eval but with ability to handle block arguments
+  ## thanks to why: http://redhanded.hobix.com/inspect/aBlockCostume.html
+  def cloaker &b
+    (class << self; self; end).class_eval do
+      define_method :cloaker_, &b
+      meth = instance_method :cloaker_
+      remove_method :cloaker_
+      meth
+    end
+  end
+end
+
+## The top-level entry method into Trollop. Creates a Parser object,
+## passes the block to it, then parses +args+ with it, handling any
+## errors or requests for help or version information appropriately (and
+## then exiting). Modifies +args+ in place. Returns a hash of option
+## values.
+##
+## The block passed in should contain zero or more calls to +opt+
+## (Parser#opt), zero or more calls to +text+ (Parser#text), and
+## probably a call to +version+ (Parser#version).
+##
+## The returned block contains a value for every option specified with
+## +opt+.  The value will be the value given on the commandline, or the
+## default value if the option was not specified on the commandline. For
+## every option specified on the commandline, a key "<option
+## name>_given" will also be set in the hash.
+##
+## Example:
+##
+##   require 'trollop'
+##   opts = Trollop::options do
+##     opt :monkey, "Use monkey mode"                     # a flag --monkey, defaulting to false
+##     opt :goat, "Use goat mode", :default => true       # a flag --goat, defaulting to true
+##     opt :num_limbs, "Number of limbs", :default => 4   # an integer --num-limbs <i>, defaulting to 4
+##     opt :num_thumbs, "Number of thumbs", :type => :int # an integer --num-thumbs <i>, defaulting to nil
+##   end
+##
+##   ## if called with no arguments
+##   p opts # => { :monkey => false, :goat => true, :num_limbs => 4, :num_thumbs => nil }
+##
+##   ## if called with --monkey
+##   p opts # => {:monkey_given=>true, :monkey=>true, :goat=>true, :num_limbs=>4, :help=>false, :num_thumbs=>nil}
+##
+## See more examples at http://trollop.rubyforge.org.
+def options args = ARGV, *a, &b
+  @p = Parser.new(*a, &b)
+  begin
+    vals = @p.parse args
+    args.clear
+    @p.leftovers.each { |l| args << l }
+    vals
+  rescue CommandlineError => e
+    $stderr.puts "Error: #{e.message}."
+    $stderr.puts "Try --help for help."
+    exit(-1)
+  rescue HelpNeeded
+    @p.educate
+    exit
+  rescue VersionNeeded
+    puts @p.version
+    exit
+  end
+end
+
+## Informs the user that their usage of 'arg' was wrong, as detailed by
+## 'msg', and dies. Example:
+##
+##   options do
+##     opt :volume, :default => 0.0
+##   end
+##
+##   die :volume, "too loud" if opts[:volume] > 10.0
+##   die :volume, "too soft" if opts[:volume] < 0.1
+##
+## In the one-argument case, simply print that message, a notice
+## about -h, and die. Example:
+##
+##   options do
+##     opt :whatever # ...
+##   end
+##
+##   Trollop::die "need at least one filename" if ARGV.empty?
+def die arg, msg=nil
+  if msg
+    $stderr.puts "Error: argument --#{@p.specs[arg][:long]} #{msg}."
+  else
+    $stderr.puts "Error: #{arg}."
+  end
+  $stderr.puts "Try --help for help."
+  exit(-1)
+end
+
+module_function :options, :die
+
+end # module