Yeah! is a DSL for quickly creating shelf applications in mruby with minimal effort:

# mrblib/your-mrbgem.rbextendYeah::DSL | extendYeah::DSL
|
setport: 3000 | opt(:port){ |port| setport: port}
|
get'/hi/{name}'do |name| | get'/hi'do"Hi #{name}" | "Hi #{params['name'].join(' and ')}"end | end

$ your-mrbgem &| $ your-mrbgem --port 8080 & Starting application at http://localhost:3000 | Starting application at http://localhost:8080
|
$ curl 'localhost:3000/hi/Ben'| $ curl 'localhost:8080/hi?name=Tom&name=Jerry'
Hi Ben | Hi Tom and Jerry

Installation

Add the line below to your build_config.rb:

MRuby::Build.newdo |conf|
# ... (snip) ...conf.gem'mruby-yeah'end

Or add this line to your aplication's mrbgem.rake:

MRuby::Gem::Specification.new('your-mrbgem')do |spec|
# ... (snap) ...spec.add_dependency'mruby-yeah'end

Routes

In Yeah!, a route is an HTTP method paired with a URL-matching pattern. Each route is associated with a block:

post'/'do
.. createsomething ..
end

Routes are matched in the order they are defined. The first route that matches the request is invoked.

Routes with trailing slashes are not different from the ones without:

get'/foo'do# Does match "GET /foo/"end

Use root to specify the default entry point:

# Redirect "GET /" to "GET /public/index.html"root'/public/index.html'

Route patterns may include named parameters, accessible via the params hash:

# matches "GET /hello/foo" and "GET /hello/bar"get'/hello/{name}'do# params[:name] is 'foo' or 'bar'"Hello #{params[:name]}!"end

You can also access named parameters via block parameters:

# matches "GET /hello/foo" and "GET /hello/bar"get'/hello/{name}'do |name|
# params[:name] is 'foo' or 'bar'# name stores params[:name]"Hello #{name}!"end

Routes may also utilize query parameters:

# matches "GET /posts?title=foo&author=bar"get'/posts'dotitle=params['title']author=params['author']end

Route matching with Regular Expressions:

get'/blog/post/{id:\\d+}'do |id|
post=Post.find(id)end

Support for regular expression requires mruby-regexp-pcre to be installed before mruby-yeah!

Routes can also be defined to match any HTTP method:

# matches "GET /" and "PUT /" and ...route'/',R3::ANYdorequest[Shelf::REQUEST_METHOD]end

Last but not least its possible to get a list of all added HTTP routes:

routes# => ['GET /blog/post/{id}']

Response

Each routing block is invoked within the scope of an instance of Yeah::Controller. The class provides access to methods like request, params, logger and render.

• request returns the Shelf request and is basically a hash.

get'/'dorequest# => { 'REQUEST_METHOD' => 'GET', 'REQUEST_PATH' => '/', 'User-Agent' => '...' }end

• params returns the query params and named URL params. Query params are accessible by string keys and named params by symbol.

# "GET /blogs/b1/posts/p1?blog_id=b2"get'/blogs/{blog_id}/posts/{post_id}'doparams# => { blog_id: 'b1', post_id: 'p1' }end

• logger returns the query params and named URL params. Query params are accessible by string keys and named params by symbol. Dont forget to include the required middleware!

useShelf::Loggerget'/'dologger# => <Logger:0x007fae54987308>end

• render returns a well-formed shelf response. The method allows varoius kind of invokation:

get'/500'do | get'/yeah'dorender500 | renderhtml: '<h1>Yeah!</h1>'end | end
|
get'/say_hi'do | post'/api/stats'dorender'Hi' | renderjson: Stats.create(params),status: 201,headers: {...}end | end
|
get'/say_hello'do | get'/'do'Hello' | renderredirect: 'public/index.html'end | end

Controller

Instead of a code block to execute a route also accepts an controller and an action similar to Rails.

classGreetingsController < Yeah::Controllerdefgreet(name)render"Hello #{name.capitalize}"endendYeah.application.routes.drawdoget'greet/{name}',to: 'greetings#greet'endYeah.application.configure:productiondolog_folder'/logs','iss.log','iss.err'endYeah.application.run!port: 3000

Command Line Arguments

Yeah! ships with a small opt parser. Each option is associated with a block:

# matches "your-mrbgem --port 80" or "your-mrbgem -p 80"opt:port,:int,8080do |port|
# port is 80set:port,portend

Opts can have a default value. The block will be invoked in any case either with the command-line value, its default value or just nil.

Sometimes however it is intended to only print out some meta informations for a single given option and then exit without starting the server:

# matches "your-mrbgem --version" or "your-mrbgem -v"opt!:versiondo# prints 'v1.0.0' on STDOUT and exit'v1.0.0'end

Configuration

Run once, at startup, in any environment:

configuredo# setting one optionset:option,'value'# setting multiple optionsseta: 1,b: 2# same as `set :option, true`enable:option# same as `set :option, false`disable:optionend

Run only when the environment (SHELF_ENV environment variable) is set to production:

configure:productiondo
...
end

Run only when the environment is set to either development or test:

configure:development,:testdo
...
end

You can access those options via settings:

configuredoset:foo,'bar'endget'/'dosettings[:foo]# => 'bar'end

Shelf Middleware

Yeah! rides on Shelf, a minimal standard interface for mruby web frameworks. One of Shelf's most interesting capabilities for application developers is support for "middleware" -- components that sit between the server and your application monitoring and/or manipulating the HTTP request/response to provide various types of common functionality.

Sinatra makes building Rack middleware pipelines a cinch via a top-level use method:

useShelf::CatchErroruseMyCustomMiddlewareget'/hello'do'Hello World'end

The semantics of use are identical to those defined for the Shelf::Builder DSL. For example, the use method accepts multiple/variable args as well as blocks:

useShelf::Static,urls: ['/public'],root: ENV['DOCUMENT_ROOT']

Shelf is distributed with a variety of standard middleware for logging, debugging, and URL routing. Yeah! uses many of these components automatically based on configuration so you typically don't have to use them explicitly.

Server

Yeah! works with any Shelf-compatible web server. Right now these are mruby-simplehttpserver and mruby-heeler:

set:server,'simplehttpserver'# => Default

However its possible to register handlers for other servers. See here for more info.

Development

Clone the repo:

$ git clone https://github.com/katzer/mruby-yeah.git && cd mruby-yeah/

Compile the source:

$ rake compile

Run the tests:

$ rake test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/katzer/mruby-yeah.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Authors

• Sebastián Katzer, Fa. appPlant GmbH

License

The mgem is available as open source under the terms of the MIT License.

Made with 😋 in Leipzig

© 2017 appPlant GmbH