kawaii-core 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95acd16e37137a291448035f6d07d4e57fd176a8
-  data.tar.gz: 59e1181f5923fe52949358ef933b54979fd9e97c
+  metadata.gz: d81d0ba32a44a5b7eceec6b3979cd33f58970ec3
+  data.tar.gz: 8da2f45e4fc4e5291372f5f5c46edfb1139e849e
 SHA512:
-  metadata.gz: 82bc0bf00758bfc60a1659c6cf97e7de0a9252a1538a43ea8060b5742cc7d90dc6a146342c51c4fc1a046fd146904ae10c141f74d2a3d3bfbab090c8b24d0c1b
-  data.tar.gz: aae617e17cbc4c848d24c02f9d0aadfc6840d3986fcc79934f2811686d40843386d9a5d246aced280736cc29e20f02966ab892c2a02fa2229a4e7e4443970e42
+  metadata.gz: 4b583cd1e65bbbc8b8f73ea402fde6e5a706d31778ebfdfd801590af617ee74dd2b3cd8985f1eaa3c42c562610f7f47b181b27a8a45fce7d53c595a9f425f1fb
+  data.tar.gz: 368d2864fe554d1923dea8e4cb438694c522eb618316d8feca27554ba3f25578eac98dbf884463bd1e1117cce89017d70697d7a74f108b28e57d431830328294

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -3,7 +3,7 @@
 
 Kawaii is a simple web framework based on Rack.
 
-** This is work in progress. The API is subject to change. **
+**This is work in progress. The API is subject to change.**
 
 ## Installation
 
@@ -23,26 +23,34 @@ Or install it yourself as:
 
 ## Running examples
 
