Class: Sinatra::Base

Inherits:
Object
  • Object
show all
Includes:
Rack::Utils, Helpers, Templates
Defined in:
lib/sinatra/base.rb

Overview

Base class for all Sinatra applications and middleware.

Direct Known Subclasses

Application

Constant Summary

URI_INSTANCE =
URI.const_defined?(:Parser) ? URI::Parser.new : URI
CALLERS_TO_IGNORE =

:nodoc:

[ # :nodoc:
  /\/sinatra(\/(base|main|show_exceptions))?\.rb$/,    # all sinatra code
  /lib\/tilt.*\.rb$/,                                 # all tilt code
  /^\(.*\)$/,                                         # generated code
  /rubygems\/(custom|core_ext\/kernel)_require\.rb$/, # rubygems require hacks
  /active_support/,                                   # active_support require hacks
  /bundler(\/runtime)?\.rb/,                          # bundler require hacks
  /<internal:/,                                       # internal in ruby >= 1.9.2
  /src\/kernel\/bootstrap\/[A-Z]/                     # maglev kernel files
]

Constants included from Helpers

Helpers::ETAG_KINDS

Class Attribute Summary (collapse)

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Templates

#asciidoc, #builder, #coffee, #creole, #erb, #erubis, #find_template, #haml, #less, #liquid, #markaby, #markdown, #mediawiki, #nokogiri, #rabl, #radius, #rdoc, #sass, #scss, #slim, #stylus, #textile, #wlang, #yajl

Methods included from Helpers

#attachment, #back, #body, #cache_control, #client_error?, #content_type, #error, #etag, #expires, #headers, #informational?, #last_modified, #logger, #mime_type, #not_found, #not_found?, #redirect, #redirect?, #send_file, #server_error?, #session, #status, #stream, #success?, #time_for, #uri

Constructor Details

- (Base) initialize(app = nil) {|_self| ... }

Returns a new instance of Base

Yields:

  • (_self)

Yield Parameters:

  • _self (Sinatra::Base)

    the object that the method was called on



877
878
879
880
881
882
# File 'lib/sinatra/base.rb', line 877

def initialize(app = nil)
  super()
  @app = app
  @template_cache = Tilt::Cache.new
  yield self if block_given?
end

Class Attribute Details

+ (Object) errors (readonly)

Returns the value of attribute errors



1157
1158
1159
# File 'lib/sinatra/base.rb', line 1157

def errors
  @errors
end

+ (Object) filters (readonly)

Returns the value of attribute filters



1157
1158
1159
# File 'lib/sinatra/base.rb', line 1157

def filters
  @filters
end

+ (Object) routes (readonly)

Returns the value of attribute routes



1157
1158
1159
# File 'lib/sinatra/base.rb', line 1157

def routes
  @routes
end

+ (Object) templates (readonly)

Returns the value of attribute templates



1157
1158
1159
# File 'lib/sinatra/base.rb', line 1157

def templates
  @templates
end

Instance Attribute Details

- (Object) app

Returns the value of attribute app



874
875
876
# File 'lib/sinatra/base.rb', line 874

def app
  @app
end

- (Object) env

Returns the value of attribute env



874
875
876
# File 'lib/sinatra/base.rb', line 874

def env
  @env
end

- (Object) params

Returns the value of attribute params



874
875
876
# File 'lib/sinatra/base.rb', line 874

def params
  @params
end

- (Object) request

Returns the value of attribute request



874
875
876
# File 'lib/sinatra/base.rb', line 874

def request
  @request
end

- (Object) response

Returns the value of attribute response



874
875
876
# File 'lib/sinatra/base.rb', line 874

def response
  @response
end

- (Object) template_cache (readonly)

Returns the value of attribute template_cache



875
876
877
# File 'lib/sinatra/base.rb', line 875

def template_cache
  @template_cache
end

Class Method Details

+ (Object) add_filter(type, path = nil, options = {}, &block)

add a filter



1334
1335
1336
1337
# File 'lib/sinatra/base.rb', line 1334

