haml 1.8.2 → 2.0.0

data/FAQ

@@ -0,0 +1,138 @@
+= Frequently Asked Questions
+
+== Haml
+
+=== How do I put a punctuation mark after an element, like "<tt>I like <strong>cake</strong>!</tt>"?
+
+Expressing the structure of a document
+and expressing inline formatting are two very different problems.
+Haml is mostly designed for structure,
+so the best way to deal with formatting is to leave it to other languages
+that are designed for it.
+You could use Textile:
+
+  %p
+    :textile
+      I like *cake*!
+
+or Markdown:
+
+  %p
+    :markdown
+      I like **cake**!
+
+or plain old XHTML:
+
+  %p I like <strong>cake</strong>!
+
+If you're inserting something that's generated by a helper, like a link,
+then it's even easier:
+
+  %p== I like #{link_to 'chocolate', 'http://franschocolates.com'}!
+
+=== How do I stop Haml from indenting the contents of my +pre+ and +textarea+ tags?
+
+Because Haml automatically indents the HTML source code,
+the contents of whitespace-sensitive tags like +pre+ and +textarea+
+can get screwed up.
+The solution is to replace the newlines inside these tags
+with HTML newline entities (<tt>&#x000A;</tt>),
+which Haml does using the Haml::Helpers#preserve and Haml::Helpers#find_and_preserve helpers.
+
+Normally, Haml will do this for you automatically
+when you're using a tag that needs it
+(this can be customized using the <tt>:preserve</tt> option;
+see the Options section of the {Haml reference}(../classes/Haml.html)).
+For example,
+
+  %p
+    %textarea= "Foo\nBar"
+
+will be compiled to
+
+  <p>
+    <textarea>Foo&#x000A;Bar</textarea>
+  </p>
+
+However, if a helper is generating the tag,
+Haml can't detect that and so you'll have to call +find_and_preserve+ yourself.
+You can also use <tt>~</tt>, which is the same as <tt>=</tt>
+except that it automatically runs +find_and_preserve+ on its input.
+For example:
+
+  %p= find_and_preserve "<textarea>Foo\nBar</textarea>"
+
+is the same as
+
+  %p~ "<textarea>Foo\nBar</textarea>"
+
+and renders
+
+  <p><textarea>Foo&#x000A;Bar</textarea></p>
+
+=== How do I make my long lines of Ruby code look nicer in my Haml document?
+
+Put them in a helper or your model.
+
+Haml purposefully makes it annoying to put lots of Ruby code into your templates,
+because lots of code doesn't belong in the view.
+If you take that huge +link_to_remote+ call
+and move it to a +update_sidebar_link+ helper,
+it'll make your view both easier to read and more semantic.
+
+If you absolutely must put lots of code in your template,
+Haml offers a somewhat awkward multiline-continuation tool.
+Put a <tt>|</tt> (pipe character) at the end of each line you want to be merged into one
+(including the last line!).
+For example:
+
+  %p= @this.is(way.too.much). |
+      code("and I should").   |
+      really_move.it.into(    |
+        :a => @helper)        |
+
+=== I have Haml installed. Why is Rails (only looking for <tt>.html.erb</tt> files | rendering Haml files as plain text | rendering Haml files as blank pages)?
+
+There are several reasons these things might be happening.
+First of all, make sure vendor/plugins/haml really exists
+and has an init.rb file in there.
+Then try restarting Mongrel or WEBrick or whatever you might be using.
+
+Finally, if none of these work,
+chances are you've got some localization plugin like Globalize installed.
+Such plugins often don't play nicely with Haml.
+Luckily, there's usually an easy fix.
+For Globalize, just edit globalize/lib/globalize/rails/action_view.rb
+and change
+
+  @@re_extension = /\.(rjs|rhtml|rxml)$/
+
+to
+
+  @@re_extension = /\.(rjs|rhtml|rxml|erb|builder|haml)$/
+
+For other plugins, a little searching will probably turn up a way to fix them as well.
+
+== Sass
+
+=== Can I use a variable from my controller in my Sass file?
+
+No. Sass files aren't views.
+They're compiled once into static CSS files,
+then left along until they're changed and need to be compiled again.
+Not only don't you want to be running a full request cycle
+every time someone requests a stylesheet,
+but it's not a great idea to put much logic in there anyway
+due to how browsers handle them.
+
+If you really need some sort of dynamic CSS,
+the best thing to do is put only the snippet you need to dynamically set
+in the +head+ of your HTML document.
+
+== You still haven't answered my question!
+
+Sorry! Try looking at the Haml or Sass references,
+in the doucmentation for the haml and Sass modules, respectively.
+If you can't find an answer there,
+feel free to ask in #haml on irc.freenode.net
+or send an email to the {mailing list}[http://groups.google.com/group/haml?hl=en].

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2007 Hampton Catlin
+Copyright (c) 2006-2008 Hampton Catlin
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/{README → README.rdoc}

@@ -67,7 +67,7 @@ a tag without a name defaults to a div. So
 becomes
 
   <div id='foo'>Hello!</div>
-  
+
 Haml uses indentation
 to bring the individual elements to represent the HTML structure.
 A tag's children are indented two spaces more than the parent tag.
@@ -228,15 +228,78 @@ becomes:
       background-color: #79d645;
       width: 15em; }
 
+Taking the idea of constants a bit further are mixins.
+These let you group whole swathes of CSS attributes into a single
+directive and then include those anywhere you want:
+
+  =blue-border
+    :border
+      :color blue
+      :width 2px
+      :style dotted
+
+  .comment
+    +blue-border
+    :padding 2px
+    :margin 10px 0
+
+  .reply
+    +blue-border
+
+becomes:
+
+  .comment {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+    padding: 2px;
+    margin: 10px 0;
+  }
+
+  .reply {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+  }
+
 A comprehensive list of features is in
 the documentation for the Sass module.
 
+== Executables
+
+The Haml gem includes several executables that are useful
+for dealing with Haml and Sass from the command line.
+
+=== +haml+
+
+The +haml+ executable transforms a source Haml file into HTML.
+See <tt>haml --help</tt> for further information and options.
+
+=== +sass+
+
+The +sass+ executable transforms a source Sass file into CSS.
+See <tt>sass --help</tt> for further information and options.
+
+=== <tt>html2haml</tt>
+
+The <tt>html2haml</tt> executable attempts to transform HTML,
+optionally with ERB markup, into Haml code.
+Since HTML is so variable, this transformation is not always perfect;
+it's a good idea to have a human check the output of this tool.
+See <tt>html2haml --help</tt> for further information and options.
+
+=== <tt>css2sass</tt>
+
+The <tt>css2sass</tt> executable attempts to transform CSS into Sass code.
+This transformation attempts to use Sass nesting where possible.
+See <tt>css2sass --help</tt> for further information and options.
+
 == Authors
 
 Haml and Sass are designed by Hampton Catlin (hcatlin) and he is the author
 of the original implementation. However, Hampton doesn't even know his way
-around the code anymore and mostly just concentrates on the language issues. 
-Hampton lives in Toronto, Ontario (though he's an American by birth) and 
+around the code anymore and mostly just concentrates on the language issues.
+Hampton lives in Toronto, Ontario (though he's an American by birth) and
 is a partner at Unspace Interactive.
 
 Nathan Weizenbaum is the primary maintainer and architect of the "modern" Ruby

data/Rakefile

@@ -1,182 +1,146 @@
 require 'rubygems'
 require 'rake'
 
-volatile_requires = ['rcov/rcovtask']
-not_loaded = []
-volatile_requires.each do |file|
-  begin
-    require file
-  rescue LoadError
-    not_loaded.push file
-  end
-end
-
 # ----- Benchmarking -----
 
-temp_desc = <<END
+desc <<END
 Benchmark haml against ERb.
-  TIMES=n sets the number of runs. Defaults to 100.
+  TIMES=n sets the number of runs. Defaults to 1000.
 END
-
-desc temp_desc.chomp
 task :benchmark do
-  require 'test/benchmark'
-
-  puts "Running benchmarks #{ENV['TIMES']} times..." if ENV['TIMES']
-  times = ENV['TIMES'].to_i if ENV['TIMES']
-  Haml.benchmark(times || 100)
-  puts '-'*51
+  sh "ruby test/benchmark.rb #{ENV['TIMES']}"
 end
 
-# Benchmarking gets screwed up if some other tasks have been
-# initialized.
-unless ARGV[0] == 'benchmark'
+# ----- Default: Testing ------
 
-  # ----- Default: Testing ------
+task :default => :test
 
-  desc 'Default: run unit tests.'
-  task :default => :test
+require 'rake/testtask'
 
-  require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+Rake::Task[:test].send(:add_comment, <<END)
+To run with an alternate version of Rails, make test/rails a symlink to that version.
+END
 
-  desc 'Test the Haml plugin'
-  Rake::TestTask.new(:test) do |t|
-    t.libs << 'lib'
-    t.pattern = 'test/**/*_test.rb'
-    t.verbose = true
-  end
+# ----- Packaging -----
 
-  # ----- Packaging -----
-
-  require 'rake/gempackagetask'
-
-  spec = Gem::Specification.new do |spec|
-    spec.name = 'haml'
-    spec.summary = "An elegant, structured XHTML/XML templating engine.\nComes with Sass, a similar CSS templating engine."
-    spec.version = File.read('VERSION').strip
-    spec.author = 'Hampton Catlin'
-    spec.email = 'haml@googlegroups.com'
-    spec.description = <<-END
-      Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML
-      that's designed to express the structure of XHTML or XML documents
-      in a non-repetitive, elegant, easy way,
-      using indentation rather than closing tags
-      and allowing Ruby to be embedded with ease.
-      It was originally envisioned as a plugin for Ruby on Rails,
-      but it can function as a stand-alone templating engine.
-    END
-    #'
-    
-    readmes = FileList.new('*') do |list|
-      list.exclude(/[a-z]/)
-      list.exclude('TODO')
-    end.to_a
-    spec.executables = ['haml', 'html2haml', 'sass', 'css2sass']
-    spec.files = FileList['lib/**/*', 'bin/*', 'test/**/*', 'Rakefile', 'init.rb'].to_a + readmes
-    spec.autorequire = ['haml', 'sass']
-    spec.homepage = 'http://haml.hamptoncatlin.com/'
-    spec.has_rdoc = true
-    spec.extra_rdoc_files = readmes
-    spec.rdoc_options += [
-      '--title', 'Haml',
-      '--main', 'README',
-      '--exclude', 'lib/haml/buffer.rb',
-      '--line-numbers',
-      '--inline-source'
-    ]
-    spec.test_files = FileList['test/**/*_test.rb'].to_a
-  end
+require 'rake/gempackagetask'
+load    'haml.gemspec'
 
-  Rake::GemPackageTask.new(spec) do |pkg|
-    pkg.need_zip     = true
+Rake::GemPackageTask.new(HAML_GEMSPEC) do |pkg|
+  if Rake.application.top_level_tasks.include?('release')
     pkg.need_tar_gz  = true
     pkg.need_tar_bz2 = true
+    pkg.need_zip     = true
   end
+end
 
-  task :install => [:package] do
-    sh %{gem install --no-ri pkg/haml-#{File.read('VERSION').strip}}
-  end
+task :revision_file do
+  require 'lib/haml'
 
-  task :release => [:package] do
-    name, version = ENV['NAME'], ENV['VERSION']
-    raise "Must supply NAME and VERSION for release task." unless name && version
-    sh %{rubyforge login}
-    sh %{rubyforge add_release haml haml "#{name} (v#{version})" pkg/haml-#{version}.gem}
-    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.gz}
-    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.bz2}
-    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.zip}
+  if Haml.version[:rev] && !Rake.application.top_level_tasks.include?('release')
+    File.open('REVISION', 'w') { |f| f.puts Haml.version[:rev] }
+  elsif Rake.application.top_level_tasks.include?('release')
+    File.open('REVISION', 'w') { |f| f.puts "(release)" }
+  else
+    File.open('REVISION', 'w') { |f| f.puts "(unknown)" }
   end
+end
+Rake::Task[:package].prerequisites.insert(0, :revision_file)
+
+# We also need to get rid of this file after packaging.
+Rake::Task[:package].enhance { File.delete('REVISION') if File.exists?('REVISION') }
 
-  # ----- Documentation -----
+task :install => [:package] do
+  sudo = RUBY_PLATFORM =~ /win32/ ? '' : 'sudo'
+  sh %{#{sudo} gem install --no-ri pkg/haml-#{File.read('VERSION').strip}}
+end
+
+task :release => [:package] do
+  name, version = ENV['NAME'], ENV['VERSION']
+  raise "Must supply NAME and VERSION for release task." unless name && version
+  sh %{rubyforge login}
+  sh %{rubyforge add_release haml haml "#{name} (v#{version})" pkg/haml-#{version}.gem}
+  sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.gz}
+  sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.bz2}
+  sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.zip}
+end
+
+# ----- Documentation -----
 
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
   require 'rake/rdoctask'
+end
 
-  rdoc_task = Proc.new do |rdoc|
-    rdoc.title    = 'Haml/Sass'
-    rdoc.options << '--line-numbers' << '--inline-source'
-    rdoc.rdoc_files.include('README')
-    rdoc.rdoc_files.include('lib/**/*.rb')
-    rdoc.rdoc_files.exclude('lib/haml/buffer.rb')
-    rdoc.rdoc_files.exclude('lib/haml/util.rb')
-    rdoc.rdoc_files.exclude('lib/sass/tree/*')
-  end
+Rake::RDocTask.new do |rdoc|
+  rdoc.title    = 'Haml/Sass'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include(*FileList.new('*') do |list|
+                            list.exclude(/(^|[^.a-z])[a-z]+/)
+                            list.exclude('TODO')
+                          end.to_a)
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('TODO')
+  rdoc.rdoc_files.exclude('lib/haml/buffer.rb')
+  rdoc.rdoc_files.exclude('lib/sass/tree/*')
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.main = 'README.rdoc'
+end
 
-  Rake::RDocTask.new do |rdoc|
-    rdoc_task.call(rdoc)
-    rdoc.rdoc_dir = 'rdoc'
-  end
+# ----- Coverage -----
 
-  Rake::RDocTask.new(:rdoc_devel) do |rdoc|
-    rdoc_task.call(rdoc)
-    rdoc.rdoc_dir = 'rdoc_devel'
-    rdoc.options << '--all'
-    rdoc.rdoc_files.include('test/*.rb')
-    
-    # Get rid of exclusion rules
-    rdoc.rdoc_files = Rake::FileList.new(*rdoc.rdoc_files.to_a)
-    rdoc.rdoc_files.include('lib/haml/buffer.rb')
-    rdoc.rdoc_files.include('lib/sass/tree/*')
-  end
+begin
+  require 'rcov/rcovtask'
 
-  # ----- Coverage -----
-
-  unless not_loaded.include? 'rcov/rcovtask'
-    Rcov::RcovTask.new do |t|
-      t.libs << "test"
-      t.test_files = FileList['test/**/*_test.rb']
-      t.rcov_opts << '-x' << '"^\/"'
-      if ENV['NON_NATIVE']
-        t.rcov_opts << "--no-rcovrt"
-      end
-      t.verbose = true
+  Rcov::RcovTask.new do |t|
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << '-x' << '"^\/"'
+    if ENV['NON_NATIVE']
+      t.rcov_opts << "--no-rcovrt"
     end
+    t.verbose = true
   end
+rescue LoadError; end
 
-  # ----- Profiling -----
+# ----- Profiling -----
 
-  temp_desc = <<-END
-  Run a profile of haml.
-    ENGINE=str sets the engine to be profiled (Haml or Sass).
-    TIMES=n sets the number of runs. Defaults to 100.
-    FILE=n sets the file to profile. Defaults to 'standard'.
-  END
-  desc temp_desc.chomp
+begin
+  require 'ruby-prof'
+
+  desc <<END
+Run a profile of haml.
+  ENGINE=str sets the engine to be profiled. Defaults to Haml.
+  TIMES=n sets the number of runs. Defaults to 1000.
+  FILE=str sets the file to profile.
+    Defaults to 'standard' for Haml and 'complex' for Sass.
+  OUTPUT=str sets the ruby-prof output format.
+    Can be Flat, CallInfo, or Graph. Defaults to Flat. Defaults to Flat.
+END
   task :profile do
-    require 'test/profile'
-
-    engine = ENV['ENGINE'] && ENV['ENGINE'].downcase == 'sass' ? Sass : Haml
-    
-    puts '-'*51, "Profiling #{engine}", '-'*51
-    
-    args = []
-    args.push ENV['TIMES'].to_i if ENV['TIMES']
-    args.push ENV['FILE'] if ENV['FILE']
-    
-    profiler = engine::Profiler.new
-    res = profiler.profile(*args)
-    puts res
-    
-    puts '-'*51
-  end
+    engine = (ENV['ENGINE'] || 'haml').downcase
+    times  = (ENV['TIMES'] || '1000').to_i
+    file   = ENV['FILE']
+
+    if engine == 'sass'
+      require 'lib/sass'
+
+      file = File.read("#{File.dirname(__FILE__)}/test/sass/templates/#{file || 'complex'}.sass")
+      result = RubyProf.profile { times.times { Sass::Engine.new(file).render } }
+    else
+      require 'lib/haml'
+
+      file = File.read("#{File.dirname(__FILE__)}/test/haml/templates/#{file || 'standard'}.haml")
+      obj = Object.new
+      Haml::Engine.new(file).def_method(obj, :render)
+      result = RubyProf.profile { times.times { obj.render } }
+    end
 
-end
+    RubyProf.const_get("#{(ENV['OUTPUT'] || 'Flat').capitalize}Printer").new(result).print 
+  end
+rescue LoadError; end