Basic Less types for plugin authors (Quick Reference Card)

[seven-phases-max]

Posting this WIP here (per discussion at less/less.js@809dc50)

---

Trivial type	Less tree type	Less value example	Corresponding plugin code (less.tree prefix omitted)
number	Dimension	12.34	new Dimension(12.34)
		42px	new Dimension(42, 'px')
identifier	Keyword	left	new Keyword('left')
		background-color	new Keyword('background-color')
string	Quoted	"Hello, World!"	new Quoted('', '"Hello, World!"') see [1]
		'Hello, World!'	new Quoted('', "'Hello, World!'") see [1]
boolean	Keyword	true	new Keyword('true')
		false	new Keyword('false') see [2]
color	Color	#369	new Color('369')
		rgba(11, 22, 33, 0.5)	new Color([11, 22, 33], .5)
		red	Color.fromKeyword('red')
comma list	Value	foo, 42	new Value([new Keyword('foo'), new Dimension(42)])
space list	Expression	foo 42	new Expression([new Keyword('foo'), new Dimension(42)])
arbitrary text	Anonymous	~'foo$bar .baz'	new Anonymous('foo$bar .baz')
		e('#$@&%*!')	new Anonymous('#$@&%*!')

---

Notes:

1. Quoted constructor is definitely broken, it does not do what you expect by looking at its code (the first parameter is in fact never used most likely because of later eval code involving only content/value value).
2. Or any other value. Basically, in when guards (so far they are the only statement where boolean values do matter) anything but Keyword('true') counts as false.

[matthew-dean]

Quoted constructor is definitely broken, it does not do what you expect by looking at its code (the first parameter is in fact never used most likely because of later eval code involving only content/value value).

Is this something to address/fix in less.js then?

[seven-phases-max]

Is this something to address/fix in less.js then?

Yes. Two alternative methods (though the details to be determined in process as always):

• A. Remove the first parameter of the Quoted-ctor since the actual quoting symbol is determined from the value anyway. I.e. the API becomes:

new Quoted("'foo'") -> 'foo'
new Quoted('"foo"') -> "foo"
new Quoted("foo")   ->  foo

• B. Fix Quoted.eval to use the quoted member value. So the API becomes:

new Quoted("'", 'foo') -> 'foo'
new Quoted('"', 'foo') -> "foo"
new Quoted('',  'foo') ->  foo

Both variants are OK I guess (for me the first one looks a bit more clean from the code-base point of view).

[matthew-dean]

Yeah, the first one looks better. We should really examine all the node parameters before we release a public API. OR we have a public API that is abstracted from the private one, which is totally doable. Technically less.quoted could take in parameters different from new tree.Quoted (or any node for that matter). One motivation I can see for this is that for parsing, the parameters can be verbose and specific to avoid a lot of if/then/else or ternary expressions or casting. But on a public API, you'd want to simplify it: make arguments flexible, allow someone to create nodes with very little input (such as not needing to pass in index / fileInfo), maybe even pass in objects with named properties vs. comma-separated arguments. And, as discussed in other threads, some tree nodes never should need to be directly created anyway, which would simplify a public API.

[seven-phases-max]

Yes, sure we can abstract the creation of these objects but it's still more code about working with the objects rather than simply creating them from a JS-values (so at worst it still will have to look like this, though the topmost dreadful thing remains to be the numerator/denominator goody of the Dimension but that's another big story (luckily this is not something to often deal with directly) :).

[matthew-dean]

@seven-phases-max The nice part is that with the "late parsing" strategy I did in 3.0, there's now some groundwork to parse whenever you want while creating nodes, so node creation can be fairly simple if you want it to be.

[seven-phases-max]

I understand I just remarked that the API is not just about creating objects. So if some tree.Foobar properties/methods are not quite consistent (like it is with Quote) and you have to deal with such object (created elsewhere), for you it does not really matter how friendly the less.foobar() could be. But never mind I understand what you mean.

[matthew-dean]

Right, I get you.