In Merb, views are actually methods on controllers. This provides not-insignificant speed benefits, as well as preventing us from needing to copy over instance variables, which we think is proof that everything belongs in one class to begin with.
Unfortunately, this means that view helpers need to be included into the <strong>Controller</strong> class. To avoid causing confusion when your helpers potentially conflict with our instance methods, we use an _ to disambiguate. As long as you don't begin your helper methods with _, you only need to worry about conflicts with Merb methods that are part of the public API.
before is a class method that allows you to specify before filters in your controllers. Filters can either be a symbol or string that corresponds to a method name to call, or a proc object. if it is a method name that method will be called and if it is a proc it will be called with an argument of self where self is the current controller object. When you use a proc as a filter it needs to take one parameter.
after is identical, but the filters are run after the action is invoked.
before :some_filter before :authenticate, :exclude => [:login, :signup] before :has_role, :with => ["Admin"], :exclude => [:index, :show] before Proc.new { some_method }, :only => :foo before :authorize, :unless => :logged_in?
You can use either :only => :actionname or :exclude => [:this, :that] but not both at once. :only will only run before the listed actions and :exclude will run for every action that is not listed.
Merb's before filter chain is very flexible. To halt the filter chain you use throw :halt. If throw is called with only one argument of :halt the return value of the method filters_halted will be what is rendered to the view. You can override filters_halted in your own controllers to control what it outputs. But the throw construct is much more powerful than just that.
throw :halt can also take a second argument. Here is what that second argument can be and the behavior each type can have:
String: when the second argument is a string then that string will be what is rendered to the browser. Since merb's #render method returns a string you can render a template or just use a plain string:
throw :halt, "You don't have permissions to do that!" throw :halt, render(:action => :access_denied)
Symbol: If the second arg is a symbol, then the method named after that symbol will be called
throw :halt, :must_click_disclaimer
Proc: If the second arg is a Proc, it will be called and its return value will be what is rendered to the browser:
throw :halt, proc { access_denied } throw :halt, proc { Tidy.new(c.index) }
:only<Symbol, Array> |
A list of actions that this filter should apply to |
:exclude<Symbol, Array |
A list of actions that this filter should not apply to |
:if<Symbol, Proc> |
Only apply the filter if the method named after the symbol or calling the proc evaluates to true |
:unless<Symbol, Proc> |
Only apply the filter if the method named after the symbol or calling the proc evaluates to false |
Arguments to be passed to the filter. Since we are talking method/proc calls, filter method or Proc should to have the same arity as number of elements in Array you pass to this option. |
Filter |
<Array[Symbol, (Symbol, String, Proc)]> |
params[:action] and params[:controller] have been deprecated as of the 0.9.0 release. They are no longer set during dispatch, and have been replaced by action_name and controller_name respectively.
Most of this list is simply constants frozen for efficiency and lowered memory consumption. Every time Ruby VM comes across a string or a number or a regexp literal, new object is created.
This means if you refer to the same string 6 times per request and your application takes 100 requests per second, there are 600 objects for weak MRI garbage collector to work on.
GC cycles take up to 80% (!) time of request processing in some cases. Eventually Rubinius and maybe MRI 2.0 gonna improve this situation but at the moment, all commonly used strings, regexp and numbers used as constants so no extra objects created and VM just operates pointers.
Require this rather than autoloading it so we can be sure the default template gets registered
require "time" # httpdate
To replace an existing logger with a new one:
Merb.logger.set_log(log{String, IO},level{Symbol, String}) for example: Merb.logger.set_log($stdout, Merb::Logger::Levels[:fatal])
Available logging levels are
Merb::Logger::{ Fatal, Error, Warn, Info, Debug }
Logging via:
Merb.logger.fatal(message<String>,&block) Merb.logger.error(message<String>,&block) Merb.logger.warn(message<String>,&block) Merb.logger.info(message<String>,&block) Merb.logger.debug(message<String>,&block)
Logging with autoflush:
Merb.logger.fatal!(message<String>,&block) Merb.logger.error!(message<String>,&block) Merb.logger.warn!(message<String>,&block) Merb.logger.info!(message<String>,&block) Merb.logger.debug!(message<String>,&block)
Flush the buffer to
Merb.logger.flush
Remove the current log object
Merb.logger.close
To initialize the logger you create a new object, proxies to set_log.
Merb::Logger.new(log{String, IO},level{Symbol, String})
*generators |
Generator paths to add to the list of generators. |
Recommended way to add Generator load paths for plugin authors.
:api: public
# File lib/merb-core.rb, line 756 def add_generators(*generators) @generators ||= [] @generators += generators end
Any specific outgoing headers should be included here. These are not the content-type header but anything in addition to it. transform_method should be set to a symbol of the method used to transform a resource into this mime type. For example for the :xml mime type an object might be transformed by calling :to_xml, or for the :js mime type, :to_json. If there is no transform method, use nil.
Adding a mime-type adds a render_type method that sets the content type and calls render.
By default this does: def render_all, def render_yaml, def render_text, def render_html, def render_xml, def render_js, and def render_yaml
key<Symbol> |
The name of the mime-type. This is used by the provides API |
transform_method<~to_s> |
The associated method to call on objects to convert them to the appropriate mime-type. For instance, :json would use :to_json as its transform_method. |
A list of possible values sent in the Accept header, such as text/html, that should be associated with this content-type. | |
new_response_headers<Hash> |
The response headers to set for the the mime type. For example: 'Content-Type' => 'application/json; charset=utf-8'; As a shortcut for the common charset option, use :charset => 'utf-8', which will be correctly appended to the mimetype itself. |
&block |
a block which recieves the current controller when the format |
is set (in the controller's #content_type method)
nil
:api: public
# File lib/merb-core/controller/mime.rb, line 70 def add_mime_type(key, transform_method, mimes, new_response_headers = {}, default_quality = 1, &block) enforce!(key => Symbol, mimes => Array) content_type = new_response_headers["Content-Type"] || mimes.first if charset = new_response_headers.delete(:charset) content_type += "; charset=#{charset}" end ResponderMixin::TYPES.update(key => {:accepts => mimes, :transform_method => transform_method, :content_type => content_type, :response_headers => new_response_headers, :default_quality => default_quality, :response_block => block }) mimes.each do |mime| ResponderMixin::MIMES.update(mime => key) end Merb::RenderMixin.class_eval def render_#{key}(thing = nil, opts = {}) self.content_type = :#{key} render thing, opts end, __FILE__, __LINE__ nil end
*rakefiles |
Rakefile paths to add to the list of Rakefiles. |
Recommended way to add Rakefiles load path for plugins authors.
:api: public
# File lib/merb-core.rb, line 744 def add_rakefiles(*rakefiles) @rakefiles ||= [] @rakefiles += rakefiles end
Hash{String => Symbol} |
A hash mapping Content-Type values to the mime type key of the appropriate entry in available_mime_types |
:api: public
# File lib/merb-core/controller/mime.rb, line 30 def available_accepts ResponderMixin::MIMES end
Returns a hash of the available mime types.
Hash{Symbol => Hash{Symbol => Object}} |
The available mime types. |
Each entry corresponds to a call to add_mime_type, having the mime type key (:html, :xml, :json, etc.) as the key and a hash containing the following entries:
:accepts # the mime types that will be recognized by this entry :transform_method # the method called on an object to convert it to content of this type (such as to_json) :content_type # the value set to the "Content-Type" HTTP header when this mime is sent in a response :response_headers # sent in a response using this content type :default_quality # the scale factor used in describing content type preference :response_block # the block to be called with the controller when a request responds to this mime type
:api: public
# File lib/merb-core/controller/mime.rb, line 21 def available_mime_types ResponderMixin::TYPES end
Boolean |
True if Merb is running as an application with bundled gems. |
Bundling required gems makes your application independent from the environment it runs in. It is a good practice to freeze application framework and gems and is very useful when application is run in some sort of sandbox, for instance, shared hosting with preconfigured gems.
:api: public
# File lib/merb-core.rb, line 526 def bundled? $BUNDLE || ENV.key?("BUNDLE") end
If block was given configures using the block.
&block |
Configuration parameter block, see example below. |
The current configuration. |
See Merb::GlobalHelpers.load_config for configuration options list.
Merb.config do beer "good" hashish :foo => "bar" environment "development" log_level "debug" use_mutex false exception_details true reload_classes true reload_time 0.5 end
:api: public
# File lib/merb-core.rb, line 675 def config(&block) Merb::Config.configure(&block) if block_given? Config end
RegExp |
Regular expression against which deferred actions are matched by Rack application handler. |
Concatenates :deferred_actions configuration option values.
:api: public
# File lib/merb-core.rb, line 421 def deferred_actions @deferred ||= begin if Merb::Config[:deferred_actions].empty? /^\00$$/ else /#{Merb::Config[:deferred_actions].join("|")}/ end end end
type<Symbol> |
The type of path to retrieve directory for, e.g. :view. |
The directory for the requested type. |
:api: public
# File lib/merb-core.rb, line 290 def dir_for(type) Merb.load_paths[type].first end
Boolean |
True if all components (or just one) are disabled. |
:api: public
# File lib/merb-core.rb, line 710 def disabled?(*components) components.all? { |c| disabled_components.include?(c) } end
Array |
All components that have been disabled. |
:api: public
# File lib/merb-core.rb, line 702 def disabled_components Merb::Config[:disabled_components] ||= [] end
Array |
All components that should be disabled. |
:api: public
# File lib/merb-core.rb, line 694 def disabled_components=(components) disabled_components.replace components end
Ask the question about which environment you're in.
env<Symbol, String> |
Name of the environment to query |
Merb.env #=> production Merb.env?(:production) #=> true Merb.env?(:development) #=> false
:api: public
# File lib/merb-core.rb, line 646 def env?(env) Merb.env == env.to_s end
Required to show exceptions in the log file
e<Exception> |
The exception that a message is being generated for |
:api: plugin
# File lib/merb-core/controller/exceptions.rb, line 346 def self.exception(e) "#{ e.message } - (#{ e.class })\n" << "#{(e.backtrace or []).join("\n")}" end
Set the current exiting state of Merb. Setting this state to true also alerts Extlib to exit and clean up its state.
Boolean |
The current exiting state of Merb |
:api: private
# File lib/merb-core.rb, line 56 def exiting=(bool) Extlib.exiting = bool @exiting = bool if bool if Extlib.const_defined?("Pooling") && Extlib::Pooling.scavenger Extlib::Pooling.scavenger.wakeup end while prc = self.at_exit_procs.pop prc.call end unless Merb::Config[:reap_workers_quickly] end @exiting end
Perform a hard Exit. Print a backtrace to the merb logger before exiting if verbose is enabled.
:api: private
# File lib/merb-core.rb, line 435 def fatal!(str, e = nil) Merb::Config[:log_stream] = STDOUT if STDOUT.tty? Merb.reset_logger! Merb.logger.fatal! Merb.logger.fatal!("\e[1;31;47mFATAL: #{str}\e[0m") Merb.logger.fatal! print_colorized_backtrace(e) if e && Merb::Config[:verbose] if Merb::Config[:show_ugly_backtraces] raise e else exit(1) end end
:api: plugin
# File lib/merb-core.rb, line 775 def forking_environment? !on_windows? && !on_jruby? end
Array(String) |
Paths generators are loaded from |
Recommended way to find out what paths generators are loaded from.
:api: public
# File lib/merb-core.rb, line 733 def generators @generators ||= [] end
type<Symbol> |
The type of path to retrieve glob for, e.g. :view. |
The pattern with which to match files within the type directory. |
:api: public
# File lib/merb-core.rb, line 301 def glob_for(type) Merb.load_paths[type][1] end
Load configuration and assign the logger.
options<Hash> |
Options to pass on to the Merb config. |
:host<String> |
host to bind to, default is 0.0.0.0. |
:port<Fixnum> |
port to run Merb application on, default is 4000. |
:adapter<String> |
name of Rack adapter to use, default is "runner" |
:rackup<String> |
name of Rack init file to use, default is "rack.rb" |
:reload_classes<Boolean> |
whether Merb should reload classes on each request, default is true |
:environment<String> |
name of environment to use, default is development |
:merb_root<String> |
Merb application root, default is Dir.pwd |
:use_mutex<Boolean> |
turns action dispatch synchronization on or off, default is on (true) |
:log_delimiter<String> |
what Merb logger uses as delimiter between message sections, default is " ~ " |
:log_auto_flush<Boolean> |
whether the log should automatically flush after new messages are added, defaults to true. |
:log_stream<IO> |
IO handle for logger. Defaults to STDOUT. |
:log_file<String> |
File path for logger. Overrides :log_stream. |
:log_level<Symbol> |
logger level, default is :info |
array of disabled component names, for instance, to disable json gem, specify :json. Default is empty array. | |
:deferred_actions<Array(Symbol, String)]> |
names of actions that should be deferred no matter what controller they belong to. Default is empty array. |
Some of these options come from command line on Merb application start, some of them are set in Merb init file or environment-specific.
:api: public
# File lib/merb-core.rb, line 597 def load_config(options = {}) Merb::Config.setup(Merb::Config.defaults.merge(options)) Merb::BootLoader::Logger.run end
Load all basic dependencies (selected BootLoaders only). This sets up Merb framework component paths (directories for models, controllers, etc) using framework.rb or default layout, loads init file and dependencies specified in it and runs before_app_loads hooks.
options<Hash> |
Options to pass on to the Merb config. |
:api: public
# File lib/merb-core.rb, line 612 def load_dependencies(options = {}) load_config(options) Merb::BootLoader::BuildFramework.run Merb::BootLoader::Dependencies.run Merb::BootLoader::BeforeAppLoads.run end
Path to the log directory which contains the log file. |
:api: public
# File lib/merb-core.rb, line 397 def log_path case Merb::Config[:log_file] when String then File.dirname(Merb::Config[:log_file]) else Merb.root_path("log") end end
The path to the log file. If this Merb instance is running as a daemon this will return STDOUT. |
When Merb.testing? the port is modified to become :test - this keeps this special environment situation from ending up in the memoized @streams just once, thereby never taking changes into account again. Now, it will be memoized as :test - and just logging to merb_test.log.
:api: public
# File lib/merb-core.rb, line 366 def log_stream(port = "main") port = :test if Merb.testing? @streams ||= {} @streams[port] ||= begin log = if Merb.testing? log_path / "merb_test.log" elsif !Merb::Config[:daemonize] && !Merb::Config[:force_logging] STDOUT else log_path / "merb.#{port}.log" end if log.is_a?(IO) stream = log elsif File.exist?(log) stream = File.open(log, (File::WRONLY | File::APPEND)) else FileUtils.mkdir_p(File.dirname(log)) stream = File.open(log, (File::WRONLY | File::APPEND | File::CREAT)) stream.write("#{Time.now.httpdate} #{Merb::Config[:log_delimiter]} " "info #{Merb::Config[:log_delimiter]} Logfile created\n") end stream.sync = true stream end end
Merge environment settings
This can allow you to have a "localdev" environment that runs like your "development".
OR
A "staging" environment that runs identical to your "production" environment.
From any environment config file (ie, development.rb, custom.rb, localdev.rb, etc).
staging.rb: Merb.merge_env "production" # We want to use all the settings production uses Merb::Config.use do |c| c[:log_level] = "debug" # except we want debug log level c[:log_stream] = @some_io # and log to this IO handle c[:exception_details] = true # and we want to see exception details end
env<~String> |
Environment to run like |
use_db<~Boolean> |
Should Merb use the merged environments DB connection |
Defaults to +false+
:api: public
# File lib/merb-core.rb, line 103 def merge_env(env,use_db=false) if Merb.environment_info.nil? Merb.environment_info = { :real_env => Merb.environment, :merged_envs => [], :db_env => Merb.environment } end #Only load if it hasn't been loaded unless Merb.environment_info[:merged_envs].member? env Merb.environment_info[:merged_envs] << env env_file = Merb.dir_for(:config) / "environments" / ("#{env}.rb") if File.exists?(env_file) load(env_file) else Merb.logger.warn! "Environment file does not exist! #{env_file}" end end # Mark specific environment to load when ORM loads, # if multiple environments are loaded, the last one # with use_db as TRUE will be loaded if use_db Merb.environment_info[:db_env] = env end end
key<Symbol> |
The key that represents the mime-type. |
Symbol |
The transform method for the mime type, e.g. :to_json. |
ArgumentError |
The requested mime type is not valid. |
:api: private
# File lib/merb-core/controller/mime.rb, line 129 def mime_transform_method(key) raise ArgumentError, ":#{key} is not a valid MIME-type" unless ResponderMixin::TYPES.key?(key) ResponderMixin::TYPES[key][:transform_method] end
:api: plugin
# File lib/merb-core.rb, line 780 def on_jruby? RUBY_PLATFORM =~ Merb::Const::JAVA_PLATFORM_REGEXP end
:api: plugin
# File lib/merb-core.rb, line 785 def on_windows? RUBY_PLATFORM =~ Merb::Const::WIN_PLATFORM_REGEXP end
@deprecated
# File lib/merb-core.rb, line 482 def orm_generator_scope Merb.logger.warn!("WARNING: Merb.orm_generator_scope is deprecated!") return :merb_default if Merb.orm == :none Merb.orm end
Print a colorized backtrace to the merb logger.
:api: private
# File lib/merb-core.rb, line 455 def print_colorized_backtrace(e) e.backtrace.map! do |line| line.gsub(/^#{Merb.framework_root}/, "\e[34mFRAMEWORK_ROOT\e[31m") end Merb.logger.fatal! "\e[34mFRAMEWORK_ROOT\e[0m = #{Merb.framework_root}" Merb.logger.fatal! Merb.logger.fatal! "\e[31m#{e.class}: \e[1;31;47m#{e.message}\e[0m" e.backtrace.each do |line| Merb.logger.fatal! "\e[31m#{line}\e[0m" end end
This is the mechanism for setting up your application layout. There are three application layouts in Merb:
Regular app/:type layout of Ruby on Rails fame:
app/models for models app/mailers for mailers (special type of controllers) app/parts for parts, Merb components app/views for templates app/controllers for controller lib for libraries
Flat application layout:
application.rb for models, controllers, mailers, etc config/init.rb for initialization and router configuration config/framework.rb for framework and dependencies configuration views for views
Camping-style "very flat" application layout, where the whole Merb
application and configs are contained within a single file.
Autoloading for lib uses an empty glob by default. If you want to have your libraries under lib use autoload, add the following to Merb init file:
Merb.push_path(:lib, Merb.root / "lib", "*/.rb") # glob set explicity.
Then lib/magicwand/lib/magicwand.rb with MagicWand module will be autoloaded when you first access that constant.
This method gives you a way to build up your own application structure, for instance, to reflect the structure Rails uses to simplify transition of legacy application, you can set it up like this:
Merb.push_path(:model, Merb.root / "app" / "models", "*/.rb") Merb.push_path(:mailer, Merb.root / "app" / "models", "*/.rb") Merb.push_path(:controller, Merb.root / "app" / "controllers", "*/.rb") Merb.push_path(:view, Merb.root / "app" / "views", "*/.rb")
type<Symbol> |
The type of path being registered (i.e. :view) |
path<String> |
The full path |
file_glob<String> |
A glob that will be used to autoload files under the path. Defaults to "*/.rb". |
:api: public
# File lib/merb-core.rb, line 256 def push_path(type, path, file_glob = "**/*.rb") enforce!(type => Symbol) load_paths[type] = [path, file_glob] end
Array(String) |
Paths Rakefiles are loaded from. |
Recommended way to find out what paths Rakefiles are loaded from.
:api: public
# File lib/merb-core.rb, line 722 def rakefiles @rakefiles ||= [] end
Reload application and framework classes. See Merb::BootLoader::ReloadClasses for details.
:api: public
# File lib/merb-core.rb, line 623 def reload Merb::BootLoader::ReloadClasses.reload end
Removes a MIME-type from the mime-type list.
key<Symbol> |
The key that represents the mime-type to remove. |
(Boolean, Hash{Symbol => Object}) |
If it was present, the old specification of the MIME-type. Same structure |
as a value in Merb.available_mime_types. False if the key was not present.
:all is the key for /; It can't be removed.
:api: public
# File lib/merb-core/controller/mime.rb, line 114 def remove_mime_type(key) return false if key == :all ResponderMixin::TYPES.delete(key) end
Removes given types of application components from load path Merb uses for autoloading.
*args<Array(Symbol)> |
component(s) names, for instance, :views, :models |
Using this combined with Merb::GlobalHelpers.push_path you can make your Merb application use legacy Rails application components.
Merb.root = "path/to/legacy/app/root" Merb.remove_paths(:mailer) Merb.push_path(:mailer, Merb.root / "app" / "models", "*/.rb")
Will make Merb use app/models for mailers just like Ruby on Rails does.
:api: public
# File lib/merb-core.rb, line 279 def remove_paths(*args) args.each {|arg| load_paths.delete(arg)} end
Removes the logger for the current thread (nil).
:api: public
# File lib/merb-core.rb, line 350 def reset_logger! Thread.current[:merb_logger] = nil end
value<String> |
Path to the root directory. |
:api: public
# File lib/merb-core.rb, line 317 def root=(value) @root = value end
*path |
The relative path (or list of path components) to a directory under the root of the application. |
The full path including the root. |
Merb.root = "/home/merb/app" Merb.path("images") # => "/home/merb/app/images" Merb.path("views", "admin") # => "/home/merb/app/views/admin"
@public
# File lib/merb-core.rb, line 335 def root_path(*path) File.join(root, *path) end
# File lib/merb-core.rb, line 789 def run_later(&blk) Merb::Dispatcher.work_queue << blk end
:api: private
# File lib/merb-core.rb, line 794 def running_irb? @running_irb end
Start Merb by setting up the Config and then starting the server. Set the Merb application environment and the root path.
argv<String, Hash> |
The config arguments to start Merb with. Defaults to ARGV. |
:api: public
# File lib/merb-core.rb, line 140 def start(argv = ARGV) Merb::Config[:original_log_stream] = Merb::Config[:log_stream] Merb::Config[:log_stream] ||= STDOUT if Hash === argv Merb::Config.setup(argv) elsif !argv.nil? Merb::Config.parse_args(argv) end # Keep information that we run inside IRB to guard it against overriding in init.rb @running_irb = Merb::Config[:adapter] == 'irb' Merb::Config[:log_stream] = STDOUT Merb.environment = Merb::Config[:environment] Merb.root = Merb::Config[:merb_root] case Merb::Config[:action] when :kill Merb::Server.kill(Merb::Config[:port], 2) when :kill_9 Merb::Server.kill(Merb::Config[:port], 9) when :fast_deploy Merb::Server.kill("main", "HUP") else Merb::Server.start(Merb::Config[:port], Merb::Config[:cluster]) @started = true end end
@deprecated
# File lib/merb-core.rb, line 499 def test_framework_generator_scope Merb.logger.warn!("WARNING: Merb.test_framework_generator_scope is deprecated") Merb.test_framework end
Install a signal handler for a given signal unless signals have been disabled with Merb.disable(:signals)
signal |
The name of the signal to install a handler for. |
&block |
The block to be run when the given signal is received. |
:api: public
# File lib/merb-core.rb, line 768 def trap(signal, &block) if Signal.list.include?(signal) Kernel.trap(signal, &block) unless Merb.disabled?(:signals) end end
Boolean |
True if Merb is running in debug or verbose mode |
:api: public
# File lib/merb-core.rb, line 534 def verbose_logging? (ENV['DEBUG'] || $DEBUG || Merb::Config[:verbose]) && Merb.logger end
Generated with the Darkfish Rdoc Generator 2.