RubyGems - bruter - Versions diffs - 0.0.2 - Mend

bruter 0.0.2

Files changed (8) hide show

data/LICENSE ADDED Viewed

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Ted Kimble
+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 ADDED Viewed

@@ -0,0 +1,222 @@
+# Bruter
+Bruter is a miniature Ruby library that allows its bearer the ability to craft elegant Rack-based web applications with ease. Bruter stands on the backs of giants:
+  * Servers interface with Bruter -- a [Rack][rack]-compatible application -- with minimal configuration
+  * Variably named paths are routed to their proper destination by [HttpRouter][http_router]
+  * Dynamic assets -- Sass, LESS, CoffeeScript and more -- are compiled and served by [Sprockets][sprockets]
+  * Views and templates are rendered as one by [Mustache][mustache]
+Surely under 200 lines of code without comments, Bruter is meant to be easy to understand and use. But do not underestimate Bruter's small footprint: Bruter's role lies in its ability to delegate responsibility and provide an intuitive syntax.
+## Example
+Bruter can be found hiding in the usual places.
+`gem install bruter`
+You'll need to create a Rackup file.
+```ruby
+# config.ru
+require 'bruter'
+$:.unshift File.dirname(__FILE__)
+require 'app/application'
+require 'app/views/hello' # Note that you need to require any files you'll reference, including views
+run Application.new
+```
+Routes and asset paths are defined in a subclass of `Bruter::Application`.
+```ruby
+# app/application.rb
+class Application < Bruter::Application
+  serve_assets 'assets'                 # Asset paths are relative to where the method is called
+  get '/hello/:name', to: 'views/hello' # Bruter will look for a Views::Hello class to render
+end
+```
+View classes should subclass `Bruter::Mustache`.
+```ruby
+# app/views/hello.rb
+module Views
+  class Hello < Bruter::Mustache
+    def name
+      params[:name]
+    end
+  end
+end
+```
+Bruter's Mustache will automatically look for an accompanying template in `'../templates'` relative to the view class.
+```html
+# app/templates/hello.mustache
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Hello {{name}}!</title>
+  <link rel="stylesheet" href="/stylesheets/application.css">
+</head>
+<body>
+  <h1>Bruter kindly welcomes you, {{name}}!</h1>
+  <img src="/images/bruter.jpg">
+</body>
+</html>
+```
+Place `'bruter.jpg'` in `'app/assets/images'` and a stylesheet of your preferred format in `'app/assets/stylesheets'` and Sprockets will take care of the rest.
+```css
+# app/assets/stylesheets/application.css.scss
+body {
+  text-align: center
+  h1 { font-size: 1.25em; }
+}
+```
+Bruter is a Rack application; choose any compatible server.
+`rackup config.ru`
+## Routing
+Routing is handled by HttpRouter. Most applications will subclass `Bruter::Application` and generate routes by calling the class method `:add`. The method accepts a path and a hash of options.
+```ruby
+add(path, options = {})
+```
+Most routes will want to specify a `:to` option. The `:to` option can be any Rack application.
+```ruby
+add '/welcome', to: [200, {'Content-Type' => 'text/html'}, ['Welcome to Bruter.']]
+```
+Or more interestingly, it can be a string representing a Mustache view class.
+```ruby
+add '/welcome', to: 'welcome'           # Looks for Welcome
+add '/hello',   to: 'views/hello_there' # Looks for Views::HelloThere
+```
+The path can include named variables and globs.
+```ruby
+add '/hello/:name',   to: 'hello'   # Matches '/hello/bruter' and '/hello/ted'
+add '/tagged/*tags',  to: 'tagged'  # Matches '/tagged/web' and '/tagged/volcano/lava/dinosaurs'
+```
+Routes can be restricted to certain HTTP request methods.
+```ruby
+add '/post/:id', to: 'posts/show', request_method: ['GET', 'HEAD']
+```
+Routes can be named in order to construct their paths at a later time.
+```ruby
+add '/post/:id', to: 'posts/show', name: :post  # In a view, calling path(:post, 5) returns '/post/5'
+```
+Variable paths can have a regex matching condition placed on them.
+```ruby
+add '/:a-plus-:b-equals', to: 'add', matching: {a: /\d+/, b: /\d+/}
+```
+### Redirects
+Redirects can be added by setting a `:redirect` option instead of a `:to` option.
+```ruby
+add '/old-path', redirect: '/new-path'
+```
+### Static Files
+Static files can be served by the router by setting a `:static` option instead of a `:to` option.
+```ruby
+add '/images', static: 'app/images'  # Will look for '/images/logo/large.png' in 'app/images/logo/large.png'
+```
+### Convenience Methods
+Bruter also provides a number of convenience methods that pass to `:add` but first set their `:request_method` option to correspond to the name of the method.
+```ruby
+    get(path, options = {})
+   post(path, options = {})
+    put(path, options = {})
+ delete(path, options = {})
+   head(path, options = {})
+options(path, options = {})
+  trace(path, options = {})
+    get(path, options = {})
+```
+### Under the Hood
+When a new `Bruter::Application` object is instantiated, an `HttpRouter` object is also instantiated and any routes added to the application class are added to the router object. This object can also be accessed directly with the `:router` getter method.
+```ruby
+app = Bruter::Application.new
+app.router.add('/').to('my_view')
+run app
+```
+See [HttpRouter][http_router] for more information.
+## Assets
+Asset compilation and serving is handled by Sprockets. Asset paths can be added to the asset environment with the class method `:serve_assets`. The method accepts a path, which is relative to the location the method is called.
+```ruby
+# app/application.rb
+class Application < Bruter::Application
+  serve_assets 'assets'
+end
+```
+This application will compile and serve assets located in `'app/assets'`. For example, a route of `/images/logo.png` will have the asset environment look for a file named `'app/assets/images/logo.png'` and compile (if necessary) and serve it. If it cannot be found, action is passed to the router.
+Like with `HttpRouter`, a new `Sprockets::Environment` object is instantiated and any asset paths appended to it when a new `Bruter::Application` object is instantiated. This environment can be accessed directly with the `:assets` getter method.
+```ruby
+app = Bruter::Application.new
+app.assets.append_path('my/assets/path')
+run app
+```
+See [Sprockets][sprockets] for more information.
+## Rendering
+Routes can be directed to Rack-compatible applications or to strings that represent Mustache view classes. When the latter occurs the application will instantiate the view class with three objects -- a Rack request object, a Rack response object, and the Router object -- and call render. The view class can simply subclass from `Mustache`, but it will likely want to subclass `Bruter::Mustache`, itself a subclass of `Mustache`.
+`Bruter::Mustache` provides a few helpers. First, it tells any subclasses to look for their templates in `'../template'` relative to the view file. It provides an `:initialize` method that accepts the three previously named objects and then attempts to invoke `:setup` if the view has defined it. It provides getter methods to access the Rack request object (`:request`), the Rack response object (`:response`), the Router object (`:router`), the Rack env (`:env`) and the params set during routing (`:params`). It also defines a `:path` method, which accepts the name of a named route and an optional list of arguments to construct a path string.
+For more information, see [Mustache][mustache].
+## License
+Bruter is Copyright &copy; 2011 by Ted Kimble and distributed under the MIT license; see `LICENSE` for more information.
+[rack]:         https://github.com/rack/rack
+[http_router]:  https://github.com/joshbuddy/http_router
+[sprockets]:    https://github.com/sstephenson/sprockets
+[mustache]:     https://github.com/defunkt/mustache

