Permalink
Browse files

increase inline documentation

  • Loading branch information...
rkh committed Sep 22, 2010
1 parent 1abac32 commit ac4d015ee4bfd8ad7252ddb930a8898333475f39
Showing with 26 additions and 3 deletions.
  1. +17 −2 lib/sinatra/base.rb
  2. +9 −1 lib/sinatra/showexceptions.rb
View
@@ -17,6 +17,8 @@ def accept
@env['HTTP_ACCEPT'].to_s.split(',').map { |a| a.split(';')[0].strip }
end
+ # Whether or not the web server (or a reverse proxy in front of it) is
+ # using SSL to communicate with the client.
def secure?
(@env['HTTP_X_FORWARDED_PROTO'] || @env['rack.url_scheme']) == 'https'
end
@@ -443,7 +445,7 @@ def call(env)
attr_accessor :env, :request, :response, :params
- def call!(env)
+ def call!(env) # :nodoc:
@env = env
@request = Request.new(env)
@response = Response.new
@@ -613,6 +615,7 @@ def indifferent_params(params)
end
end
+ # Creates a Hash with indifferent access.
def indifferent_hash
Hash.new {|hash,key| hash[key.to_s] if Symbol === key }
end
@@ -663,6 +666,7 @@ def dispatch!
filter! :after unless env['sinatra.static_file']
end
+ # Special treatment for 404s in order to play nice with cascades.
def handle_not_found!(boom)
@env['sinatra.error'] = boom
@response.status = 404
@@ -671,6 +675,7 @@ def handle_not_found!(boom)
error_block! boom.class, NotFound
end
+ # Error handling during requests.
def handle_exception!(boom)
@env['sinatra.error'] = boom
@@ -712,6 +717,8 @@ def dump_errors!(boom)
class << self
attr_reader :routes, :filters, :templates, :errors
+ # Removes all routes, filters, middleware and extension hooks from the
+ # current class (not routes/filters/... defined by its superclass).
def reset!
@conditions = []
@routes = {}
@@ -871,10 +878,13 @@ def condition(&block)
end
private
+ # Condition for matching host name. Parameter might be String or Regexp.
def host_name(pattern)
condition { pattern === request.host }
end
+ # Condition for matching user agent. Parameter should be Regexp.
+ # Will set params[:agent].
def user_agent(pattern)
condition {
if request.user_agent =~ pattern
@@ -887,6 +897,7 @@ def user_agent(pattern)
end
alias_method :agent, :user_agent
+ # Condition for matching mimetypes. Accepts file extensions.
def provides(*types)
types = [types] unless types.kind_of? Array
types.map!{|t| mime_type(t)}
@@ -985,6 +996,8 @@ def helpers(*extensions, &block)
include(*extensions) if extensions.any?
end
+ # Register an extension. Alternatively take a block from which an
+ # extension will be created and registered on the fly.
def register(*extensions, &block)
extensions << Module.new(&block) if block_given?
@extensions += extensions
@@ -1089,7 +1102,7 @@ def metadef(message, &block)
end
public
- CALLERS_TO_IGNORE = [
+ CALLERS_TO_IGNORE = [ # :nodoc:
/\/sinatra(\/(base|main|showexceptions))?\.rb$/, # all sinatra code
/lib\/tilt.*\.rb$/, # all tilt code
/\(.*\)/, # generated code
@@ -1108,6 +1121,8 @@ def caller_files
map { |file,line| file }
end
+ # Like caller_files, but containing Arrays rather than strings with the
+ # first element being the file, and the second being the line.
def caller_locations
caller(1).
map { |line| line.split(/:(?=\d|in )/)[0,2] }.
@@ -1,12 +1,20 @@
require 'rack/showexceptions'
module Sinatra
+ # Sinatra::ShowExceptions catches all exceptions raised from the app it
+ # wraps. It shows a useful backtrace with the sourcefile and clickable
+ # context, the whole Rack environment and the request data.
+ #
+ # Be careful when you use this on public-facing sites as it could reveal
+ # information helpful to attackers.
class ShowExceptions < Rack::ShowExceptions
def initialize(app)
@app = app
@template = ERB.new(TEMPLATE)
end
+ private
+
def frame_class(frame)
if frame.filename =~ /lib\/sinatra.*\.rb/
"framework"
@@ -18,7 +26,7 @@ def frame_class(frame)
end
end
-TEMPLATE = <<HTML
+TEMPLATE = <<-HTML # :nodoc:
<!DOCTYPE html>
<html>
<head>

0 comments on commit ac4d015

Please sign in to comment.