Haml Spec
Norman Clarke
A few months back we had a discussion on the list about coming up with
a set of generic tests to use for testing all of the various versions
of Haml out there.
Today I pulled out most of the renderer tests from Lua Haml, and set
them up so that they can be run with Ruby and Lua.
The project can be found here:
http://github.com/norman/haml-spec
Github's site is experiencing a DoS attack right now, so if you can't
get to the URL, you can clone the repo from:
git://github.com/norman/haml-spec.git
The main test file is in JSON format, since I saw this as the lowest
common denominator for the various languages we work with. Adding
support for your implementation in another language should be very
easy, the Lua and Ruby runners are each less than 30 lines.
The tests are all very simple, as the idea is provide a common
baseline, rather than a comprehensive suite for testing *everything.*
You can use them to make sure your implementation's output matches
that of the Ruby version.
I'd love to have your feedback and patches! At the moment it is
incomplete because it only tests what I've already implemented in Lua
Haml. I'll be adding more tests as I continue to work on my
implementation.
Regards,
Norman
PS I would have put this up sooner, but ended up going on a huge yak-
shaving expedition to implement a test framework in order to
adequately test Lua Haml. :-)
Enrique Gimenez
My Python Haml / PySass projects sleep deep for now, but this is encouraging!
Will definitely take a look...
chepi
Steve Wagner
implementation too.
A nice idea would it be to give each test an id so parsers which dose
not implement some features could ignore specific tests in their test
suite.
Steve
Norman Clarke schrieb:
Norman Clarke
Nathan Weizenbaum
- Future-proof it. Rather than having the tests be Haml/HTML pairs, make them be objects with properties: {"haml": haml_code, "html": html_code}. Then if we want to add more attributes later (see below) it's easy.
- Name each of the tests. I like that the groups are named, but I think the individual tests should be, too. This helps in debugging, and it helps to keep track of exactly what each test is testing (which in turn helps us make sure that all the functionality is tested). I know this is a pain, but after having generated a lot of Haml tests, many without explanation as to their purpose, I find myself pretty befuddled when I go back and look and afraid that if I remove any of them I'll stop testing some functionality that's not tested anywhere else.
- Make the locals a property of the individual test, rather than an assumed global thing. This will make keeping track of the locals easier.
- Test trailing whitespace. Always having exactly one trailing newline is a usability issue.
- Test whitespace-only documents. Make sure various documents that produce only whitespace produce one and only one trailing newline.
- Minor nitpick: instead of "portable-style attributes", "HTML-style attributes". This is what I've been calling them pretty consistently. As a side note, we need to decide at some point if this will be the only style of attribute mandated for all Haml implementations.
Norman Clarke
On Fri, Sep 18, 2009 at 6:17 AM, Nathan Weizenbaum <nex...@gmail.com> wrote:
> I've integrated this into Ruby Haml as of
> http://github.com/nex3/haml/commit/7bf25c4e30c88719fa37e9f01f3fcd03429a9d19.
Great - I'm glad you find it useful!
> However, I'd like to make a few suggestions:
>
> Future-proof it. Rather than having the tests be Haml/HTML pairs, make them
> be objects with properties: {"haml": haml_code, "html": html_code}. Then if
> we want to add more attributes later (see below) it's easy.
> Name each of the tests. I like that the groups are named, but I think the
> individual tests should be, too. This helps in debugging, and it helps to
> keep track of exactly what each test is testing (which in turn helps us make
> sure that all the functionality is tested). I know this is a pain, but after
> having generated a lot of Haml tests, many without explanation as to their
> purpose, I find myself pretty befuddled when I go back and look and afraid
> that if I remove any of them I'll stop testing some functionality that's not
> tested anywhere else.
> Make the locals a property of the individual test, rather than an assumed
> global thing. This will make keeping track of the locals easier.
> Test trailing whitespace. Always having exactly one trailing newline is a
> usability issue.
> Test whitespace-only documents. Make sure various documents that produce
> only whitespace produce one and only one trailing newline.
> Minor nitpick: instead of "portable-style attributes", "HTML-style
> attributes". This is what I've been calling them pretty consistently. As a
> side note, we need to decide at some point if this will be the only style of
> attribute mandated for all Haml implementations.
Thanks for the feedback. I think these are all great ideas, and I'll
start implementing them today.
I had actually considered making a more detailed JSON format for the
tests, but honestly I wanted to see if anyone else was going to use it
before putting in the time. Now that I know it's going to be used by
more than just me I'm a lot happier to put in the time necessary to
make it awesome rather than just adequate. :-)
Having the tests be objects rather than simple arrays will also let us
incoroporate tests that are expected to produce errors/failures; we
can add a field to the object that indicates the expected test
outcome. Right now the tests only validate the "happy path," which is
usually significantly less than half the battle. The current set of
Haml error tests is really solid so I can probably incorporate most of
them as-is once I get the new format in place.
Regards,
Norman
Norman Clarke
> attributes". This is what I've been calling them pretty consistently. As a
> side note, we need to decide at some point if this will be the only style of
> attribute mandated for all Haml implementations.
Well, Ruby-style attribute hashes are not simply passed through
untouched to Ruby, Haml does a fair bit of processing on them. So
while the syntax is inspired by Ruby, from the precompiler's
standpoint it is part of the Haml language. As a point of comparison,
this is different from script given after "=" and "-" operators which
is sent through to be executed by the renderer untouched, so from the
precompiler's standpoint is an external language hosted by Haml.
So, because Ruby-style attributes are *a part of Haml* and *not just
Ruby,* I think it's reasonable to expect non-Ruby versions of Haml to
support the syntax of Ruby-style attributes. I have already added
support for them to Lua Haml and it was almost exactly as much work as
adding support for HTML-style attributes; if anything it was easier.
-Norman
Norman Clarke
> That's about it. As an example of what I'm thinking a test should look like,
> see
> http://github.com/nex3/haml/commit/7bf25c4e30c88719fa37e9f01f3fcd03429a9d19.
> Thanks for all your work on this, Norman!
OK, I've committed tests in the new JSON format and updated the Ruby
and Lua test runners. In addition to locals, I added configs in the
JSON in order to test different outputs for xhtml, html4, html5, etc.
I still haven't added the tests for badly formed Haml. Still very much
a work in progress, but getting better!
-Norman
Hampton
This stuff is awesome!
-hampton.
Nathan Weizenbaum
Well, Ruby-style attribute hashes are not simply passed through
untouched to Ruby, Haml does a fair bit of processing on them. So
while the syntax is inspired by Ruby, from the precompiler's
standpoint it is part of the Haml language. As a point of comparison,
this is different from script given after "=" and "-" operators which
is sent through to be executed by the renderer untouched, so from the
precompiler's standpoint is an external language hosted by Haml.
So, because Ruby-style attributes are *a part of Haml* and *not just
Ruby,* I think it's reasonable to expect non-Ruby versions of Haml to
support the syntax of Ruby-style attributes. I have already added
support for them to Lua Haml and it was almost exactly as much work as
adding support for HTML-style attributes; if anything it was easier.
I don't think this is a great argument in favor of their inclusion. Yes, the Haml precompiler does a fair amount of work on them; however, this is largely for efficiency, and to allow them to be used with :suppress_eval. I don't think it's a good reason to make other implementations implement this style of attributes. What might be a good reason is that people overwhelmingly use Ruby-style attributes over HTML-style, so it might be a nice compatibility feature there.
I've updated my runner for the haml-spec tests. Thanks for making the changes.
Norman Clarke
I'm just wondering, why *not* implement them? Is it just because it
"looks like Ruby?" Haml already looks freaking bizarre the first time
you see it anyway, so I don't know if that matters.
If it's *not* required then the tacit recommendation would seem to be,
if you want your Haml to be "as good" as the Ruby one, then implement
HTML-style, and a style that's local to your language:
Ruby: #id{ :hello => "world" }
PHP: #id( "hello" => "world" )
Lua: #id{ hello = "world" }
Python: #id{ "hello": "world" }
My point was, that Ruby Haml doesn't just get the :key => "value"
syntax magically, there's work involved, and it's going to be the same
work for Python Haml to support "key": "value" as :key => "value". So
the question is, is the syntax part of Ruby or part of Haml? Because
if it's part of Haml, then the recommendation should be to implement
it. If we consider it part of Ruby, and say "implement it if you want
to," then people will likely end up doing something like their local
language rather than the "Ruby" style.
I see the syntax as part of Haml and think there's long-term benefit
to the language being uniform across platforms. But I can imagine some
people may also see a beneift to having a syntax more similar to the
host language. So I guess you have to weight the beneifts of
idiomacity vs. the beneifts of uniformity.
-Norman
Nathan Weizenbaum
Steve Wagner
work?
In example this could lists something like "%%meta" with position 1 and
length 1.
With this all haml parsers behave similar in error cases.
Steve
Norman Clarke schrieb:
Norman Clarke
Yes, I'm going to add that soon - it's a work in progress! I've become a bit busy with some other things at the moment, but I should have the error tests in place in another week or so.
-Norman
On Sep 30, 2009 7:28 AM, "Steve Wagner" <li...@lanwin.de> wrote:
You did a nice work, but shouldn't there be also an spec what no should
work?
In example this could lists something like "%%meta" with position 1 and
length 1.
With this all haml parsers behave similar in error cases.
Steve
Norman Clarke schrieb:
> Hello, > > A few months back we had a discussion on the list about coming up with > a set of gene...
--~--~---------~--~----~------------~-------~--~----~ You received this message because you are subs...
Norman Clarke
a little shrill from they way I typed it quickly on my phone.
I meant to say, I definitely agree with your suggestion and plan on
getting that in there as soon as I can. :-)
Hampton
Shrill is acceptable.
Steve Wagner
"basic Haml tags and CSS -> a tag with an id followed by a class"
The expected output of "%p#id1.class1" is
<p class='class1' id='id1'></p>
but shouldn't it
<p id='id1' class='class1'></p>
Means output of id and class in the same order as they are in Haml?
Steve
Norman Clarke schrieb:
Norman Clarke
Nathan mentioning he might make the next version of Haml leave them in
the order given in the template, but I'm not sure if that's officially
on the TODO list.
Attribute order has no meaning in HTML so I'm not sure how important
it really is. Or rather, my opinion is that it is completely
unimportant, and I like the fact that Haml outputs them in a very
predictable way. But that may just be me, and I guess maybe it's a
matter of how many people complain about the current behavior.
-Norm
Hampton Catlin
- Hampton
Nathan Weizenbaum
Steve Wagner
Test: tags with HTML-style attributes => a tag with a CSS class and
'class' as a variable attribute
Haml: %p.class2(class='class1')
Expected: <p class='class1 class2'></p>
What is the sorting story behind this?
@Norman: Eventually would it be nice to add some notes to the spec how
about this sorting.
Steve
Nathan Weizenbaum schrieb:
Norman Clarke
>
> Makes sens Nathan, but another sorting problem in case of a unit test:
>
> Test: tags with HTML-style attributes => a tag with a CSS class and
> 'class' as a variable attribute
>
> Haml: %p.class2(class='class1')
> Expected: <p class='class1 class2'></p>
>
> What is the sorting story behind this?
It's the same as above; the order of CSS classes in an HTML "class"
attribute is irrelevant. When I saw this I looked it up because I
expected order to be relevant here to *cascading* style sheets, but
surprisingly, it's not. I assume the alphabetical sort here is also
intended to provide a deterministic output.
> @Norman: Eventually would it be nice to add some notes to the spec how
> about this sorting.
Agreed. I realized once I started working on this that JSON,
surprisingly, does not allow comments. I suppose we could add a
"comment" field to the test objects in order to store the comment as
part of the code. Another possibility it to switch to YAML, (JSON is
actually a proper subset of YAML), but how "weird" is YAML for .NET,
Python or Ruby developers? Would it be worth making the change?
I do see the lack of an explanation for some of the tests as a
usability problem.
-Norman
Steve Wagner
> On Fri, Oct 2, 2009 at 10:22 AM, Steve Wagner <li...@lanwin.de> wrote:
>> Makes sens Nathan, but another sorting problem in case of a unit test:
>>
>> Test: tags with HTML-style attributes => a tag with a CSS class and
>> 'class' as a variable attribute
>>
>> Haml: %p.class2(class='class1')
>> Expected: <p class='class1 class2'></p>
>>
>> What is the sorting story behind this?
>
> It's the same as above; the order of CSS classes in an HTML "class"
> attribute is irrelevant. When I saw this I looked it up because I
> expected order to be relevant here to *cascading* style sheets, but
> surprisingly, it's not. I assume the alphabetical sort here is also
> intended to provide a deterministic output.
@Nathan: Should we assume here also alphabetical order? I would suggest
to don use there parsing order since otherwise the attributes could only
be sorted if all dynamics are inferred.
>> @Norman: Eventually would it be nice to add some notes to the spec how
>> about this sorting.
>
> Agreed. I realized once I started working on this that JSON,
> surprisingly, does not allow comments. I suppose we could add a
> "comment" field to the test objects in order to store the comment as
> part of the code. Another possibility it to switch to YAML, (JSON is
> actually a proper subset of YAML), but how "weird" is YAML for .NET,
> Python or Ruby developers? Would it be worth making the change?
-1 As far as i know is there currently no good YAML Parser for .Net and
i think another optional argument would be ok. An alternative would be a
specs.txt where this constrains are described as text.
Steve
Norman Clarke
>> Agreed. I realized once I started working on this that JSON,
>> surprisingly, does not allow comments. I suppose we could add a
>> "comment" field to the test objects in order to store the comment as
>> part of the code. Another possibility it to switch to YAML, (JSON is
>> actually a proper subset of YAML), but how "weird" is YAML for .NET,
>> Python or Ruby developers? Would it be worth making the change?
>
> -1 As far as i know is there currently no good YAML Parser for .Net and
> i think another optional argument would be ok. An alternative would be a
> specs.txt where this constrains are described as text.
Ok, I think I'd prefer a comment field in the JSON itself, to make it
easier to read things in context. I'll be traveling a bit over the
next 2 weeks but will try to find some time to work on this when I
can.
Nathan Weizenbaum
Steve Wagner
I would suggest to do the numbering of the tests in the following way.
Give each group a unique number. In example 11 for group interpolation.
Then number each test and prefix it with the group number so that all
tests look like this.
11001: interpolation inside code
If i now want to search or ignore a test, i have to only search for the
number.
In general what is missing are tests with more lines to test the exact
indentation and exact line break.
Whats also missing are tests with multiline |.
Also are tests which answer some special situation like what is the
output of the following haml.
:plain
test
%p
test
Also what is missing is when the } in the interpolation tests is escaped
like this: #{test\}test}.
And then i have a problem the this test:
interpolation: interpolation inside code
%p= "#{var}"
How dose haml parses this? It seems very ruby specific sine i have to
know that i am inside of a string and pre execute the code inside of the
#{var} and than insert it into the string to execute this code also.
I would suggest to remove this test from the suite.
-Steve
Norman Clarke schrieb:
Nathan Weizenbaum
Hi Norman, i have some more suggestion and one problem.
I would suggest to do the numbering of the tests in the following way.
Give each group a unique number. In example 11 for group interpolation.
Then number each test and prefix it with the group number so that all
tests look like this.
11001: interpolation inside code
I'm not sure I like numeric ids... it seems like they'd clutter stuff up. What's wrong with just going on the name of the test?
If i now want to search or ignore a test, i have to only search for the
number.
In general what is missing are tests with more lines to test the exact
indentation and exact line break.
Whats also missing are tests with multiline |.
Also are tests which answer some special situation like what is the
output of the following haml.
:plain
test
%p
test
Also what is missing is when the } in the interpolation tests is escaped
like this: #{test\}test}.
And then i have a problem the this test:
interpolation: interpolation inside code
%p= "#{var}"
This is definitely Ruby-specific functionality. The = and - operators probably shouldn't be tested at all, because they're heavily language-specific.
Norman Clarke
> On Mon, Oct 5, 2009 at 10:28 AM, Steve Wagner <li...@lanwin.de> wrote:
>> Give each group a unique number. In example 11 for group interpolation.
>>
>> Then number each test and prefix it with the group number so that all
>> tests look like this.
>>
>> 11001: interpolation inside code
>
> I'm not sure I like numeric ids... it seems like they'd clutter stuff up.
> What's wrong with just going on the name of the test?
Agreed, I really don't want to do this because it will be a nightmare
to maintain. I also don't really understand what would be gained by
having numbers.
>> Whats also missing are tests with multiline |.
>>
>> Also are tests which answer some special situation like what is the
>> output of the following haml.
>>
>> :plain
>> test
>> %p
>> test
>>
>> Also what is missing is when the } in the interpolation tests is escaped
>> like this: #{test\}test}.
So far I've mostly added tests that match the functionality I have
working in Lua Haml, so there's definitely some stuff missing. Like I
said before, it's a work in progress. I would be happy to accept any
additional tests you might want to add.
>>
>> And then i have a problem the this test:
>>
>> interpolation: interpolation inside code
>>
>> %p= "#{var}"
>
> This is definitely Ruby-specific functionality. The = and - operators
> probably shouldn't be tested at all, because they're heavily
> language-specific.
I included a few simple tests for - and = as a compromise, because on
one hand they are language-specific, but on the other hand it's such a
fundamental part of Haml that it just didn't seem right to leave them
out of the tests completely.
A lot of this comes down to where the dividing line between Haml and
Ruby is. Haml draws upon Ruby for some of its features and syntax, and
it's not always clear where Ruby ends and Haml begins.
I'm OK with leaving this one out if you all think it looks too
Rubyish, but it works in Lua Haml. :-) I had to add support for the
#{} interpolation syntax from scratch because Lua doesn't do string
interpolation at all. I thought it worthwhile because I wanted to err
on the side of completeness.
So is string interpolation going to become another problematic thing
like attributes? Is "#{}" part of Ruby or part of Haml, or both?
-Norman
Nathan Weizenbaum
Norman Clarke
Nathan Weizenbaum
Norman Clarke
a regexp to make them work with their own syntax. To my knowledge only
PHP and Perl require a sigil before variable names. "#{}" is however
VERY Rubyish.
Maybe we can add a designation to some tests to indicate that they can
be used by implementations which seek 100% compatiblity with the Ruby
implementation of Haml.
Lua Haml, for example, has as one of its goals, to run Haml that
embeds almost any language. I already have basic support for Ruby and
intend to add LOLCODE as an example
of how you can use it. For me testing ongoing compatibility with the
original implementation is important.
Nathan Weizenbaum
Norman Clarke
all? My goal is to make something that everybody wants to use, even
though I'm sure none of us will end up with everything we want. :-)
Chris Eppstein
Steve Wagner
part of haml and the other implementations should also support it. If an
implementations dose not want to support it, it simply could skip the
whole interpolation group.
So i am perfectly fine with the interpolations only not with the one
which is in a code blog (means behind a =).
It would be good to have tests which test of markup like %p= works or
the other = and - operators. So i would suggest to put a placeholder in
the tests which then implementation can then simply replace. Example
Haml: %p= $$$$
Haml(replaced): %p= "test"
Haml <p>test</p>
Norman Clarke schrieb:
Steve Wagner
> I'm not sure I like numeric ids... it seems like they'd clutter stuff up.
> What's wrong with just going on the name of the test?
Only because of the much simple exclusion and it also works when test
names change.
Steve Wagner
%p#bc#ab
%p#ab#bc
%p(id='bc' id='ab')
%p(id="ab" id="bc")
%p#bc(id="ab")
produces
<p id='ab'></p>
<p id='bc'></p>
<p id='ab'></p>
<p id='bc'></p>
<p id='bc_ab'></p>
The question is, why the last one behave different? I currently see no
reason. Shouldn't it be more consistent and clear if
p%#bc
is exactly the same as
p%(id='bc')
?
- Steve
Norman Clarke
object id's to a base id, for example:
- posts.each do |post|
#post(id = post.id)
Would output:
<div id='post_1'></div>
<div id='post_2'></div>
etc...
I was surprised by this functionality, as I don't think it's in the
Haml reference docs. I think it seems pretty useful, though. All the
same I don't have any strong opinion on how Haml *should* handle this,
I just implemented what was in Ruby Haml.
Sorry I haven't had much time to work on Haml Spec lately, I'm
wrapping up a couple of big projects, then I should get back to
implementing some more tests.
--Norman
Steve Wagner
Norman Clarke schrieb:
> I believe the last one is different so that you can easily append
> object id's to a base id, for example:
>
> - posts.each do |post|
> #post(id = post.id)
>
> Would output:
>
> <div id='post_1'></div>
> <div id='post_2'></div>
> etc...
>
> I was surprised by this functionality, as I don't think it's in the
> Haml reference docs. I think it seems pretty useful, though. All the
> same I don't have any strong opinion on how Haml *should* handle this,
> I just implemented what was in Ruby Haml.
Ok right makes sens, but then i would suggest to do this for all ids
also for the 4 first ones.
@Nathen whats your meaning about that?
> Sorry I haven't had much time to work on Haml Spec lately, I'm
> wrapping up a couple of big projects, then I should get back to
> implementing some more tests.
No problem, thats what currently there is still really good.
-Steve
Hampton
so its overwriteable and generated on each render (maybe). and #id#other in
the actual tag is just messy and I think should throw an error or just be some
behaviour defined by the implementation.
Nathan Weizenbaum
As for interpolation, which I still haven't addressed fully: since interpolation, like variables, is a strongly language-specific feature, it won't be specified as part of the core, language-agnostic portion of Haml (which seems to be what these tests are aiming at). For the language-specific portion, the exact syntax will be left up to the implementation, with the general expectation that it will correspond with the implementation's interpolation syntax, if any.
Hampton
Nathan Weizenbaum
Steve Wagner
concatenated?
Would it the best behavior to concat them in in all conditions?
%p#ab#bc
%p#ab(id="bc")
<p id="ab_bc"></p>
For understanding haml this makes the most sens.
-Steve
Nathan Weizenbaum schrieb:
Nathan Weizenbaum
Hampton
#you#me ======> id ="me"
#you(id = 'me') =====> id = you_me
.div(id = "you" id="me") ===== id = "me"
Why? Because, I see the second version as a *special* feature, and
all the other ones are actually invalid... and simply acts as a key-value-store.
The second one is the only one that makes sense to me in any actual
use-case. Can you guys come up with anything for the others?
-hampton.
Norman Clarke
> Personally, I still think that...
>
> #you#me ======> id ="me"
> #you(id = 'me') =====> id = you_me
> .div(id = "you" id="me") ===== id = "me"
>
> Why? Because, I see the second version as a *special* feature, and
> all the other ones are actually invalid... and simply acts as a
> key-value-store.
>
> The second one is the only one that makes sense to me in any actual
> use-case. Can you guys come up with anything for the others?
The only reason I see for Haml not barfing when someone does #you#me
is because it's already flexible about invalid CSS. Right now Haml
lets you create technically invalid CSS like #000 or #y^y with no
complaints. I think this is the right approach for a template
language: "if you want to create invalid markup/CSS, go right ahead."
I think it's in the same spirit for Haml to silently "repair"
something silly like a tag with 2 ids; for Haml to be loose about
other things and suddenly strict about that would seem out of
character.
So if we're going to do a repair, I agree the most sensible thing is
to treat the id attribute as a hash with multiple assignments to the
same key, leaving the last assignment in place.
--Norman