data/lib/bruter.rb ADDED Viewed

@@ -0,0 +1,9 @@
+require 'rack'
+require 'http_router'
+require 'sprockets'
+require 'mustache'
+require 'active_support/core_ext/string/inflections'
+require 'bruter/version'
+require 'bruter/router'
+require 'bruter/mustache'
+require 'bruter/application'

data/lib/bruter/application.rb ADDED Viewed

@@ -0,0 +1,158 @@
+module Bruter
+  class Application
+    class << self
+      attr_accessor :_directory, :routes, :asset_paths
+      # Hack to set :_directory to the file location in which this class is
+      # subclassed. Those not subclassing Bruter::Mustache in a file may want
+      # to explicitly set :_directory.
+      def inherited(klass)
+        klass._directory = File.dirname(caller.first[/^[^:]+/])
+      end
+      # Retrieves the absolute path of the argument path relative to where
+      # Bruter::Application was subclassed (:_directory, see above).
+      def absolute_path(path)
+        File.expand_path(path, _directory)
+      end
+      # Ensure that :routes defaults to an array.
+      def routes
+        @routes ||= []
+      end
+      # Ensure that :asset_paths defaults to an array.
+      def asset_paths
+        @asset_paths ||= []
+      end
+      # Adds a route to the application. Accepts the path of the route and a
+      # hash of options. The path is required and can include named variables
+      # ('/post/:id') and globs ('/tags/*tags').
+      #
+      # The options hash must include either a :to, :redirect or :static key;
+      # the route will not be recognized if none is present. If more than one
+      # is present the preceding order of keys will serve as precedence.
+      #
+      # The :to key should be either a Rack application or a string
+      # representing a Mustache view class. (eg 'my_blog/index' =>
+      # MyBlog::Index)
+      #
+      # The :redirect key should be a string representing the new path or
+      # url that the route should redirect to.
+      #
+      # The :static key should be a string representing a path on the file
+      # system (relative to where the method was called).
+      #
+      # Additional options:
+      # Add a name to the route (:name => :posts)
+      # Add a regex matching condition (:matching => {:id => /\d+/})
+      # Add a HTTP method constraint (:request_method => ['POST', 'HEAD'])
+      #
+      # Examples:
+      # add '/',           to: 'views/posts/index',   name: :posts
+      # add '/posts/:id',  to: 'views/posts/show',    name: :post
+      # add '/posts/:id',  to: 'views/posts/update',  request_method: ['PUT']
+      # add '/tags/*tags', to: 'views/posts/tagged',  name: :tagged
+      #
+      # add '/:i/is-an-integer', to: 'views/integer', matching: {i: /\d+/}
+      #
+      # add '/old-location', redirect: '/new-location'
+      # add '/images/*',     static:   'images'
+      #
+      # For more information see the HttpRouter library
+      # (https://github.com/joshbuddy/http_router)
+      def add(path, options = {})
+        routes << {path: path, options: options}
+      end
+      # Convenience method setting the :request_method option to 'GET'.
+      def get(path, options = {})
+        add(path, options.merge(request_method: 'GET'))
+      end
+      # Convenience method setting the :request_method option to 'POST'.
+      def post(path, options = {})
+        add(path, options.merge(request_method: 'POST'))
+      end
+      # Convenience method setting the :request_method option to 'PUT'.
+      def put(path, options = {})
+        add(path, options.merge(request_method: 'PUT'))
+      end
+      # Convenience method setting the :request_method option to 'DELETE'.
+      def delete(path, options = {})
+        add(path, options.merge(request_method: 'DELETE'))
+      end
+      # Convenience method setting the :request_method option to 'HEAD'.
+      def head(path, options = {})
+        add(path, options.merge(request_method: 'HEAD'))
+      end
+      # Convenience method setting the :request_method option to 'OPTIONS'.
+      def options(path, options = {})
+        add(path, options.merge(request_method: 'OPTIONS'))
+      end
+      # Convenience method setting the :request_method option to 'TRACE'.
+      def trace(path, options = {})
+        add(path, options.merge(request_method: 'TRACE'))
+      end
+      # Tells the application's asset environment to serve and compile assets
+      # in the path argument without passing to the router. The path is
+      # relative to where Bruter::Application is subclassed.
+      def serve_assets(path)
+        asset_paths << path
+      end
+    end
+    attr_accessor :router, :assets
+    # Initializing a new Bruter::Application or a subclass of it will
+    # instantiate a new Router and Sprockets::Environment and subsequently add
+    # all routes to the router and asset paths to the asset environment.
+    def initialize
+      @router = Router.new
+      @assets = Sprockets::Environment.new
+      #
+      self.class.routes.each do |r|
+        path      = r[:path]
+        options   = r[:options]
+        to        = options.delete(:to)
+        redirect  = options.delete(:redirect)
+        static    = options.delete(:static)
+        route     = @router.add(path)
+        if to
+          route.to(to)
+        elsif redirect
+          route.redirect(redirect)
+        elsif static
+          route.static(self.class.absolute_path(static))
+        end
+        options.each { |k, v| route.send(k, v) if route.respond_to?(k) }
+      end
+      #
+      self.class.asset_paths.each do |path|
+        @assets.append_path(self.class.absolute_path(path))
+      end
+    end
+    # A call to this application will first check to see if the path is in any
+    # of the asset environment's paths. If so, the asset environment will
+    # attempt to serve and compile the asset; if not, action is passed to the
+    # router.
+    def call(env)
+      if @assets.find_asset(env['PATH_INFO'].gsub(/\A\//, ''))
+        @assets.call(env)
+      else
+        @router.call(env)
+      end
+    end
+  end
+end

data/lib/bruter/mustache.rb ADDED Viewed

@@ -0,0 +1,82 @@
+module Bruter
+  class Mustache < Mustache
+    class << self
+      attr_accessor :_directory
+      # Hack to set :_directory to the file location in which this class is
+      # subclassed. Those not subclassing Bruter::Mustache in a file may want
+      # to explicitly set :_directory or the @template_path variable with
+      # :template_path=(path).
+      def inherited(klass)
+        klass._directory = File.dirname(caller.first[/^[^:]+/])
+      end
+      # Sets the default template path to '../templates' relative to where the
+      # this class is subclassed.
+      #
+      # Example:
+      #     # in '/path/to/app/views/tagged.rb'
+      #     module Views
+      #       class TaggedPosts < Bruter::Mustache
+      #         puts self.template_path
+      #       end
+      #     end
+      #
+      #     => '/path/to/app/templates'
+      def template_path
+        if _directory
+          @template_path ||= File.expand_path('../templates', _directory)
+        else
+          super
+        end
+      end
+      # Sets the default template name to an underscored version of the class
+      # name.
+      #
+      # Example:
+      #     # in '/path/to/app/views/tagged.rb'
+      #     module Views
+      #       class TaggedPosts < Bruter::Mustache
+      #         puts self.template_name
+      #         puts self.template_file
+      #       end
+      #     end
+      #
+      #     => 'tagged_posts'
+      #     => '/path/to/app/templates/tagged_posts.mustache'
+      def template_name
+        @template_name ||= self.to_s.underscore.split('/').last
+      end
+    end
+    attr_reader :request, :response, :router
+    # Sets the Rack request and response objects and the calling router
+    # object. Subclasses can define a :setup method that will be invoked after
+    # initialization is complete.
+    def initialize(request, response, router)
+      @request  = request
+      @response = response
+      @router   = router
+      send :setup if respond_to?(:setup)
+    end
+    # Retrieves the Rack request's env.
+    def env
+      @request.env
+    end
+    # Retrieves the params from a name variable or globbed route.
+    def params
+      env['router.params']
+    end
+    # Retrieves the path for a named route given the name and any arguments.
+    def path(name, *args)
+      args.any? ? router.url(name, *args) : router.url(name)
+    end
+  end
+end

data/lib/bruter/router.rb ADDED Viewed

@@ -0,0 +1,22 @@
+module Bruter
+  class Router < HttpRouter
+    # Catches destinations that do not respond to :call(env) and transforms
+    # them into a constant, initializes them with Rack request and response
+    # objects and the router itself, and invokes :render. The Rack response's
+    # body will be set to the result of :render and the response finished.
+    def process_destination_path(path, env)
+      destination = path.route.dest
+      if destination.respond_to?(:call)
+        destination.call(env)
+      else
+        request       = ::Rack::Request.new(env)
+        response      = ::Rack::Response.new
+        view          = destination.camelize.constantize
+        response.body = [view.new(request, response, self).render]
+        response.finish
+      end
+    end
+  end
+end

data/lib/bruter/version.rb ADDED Viewed

@@ -0,0 +1,3 @@
+module Bruter
+  VERSION = '0.0.2'
+end

metadata ADDED Viewed

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: bruter
+version: !ruby/object:Gem::Version
+  hash: 27
+  prerelease:
+  segments:
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors:
+- Ted Kimble
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2011-10-28 00:00:00 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        hash: 29
+        segments:
+        - 1
+        - 3
+        - 3
+        version: 1.3.3
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency
+  name: http_router
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - "="
+      - !ruby/object:Gem::Version
+        hash: 51
+        segments:
+        - 0
+        - 10
+        - 2
+        version: 0.10.2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency
+  name: sprockets
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - "="
+      - !ruby/object:Gem::Version
+        hash: 15
+        segments:
+        - 2
+        - 0
+        - 0
+        version: 2.0.0
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - "="
+      - !ruby/object:Gem::Version
+        hash: 3
+        segments:
+        - 3
+        - 1
+        - 0
+        version: 3.1.0
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency
+  name: i18n
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        hash: 3
+        segments:
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency
+  name: mustache
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        hash: 411
+        segments:
+        - 0
+        - 99
+        - 4
+        version: 0.99.4
+  type: :runtime
+  version_requirements: *id006
+description: Bruter is a miniature Ruby library that allows its bearer the ability to craft elegant Rack-based web applications with ease.
+email: ted@kimble.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/bruter/application.rb
+- lib/bruter/mustache.rb
+- lib/bruter/router.rb
+- lib/bruter/version.rb
+- lib/bruter.rb
+homepage: https://github.com/tedkimble/bruter
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 55
+      segments:
+      - 1
+      - 9
+      - 2
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+requirements: []
+rubyforge_project: bruter
+rubygems_version: 1.8.6
+signing_key:
+specification_version: 3
+summary: Bruter helps you craft elegant Ruby web applications.
+test_files: []