-The `/examples` directory contains various basic usage examples.
+Clone the Kawaii project to run the examples. The [/examples directory](https://github.com/bilus/kawaii/tree/master/examples) contains various basic usage examples.
+
+```
+$ git clone https://github.com/bilus/kawaii.git
+$ cd kawaii
+```
 
 Run the examples using rackup or directly:
 
 ```
 $ cd examples
-$ rackup -r kawaii modular.ru
+$ rackup -I ../lib modular.ru
 ```
 
 Many examples can also be run directly without rackup, e.g.:
 
-```
+```ruby
 $ cd examples
-$ ruby -r kawaii hello_world.rb
+$ ruby -I ../lib hello_world.rb
+```
 
 ## Getting started
 
+Note: In addition to this Readme, there's also an online [API reference](http://bilus.github.io/kawaii/Kawaii.html).
+
 Kawaii's basic usage is very similar how you'd use Sinatra. You can define route handlers at the file scope. Here's an example:
 
-```
+```ruby
 require 'kawaii'
 
 get '/' do
@@ -62,7 +70,7 @@ Then navigate to `http://localhost:8088` to see the greeting.
 
 To run the app you created in the "Getting started" section above using rackup, create the following `hello.ru` file:
 
-```
+```ruby
 require 'kawaii'
 require_relative 'hello'
 
@@ -79,7 +87,7 @@ There are several methods you can use to build your routes, handle passed parame
 
 The basic way to add a route handler is to invoke a method corresponding to the given HTTP verb, e.g.:
 
-```
+```ruby
 post '/users' do
   # Some response
 end
@@ -110,7 +118,7 @@ For example `get '/users/?'` matches both `/users/` and `/users` while `get '/us
 
 Route patterns may contain named parameters, prefixed with a colon. Parameters are accessible through the `params` hash in handler:
 
-```
+```ruby
 get '/users/:id' do
   params[:id]
 end
@@ -122,7 +130,7 @@ end
 
 Route patterns may contain regular expressions. Example:
 
-```
+```ruby
 get %r{/users/.*} do
   'Hello, world'
 end
@@ -132,7 +140,7 @@ end
 
 Routes may be nested using the `context` method. Example:
 
-```
+```ruby
 context '/api' do
   get '/users' do
     'Hello'
@@ -146,13 +154,13 @@ Will above handler will be accessible through `/api/users`.
 
 If string patterns and regular expression are not flexible enough, you can create a custom matcher.
 
-A matcher instance responds to `match` method and returns either a `Match` instance or nil if there's no match. See documentation for {Matcher#match} for more details.
+A matcher instance responds to `match` method and returns either a `Match` instance or nil if there's no match. See documentation for {Kawaii::Matcher#match} for more details.
 
 ### Request object
 
 Handlers can access the `Rack::Request` instance corresponding to the current request:
 
-```
+```ruby
 get '/' do
   request.host
 end
@@ -162,7 +170,7 @@ end
 
 View templates must currently be stored in `views/` directory of the project using Kawaii. They can be rendered using the `render` method:
 
-```
+```ruby
 get '/' do
   render('index.html.erb')
 end
@@ -170,7 +178,7 @@ end
 
 You can set instance variables and use them in the templates.
 
-```
+```ruby
 get '/' do
   @title = 'Hello, world'
   render('index.html.erb')
@@ -179,7 +187,7 @@ end
 
 Let's say `views/index.html.erb` looks like this:
 
-```
+```html
 <h1><%= @title %></h1>
 ```
 
@@ -311,10 +319,40 @@ describe MyApp
 end
 ```
 
+## Custom 404 handler
+
+By default Kawaii will respond with 404 'Not found' if no matching routes can be found.
+
+You can define your own 404 handler:
+
+```ruby
+not_found do
+  [404, {Rack::CONTENT_TYPE => 'text/plain'}, ['No matching routes found']]
+end
+```
+
+Notice that it needs to respond with a valid Rack response Array.
+
+## Custom exception handler
+
+You can define your own 500 handler for unhandled exception:
+
+```ruby
+get '/' do
+  fail 'Ooops!'
+end
+on_error do |e|
+  [500, {Rack::CONTENT_TYPE => 'text/plain'}, [e.to_s]]
+end
+```
+
+Just like with `not_found`, you need to return a well-formed Rack response Array.
+
 ## Resources
 
-See `/examples` 
-### Reference
+1. [API reference](http://bilus.github.io/kawaii/Kawaii.html).
+2. See [examples](https://github.com/bilus/kawaii/tree/master/examples) of basic usage of Kawaii.
+3. Small [example project](https://github.com/bilus/kawaii-sample) using the gem.
 
 ## Contributing
 
@@ -328,43 +366,74 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## TODO
 
-+ Hello world app.
-+ Specs for the app.
-+ GET routes inside a class deriving from Base.
-+ Support for running apps without config.ru (ruby -I ./lib examples/hello_world.rb
-+ Top-level routes.
-+ Example for top-level routes.
-+ Nested routes.
-+ Modular apps (multiple modules via config.ru).
-+ Matchers.
-+ Wildcard regex routes, e.g. '/foo/bar/?'.
-+ Parameter-based routes. Unsupported in 'context'.
-+ Request object.
-+ Merge Rack Request params.
-+ String responses.
-+ Other HTTP verbs.
-+ Refactor & create individual files.
-+ Views (via `render` method in handlers) using Tilt.
-+ Rack route test helpers work.
-+ API reference.
-+ Check: References to methods defined in contexts and at class scope.
-+ Controllers - 'hello_world#index'
-+ 'route' to controllers (via class name or symbol references).
-+ Controllers - render.
-
-- Readme - description and tutorial.
-- Rubocop-compliant.
-- Push gem.
-
-- Example project using the gem and controllers (with views).
-
-- Rack/custom global middleware.
-- Route-specific middleware.
-- Custom error handling (intercept exceptions, 404 what else?).
-- Code review
+X Hello world app.
+
+X Specs for the app.
+
+X GET routes inside a class deriving from Base.
+
+X Support for running apps without config.ru (ruby -I ./lib examples/hello_world.rb
+
+X Top-level routes.
+
+X Example for top-level routes.
+
+X Nested routes.
+
+X Modular apps (multiple modules via config.ru).
+
+X Matchers.
+
+X Wildcard regex routes, e.g. '/foo/bar/?'.
+
+X Parameter-based routes. Unsupported in 'context'.
+
+X Request object.
+
+X Merge Rack Request params.
+
+X String responses.
+
+X Other HTTP verbs.
+
+X Refactor & create individual files.
+
+X Views (via `render` method in handlers) using Tilt.
+
+X Rack route test helpers work.
+
+X API reference.
+
+X Check: References to methods defined in contexts and at class scope.
+
+X Controllers - 'hello_world#index'
+
+X 'route' to controllers (via class name or symbol references).
+
+X Controllers - render.
+
+X Push gem.
+
+X Readme - description and tutorial.
+
+X Example project using the gem and controllers (with views).
+
+X Custom error handling (intercept exceptions, 404 what else?).
+
+X Rubocop-compliant.
+
+O Update and push.
+
+O Code review
+
+O Rack/custom global middleware.
+
+O Route-specific middleware.
 
 ## Known issues
 
+**There are many missing features and glitches are inevitable. The library hasn't been used in production yet. Please report them to `gyamtso at gmail dot com`.**
+
 ### Rubocop
 
 `lib/kawaii/routing_methods.rb:46:1: C: Extra blank line detected.`

data/kawaii-core.gemspec

@@ -9,10 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors   = ['Marcin Bilski']
   spec.email     = ['gyamtso@gmail.com']
 
-  spec.summary       = 'Kawaii is a simple web framework based on Rack'
-  spec.description   = 'Kawaii is a basic but extensible web framework based on Rack'
-  
-  spec.homepage  = "https://github.com/bilus/kawaii"
+  spec.summary       = 'A simple web framework based on Rack'
+  spec.description   = 'Kawaii is a simple web framework based on Rack'
+
+  spec.homepage  = 'https://github.com/bilus/kawaii'
   spec.license   = 'MIT'
 
   spec.files     = `git ls-files -z`.split("\x0").reject { |f|
@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'guard-rspec', '~>4.6'
   spec.add_development_dependency 'rack-test', '~>0.6'
   spec.add_development_dependency 'yard', '~> 0.8'
+  spec.add_development_dependency 'rubocop', '~> 0.35'
 end

data/lib/kawaii/base.rb

@@ -20,29 +20,53 @@ module Kawaii
 
     # Instances of classes derived from [Kawaii::Base] are Rack applications.
     def call(env)
-      matching = self.class.match(env) || not_found
+      matching = self.class.match(env)
       matching.call(env)
+    rescue => e
+      self.class.handle_error(e)
     end
 
     class << self
       include ServerMethods
       include RoutingMethods
 
+      # Define 404 handler. Has to return a valid Rack response.
+      def not_found(&block)
+        @not_found_handler = block
+      end
+
+      # Define an unhandled exception handler. Has to return a valid Rack
+      # response.
+      def on_error(&block)
+        @error_handler = block
+      end
+
+      def match(env)
+        super(env) || not_found_handler
+      end
+
       # Make it runnable via `run MyApp`.
       def call(env)
         @app ||= new
         @app.call(env)
       end
-    end
 
-    protected
+      def handle_error(e)
+        handler = @error_handler || ->(ex) { fail ex }
+        handler.call(e)
+      end
 
-    def not_found
-      @downstream_app || ->(_env) { text(404, 'Not found') }
-    end
+      protected
 
-    def text(status, s)
-      [status, { Rack::CONTENT_TYPE => 'text/plain' }, [s]]
+      def not_found_handler
+        @downstream_app ||
+          @not_found_handler ||
+          ->(_env) { text(404, 'Not found') }
+      end
+
+      def text(status, s)
+        [status, { Rack::CONTENT_TYPE => 'text/plain' }, [s]]
+      end
     end
   end
 end

data/lib/kawaii/controller.rb

@@ -17,7 +17,7 @@ module Kawaii
   #  get '/', 'hello_world#index'
   class Controller
     include RenderMethods
-    
+
     # Parameter [Hash] accessible in actions
     attr_reader :params
     # Rack::Request accessible in actions

data/lib/kawaii/matchers.rb

@@ -43,7 +43,7 @@ module Kawaii
     end
 
     # Tries to match the actual path.
-    # @param path [String] the actual path from Rack env
+    # @param _path [String] the actual path from Rack env
     # @return {Match} if the beginning of path does match or nil if there is
     # no match.
     def match(_path)
@@ -100,7 +100,7 @@ module Kawaii
   #   get /\/users.*/ do ... end
   class RegexpMatcher
     # Creates a {RegexpMatcher}
-    # @param path [Regexp] path specification regex
+    # @param rx [Regexp] path specification regex
     # @todo Support parameters based on named capture groups.
     def initialize(rx)
       @rx = rx

data/lib/kawaii/method_chain.rb

@@ -1,6 +1,6 @@
 module Kawaii
   # Allows handlers to use methods defined in outer contexts or at class scope.
-  # Set {#parent_scope} in constructor.
+  # Set MethodChain.parent_scope in constructor.
   module MethodChain
     attr_writer :parent_scope
 

data/lib/kawaii/render_methods.rb

@@ -2,7 +2,8 @@ module Kawaii
   # Template rendering based on Tilt.
   module RenderMethods
     # Renders a template.
-    # @param tmpl [String] file name or path to template, relative to /views in project dir
+    # @param tmpl [String] file name or path to template, relative to /views in
+    #        project dir
     # @example Rendering html erb file
     #   render('index.html.erb')
     # @todo Layouts.

data/lib/kawaii/routing_methods.rb

@@ -50,7 +50,7 @@ module Kawaii
     #        corresponds to HelloWorld).
     # @example REST resource routes
     #    route '/users/', 'hello_world'
-    # 
+    #
     #    # Will insert routes corresponding to:
     #    # GET /users/? -> Controller#index
     #    # GET /users/:id/? -> Controller#show

data/lib/kawaii/version.rb

@@ -1,4 +1,4 @@
 # Gem version.
 module Kawaii
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kawaii-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Marcin Bilski
@@ -122,7 +122,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-description: Kawaii is a basic but extensible web framework based on Rack
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.35'
+description: Kawaii is a simple web framework based on Rack
 email:
 - gyamtso@gmail.com
 executables: []
@@ -185,9 +199,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
-summary: Kawaii is a simple web framework based on Rack
+summary: A simple web framework based on Rack
 test_files: []
 has_rdoc: