Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Build Status codebeat badge Build Status

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

# mrblib/your-mrbgem.rb

extend Yeah::DSL                                      |   extend Yeah::DSL
set port: 3000                                        |   opt(:port) { |port| set port: 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


Add the line below to your build_config.rb: do |conf|
  # ... (snip) ...
  conf.gem 'mruby-yeah'

Or add this line to your aplication's mrbgem.rake:'your-mrbgem') do |spec|
  # ... (snap) ...
  spec.add_dependency 'mruby-yeah'


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

post '/' do
  .. create something ..

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/"

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]}!"

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}!"

Routes may also utilize query parameters:

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

Route matching with Regular Expressions:

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

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::ANY do

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

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


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 '/' do
  request # => { 'REQUEST_METHOD' => 'GET', 'REQUEST_PATH' => '/', 'User-Agent' => '...' }
  • 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}' do
  params # => { 'blog_id' => 'b2', blog_id: 'b1', post_id: 'p1' }
  • 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!
use Shelf::Logger

get '/' do
  logger # => <Logger:0x007fae54987308>
  • render returns a well-formed shelf response. The method allows varoius kind of invokation:
get '/500' do                     |   get '/yeah' do
  render 500                      |     render html: '<h1>Yeah!</h1>'
end                               |   end
get '/say_hi' do                  |   post '/api/stats' do
  render 'Hi'                     |     render json: Stats.create(params), status: 201, headers: {...}
end                               |   end
get '/say_hello' do               |   get '/' do
  'Hello'                         |     render redirect: 'public/index.html'
end                               |   end


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

class GreetingsController < Yeah::Controller
  def greet(name)
    render "Hello #{name.capitalize}"

Yeah.application.routes.draw do
  get 'greet/{name}', to: 'greetings#greet'

Yeah.application.configure :production do
  log_folder '/logs', 'iss.log', 'iss.err'
end! 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, 8080 do |port|
  # port is 80
  set :port, port

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! :version do
  # prints 'v1.0.0' on STDOUT and exit


Run once, at startup, in any environment:

configure do
  # setting one option
  set :option, 'value'
  # setting multiple options
  set a: 1, b: 2
  # same as `set :option, true`
  enable :option
  # same as `set :option, false`
  disable :option

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

configure :production do

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

configure :development, :test do

You can access those options via settings:

configure do
  set :foo, 'bar'

get '/' do
  settings[:foo] # => 'bar'

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:

use Shelf::CatchError
use MyCustomMiddleware

get '/hello' do
  'Hello World'

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:

use Shelf::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.


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.


Clone the repo:

$ git clone && cd mruby-yeah/

Compile the source:

$ rake compile

Run the tests:

$ rake test


Bug reports and pull requests are welcome on GitHub at

  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


  • Sebastián Katzer, Fa. appPlant GmbH


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

Made with 😋 from Leipzig

© 2017 appPlant GmbH