def add_filter(type, path = nil, options = {}, &block)
  path, options = //, path if path.respond_to?(:each_pair)
  filters[type] << compile!(type, path || //, block, options)
end

+ (Object) after(path = nil, options = {}, &block)

Define an after filter; runs after all requests within the same context as route handlers and may access/modify the request and response.



1329
1330
1331
# File 'lib/sinatra/base.rb', line 1329

def after(path = nil, options = {}, &block)
  add_filter(:after, path, options, &block)
end

+ (Object) before(path = nil, options = {}, &block)

Define a before filter; runs before all requests within the same context as route handlers and may access/modify the request and response.



1322
1323
1324
# File 'lib/sinatra/base.rb', line 1322

def before(path = nil, options = {}, &block)
  add_filter(:before, path, options, &block)
end

+ (Object) build(app)

Creates a Rack::Builder instance with all the middleware set up and the given app as end point.



1469
1470
1471
1472
1473
1474
1475
# File 'lib/sinatra/base.rb', line 1469

def build(app)
  builder = Rack::Builder.new
  setup_default_middleware builder
  setup_middleware builder
  builder.run app
  builder
end

+ (Object) call(env)



1477
1478
1479
# File 'lib/sinatra/base.rb', line 1477

def call(env)
  synchronize { prototype.call(env) }
end

+ (Object) caller_files

Like Kernel#caller but excluding certain magic entries and without line / method information; the resulting array contains filenames only.



1483
1484
1485
# File 'lib/sinatra/base.rb', line 1483

def caller_files
  cleaned_caller(1).flatten
end

+ (Object) caller_locations

Like caller_files, but containing Arrays rather than strings with the first element being the file, and the second being the line.



1489
1490
1491
# File 'lib/sinatra/base.rb', line 1489

def caller_locations
  cleaned_caller 2
end

+ (Object) condition(name = "#{caller.first[/`.*'/]} condition", &block)

Add a route condition. The route is considered non-matching when the block returns false.



1341
1342
1343
# File 'lib/sinatra/base.rb', line 1341

def condition(name = "#{caller.first[/`.*'/]} condition", &block)
  @conditions << generate_method(name, &block)
end

+ (Object) configure(*envs) {|_self| ... }

Set configuration options for Sinatra and/or the app. Allows scoping of settings for certain environments.

Yields:

  • (_self)

Yield Parameters:

  • _self (Sinatra::Base)

    the object that the method was called on



1401
1402
1403
# File 'lib/sinatra/base.rb', line 1401

def configure(*envs)
  yield self if envs.empty? || envs.include?(environment.to_sym)
end

+ (Object) delete(path, opts = {}, &bk)



1370
# File 'lib/sinatra/base.rb', line 1370

def delete(path, opts = {}, &bk)  route 'DELETE',  path, opts, &bk end

+ (Boolean) development?

Returns:

  • (Boolean)


1395
# File 'lib/sinatra/base.rb', line 1395

def development?; environment == :development end

+ (Object) disable(*opts)

Same as calling `set :option, false` for each of the given options.



1238
1239
1240
# File 'lib/sinatra/base.rb', line 1238

def disable(*opts)
  opts.each { |key| set(key, false) }
end

+ (Object) enable(*opts)

Same as calling `set :option, true` for each of the given options.



1233
1234
1235
# File 'lib/sinatra/base.rb', line 1233

def enable(*opts)
  opts.each { |key| set(key, true) }
end

+ (Object) error(*codes, &block)

Define a custom error handler. Optionally takes either an Exception class, or an HTTP status code to specify which errors should be handled.



1245
1246
1247
1248
1249
1250
# File 'lib/sinatra/base.rb', line 1245

def error(*codes, &block)
  args  = compile! "ERROR", //, block
  codes = codes.map { |c| Array(c) }.flatten
  codes << Exception if codes.empty?
  codes.each { |c| (@errors[c] ||= []) << args }
end

+ (Object) extensions

Extension modules registered on this class and all superclasses.



1178
1179
1180
1181
1182
1183
1184
# File 'lib/sinatra/base.rb', line 1178

def extensions
  if superclass.respond_to?(:extensions)
    (@extensions + superclass.extensions).uniq
  else
    @extensions
  end
end

+ (Object) get(path, opts = {}, &block)

Defining a `GET` handler also automatically defines a `HEAD` handler.



1360
1361
1362
1363
1364
1365
1366
# File 'lib/sinatra/base.rb', line 1360

def get(path, opts = {}, &block)
  conditions = @conditions.dup
  route('GET', path, opts, &block)

  @conditions = conditions
  route('HEAD', path, opts, &block)
end

+ (Object) head(path, opts = {}, &bk)



1371
# File 'lib/sinatra/base.rb', line 1371

def head(path, opts = {}, &bk)    route 'HEAD',    path, opts, &bk end

+ (Object) helpers(*extensions, &block)

Makes the methods defined in the block and in the Modules given in `extensions` available to the handlers and templates



1379
1380
1381
1382
# File 'lib/sinatra/base.rb', line 1379

def helpers(*extensions, &block)
  class_eval(&block)   if block_given?
  include(*extensions) if extensions.any?
end

+ (Object) inline_templates=(file = nil)

Load embedded templates from the file; uses the caller's __FILE__ when no file is specified.



1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
# File 'lib/sinatra/base.rb', line 1271

def inline_templates=(file = nil)
  file = (file.nil? || file == true) ? (caller_files.first || File.expand_path($0)) : file

  begin
    io = ::IO.respond_to?(:binread) ? ::IO.binread(file) : ::IO.read(file)
    app, data = io.gsub("\r\n", "\n").split(/^__END__$/, 2)
  rescue Errno::ENOENT
    app, data = nil
  end

  if data
    if app and app =~ /([^\n]*\n)?#[^\n]*coding: *(\S+)/m
      encoding = $2
    else
      encoding = settings.default_encoding
    end
    lines = app.count("\n") + 1
    template = nil
    force_encoding data, encoding
    data.each_line do |line|
      lines += 1
      if line =~ /^@@\s*(.*\S)\s*$/
        template = force_encoding('', encoding)
        templates[$1.to_sym] = [template, file, lines]
      elsif template
        template << line
      end
    end
  end
end

+ (Object) layout(name = :layout, &block)

Define the layout template. The block must return the template source.



1265
1266
1267
# File 'lib/sinatra/base.rb', line 1265

def layout(name = :layout, &block)
  template name, &block
end


1374
# File 'lib/sinatra/base.rb', line 1374

def link(path, opts = {}, &bk)    route 'LINK',    path, opts, &bk end

+ (Object) middleware

Middleware used in this class and all superclasses.



1187
1188
1189
1190
1191
1192
1193
# File 'lib/sinatra/base.rb', line 1187

def middleware
  if superclass.respond_to?(:middleware)
    superclass.middleware + @middleware
  else
    @middleware
  end
end

+ (Object) mime_type(type, value = nil)

Lookup or register a mime type in Rack's mime registry.



1303
1304
1305
1306
1307
1308
1309
# File 'lib/sinatra/base.rb', line 1303

def mime_type(type, value = nil)
  return type      if type.nil?
  return type.to_s if type.to_s.include?('/')
  type = ".#{type}" unless type.to_s[0] == ?.
  return Rack::Mime.mime_type(type, nil) unless value
  Rack::Mime::MIME_TYPES[type] = value
end

+ (Object) mime_types(type)

provides all mime types matching type, including deprecated types:

mime_types :html # => ['text/html']
mime_types :js   # => ['application/javascript', 'text/javascript']


1314
1315
1316
1317
# File 'lib/sinatra/base.rb', line 1314

def mime_types(type)
  type = mime_type type
  type =~ /^application\/(xml|javascript)$/ ? [type, "text/#$1"] : [type]
end

+ (Object) new(*args, &bk)

Create a new instance of the class fronted by its middleware pipeline. The object is guaranteed to respond to #call but may not be an instance of the class new was called on.



1462
1463
1464
1465
# File 'lib/sinatra/base.rb', line 1462

def new(*args, &bk)
  instance = new!(*args, &bk)
  Wrapper.new(build(instance).to_app, instance)
end

+ (Object) not_found(&block)

Sugar for `error(404) { … }`



1253
1254
1255
1256
# File 'lib/sinatra/base.rb', line 1253

def not_found(&block)
  error(404, &block)
  error(Sinatra::NotFound, &block)
end

+ (Object) options(path, opts = {}, &bk)



1372
# File 'lib/sinatra/base.rb', line 1372

def options(path, opts = {}, &bk) route 'OPTIONS', path, opts, &bk end

+ (Object) patch(path, opts = {}, &bk)



1373
# File 'lib/sinatra/base.rb', line 1373

def patch(path, opts = {}, &bk)   route 'PATCH',   path, opts, &bk end

+ (Object) post(path, opts = {}, &bk)



1369
# File 'lib/sinatra/base.rb', line 1369

def post(path, opts = {}, &bk)    route 'POST',    path, opts, &bk end

+ (Boolean) production?

Returns:

  • (Boolean)


1396
# File 'lib/sinatra/base.rb', line 1396

def production?;  environment == :production  end

+ (Object) prototype

The prototype instance used to process requests.



1452
1453
1454
# File 'lib/sinatra/base.rb', line 1452

def prototype
  @prototype ||= new
end

+ (Object) public=(value)



1345
1346
1347
1348
# File 'lib/sinatra/base.rb', line 1345

def public=(value)
  warn ":public is no longer used to avoid overloading Module#public, use :public_folder or :public_dir instead"
  set(:public_folder, value)
end

+ (Object) public_dir



1354
1355
1356
# File 'lib/sinatra/base.rb', line 1354

def public_dir
  public_folder
end

+ (Object) public_dir=(value)



1350
1351
1352
# File 'lib/sinatra/base.rb', line 1350

def public_dir=(value)
  self.public_folder = value
end

+ (Object) put(path, opts = {}, &bk)



1368
# File 'lib/sinatra/base.rb', line 1368

def put(path, opts = {}, &bk)     route 'PUT',     path, opts, &bk end

+ (Object) quit! Also known as: stop!

Stop the self-hosted server if running.



1412
1413
1414
1415
1416
1417
1418
1419
# File 'lib/sinatra/base.rb', line 1412

def quit!
  return unless running?
  # Use Thin's hard #stop! if available, otherwise just #stop.
  running_server.respond_to?(:stop!) ? running_server.stop! : running_server.stop
  $stderr.puts "== Sinatra has ended his set (crowd applauds)" unless handler_name =~/cgi/i
  set :running_server, nil
  set :handler_name, nil
end

+ (Object) register(*extensions, &block)

Register an extension. Alternatively take a block from which an extension will be created and registered on the fly.



1386
1387
1388
1389
1390
1391
1392
1393
# File 'lib/sinatra/base.rb', line 1386

def register(*extensions, &block)
  extensions << Module.new(&block) if block_given?
  @extensions += extensions
  extensions.each do |extension|
    extend extension
    extension.registered(self) if extension.respond_to?(:registered)
  end
end

+ (Object) reset!

Removes all routes, filters, middleware and extension hooks from the current class (not routes/filters/… defined by its superclass).



1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
# File 'lib/sinatra/base.rb', line 1161

def reset!
  @conditions     = []
  @routes         = {}
  @filters        = {:before => [], :after => []}
  @errors         = {}
  @middleware     = []
  @prototype      = nil
  @extensions     = []

  if superclass.respond_to?(:templates)
    @templates = Hash.new { |hash,key| superclass.templates[key] }
  else
    @templates = {}
  end
end

+ (Object) run!(options = {}, &block) Also known as: start!

Run the Sinatra app as a self-hosted server using Thin, Puma, Mongrel, or WEBrick (in that order). If given a block, will call with the constructed handler once we have taken the stage.



1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
# File 'lib/sinatra/base.rb', line 1426

def run!(options = {}, &block)
  return if running?
  set options
  handler         = detect_rack_handler
  handler_name    = handler.name.gsub(/.*::/, '')
  server_settings = settings.respond_to?(:server_settings) ? settings.server_settings : {}
  server_settings.merge!(:Port => port, :Host => bind)

  begin
    start_server(handler, server_settings, handler_name, &block)
  rescue Errno::EADDRINUSE
    $stderr.puts "== Someone is already performing on port #{port}!"
    raise
  ensure
    quit!
  end
end

+ (Boolean) running?

Check whether the self-hosted server is running or not.

Returns:

  • (Boolean)


1447
1448
1449
# File 'lib/sinatra/base.rb', line 1447

def running?
  running_server?
end

+ (Object) set(option, value = (not_set = true), ignore_setter = false, &block)

Sets an option to the given value. If the value is a proc, the proc will be called every time the option is accessed.

Raises:

  • (ArgumentError)


1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
# File 'lib/sinatra/base.rb', line 1197

def set(option, value = (not_set = true), ignore_setter = false, &block)
  raise ArgumentError if block and !not_set
  value, not_set = block, false if block

  if not_set
    raise ArgumentError unless option.respond_to?(:each)
    option.each { |k,v| set(k, v) }
    return self
  end

  if respond_to?("#{option}=") and not ignore_setter
    return __send__("#{option}=", value)
  end

  setter = proc { |val| set option, val, true }
  getter = proc { value }

  case value
  when Proc
    getter = value
  when Symbol, Fixnum, FalseClass, TrueClass, NilClass
    getter = value.inspect
  when Hash
    setter = proc do |val|
      val = value.merge val if Hash === val
      set option, val, true
    end
  end

  define_singleton("#{option}=", setter) if setter
  define_singleton(option, getter) if getter
  define_singleton("#{option}?", "!!#{option}") unless method_defined? "#{option}?"
  self
end

+ (Object) settings

Access settings defined with Base.set.



913
914
915
# File 'lib/sinatra/base.rb', line 913

def self.settings
  self
end

+ (Object) template(name, &block)

Define a named template. The block must return the template source.



1259
1260
1261
1262
# File 'lib/sinatra/base.rb', line 1259

def template(name, &block)
  filename, line = caller_locations.first
  templates[name] = [block, filename, line.to_i]
end

+ (Boolean) test?

Returns:

  • (Boolean)


1397
# File 'lib/sinatra/base.rb', line 1397

def test?;        environment == :test        end


1375
# File 'lib/sinatra/base.rb', line 1375

def unlink(path, opts = {}, &bk)  route 'UNLINK',  path, opts, &bk end

+ (Object) use(middleware, *args, &block)

Use the specified Rack middleware



1406
1407
1408
1409
# File 'lib/sinatra/base.rb', line 1406

def use(middleware, *args, &block)
  @prototype = nil
  @middleware << [middleware, args, block]
end

Instance Method Details

- (Object) call(env)

Rack call interface.



885
886
887
# File 'lib/sinatra/base.rb', line 885

def call(env)
  dup.call!(env)
end

- (Object) call!(env)

:nodoc:



889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
# File 'lib/sinatra/base.rb', line 889

def call!(env) # :nodoc:
  @env      = env
  @request  = Request.new(env)
  @response = Response.new
  @params   = indifferent_params(@request.params)
  template_cache.clear if settings.reload_templates
  force_encoding(@params)

  @response['Content-Type'] = nil
  invoke { dispatch! }
  invoke { error_block!(response.status) } unless @env['sinatra.error']

  unless @response['Content-Type']
    if Array === body and body[0].respond_to? :content_type
      content_type body[0].content_type
    else
      content_type :html
    end
  end

  @response.finish
end

- (Object) forward

Forward the request to the downstream app – middleware only.



943
944
945
946
947
948
949
950
# File 'lib/sinatra/base.rb', line 943

def forward
  fail "downstream app not set" unless @app.respond_to? :call
  status, headers, body = @app.call env
  @response.status = status
  @response.body = body
  @response.headers.merge! headers
  nil
end

- (Object) halt(*response)

Exit the current block, halts any further processing of the request, and returns the specified response.



930
931
932
933
# File 'lib/sinatra/base.rb', line 930

def halt(*response)
  response = response.first if response.length == 1
  throw :halt, response
end

- (Object) new!



1457
# File 'lib/sinatra/base.rb', line 1457

alias new! new

- (Object) options



922
923
924
925
926
# File 'lib/sinatra/base.rb', line 922

def options
  warn "Sinatra::Base#options is deprecated and will be removed, " \
    "use #settings instead."
  settings
end

- (Object) pass(&block)

Pass control to the next matching route. If there are no more matching routes, Sinatra will return a 404 response.



938
939
940
# File 'lib/sinatra/base.rb', line 938

def pass(&block)
  throw :pass, block
end

- (Object) settings

Access settings defined with Base.set.



918
919
920
# File 'lib/sinatra/base.rb', line 918

def settings
  self.class.settings
end