kawaii-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 95acd16e37137a291448035f6d07d4e57fd176a8
+  data.tar.gz: 59e1181f5923fe52949358ef933b54979fd9e97c
+SHA512:
+  metadata.gz: 82bc0bf00758bfc60a1659c6cf97e7de0a9252a1538a43ea8060b5742cc7d90dc6a146342c51c4fc1a046fd146904ae10c141f74d2a3d3bfbab090c8b24d0c1b
+  data.tar.gz: aae617e17cbc4c848d24c02f9d0aadfc6840d3986fcc79934f2811686d40843386d9a5d246aced280736cc29e20f02966ab892c2a02fa2229a4e7e4443970e42

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kawaii.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,42 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Martin Bilski
+
+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,372 @@
+
+# Kawaii
+
+Kawaii is a simple web framework based on Rack.
+
+** This is work in progress. The API is subject to change. **
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'kawaii-core'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kawaii-core
+
+## Running examples
+
+The `/examples` directory contains various basic usage examples.
+
+Run the examples using rackup or directly:
+
+```
+$ cd examples
+$ rackup -r kawaii modular.ru
+```
+
+Many examples can also be run directly without rackup, e.g.:
+
+```
+$ cd examples
+$ ruby -r kawaii hello_world.rb
+
+## Getting started
+
+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:
+
+```
+require 'kawaii'
+
+get '/' do
+  'Hello, world!'
+end
+```
+
+Save it to `hello.rb` and start the server like this:
+
+```
+$ rackup -r kawaii hello.rb --port 8088
+```
+
+Then navigate to `http://localhost:8088` to see the greeting.
+
+## Using rackup
+
+To run the app you created in the "Getting started" section above using rackup, create the following `hello.ru` file:
+
+```
+require 'kawaii'
+require_relative 'hello'
+
+run Kawaii::SingletonApp
+```
+
+`SingletonApp` contains all routes defined at the file scope.
+
+## Defining routes
+
+There are several methods you can use to build your routes, handle passed parameters and so on.
+
+### Supported HTTP methods
+
+The basic way to add a route handler is to invoke a method corresponding to the given HTTP verb, e.g.:
+
+```
+post '/users' do
+  # Some response
+end
+```
+
+Here, the `post` method corresponds to the `POST` HTTP verb.
+
+Here's a list of supported HTTP verbs:
+
+- get
+- post
+- put
+- patch
+- delete
+- head
+- options
+- link
+- unlink
+- trace
+
+### Wildcard matching
+
+Patterns in route definitions may contain wildcard characters `*` and `?`.
+
+For example `get '/users/?'` matches both `/users/` and `/users` while `get '/users/*'` will match any path starting with '/users/' e.g. '/users/foo/bar'.
+
+### Parameters
+
+Route patterns may contain named parameters, prefixed with a colon. Parameters are accessible through the `params` hash in handler:
+
+```
+get '/users/:id' do
+  params[:id]
+end
+```
+
+(When requested with `/users/123`, the above route handler will render `"123"`.)
+
+### Regular expressions
+
+Route patterns may contain regular expressions. Example:
+
+```
+get %r{/users/.*} do
+  'Hello, world'
+end
+```
+
+### Nested routes
+
+Routes may be nested using the `context` method. Example:
+
+```
+context '/api' do
+  get '/users' do
+    'Hello'
+  end
+end
+```
+
+Will above handler will be accessible through `/api/users`.
+
+### Custom matchers
+
+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.
+
+### Request object
+
+Handlers can access the `Rack::Request` instance corresponding to the current request:
+
+```
+get '/' do
+  request.host
+end
+```
+
+### View templates
+
+View templates must currently be stored in `views/` directory of the project using Kawaii. They can be rendered using the `render` method:
+
+```
+get '/' do
+  render('index.html.erb')
+end
+```
+
+You can set instance variables and use them in the templates.
+
+```
+get '/' do
+  @title = 'Hello, world'
+  render('index.html.erb')
+end
+```
+
+Let's say `views/index.html.erb` looks like this:
+
+```
+<h1><%= @title %></h1>
+```
+
+In that case, when you visit the page, you'll see **Hello, world**.
+
+Supported templating engines include: ERB, Haml, Liquid, Builder, Kramdown and others. Note that you may need to include the specific gem implementing the given templating engine as inferred from the file name of the template.
+
+## Modular apps
+
+For building more complex applications, you can split them into separate classes, each implementing a subset of functionality (e.g. website and an API).
+
+To create an application, inherit from `Kawaii::Base` and define your routes inside the class.
+
+Let's create `website.rb`:
+
+```ruby
+require 'kawaii'
+
+class Website < Kawaii::Base
+  get '/' do
+    'Hello, world'
+  end
+end
+```
+
+Now here's how `api.rb` may look like:
+
+```ruby
+require 'kawaii'
+
+class API < Kawaii::Base
+  get '/info' do
+    'This is some information'
+  end
+end
+```
+
+Let's use the apps in a `config.ru`:
+
+```ruby
+require 'kawaii'
+require_relative 'website'
+require_relative 'api'
+
+map '/' do
+  run Website
+end
+
+map '/api' do
+  run API
+end
+```
+
+## Model-view-controller apps
+
+Kawaii supports routing to controllers by either specifying the specific controller + action for a given route or by creating automatic Restful resources (via `route`).
+
+Let's suppose we have a controller in `hello_world.rb` has typical CRUD methods that mimick Rails controllers:
+
+```ruby
+class HelloWorld < Kawaii::Controller
+  def index
+    'Hello, world'
+  end
+end
+```
+
+An in `users.rb`:
+
+```ruby
+class Users < Kawaii::Controller
+  def index
+    'GET /users'
+  end
+
+  def show
+    "GET /users/#{params[:id]}"
+  end
+
+  def create
+    'POST /users'
+  end
+
+  def update
+    "PATCH /users/#{params[:id]}"
+  end
+
+  def destroy
+    "DELETE /users/#{params[:id]}"
+  end
+end
+```
+
+Here's how we can define routes (in `app.rb`):
+
+```ruby
+  require 'kawaii'
+  require_relative 'hello_world'
+  require_relative 'users'
+
+  get '/', 'hello_world#index' # Explicitly route to `HelloWorld#index` to show the welcome page
+
+  route '/users', 'users'
+```
+
+You can run the app directly using `ruby` or create `config.ru`:
+
+```ruby
+require_relative 'app.rb'
+
+run Kawaii::SingletonApp
+```
+
+Of course, you can 
+
+## Testing
+
+I recommend using `Rack::Test` for testing (see [here](https://github.com/brynary/rack-test)). Look at specs in `spec/` to see how you can use it.
+
+To make a long story short, a class deriving from `Kawaii::Base` containing your routes is `app`. Let's suppose, your app class is `MyApp`, here's how you could test it:
+
+```ruby
+describe MyApp
+  let(:app) { MyApp }
+  it 'renders home page' do
+    get '/'
+    expect(last_response).to be_ok
+  end
+end
+```
+
+## Resources
+
+See `/examples` 
+### Reference
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bilus/kawaii.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+
+## 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
+
+## Known issues
+
+### Rubocop
+
+`lib/kawaii/routing_methods.rb:46:1: C: Extra blank line detected.`
+
+The extra line is necessary for Yard to ignore the comment. Adjust Rubocop settings.