sinatra-support 1.0.1

data/HISTORY.md

@@ -0,0 +1,53 @@
+v1.0.1 - Mar 27, 2011
+---------------------
+
+### Added:
+  * Implement Sinatra::I18nSupport
+
+### Misc:
+  * Update README with URLs
+  * Correct the wrong gem name in the documentation
+
+v1.0.0 - Mar 27, 2011
+---------------------
+
+Massive 1.0 refactor and massive documentation update. Now sporting a
+completely new API and breaks compatibility with 0.2.0.
+
+### Added:
+  * CssSupport
+  * JsSupport
+  * IfHelpers
+
+v0.2.0
+------
+
+### Fixed:
+  * documentation for private objects / methods
+
+### Added:
+  * currency helpers with tests and documentation
+  * day_choices
+  * full docs to all helper methods
+  * link to docs
+
+### Removed:
+  * old sinatra-helpers files
+
+### Changed:
+  * Allow descending year_choices
+  * change how tag works for self_closing
+  * Initial renamed sprint from sinatra-helpers
+  * Tweak documentation for Methods.rb and load order
+  * select option tweaks
+
+v0.1.1
+------
+
+### Changed:
+  * some tweaks for ruby1.8.6 compat
+
+v0.1.0
+------
+
+Initial version.

data/Rakefile

@@ -0,0 +1,7 @@
+task(:test) {
+  Dir['./test/**/test_*.rb'].each { |f| load f }
+}
+
+task(:update_doc) {
+  system "yard && cd doc && git add . && git add -u && git commit -m . && git push"
+}

data/lib/sinatra/support/compat-1.8.6.rb

@@ -0,0 +1,30 @@
+# Taken from ohm
+
+unless "".respond_to?(:lines)
+  # @private 1.8.6 compatibility only
+  class String
+    # @private
+    # This version of String#lines is almost fully compatible with that
+    # of Ruby 1.9. If a zero-length record separator is supplied in Ruby
+    # 1.9, the string is split into paragraphs delimited by multiple
+    # successive newlines. This replacement ignores that feature in
+    # favor of code simplicity.
+    def lines(separator = $/)
+      result = split(separator).map { |part| "#{part}#{separator}" }
+      result.each { |r| yield r } if block_given?
+      result
+    end
+  end
+end
+
+unless respond_to?(:tap)
+  # @private 1.8.6 compatibility only
+  class Object
+    # @private no need to explain. Standard ruby 1.9 stuff.
+    # @see http://ruby-doc.org/ruby-1.9/classes/Object.html#M000239
+    def tap
+      yield(self)
+      self
+    end
+  end
+end

data/lib/sinatra/support/country.rb

