mirror of
https://github.com/haml/haml.git
synced 2022-11-09 12:33:31 -05:00
[Haml] Convert Haml::Engine docs to YARD.
This commit is contained in:
Nathan Weizenbaum
parent
f5d1ba646f
commit
9616393b89
1 changed files with 101 additions and 80 deletions
|
|
@ -5,58 +5,62 @@ require 'haml/filters'
|
|||
require 'haml/error'
|
||||
|
||||
module Haml
|
||||
# This is the class where all the parsing and processing of the Haml
|
||||
# template is done. It can be directly used by the user by creating a
|
||||
# new instance and calling <tt>to_html</tt> to render the template. For example:
|
||||
# This is the frontend for using Haml programmatically.
|
||||
# It can be directly used by the user by creating a
|
||||
# new instance and calling \{#render} to render the template.
|
||||
# For example:
|
||||
#
|
||||
# template = File.read('templates/really_cool_template.haml')
|
||||
# haml_engine = Haml::Engine.new(template)
|
||||
# output = haml_engine.to_html
|
||||
# puts output
|
||||
# template = File.read('templates/really_cool_template.haml')
|
||||
# haml_engine = Haml::Engine.new(template)
|
||||
# output = haml_engine.render
|
||||
# puts output
|
||||
class Engine
|
||||
include Precompiler
|
||||
|
||||
# Allow reading and writing of the options hash
|
||||
# The options hash.
|
||||
# See [the Haml options documentation](../Haml.html#haml_options).
|
||||
#
|
||||
# @return [Hash<Symbol, Object>]
|
||||
attr_accessor :options
|
||||
|
||||
# This string contains the source code that is evaluated
|
||||
# to produce the Haml document.
|
||||
# The source code that is evaluated to produce the Haml document.
|
||||
#
|
||||
# @return [String]
|
||||
attr_accessor :precompiled
|
||||
|
||||
# A string containing the indentation used for the Haml document.
|
||||
# nil if the indentation is ambiguous
|
||||
# The indentation used in the Haml document,
|
||||
# or `nil` if the indentation is ambiguous
|
||||
# (for example, for a single-level document).
|
||||
#
|
||||
# @return [String]
|
||||
attr_accessor :indentation
|
||||
|
||||
# True if the format is XHTML
|
||||
# @return [Boolean] Whether or not the format is XHTML.
|
||||
def xhtml?
|
||||
not html?
|
||||
end
|
||||
|
||||
# True if the format is any flavor of HTML
|
||||
# @return [Boolean] Whether or not the format is any flavor of HTML.
|
||||
def html?
|
||||
html4? or html5?
|
||||
end
|
||||
|
||||
# True if the format is HTML4
|
||||
# @return [Boolean] Whether or not the format is HTML4.
|
||||
def html4?
|
||||
@options[:format] == :html4
|
||||
end
|
||||
|
||||
# True if the format is HTML5
|
||||
# @return [Boolean] Whether or not the format is HTML5.
|
||||
def html5?
|
||||
@options[:format] == :html5
|
||||
end
|
||||
|
||||
# Creates a new instace of Haml::Engine that will compile the given
|
||||
# template string when <tt>render</tt> is called.
|
||||
# See the Haml module documentation for available options.
|
||||
#
|
||||
#--
|
||||
# When adding options, remember to add information about them
|
||||
# to lib/haml.rb!
|
||||
#++
|
||||
# Precompiles the Haml template.
|
||||
#
|
||||
# @param template [String] The Haml template
|
||||
# @param options [Hash<Symbol, Object>] An options hash;
|
||||
# wee [the Haml options documentation](../Haml.html#haml_options)
|
||||
# @raise [Haml::Error] if there's a Haml syntax error in the template
|
||||
def initialize(template, options = {})
|
||||
@options = {
|
||||
:suppress_eval => false,
|
||||
|
|
@ -108,39 +112,45 @@ END
|
|||
|
||||
# Processes the template and returns the result as a string.
|
||||
#
|
||||
# +scope+ is the context in which the template is evaluated.
|
||||
# If it's a Binding or Proc object,
|
||||
# Haml uses it as the second argument to Kernel#eval;
|
||||
# otherwise, Haml just uses its #instance_eval context.
|
||||
# `scope` is the context in which the template is evaluated.
|
||||
# If it's a `Binding` or `Proc` object,
|
||||
# Haml uses it as the second argument to `Kernel#eval`;
|
||||
# otherwise, Haml just uses its `#instance_eval` context.
|
||||
#
|
||||
# Note that Haml modifies the evaluation context
|
||||
# (either the scope object or the "self" object of the scope binding).
|
||||
# It extends Haml::Helpers, and various instance variables are set
|
||||
# (all prefixed with "haml").
|
||||
# (either the scope object or the `self` object of the scope binding).
|
||||
# It extends {Haml::Helpers}, and various instance variables are set
|
||||
# (all prefixed with `haml_`).
|
||||
# For example:
|
||||
#
|
||||
# s = "foobar"
|
||||
# Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
|
||||
# s = "foobar"
|
||||
# Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
|
||||
#
|
||||
# # s now extends Haml::Helpers
|
||||
# s.responds_to?(:html_attrs) #=> true
|
||||
# # s now extends Haml::Helpers
|
||||
# s.responds_to?(:html_attrs) #=> true
|
||||
#
|
||||
# +locals+ is a hash of local variables to make available to the template.
|
||||
# `locals` is a hash of local variables to make available to the template.
|
||||
# For example:
|
||||
#
|
||||
# Haml::Engine.new("%p= foo").render(Object.new, :foo => "Hello, world!") #=> "<p>Hello, world!</p>"
|
||||
# Haml::Engine.new("%p= foo").render(Object.new, :foo => "Hello, world!") #=> "<p>Hello, world!</p>"
|
||||
#
|
||||
# If a block is passed to render,
|
||||
# that block is run when +yield+ is called
|
||||
# that block is run when `yield` is called
|
||||
# within the template.
|
||||
#
|
||||
# Due to some Ruby quirks,
|
||||
# if scope is a Binding or Proc object and a block is given,
|
||||
# if `scope` is a `Binding` or `Proc` object and a block is given,
|
||||
# the evaluation context may not be quite what the user expects.
|
||||
# In particular, it's equivalent to passing <tt>eval("self", scope)</tt> as scope.
|
||||
# In particular, it's equivalent to passing `eval("self", scope)` as `scope`.
|
||||
# This won't have an effect in most cases,
|
||||
# but if you're relying on local variables defined in the context of scope,
|
||||
# but if you're relying on local variables defined in the context of `scope`,
|
||||
# they won't work.
|
||||
#
|
||||
# @param scope [Binding, Proc, Object] The context in which the template is evaluated
|
||||
# @param locals [Hash<Symbol, Object>] Local variables that will be made available
|
||||
# to the template
|
||||
# @param block [#to_proc] A block that can be yielded to within the template
|
||||
# @return [String] The rendered template
|
||||
def render(scope = Object.new, locals = {}, &block)
|
||||
buffer = Haml::Buffer.new(scope.instance_variable_get('@haml_buffer'), options_for_buffer)
|
||||
|
||||
|
|
@ -173,24 +183,27 @@ END
|
|||
# Returns a proc that, when called,
|
||||
# renders the template and returns the result as a string.
|
||||
#
|
||||
# +scope+ works the same as it does for render.
|
||||
# `scope` works the same as it does for render.
|
||||
#
|
||||
# The first argument of the returned proc is a hash of local variable names to values.
|
||||
# However, due to an unfortunate Ruby quirk,
|
||||
# the local variables which can be assigned must be pre-declared.
|
||||
# This is done with the +local_names+ argument.
|
||||
# This is done with the `local_names` argument.
|
||||
# For example:
|
||||
#
|
||||
# # This works
|
||||
# Haml::Engine.new("%p= foo").render_proc(Object.new, :foo).call :foo => "Hello!"
|
||||
# #=> "<p>Hello!</p>"
|
||||
# # This works
|
||||
# Haml::Engine.new("%p= foo").render_proc(Object.new, :foo).call :foo => "Hello!"
|
||||
# #=> "<p>Hello!</p>"
|
||||
#
|
||||
# # This doesn't
|
||||
# Haml::Engine.new("%p= foo").render_proc.call :foo => "Hello!"
|
||||
# #=> NameError: undefined local variable or method `foo'
|
||||
# # This doesn't
|
||||
# Haml::Engine.new("%p= foo").render_proc.call :foo => "Hello!"
|
||||
# #=> NameError: undefined local variable or method `foo'
|
||||
#
|
||||
# The proc doesn't take a block;
|
||||
# any yields in the template will fail.
|
||||
# The proc doesn't take a block; any yields in the template will fail.
|
||||
#
|
||||
# @param scope [Binding, Proc, Object] The context in which the template is evaluated
|
||||
# @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
|
||||
# @return [Proc] The proc that will run the template
|
||||
def render_proc(scope = Object.new, *local_names)
|
||||
if scope.is_a?(Binding) || scope.is_a?(Proc)
|
||||
scope_object = eval("self", scope)
|
||||
|
|
@ -203,41 +216,44 @@ END
|
|||
precompiled_with_ambles(local_names) + "}\n", scope, @options[:filename], @options[:line])
|
||||
end
|
||||
|
||||
# Defines a method on +object+
|
||||
# with the given name
|
||||
# Defines a method on `object` with the given name
|
||||
# that renders the template and returns the result as a string.
|
||||
#
|
||||
# If +object+ is a class or module,
|
||||
# If `object` is a class or module,
|
||||
# the method will instead by defined as an instance method.
|
||||
# For example:
|
||||
#
|
||||
# t = Time.now
|
||||
# Haml::Engine.new("%p\n Today's date is\n .date= self.to_s").def_method(t, :render)
|
||||
# t.render #=> "<p>\n Today's date is\n <div class='date'>Fri Nov 23 18:28:29 -0800 2007</div>\n</p>\n"
|
||||
# t = Time.now
|
||||
# Haml::Engine.new("%p\n Today's date is\n .date= self.to_s").def_method(t, :render)
|
||||
# t.render #=> "<p>\n Today's date is\n <div class='date'>Fri Nov 23 18:28:29 -0800 2007</div>\n</p>\n"
|
||||
#
|
||||
# Haml::Engine.new(".upcased= upcase").def_method(String, :upcased_div)
|
||||
# "foobar".upcased_div #=> "<div class='upcased'>FOOBAR</div>\n"
|
||||
# Haml::Engine.new(".upcased= upcase").def_method(String, :upcased_div)
|
||||
# "foobar".upcased_div #=> "<div class='upcased'>FOOBAR</div>\n"
|
||||
#
|
||||
# The first argument of the defined method is a hash of local variable names to values.
|
||||
# However, due to an unfortunate Ruby quirk,
|
||||
# the local variables which can be assigned must be pre-declared.
|
||||
# This is done with the +local_names+ argument.
|
||||
# This is done with the `local_names` argument.
|
||||
# For example:
|
||||
#
|
||||
# # This works
|
||||
# obj = Object.new
|
||||
# Haml::Engine.new("%p= foo").def_method(obj, :render, :foo)
|
||||
# obj.render(:foo => "Hello!") #=> "<p>Hello!</p>"
|
||||
# # This works
|
||||
# obj = Object.new
|
||||
# Haml::Engine.new("%p= foo").def_method(obj, :render, :foo)
|
||||
# obj.render(:foo => "Hello!") #=> "<p>Hello!</p>"
|
||||
#
|
||||
# # This doesn't
|
||||
# obj = Object.new
|
||||
# Haml::Engine.new("%p= foo").def_method(obj, :render)
|
||||
# obj.render(:foo => "Hello!") #=> NameError: undefined local variable or method `foo'
|
||||
# # This doesn't
|
||||
# obj = Object.new
|
||||
# Haml::Engine.new("%p= foo").def_method(obj, :render)
|
||||
# obj.render(:foo => "Hello!") #=> NameError: undefined local variable or method `foo'
|
||||
#
|
||||
# Note that Haml modifies the evaluation context
|
||||
# (either the scope object or the "self" object of the scope binding).
|
||||
# It extends Haml::Helpers, and various instance variables are set
|
||||
# (all prefixed with "haml").
|
||||
# (either the scope object or the `self` object of the scope binding).
|
||||
# It extends {Haml::Helpers}, and various instance variables are set
|
||||
# (all prefixed with `haml_`).
|
||||
#
|
||||
# @param object [Object, Module] The object on which to define the method
|
||||
# @param name [String, Symbol] The name of the method to define
|
||||
# @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
|
||||
def def_method(object, name, *local_names)
|
||||
method = object.is_a?(Module) ? :module_eval : :instance_eval
|
||||
|
||||
|
|
@ -245,16 +261,13 @@ END
|
|||
@options[:filename], @options[:line])
|
||||
end
|
||||
|
||||
private
|
||||
protected
|
||||
|
||||
def set_locals(locals, scope, scope_object)
|
||||
scope_object.send(:instance_variable_set, '@_haml_locals', locals)
|
||||
set_locals = locals.keys.map { |k| "#{k} = @_haml_locals[#{k.inspect}]" }.join("\n")
|
||||
eval(set_locals, scope)
|
||||
end
|
||||
|
||||
# Returns a hash of options that Haml::Buffer cares about.
|
||||
# This should remain loadable from #inspect.
|
||||
# Returns a subset of \{#options}: those that {Haml::Buffer} cares about.
|
||||
# All of the values here are such that when `#inspect` is called on the hash,
|
||||
# it can be `Kernel#eval`ed to get the same result back.
|
||||
#
|
||||
# @return [Hash<Symbol, Object>] The options hash
|
||||
def options_for_buffer
|
||||
{
|
||||
:autoclose => @options[:autoclose],
|
||||
|
|
@ -264,5 +277,13 @@ END
|
|||
:format => @options[:format]
|
||||
}
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def set_locals(locals, scope, scope_object)
|
||||
scope_object.send(:instance_variable_set, '@_haml_locals', locals)
|
||||
set_locals = locals.keys.map { |k| "#{k} = @_haml_locals[#{k.inspect}]" }.join("\n")
|
||||
eval(set_locals, scope)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue