pirj-sinatra-contrib 1.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2011 Nicolas Sanguinetti, entp.com, Konstantin Haase
+
+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,135 @@
+Collection of common Sinatra extensions, semi-officially supported.
+
+# Goals
+
+* For every future Sinatra release, have at least one fully compatible release
+* High code quality, high test coverage
+* Include plugins people usually ask for a lot
+
+# TODO
+
+* Write documentation, integrate into Sinatra website
+* Finish imports and rewrites
+* Wrap up first release
+* Find contributors (both code and docs)
+
+# Included extensions
+
+## Common Extensions
+
+These are common extension which will not add significant overhead or change any
+behavior of already existing APIs. They do not add any dependencies not already
+installed with this gem.
+
+Currently included:
+
+* `sinatra/capture`: Let's you capture the content of blocks in templates.
+
+* `sinatra/config_file`: Allows loading configuration from yaml files.
+
+* `sinatra/content_for`: Adds Rails-style `content_for` helpers to Haml, Erb,
+  Erubis and Slim.
+
+* `sinatra/cookies`: A `cookies` helper for reading and writing cookies.
+
+* `sinatra/engine_tracking`: Adds methods like `haml?` that allow helper
+  methods to check whether they are called from within a template.
+
+* `sinatra/json`: Adds a `#json` helper method to return JSON documents.
+
+* `sinatra/link_header`: Helpers for generating `link` HTML tags and
+  corresponding `Link` HTTP headers. Adds `link`, `stylesheet` and `prefetch`
+  helper methods.
+
+* `sinatra/multi_route`: Adds ability to define one route block for multiple
+  routes and multiple or custom HTTP verbs.
+
+* `sinatra/namespace`: Adds namespace support to Sinatra.
+
+* `sinatra/respond_with`: Choose action and/or template depending automatically
+  depending on the incoming request. Adds helpers `respond_to` and
+  `respond_with`.
+
+
+## Custom Extensions
+
+These extensions may add additional dependencies and enhance the behavior of the
+existing APIs.
+
+Currently included:
+
+* `sinatra/decompile`: Recreates path patterns from Sinatra's internal data
+  structures (used by other extensions).
+
+* `sinatra/reloader`: Automatically reloads Ruby files on code changes.
+
+## Other Tools
+
+* `sinatra/extension`: Mixin for writing your own Sinatra extensions.
+
+* `sinatra/test_helpers`: Helper methods to ease testing your Sinatra
+  application. Partly extracted from Sinatra. Testing framework agnostic
+
+# Usage
+
+## Classic Style
+
+A single extension (example: sinatra-content-for):
+
+``` ruby
+require 'sinatra'
+require 'sinatra/content_for'
+```
+
+Common extensions:
+
+``` ruby
+require 'sinatra'
+require 'sinatra/contrib'
+```
+
+All extensions:
+
+``` ruby
+require 'sinatra'
+require 'sinatra/contrib/all'
+```
+
+## Modular Style
+
+A single extension (example: sinatra-content-for):
+
+``` ruby
+require 'sinatra/base'
+require 'sinatra/content_for'
+require 'sinatra/namespace'
+
+class MyApp < Sinatra::Base
+  # Note: Some modules are extensions, some helpers, see the specific
+  # documentation or the source
+  helpers Sinatra::ContentFor
+  register Sinatra::Namespace
+end
+```
+
+Common extensions:
+
+``` ruby
+require 'sinatra/base'
+require 'sinatra/contrib'
+
+class MyApp < Sinatra::Base
+  register Sinatra::Contrib
+end
+```
+
+All extensions:
+
+``` ruby
+require 'sinatra/base'
+require 'sinatra/contrib'
+
+class MyApp < Sinatra::Base
+  register Sinatra::Contrib
+end
+```

data/Rakefile

@@ -0,0 +1,61 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'open-uri'
+require 'yaml'
+
+desc "run specs"
+task(:spec) { ruby '-S rspec spec -c' }
+task(:test => :spec)
+task(:default => :spec)
+
+namespace :doc do
+  task :readmes do
+    Dir.glob 'lib/sinatra/*.rb' do |file|
+      excluded_files = %w[lib/sinatra/contrib.rb lib/sinatra/capture.rb lib/sinatra/engine_tracking.rb]
+      next if excluded_files.include?(file)
+      doc  = File.read(file)[/^module Sinatra(\n)+(  #[^\n]*\n)*/m].scan(/^ *#(?!#) ?(.*)\n/).join("\n")
+      file = "doc/#{file[4..-4].tr("/_", "-")}.rdoc"
+      Dir.mkdir "doc" unless File.directory? "doc"
+      puts "writing #{file}"
+      File.open(file, "w") { |f| f << doc }
+    end
+  end
+
+  task :all => [:readmes]
+end
+
+desc "generate documentation"
+task :doc => 'doc:all'
+
+desc "generate gemspec"
+task 'sinatra-contrib.gemspec' do
+  require 'sinatra/contrib/version'
+  content = File.read 'sinatra-contrib.gemspec'
+
+  fields = {
+    :authors => `git shortlog -sn`.scan(/[^\d\s].*/),
+    :email   => `git shortlog -sne`.scan(/[^<]+@[^>]+/),
+    :files   => `git ls-files`.split("\n").reject { |f| f =~ /^(\.|Gemfile)/ }
+  }
+
+  fields.each do |field, values|
+    updated = "  s.#{field} = ["
+    updated << values.map { |v| "\n    %p" % v }.join(',')
+    updated << "\n  ]"
+    content.sub!(/  s\.#{field} = \[\n(    .*\n)*  \]/, updated)
+  end
+
+  content.sub! /(s\.version.*=\s+).*/, "\\1\"#{Sinatra::Contrib::VERSION}\""
+  File.open('sinatra-contrib.gemspec', 'w') { |f| f << content }
+end
+
+task :gemspec => 'sinatra-contrib.gemspec'
+
+desc 'update travis config to correspond to sinatra'
+task :travis, [:branch] do |t, a|
+  a.with_defaults :branch => :master
+  data = YAML.load open("https://raw.github.com/sinatra/sinatra/#{a.branch}/.travis.yml")
+  data["notifications"]["recipients"] << "ohhgabriel@gmail.com"
+  File.open('.travis.yml', 'w') { |f| f << data.to_yaml }
+  system 'git add .travis.yml && git diff --cached .travis.yml'
+end
+

data/ideas.md

@@ -0,0 +1,29 @@
+* Extension that does something like this:
+
+      def build(*)
+        if settings.memcached?
+          use Rack::Cache, :backend => :memcached
+          use Rack::Session::Memcached
+          # ...
+        end
+        super
+      end
+
+* `sinatra-smart-cache`: update cache header only if arguments are more
+  restrictive than curent value, set caching headers that way for most helper
+  methods (i.e. `sass` or `send_file`)
+
+* Some verbose logging extension: Log what filters, routes, error handlers,
+  templates, and so on is used.
+
+* Form helpers, with forms as first class objects that accepts hashes or
+  something, so the form meta data can also be used to expose a JSON API or
+  similar, possibly defining routes (like "Sinatra's Hat"), strictly using
+  the ActiveModel API.
+
+* Extend `sinatra-content-for` to support Liquid, Radius, Markaby, Nokogiri and
+  Builder. At least the first two probably involve patching Tilt.
+
+* Rewrite of `sinatra-compass`?
+
+* Helpers for HTML escaping and such.

data/lib/sinatra/capture.rb

@@ -0,0 +1,42 @@
+require 'sinatra/base'
+require 'sinatra/engine_tracking'
+require 'backports'
+
+module Sinatra
+  module Capture
+    include Sinatra::EngineTracking
+
+    DUMMIES = {
+      :haml => "!= capture_haml(*args, &block)",
+      :erb  => "<% @capture = yield(*args) %>",
+      :slim => "== yield(*args)"
+    }
+
+    DUMMIES[:erubis] = DUMMIES[:erb]
+
+    def capture(*args, &block)
+      @capture = nil
+      if current_engine == :ruby
+        result = block[*args]
+      else
+        buffer     = eval '_buf if defined?(_buf)', block.binding
+        old_buffer = buffer.dup if buffer
+        dummy      = DUMMIES.fetch(current_engine)
+        options    = { :layout => false, :locals => {:args => args, :block => block }}
+
+        buffer.try :clear
+        result = render(current_engine, dummy, options, &block)
+      end
+      result.strip.empty? && @capture ? @capture : result
+    ensure
+      buffer.try :replace, old_buffer
+    end
+
+    def capture_later(&block)
+      engine = current_engine
+      proc { |*a| with_engine(engine) { @capture = capture(*a, &block) }}
+    end
+  end
+
+  helpers Capture
+end

data/lib/sinatra/config_file.rb

@@ -0,0 +1,151 @@
+require 'sinatra/base'
+require 'yaml'
+
+module Sinatra
+
+  # = Sinatra::ConfigFile
+  #
+  # <tt>Sinatra::ConfigFile</tt> is an extension that allows you to load the
+  # application's configuration from YAML files.  It automatically detects if
+  # the files contains specific environment settings and it will use the
+  # corresponding to the current one.
+  #
+  # Within the application you can access those options through +settings+.  If
+  # you try to get the value for a setting that hasn't been defined in the
+  # config file for the current environment, you will get whatever it was set
+  # to in the application.
+  #
+  # == Usage
+  #
+  # Once you have written your configurations to a YAML file you can tell the
+  # extension to load them.  See below for more information about how these
+  # files are interpreted.
+  #
+  # For the examples, lets assume the following config.yml file:
+  #
+  #     greeting: Welcome to my file configurable application
+  #
+  # === Classic Application
+  #
+  #     require "sinatra"
+  #     require "sinatra/config_file"
+  #
+  #     config_file 'path/to/config.yml'
+  #
+  #     get '/' do
+  #       @greeting = settings.greeting
+  #       haml :index
+  #     end
+  #
+  #     # The rest of your classic application code goes here...
+  #
+  # === Modular Application
+  #
+  #     require "sinatra/base"
+  #     require "sinatra/config_file"
+  #
+  #     class MyApp < Sinatra::Base
+  #       register Sinatra::ConfigFile
+  #
+  #       config_file 'path/to/config.yml'
+  #
+  #       get '/' do
+  #         @greeting = settings.greeting
+  #         haml :index
+  #       end
+  #
+  #       # The rest of your modular application code goes here...
+  #     end
+  #
+  # === Config File Format
+  #
+  # In its most simple form this file is just a key-value list:
+  #
+  #     foo: bar
+  #     something: 42
+  #     nested:
+  #       a: 1
+  #       b: 2
+  #
+  # But it also can provide specific environment configuration.  There are two
+  # ways to do that: at the file level and at the setting level.  They are
+  # illustrated, repsectively, as follows:
+  #
+  #     development:
+  #       foo: development
+  #       bar: bar
+  #     test:
+  #       foo: test
+  #       bar: bar
+  #     production:
+  #       foo: production
+  #       bar: bar
+  #
+  # and
+  #
+  #     foo:
+  #       development: development
+  #       test: test
+  #       production: production
+  #     bar: bar
+  #
+  # In either case, <tt>settings.foo</tt> will return the environment name, and
+  # <tt>settings.bar</tt> will return <tt>"bar"</tt>.
+  #
+  # Be aware that if you have a different environment, besides development,
+  # test and production, you will also need to adjust the +environments+
+  # setting.  For instance, when you also have a staging environment:
+  #
+  #     set :environments, %w{development test production staging}
+  #
+  module ConfigFile
+
+    # When the extension is registered sets the +environments+ setting to the
+    # traditional environments: development, test and production.
+    def self.registered(base)
+      base.set :environments, %w[test production development]
+    end
+
+    # Loads the configuration from the YAML files whose +paths+ are passed as
+    # arguments, filtering the settings for the current environment.  Note that
+    # these +paths+ can actually be globs.
+    def config_file(*paths)
+      Dir.chdir(root || '.') do
+        paths.each do |pattern|
+          Dir.glob(pattern) do |file|
+            $stderr.puts "loading config file '#{file}'" if logging?
+            yaml = config_for_env(YAML.load_file(file)) || {}
+            yaml.each_pair do |key, value|
+              for_env = config_for_env(value)
+              set key, for_env unless value and for_env.nil? and respond_to? key
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    # Given a +hash+ with some application configuration it returns the
+    # settings applicable to the current environment.  Note that this can only
+    # be done when all the keys of +hash+ are environment names included in the
+    # +environments+ setting (which is an Array of Strings).  Also, the
+    # returned config is a indifferently accessible Hash, which means that you
+    # can get its values using Strings or Symbols as keys.
+    def config_for_env(hash)
+      if hash.respond_to? :keys and hash.keys.all? { |k| environments.include? k.to_s }
+        hash = hash[environment.to_s] || hash[environment.to_sym]
+      end
+
+      if hash.respond_to? :to_hash
+        indifferent_hash = Hash.new {|hash,key| hash[key.to_s] if Symbol === key }
+        indifferent_hash.merge hash.to_hash
+      else
+        hash
+      end
+    end
+  end
+
+  register ConfigFile
+  Delegator.delegate :config_file
+end

data/lib/sinatra/content_for.rb

@@ -0,0 +1,111 @@
+require 'sinatra/base'
+require 'sinatra/capture'
+
+module Sinatra
+
+  # = Sinatra::ContentFor
+  #
+  # <tt>Sinatra::ContentFor</tt> is a set of helpers that allows you to capture
+  # blocks inside views to be rendered later during the request. The most
+  # common use is to populate different parts of your layout from your view.
+  #
+  # The currently supported engines are: Erb, Erubis, Haml and Slim.
+  #
+  # == Usage
+  #
+  # You call +content_for+, generally from a view, to capture a block of markup
+  # giving it an identifier:
+  #
+  #     # index.erb
+  #     <% content_for :some_key do %>
+  #       <chunk of="html">...</chunk>
+  #     <% end %>
+  #
+  # Then, you call +yield_content+ with that identifier, generally from a
+  # layout, to render the captured block:
+  #
+  #     # layout.erb
+  #     <%= yield_content :some_key %>
+  #
+  # === Classic Application
+  #
+  # To use the helpers in a classic application all you need to do is require
+  # them:
+  #
+  #     require "sinatra"
+  #     require "sinatra/content_for"
+  #
+  #     # Your classic application code goes here...
+  #
+  # === Modular Application
+  #
+  # To use the helpers in a modular application you need to require them, and
+  # then, tell the application you will use them:
+  #
+  #     require "sinatra/base"
+  #     require "sinatra/content_for"
+  #
+  #     class MyApp < Sinatra::Base
+  #       register Sinatra::ContentFor
+  #
+  #       # The rest of your modular application code goes here...
+  #     end
+  #
+  # == And How Is This Useful?
+  #
+  # For example, some of your views might need a few javascript tags and
+  # stylesheets, but you don't want to force this files in all your pages.
+  # Then you can put <tt><% yield_content :scripts_and_styles %></tt> on your
+  # layout, inside the <head> tag, and each view can call <tt>content_for</tt>
+  # setting the appropriate set of tags that should be added to the layout.
+  #
+  module ContentFor
+    include Capture
+
+    # Capture a block of content to be rendered later. For example:
+    #
+    #     <% content_for :head do %>
+    #       <script type="text/javascript" src="/foo.js"></script>
+    #     <% end %>
+    #
+    # You can call +content_for+ multiple times with the same key
+    # (in the example +:head+), and when you render the blocks for
+    # that key all of them will be rendered, in the same order you
+    # captured them.
+    #
+    # Your blocks can also receive values, which are passed to them
+    # by <tt>yield_content</tt>
+    def content_for(key, &block)
+      content_blocks[key.to_sym] << capture_later(&block)
+    end
+
+    # Render the captured blocks for a given key. For example:
+    #
+    #     <head>
+    #       <title>Example</title>
+    #       <%= yield_content :head %>
+    #     </head>
+    #
+    # Would render everything you declared with <tt>content_for 
+    # :head</tt> before closing the <tt><head></tt> tag.
+    #
+    # You can also pass values to the content blocks by passing them
+    # as arguments after the key:
+    #
+    #     <%= yield_content :head, 1, 2 %>
+    #
+    # Would pass <tt>1</tt> and <tt>2</tt> to all the blocks registered
+    # for <tt>:head</tt>.
+    def yield_content(key, *args)
+      content_blocks[key.to_sym].map { |b| capture(*args, &b) }.join
+    end
+
+    private
+
+    def content_blocks
+      @content_blocks ||= Hash.new {|h,k| h[k] = [] }
+    end
+  end
+
+  helpers ContentFor
+end