#
# Haml code!
\n" # # == Characters with meaning to Haml # # Various characters, when placed at a certain point in a line, # instruct Haml to render different types of things. # # === XHTML Tags # # These characters render XHTML tags. # # ==== % # # # The percent character is placed at the beginning of a line. # It's followed immediately by the name of an element, # then optionally by modifiers (see below), a space, # and text to be rendered inside the element. # It creates an element in the form ofThe magical fruit
## # And: # # %img # %img> # %img # # is compiled to: # ## Foo! #
Foo # Bar
# # And finally: # # %img # %pre>< # foo # bar # %img # # is compiled to: # #foo # bar
hello
# # ==== ~ # # ~ works just like =, except that it runs Haml::Helpers#find_and_preserve on its input. # For example, # # ~ "Foo\nBar\nBaz" # # is the same as: # # = find_and_preserve("Foo\n
Bar\nBaz") # # and is compiled to: # # Foo #
Bar Baz# # See also Whitespace Preservation, below. # # === XHTML Helpers # # ==== No Special Character # # If no special character appears at the beginning of a line, # the line is rendered as plain text. # For example: # # %gee # %whiz # Wow this is cool! # # is compiled to: # #
Sign my guestbook
# # # # You can also specify the version and type of XHTML after the !!!. # XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported. # The default version is 1.0 and the default type is Transitional. # For example: # # !!! 1.1 # # is compiled to: # # # # and # # !!! Strict # # is compiled to: # # # # If you're not using the UTF-8 character set for your document, # you can specify which encoding should appear # in the XML prolog in a similar way. # For example: # # !!! XML iso-8859-1 # # is compiled to: # # # # ==== / # # The forward slash character, when placed at the beginning of a line, # wraps all text after it in an HTML comment. # For example: # # %peanutbutterjelly # / This is the peanutbutterjelly element # I like sandwiches! # # is compiled to: # ##
Hello, World
# # # Filters can have Ruby code interpolated, like with ==. # For example, # # - flavor = "raspberry" # #content # :textile # I *really* prefer _#{h flavor}_ jam. # # is compiled to # #I really prefer raspberry jam.
## hello there you! #
# # ==== == # # Two equals characters interpolates Ruby code into plain text, # similarly to Ruby string interpolation. # For example, # # %p== This is #{h quality} cake! # # is the same as # # %p= "This is #{h quality} cake!" # # and might compile to # #This is scrumptious cake!
# # Backslashes can be used to escape "#{" strings, # but they don't act as escapes anywhere else in the string. # For example: # # %p # == \\ Look at \\#{h word} lack of backslash: \#{foo} # # might compile to # ## \\ Look at \yon lack of backslash: #{foo} #
# # ==== &= # # An ampersand followed by one or two equals characters # evaluates Ruby code just like the equals without the ampersand, # but sanitizes any HTML-sensitive characters in the result of the code. # For example: # # &= "I like cheese & crackers" # # compiles to # # I like cheese & crackers # # If the :escape_html option is set, # &= behaves identically to =. # # ==== != # # An exclamation mark followed by one or two equals characters # evaluates Ruby code just like the equals would, # but never sanitizes the HTML. # # By default, the single equals doesn't sanitize HTML either. # However, if the :escape_html option is set, = will sanitize the HTML, but != still won't. # For example, if :escape_html is set: # # = "I feel !" # != "I feel !" # # compiles to # # I feel <strong>! # I feel ! # # ===== Blocks # # Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml. # Rather, they're automatically closed, based on indentation. # A block begins whenever the indentation is increased # after a silent script command. # It ends when the indentation decreases # (as long as it's not an +else+ clause or something similar). # For example: # # - (42...47).each do |i| # %p= i # %p See, I can count! # # is compiled to: # ## 42 #
## 43 #
## 44 #
## 45 #
## 46 #
# # Another example: # # %p # - case 2 # - when 1 # = "1!" # - when 2 # = "2?" # - when 3 # = "3." # # is compiled to: # ## 2? #
# # ==== -# # # The hyphen followed immediately by the pound sign # signifies a silent comment. # Any text following this isn't rendered in the resulting document # at all. # # For example: # # %p foo # -# This is a comment # %p bar # # is compiled to: # #foo
#bar
# # You can also nest text beneath a silent comment. # None of this text will be rendered. # For example: # # %p foo # -# # This won't be displayed # Nor will this # %p bar # # is compiled to: # #foo
#bar
# # == Other Useful Things # # === Whitespace Preservation # # Sometimes you don't want Haml to indent all your text. # For example, tags like +pre+ and +textarea+ are whitespace-sensitive; # indenting the text makes them render wrong. # # Haml deals with this by "preserving" newlines before they're put into the document -- # converting them to the XHTML whitespace escape code, . # Then Haml won't try to re-format the indentation. # # Literal +textarea+ and +pre+ tags automatically preserve their content. # Dynamically can't be caught automatically, # and so should be passed through Haml::Helpers#find_and_preserve or the ~ command, # which has the same effect (see above). # # Blocks of literal text can be preserved using the :preserve filter (see above). # # === Helpers # # Haml offers a bunch of helpers that are useful # for doing stuff like preserving whitespace, # creating nicely indented output for user-defined helpers, # and other useful things. # The helpers are all documented in the Haml::Helpers and Haml::Helpers::ActionViewExtensions modules. # # === Haml Options # # Options can be set by setting the hash Haml::Template.options # from environment.rb in Rails, # or by passing an options hash to Haml::Engine. # Available options are: # # [:output] Determines the output format. The default is :xhtml. # Other options are :html4 and :html5, which are # identical to :xhtml except there are no self-closing tags, # XML prolog is ignored and correct DOCTYPEs are generated. # # [:escape_html] Sets whether or not to escape HTML-sensitive characters in script. # If this is true, = behaves like &=; # otherwise, it behaves like !=. # Note that this escapes tag attributes. # Defaults to false. # # [:suppress_eval] Whether or not attribute hashes and Ruby scripts # designated by = or ~ should be # evaluated. If this is true, said scripts are # rendered as empty strings. Defaults to false. # # [:attr_wrapper] The character that should wrap element attributes. # This defaults to ' (an apostrophe). Characters # of this type within the attributes will be escaped # (e.g. by replacing them with ') if # the character is an apostrophe or a quotation mark. # # [:filename] The name of the Haml file being parsed. # This is only used as information when exceptions are raised. # This is automatically assigned when working through ActionView, # so it's really only useful for the user to assign # when dealing with Haml programatically. # # [:line] The line offset of the Haml template being parsed. # This is useful for inline templates, # similar to the last argument to Kernel#eval. # # [:filters] A hash of filters that can be applied to Haml code. # The keys are the string names of the filters; # the values are references to the classes of the filters. # User-defined filters should always have lowercase keys, # and should have the interface described in Haml::Filters::Base. # # [:autoclose] A list of tag names that should be automatically self-closed # if they have no content. # Defaults to ['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']. # # [:preserve] A list of tag names that should automatically have their newlines preserved # using the Haml::Helpers#preserve helper. # This means that any content given on the same line as the tag will be preserved. # For example: # # %textarea= "Foo\nBar" # # compiles to: # # # # Defaults to ['textarea', 'pre']. # # See also Whitespace Preservation, above. # module Haml # Returns a hash representing the version of Haml. # The :major, :minor, and :teeny keys have their respective numbers. # The :string key contains a human-readable string representation of the version. # If Haml is checked out from Git, # the :rev key will have the revision hash. def self.version return @@version if defined?(@@version) numbers = File.read(scope('VERSION')).strip.split('.').map { |n| n.to_i } @@version = { :major => numbers[0], :minor => numbers[1], :teeny => numbers[2] } @@version[:string] = [:major, :minor, :teeny].map { |comp| @@version[comp] }.compact.join('.') if File.exists?(scope('REVISION')) rev = File.read(scope('REVISION')).strip rev = nil if rev !~ /a-f0-9+/ end if rev.nil? && File.exists?(scope('.git/HEAD')) rev = File.read(scope('.git/HEAD')).strip if rev =~ /^ref: (.*)$/ rev = File.read(scope(".git/#{$1}")).strip end end if rev @@version[:rev] = rev @@version[:string] << "." << rev[0...7] end @@version end # Returns the path of file relative to the Haml root. def self.scope(file) # :nodoc: File.join(File.dirname(__FILE__), '..', file) end # A string representing the version of Haml. # A more fine-grained representation is generated by Haml.version. VERSION = version[:string] unless defined?(Haml::VERSION) # This method is called by init.rb, # which is run by Rails on startup. # We use it rather than putting stuff straight into init.rb # so we can change the initialization behavior # without modifying the file itself. def self.init_rails(binding) %w[haml/template sass sass/plugin].each(&method(:require)) end end require 'haml/engine'