@@ -0,0 +1,300 @@
+# encoding: UTF-8
+
+# A simple module containing all countries as of 2010.
+# 
+module Sinatra::Country
+  @all = {
+    :AF => "Afghanistan",
+    :AX => "Åland Islands",
+    :AL => "Albania",
+    :DZ => "Algeria",
+    :AS => "American Samoa",
+    :AD => "Andorra",
+    :AO => "Angola",
+    :AI => "Anguilla",
+    :AQ => "Antarctica",
+    :AG => "Antigua and Barbuda",
+    :AR => "Argentina",
+    :AM => "Armenia",
+    :AW => "Aruba",
+    :AU => "Australia",
+    :AT => "Austria",
+    :AZ => "Azerbaijan",
+    :BS => "Bahamas",
+    :BH => "Bahrain",
+    :BD => "Bangladesh",
+    :BB => "Barbados",
+    :BY => "Belarus",
+    :BE => "Belgium",
+    :BZ => "Belize",
+    :BJ => "Benin",
+    :BM => "Bermuda",
+    :BT => "Bhutan",
+    :BO => "Bolivia, Plurinational State of",
+    :BA => "Bosnia and Herzegovina",
+    :BW => "Botswana",
+    :BV => "Bouvet Island",
+    :BR => "Brazil",
+    :IO => "British Indian Ocean Territory",
+    :BN => "Brunei Darussalam",
+    :BG => "Bulgaria",
+    :BF => "Burkina Faso",
+    :BI => "Burundi",
+    :KH => "Cambodia",
+    :CM => "Cameroon",
+    :CA => "Canada",
+    :CV => "Cape Verde",
+    :KY => "Cayman Islands",
+    :CF => "Central African Republic",
+    :TD => "Chad",
+    :CL => "Chile",
+    :CN => "China",
+    :CX => "Christmas Island",
+    :CC => "Cocos (Keeling) Islands",
+    :CO => "Colombia",
+    :KM => "Comoros",
+    :CG => "Congo",
+    :CD => "Congo, the Democratic Republic of the",
+    :CK => "Cook Islands",
+    :CR => "Costa Rica",
+    :CI => "CÔte D'ivoire",
+    :HR => "Croatia",
+    :CU => "Cuba",
+    :CY => "Cyprus",
+    :CZ => "Czech Republic",
+    :DK => "Denmark",
+    :DJ => "Djibouti",
+    :DM => "Dominica",
+    :DO => "Dominican Republic",
+    :EC => "Ecuador",
+    :EG => "Egypt",
+    :SV => "El Salvador",
+    :GQ => "Equatorial Guinea",
+    :ER => "Eritrea",
+    :EE => "Estonia",
+    :ET => "Ethiopia",
+    :FK => "Falkland Islands (Malvinas)",
+    :FO => "Faroe Islands",
+    :FJ => "Fiji",
+    :FI => "Finland",
+    :FR => "France",
+    :GF => "French Guiana",
+    :PF => "French Polynesia",
+    :TF => "French Southern Territories",
+    :GA => "Gabon",
+    :GM => "Gambia",
+    :GE => "Georgia",
+    :DE => "Germany",
+    :GH => "Ghana",
+    :GI => "Gibraltar",
+    :GR => "Greece",
+    :GL => "Greenland",
+    :GD => "Grenada",
+    :GP => "Guadeloupe",
+    :GU => "Guam",
+    :GT => "Guatemala",
+    :GG => "Guernsey",
+    :GN => "Guinea",
+    :GW => "Guinea-bissau",
+    :GY => "Guyana",
+    :HT => "Haiti",
+    :HM => "Heard Island and Mcdonald Islands",
+    :VA => "Holy See (Vatican City State)",
+    :HN => "Honduras",
+    :HK => "Hong Kong",
+    :HU => "Hungary",
+    :IS => "Iceland",
+    :IN => "India",
+    :ID => "Indonesia",
+    :IR => "Iran, Islamic Republic of",
+    :IQ => "Iraq",
+    :IE => "Ireland",
+    :IM => "Isle of Man",
+    :IL => "Israel",
+    :IT => "Italy",
+    :JM => "Jamaica",
+    :JP => "Japan",
+    :JE => "Jersey",
+    :JO => "Jordan",
+    :KZ => "Kazakhstan",
+    :KE => "Kenya",
+    :KI => "Kiribati",
+    :KP => "Korea, Democratic People's Republic of",
+    :KR => "Korea, Republic of",
+    :KW => "Kuwait",
+    :KG => "Kyrgyzstan",
+    :LA => "Lao People's Democratic Republic",
+    :LV => "Latvia",
+    :LB => "Lebanon",
+    :LS => "Lesotho",
+    :LR => "Liberia",
+    :LY => "Libyan Arab Jamahiriya",
+    :LI => "Liechtenstein",
+    :LT => "Lithuania",
+    :LU => "Luxembourg",
+    :MO => "Macao",
+    :MK => "Macedonia, the Former Yugoslav Republic of",
+    :MG => "Madagascar",
+    :MW => "Malawi",
+    :MY => "Malaysia",
+    :MV => "Maldives",
+    :ML => "Mali",
+    :MT => "Malta",
+    :MH => "Marshall Islands",
+    :MQ => "Martinique",
+    :MR => "Mauritania",
+    :MU => "Mauritius",
+    :YT => "Mayotte",
+    :MX => "Mexico",
+    :FM => "Micronesia, Federated States of",
+    :MD => "Moldova, Republic of",
+    :MC => "Monaco",
+    :MN => "Mongolia",
+    :ME => "Montenegro",
+    :MS => "Montserrat",
+    :MA => "Morocco",
+    :MZ => "Mozambique",
+    :MM => "Myanmar",
+    :NA => "Namibia",
+    :NR => "Nauru",
+    :NP => "Nepal",
+    :NL => "Netherlands",
+    :AN => "Netherlands Antilles",
+    :NC => "New Caledonia",
+    :NZ => "New Zealand",
+    :NI => "Nicaragua",
+    :NE => "Niger",
+    :NG => "Nigeria",
+    :NU => "Niue",
+    :NF => "Norfolk Island",
+    :MP => "Northern Mariana Islands",
+    :NO => "Norway",
+    :OM => "Oman",
+    :PK => "Pakistan",
+    :PW => "Palau",
+    :PS => "Palestinian Territory, Occupied",
+    :PA => "Panama",
+    :PG => "Papua New Guinea",
+    :PY => "Paraguay",
+    :PE => "Peru",
+    :PH => "Philippines",
+    :PN => "Pitcairn",
+    :PL => "Poland",
+    :PT => "Portugal",
+    :PR => "Puerto Rico",
+    :QA => "Qatar",
+    :RE => "RÉunion",
+    :RO => "Romania",
+    :RU => "Russian Federation",
+    :RW => "Rwanda",
+    :BL => "Saint BarthÉlemy",
+    :SH => "Saint Helena, Ascension and Tristan Da Cunha",
+    :KN => "Saint Kitts and Nevis",
+    :LC => "Saint Lucia",
+    :MF => "Saint Martin",
+    :PM => "Saint Pierre and Miquelon",
+    :VC => "Saint Vincent and the Grenadines",
+    :WS => "Samoa",
+    :SM => "San Marino",
+    :ST => "Sao Tome and Principe",
+    :SA => "Saudi Arabia",
+    :SN => "Senegal",
+    :RS => "Serbia",
+    :SC => "Seychelles",
+    :SL => "Sierra Leone",
+    :SG => "Singapore",
+    :SK => "Slovakia",
+    :SI => "Slovenia",
+    :SB => "Solomon Islands",
+    :SO => "Somalia",
+    :ZA => "South Africa",
+    :GS => "South Georgia and the South Sandwich Islands",
+    :ES => "Spain",
+    :LK => "Sri Lanka",
+    :SD => "Sudan",
+    :SR => "Suriname",
+    :SJ => "Svalbard and Jan Mayen",
+    :SZ => "Swaziland",
+    :SE => "Sweden",
+    :CH => "Switzerland",
+    :SY => "Syrian Arab Republic",
+    :TW => "Taiwan, Province of China",
+    :TJ => "Tajikistan",
+    :TZ => "Tanzania, United Republic of",
+    :TH => "Thailand",
+    :TL => "Timor-leste",
+    :TG => "Togo",
+    :TK => "Tokelau",
+    :TO => "Tonga",
+    :TT => "Trinidad and Tobago",
+    :TN => "Tunisia",
+    :TR => "Turkey",
+    :TM => "Turkmenistan",
+    :TC => "Turks and Caicos Islands",
+    :TV => "Tuvalu",
+    :UG => "Uganda",
+    :UA => "Ukraine",
+    :AE => "United Arab Emirates",
+    :GB => "United Kingdom",
+    :US => "United States",
+    :UM => "United States Minor Outlying Islands",
+    :UY => "Uruguay",
+    :UZ => "Uzbekistan",
+    :VU => "Vanuatu",
+    :VA => "Vatican City State",
+    :VE => "Venezuela, Bolivarian Republic of",
+    :VN => "Viet Nam",
+    :VG => "Virgin Islands, British",
+    :VI => "Virgin Islands, U.S.",
+    :WF => "Wallis and Futuna",
+    :EH => "Western Sahara",
+    :YE => "Yemen",
+    :ZM => "Zambia",
+    :ZW => "Zimbabwe"
+  }
+  
+  # @example
+  #   
+  #   p Country.to_select
+  #   [["Afghanistan", "AF"], ["Åland Islands", "AX"], ["Albania", "AL"], 
+  #   ["Algeria", "DZ"], ["American Samoa", "AS"], ... ["Zimbabwe", "ZW"]]
+  #
+  # @return [Array] a collection of pairs with the first element being 
+  #                 country name and the last element being the code.
+  #
+  # @see Sinatra#country_choices
+  def to_select
+    all.map { |code, name| [name, code.to_s] }
+  end
+  
+  # Retrieves the country name given a country code.
+  # @example
+  #   
+  #   Sinatra::Country["US"] == "United States"
+  #   # => true
+  #
+  #   Sinatra::Country[:US] == "United States"
+  #   # => true
+  #
+  # @param [#to_sym] code The country code in 2 letter all caps format.
+  # @return [String] The corresponding country name given the code.
+  # @return [nil] nil if no matching country code.
+  def [](code)
+    all[code.to_sym]  if not code.to_s.empty?
+  end
+  
+  # For use with seeding dummy data.
+  # @return [Symbol] a randomized country code.
+  def random
+    all.keys.shuffle.first
+  end
+  
+  # Gives all countries in a Hash.
+  #
+  # @return [Hash] the code => name pairs of all countries.
+  def all
+    @all
+  end
+
+  module_function :all, :to_select, :[], :random
+end

