escaping.md.eco

## Escaping and unescaping

When you print an expression in a template with `<%%= ... %>`, its
value is HTML-escaped. For example,

    eco.render "<%%= @description %>",
      description: "<strong>HTML 5</strong> mobile app"

would render:

    &lt;strong&gt;HTML 5&lt;/strong&gt; mobile app

You can use the `<%%- ... %>` tag to print the value of an expression
without escaping it. So this code:

    eco.render "<%%- @description %>",
      description: "<strong>HTML 5</strong> mobile app"

would produce:

    <strong>HTML 5</strong> mobile app

It is sometimes useful to generate markup in helper methods. The
special `safe` method on the context object tells Eco that the string
can be printed in `<%%= ... %>` tags without being escaped. You can use
this in conjunction with the context object's `escape` method to
selectively sanitize parts of the string. For example,

    eco.render "<%%= linkTo @project %>",
      project: { id: 4, name: "Crate & Barrel" }
      linkTo: (project) ->
        url  = "/projects/#{project.id}"
        name = @escape project.name
        @safe "<a href='#{url}'>#{name}</a>"

would render:

    <a href='/projects/4'>Crate &amp; Barrel</a>

## Custom escape helpers

By default, Eco's `escape` method takes a string and returns an
HTML-escaped string. You can override this behavior to escape for
formats other than HTML, or to bypass escaping entirely. For example,

    eco.render "From: <%%= @address %>",
      address: "Sam Stephenson <sstephenson@gmail.com>"
      escape:  (string) -> string      

would return:

    From: Sam Stephenson <sstephenson@gmail.com>