Our First Deprecation: ~

[Nathan Weizenbaum]

That's right, folks, Haml is deprecating one of its commands: the
(apparently little-known) "~". Once useful for allowing people to create
whitespace-sensitive blocks of text inline, and styliciously handling
<textarea> and <pre> tags, "~" is now more or less rendered redundant
with the introduction of filters
(http://groups.google.com/group/haml/browse_thread/thread/5ed706013a47a483)
and a clever use of helper functions.

"~" had two different functions. First, it could be used as an
alternative to "=" that would replace all newlines in
whitespace-sensitive tags such as <pre> and <textarea> with the HTML
characters for newlines, thus preserving both whitespace /and/ style.
This function can now be done literally with a function:
find_and_preserve. For example, what was once:

~ text_area :user, :profile

becomes

= find_and_preserve(text_area :user, :profile)

There's also another, related helper function, just called "preserve",
that removes all newlines period, without regard for what tag is where.

The second function was to precede a nested block of text, which would
ensure that all whitespace in that text was preserved. The idea of doing
stuff with nested blocks of text might sound a lot like filters to
you... and it does to us, too, which is why we're replacing that
function with an actual filter. The "preserve" filter serves the same
purpose as the "~" on its own. For instance, what was

%pre
~
1
2
3
4

is now

%pre
:preserve
1
2
3
4

The "~" command will still be around, although undocumented, as of the
next release of Haml (1.5). If you use it, Haml will spit out a warning,
but it will work. However, in the release after 1.5, it will be gone for
good, so update your views as soon as possible.

You may be wondering why we're deprecating this at all. "Sure, Nathan,
it's like a filter," you say, "but is it really worth it to get rid of
it altogether?" Well, if you were to ask this, I would reply that yes,
yes it is worth it. There are several reasons to get rid of this:

1. It cluttered up the code. Checking for preserved text necessitated
more than its fair share of logic precisely where we wanted the
least logic. When we do eventually remove it, the code will become
much neater.
2. It was redundant. Everything it did could, and probably should,
have been done with filters or helpers.
3. It cluttered up Haml. Haml aims to be simple and easy to learn,
and having lots of obscure commands doesn't help that at all. This
is particularly true when the commands intuitively seem like they
should be something other than commands (see point 2).

We don't like deprecating stuff, and this is probably the only thing
we'll be deprecating in a good while, so don't worry about your views
breaking beyond this (if you use this... how many of you folks even knew
this command existed?).

- Nathan

[Jeff]

I needed ~ to make my textareas work. Why would one ever want the
unfiltered behavior for textarea and pre tags? Why doesn't haml
filter those tags automatically? IMHO haml breaks those tags and I
shouldn't have to use a filter to get the behavior I would expect.

I think I should be able to say:
= textarea :user, :profile

and get the same result as is currently returned by
~ textarea :user, :profile

The new methods may improve the haml source code, but from my
perspective as a user, they don't improve ease of use or readiblity of
my code.

Thanks,
-- Jeff

On Feb 6, 3:30 am, Nathan Weizenbaum <nex...@gmail.com> wrote:
> That's right, folks, Haml is deprecating one of its commands: the
> (apparently little-known) "~". Once useful for allowing people to create
> whitespace-sensitive blocks of text inline, and styliciously handling
> <textarea> and <pre> tags, "~" is now more or less rendered redundant
> with the introduction of filters

> (http://groups.google.com/group/haml/browse_thread/thread/5ed706013a47...)

[s.ross]

My personal opinion is that we shouldn't want our templating engine
to be too smart. Special handling in certain instances such as you
mention here is soooo tempting because it happens so often, but it
violates the principle of least surprise. I expect

= <an expression>

to behave exactly the same way no matter what follows it. What would
be surprising is if somewhere along the line that behavior changed on
a case by case basis.

Just my $.02.

[Nathan Weizenbaum]

I agree with Steve. We want the Haml commands, especially those used
most commonly (%, -, and =) to behave as intuitively as possible, not
have special behaviors for various special cases that probably don't
come up at all for most people. Special cases have special handlers; in
this case, the find_and_preserve helper function.

As to readability, I think having an obscure command, such as "~", or
worse yet no command at all, is much less readable than a clearly-named
helper method.

- Nathan

[Hampton]

~ is the special handler for special cases.

And I still use it.

-hampton

[Nathan Weizenbaum]

Well, after the deprecation, :preserve and find_and_preserve are the
special handlers.

- Nathan

[Jeff]

Nathan,

IMHO, textarea is not a "case that doesn't come up at all for most
people". It comes up for everyone who creates a form.

Ross argues for maintaining the integrity of haml the template
langauge. When I suggested special behavior for textarea and pre, I
was arguing for maintaining the integrity of the markup that haml
produces.

I love haml and I can live with the deprecation, but I don't buy the
arguments. ~ is no more obscure than %, - or find_and_preserve.

-- Jeff

[weepy]

it's a shame that we have to get funky with pre and textarea. isn't
the main problem with pre and textarea to do with the way in which
Haml chooses to show display it's html ? i.e. indented ? would the
problem be fixed if we chose Haml to display unindented? or am i
missing the point ?

on a side note, can someone explain the logic behind the name
find_and_preserve ? --- what are we finding ?

[Hampton]

find_and_preserve is what ~ originally did.

It finds whitespace sensitive elements <pre>, <textarea>, and a few
others... when it finds one... it takes the contents of the area and
then converts \n into the HTML entity for endline. That way...
basically multi-line things *look* like single lines that be browser
treats as having endlines. It used be be called "find_and_flatten".

%textarea
I'm
here

becomes

<textarea>I'm&ENTITYICANTREMEMBERhere</textarea>

That way when later Haml templates get the area, they can indent
freely, since there aren't any \ns.... The browser treats them the
same.

Its basically a hack that allows us to have whitespace sensitive areas
on the page and still have it look pretty when we indent it properly.

-hampton.

[Nathan Weizenbaum]

Preloading a textarea with whitespace-sensitive content is not terribly
common. But the point is that no matter the degree of its commonness,
it's a special case, and handling special cases is something that
shouldn't be done by default. It's inefficient, leads to feature bloat,
could make for nasty surprises, and causes the documentation to get very
tangled very quickly.

"~" is more obscure than "%" or "-" because it's not commonly used. The
largest number of questions I heard about Haml when it was first
released were, "I get =, but what does ~ do?" For a long time we've been
getting people saying "My whitespace doesn't work!" Even though this
command is fully documented in the reference, people didn't know it
existed. The difference between "%" and "-" is that both of those are
fundamental to the functionality of Haml... "~" was not.

By changing it to find_and_preserve, we've done two things. First, we've
linked it into the existing Helper functionality, which is (hopefully) a
place people look for solutions to these problems. Second, we've made
the name very descriptive, unlike "~", which doesn't convey any meaning
at all.

- Nathan

[Nathan Weizenbaum]

Having well-formatted output is one of the primary reasons Haml was
created in the first place. That's not something we're going to give up on.

- Nathan

[Jeff]

I don't know about preloading whitespace, but typing newlines into a
textarea is terribly common. Every blog in the universe does it.
This message board does it.

JR

[Hampton]

Every site I build uses it at least 2-4 times.

-hampton.

[weepy]

how about preserve rather than find_and_preserve. i'm not sure that
the find bit is particularily useful ?
preserve is nice and short and straight to the point . or does it
clash with :preserve ?

Can we list all situations where we commonly use preserve? Is it
restricted to only textarea and pre ? Or are their other (common)
reasons?

weepy

On Feb 12, 2:08 am, Hampton <hcat...@gmail.com> wrote:
> Every site I build uses it at least 2-4 times.
>
> -hampton.
>

[Nathan Weizenbaum]

There already is a preserve helper... it does the same thing as
find_and_preserve, but instead of just doing it within <pre>, <code>,
and <textarea> tags, it does it to the entirety of the text passed to it.

- Nathan

[Nathan Weizenbaum]

Huh, my mistake. But the point still remains that it's a special case,
even if it /is/ used in every textarea ever created. It's certainly not
used every time someone uses "=", and it's not the expected behavior.
Yes, Haml mucking up the whitespace is a problem, but that's why there's
a solution for when that problem comes up.

- Nathan

[Jeff]

Nathan,

My point is that it IS the expected behavior for textarea, pre and
code tags. That's why newbies write to you saying "my whitespace
doesn't work". That's why newbies don't use the "~" in the first
place, because they think "=" should work.

That being said, I'll agree that it is reasonable to demand that those
tags be treated as special cases. However "find_and_preserve" is not
very descriptive or elegant. And while "~" is not particularly
descriptive, it is IMHO elegant.

If I understood your previous posts in this thread, there are valid
software engineering issues which make the deprecation a good idea.
But as a user, the arguments that "it's better for you" and "it
shouldn't matter to you" ring false.

Regards,
Jeff

[weepy]

jeff, i think thats a very fair and balanced argument on the point.

[Nathan Weizenbaum]

Hampton and I have discussed this, and we've decided that we're going to
bring back part of the functionality of the "~" character. It will now
just be a shortcut for wrapping the result of a function call in
find_and_preserve. The nested text functionality will still be
deprecated, and find_and_preserve will not be part of the default
behavior of the "=" command.

- Nathan