data/lib/sinatra/support/countryhelpers.rb

@@ -0,0 +1,28 @@
+require File.expand_path('../country', __FILE__)
+
+# Country helpers.
+#
+#   require 'sinatra/support/countryhelpers'
+#   require 'sinatra/support/htmlhelpers'
+#
+#   class Main < Sinatra::Base
+#     helpers Sinatra::HtmlHelpers
+#     helpers Sinatra::CountryHelpers
+#   end
+#
+# == Helpers
+#
+# Provides the following helpers:
+#
+# === {#country_choices country_choices} - Country choices for select_options.
+#
+#   <!-- A dropdown box of countries. -->
+#   <select name="country">
+#     <%= select_options country_choices %>
+#   </select>
+#
+module Sinatra::CountryHelpers
+  def country_choices
+    Sinatra::Country.to_select
+  end
+end

data/lib/sinatra/support/csssupport.rb

@@ -0,0 +1,58 @@
+# Support for Sass/SCSS/Less.
+#
+# == Usage
+#
+#   require 'sinatra/support/csssupport'
+#
+# Use {#serve_css} in the Sinatra DSL to serve up files.
+#
+#   register Sinatra::CssSupport
+#   serve_css '/styles', from: './app/css'
+#
+# Assuming you have a +app/css/print.scss+ file, you will
+# then be able to access it from the given URL prefix.
+#
+#   $ curl "http://localhost:4567/styles/print.css"
+#
+# This plugin supports Sass, Less and SCSS and guesses by the
+# file name.
+#
+# == Caveats
+#
+# Note that you will need to set your Sass/SCSS +load_path+ settings.
+#
+#   Main.configure do |m|
+#     m.set :scss, {
+#       :load_paths => [ 'app/css' ]
+#     }
+#     m.set :scss, self.scss.merge(:style => :compressed) if m.production?
+#   end
+#
+module Sinatra::CssSupport
+  def self.registered(app)
+    app.set :css_max_age, app.development? ? 0 : 86400*30
+  end
+
+  def serve_css(url_prefix, options={})
+    path   = File.join(url_prefix, '*.css')
+    prefix = options[:from]
+
+    get path do |name|
+      fname = Dir[File.join(prefix, "#{name}.{css,scss,less}")].first  or pass
+
+      content_type :css, :charset => 'utf-8'
+      last_modified File.mtime(fname)
+      cache_control :public, :must_revalidate, :max_age => settings.css_max_age
+
+      if fname =~ /\.scss$/
+        scss File.read(fname)
+      elsif fname =~ /\.scss$/
+        sass File.read(fname)
+      elsif fname =~ /\.less$/
+        less File.read(fname)
+      else
+        send_file fname
+      end
+    end
+  end
+end

data/lib/sinatra/support/dateforms.rb

@@ -0,0 +1,145 @@
+require File.expand_path('../compat-1.8.6.rb', __FILE__)
+
+# Date helpers.
+#
+#   require 'sinatra/support/dateforms'
+#
+#   class Main < Sinatra::Base
+#     register Sinatra::DateForms
+#   end
+#
+# == Helpers
+#
+# This plugin provides the following helpers:
+#
+# === {Helpers#month_choices month_choices} - Provides month choices for dropdowns.
+#
+#  <select name="birthday[month]">
+#    <%= month_choices %>
+#  </select>
+#  
+# === {Helpers#day_choices day_choices} - Day choices.
+#
+#  <select name="birthday[day]">
+#    <%= day_choices %>
+#  </select>
+#
+# === {Helpers#year_choices year_choices} - Year dropdown.
+#
+#  <select name="birthday[year]">
+#    <%= year_choices %>
+#  </select>
+#  
+# == Settings
+# 
+# Provides the following settings in your application:
+#
+# [+default_year_loffset+]   (Numeric) How many years back to display.
+#                            Defaults to +-60+.
+# [+default_year_loffset+]   (Numeric) How many years forward. Defaults
+#                            to +0+.
+# [+default_month_names+]    (Array) The names of the months. Defaults
+#                            To +Date::MONTHNAMES+.
+#
+# You may change them like this:
+#
+#   Main.configure do |m|
+#     m.set :default_year_loffset, -60 
+#     m.set :default_year_uoffset, 0
+#     m.set :default_month_names, Date::MONTHNAMES
+#   end
+#
+module Sinatra::DateForms
+  def self.registered(app)
+    app.set :default_year_loffset, -60
+    app.set :default_year_uoffset, 0
+    app.set :default_month_names, Date::MONTHNAMES
+
+    app.helpers Helpers
+  end
+
+  module Helpers
+    # Returns an array of date pairs. Best used with
+    # {Sinatra::HtmlHelpers#select_options}.
+    #
+    # @return [Array] the array of day, day pairs.
+    #
+    # @example This is perfect for @select_options@.
+    #
+    #   <select name="date">
+    #     <%= select_options day_choices %>
+    #
+    # An example output looks like:
+    #
+    #   - [1, 1]
+    #   - [2, 2]
+    #   - ...
+    #   - [31, 31]
+    #
+    def day_choices(max=31)
+      days = (1..max).to_a
+      days.zip(days)
+    end
+    
+    # Returns an array of pairs.
+    #
+    # You may pass in @Date::ABBR_MONTHNAMES@ if you want the shortened month 
+    # names.
+    #
+    # @example output
+    #
+    #   - ['January', 1]
+    #   - ['February', 2]
+    #   - ...
+    #   - ['December', 12]
+    #
+    # @param  [Array] month_names (defaults to Date::MONTHNAMES) an array with the
+    #                 first element being nil, element 1 being January, etc.
+    # @return [Array] the array of month name, month pairs.
+    def month_choices(month_names = settings.default_month_names)
+      month_names.map.
+        with_index { |month, idx| [month, idx] }.
+        tap        { |arr| arr.shift }
+    end
+
+    # Returns an array of pairs.
+    #
+    # @example Output
+    #
+    #   - [2005, 2005]
+    #   - [2006, 2006]
+    #   - ...
+    #   - [2010, 2010]
+    #
+    # @example
+    #
+    #   year_choices # assuming it's now 2010
+    #   # => [[1950, 1950], ..., [2010, 2010]]
+    #
+    #   # we can pass in options
+    #   year_choices(0, 6) # like for credit card options
+    #   # => [[2010, 2010], ..., [2016, 2016]]
+    #
+    #   # also we can override settings at the app level
+    #   set :default_year_loffset, 0
+    #   set :default_year_uoffset, 6
+    #   year_choices
+    #   # => [[2010, 2010], ..., [2016, 2016]]
+    #
+    # @param [Fixnum] loffset (defaults to -60) The lower offset relative to the current year.
+    #                 If it's 2010 now, passing in -5 here will start the year
+    #                 list at 2005 for example.
+    # @param [Fixnum] uoffset (defaults to 0) The upper offset relative to the 
+    #                 current year. If it's 2010 now, passing in 5 or +5 here 
+    #                 will end the year list at 2015 for example.
+    # @return [Array] the array of year, year pairs.
+    #
+    def year_choices(loffset = settings.default_year_loffset, uoffset = settings.default_year_uoffset)
+      start  = loffset + Date.today.year
+      finish = uoffset + Date.today.year
+      
+      enum   = start < finish ? start.upto(finish) : start.downto(finish)
+      enum.map { |e| [e, e] }
+    end
+  end
+end

data/lib/sinatra/support/errorhelpers.rb

@@ -0,0 +1,62 @@
+# Ohm error helpers.
+#
+# == Usage
+#
+#   # Only for those who use Ohm and HAML
+#   require 'ohm'
+#   require 'haml'
+#
+#   require 'sinatra/support/ohmerrorhelpers'
+#
+#   class Main < Sinatra::Base
+#     helpers Sinatra::OhmErrorHelpers
+#   end
+#
+# == Common usage
+#   
+#   - errors_on @user do |e|
+#     - e.on [:email, :not_present], "We need your email address."
+#     - e.on [:password, :not_present], "You must specify a password."
+#
+#   # produces the following:
+#   # <div class="errors">
+#   #   <ul>
+#   #     <li>We need your email address</li>
+#   #     <li>You must specify a password.</li>
+#   #   </ul>
+#   # </div>
+#
+module Sinatra::OhmErrorHelpers
+  # Presents errors on your form. Takes the explicit approach and assumes
+  # that for every form you have, the copy for the errors are important,
+  # instead of producing canned responses.
+  #
+  # @param [#errors] object An object responding to #errors. This validation
+  #                  also checks for the presence of a #full_messages method
+  #                  in the errors object for compatibility with 
+  #                  ActiveRecord style objects.
+  # @param [Hash] options a hash of HTML attributes to place on the
+  #               containing div.
+  # @option options [#to_s] :class (defaults to errors) The css class to put 
+  #                                in the div.
+  #
+  # @yield [Sinatra::Support::HamlErrorPresenter] an object responding to #on.
+  #
+  def errors_on(object, options = { :class => 'errors' }, &block)
+    return if object.errors.empty?
+
+    lines = if object.errors.respond_to?(:full_messages)
+      object.errors.full_messages
+    else
+      HamlErrorPresenter.new(object.errors).present(self, &block)
+    end
+
+    haml_tag(:div, options) do
+      haml_tag(:ul) do
+        lines.each do |error|
+          haml_tag(:li, error)
+        end
+      end
+    end
+  end
+end