` tags that are within ``.
To express more succintly this pattern of nested selectors (the actual name is [descendant combinators](http://www.w3.org/TR/css3-selectors/#descendant-combinators)), we can write a litc as the contents of another litc.
```javascript
['div.links', {width: 100}, ['a', {'font-size': 14}]];
```
This litc will generate the CSS above.
Notice that you can place multiple litcs within the contents of another litc. For example:
```javascript
['div.links', {width: 100}, [
['a', {'font-size': 14}],
['p', {color: 'red'}]
]];
```
which will generate:
```css
div.links {
width: 100px;
}
div.links a {
font-size: 14px;
}
div.links p {
color: red;
}
```
Nested liths also allow to reference the parent selector by using the ampersand (`&`). Like nested selectors, this feature was taken from [SASS](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector). Let's see an example:
```css
div.links {
width: 100px;
}
div.links a {
font-size: 14px;
}
div.links a:hover {
color: red;
}
```
We can generate the same CSS with the following litc:
```javascript
['div.links', {width: 100}, [
['a', {'font-size': 14}, ['&:hover', {color: 'red'}]]
]];
```
Notice how `&` is replaced by `div.links a`, which is the combined selector of the parent elements of the innermost litc.
The ampersand can be a prefix, a suffix or even be in the middle of a selector. In every case, it will be replaced by the selector of its ancestors.
Multiple CSS selectors will be properly nested. For example, if you want to write:
```css
h2 span, h3 span {
color: green;
}
```
You can do write it with the following litc:
```javascript
['h2, h3', ['span', {color: 'green'}]]
```
This also works if you use commas in the nested selector:
```css
div h2, div h3 {
color: green;
}
```
```javascript
['div', ['h2, h3', {color: 'green'}]]
```
You can also use the ampersand and nest multiple selectors as deeply as you want.
```css
div h2:hover, div h3:hover {
color: green;
}
```
```javascript
['div', ['h2, h3', ['&:hover', {color: 'green'}]]]
```
### Litc usage
litcs are generated using two core functions:
1. `lith.css.g`: this function generates CSS from a litc.
2. `lith.css.v`: a helper function that validates a litc.
The input to both functions is either a litc or a litcbag. In either case, the input can only be a single array.
You don't need to invoke `lith.css.v`, since `lith.css.g` validates its own input.
If the input to lith is invalid, `false` is returned. Otherwise, you get a string with CSS.
If the input is invalid, lith will print an error through teishi.
If the input to `lith.g` contains anywhere a lith of the following form: `['style', ['div.canvas', {color: 'blue'}]]` (where the second element is an array and presumably a litc), `lith.g` will automatically invoke `lith.css.g` on the litc. The example above, when passed to `lith.g`, will generate `'`. If the contents are an array that is not a valid litc, the entire input will be considered invalid.
As with `lith.g`, if you pass `true` as a second argument to `lith.css.g`, `prod mode` will be enabled and no validations will be performed. This will also happen if you set `lith.prod` to `true`.
If you want to check whether an input is valid litc without having the error be printed to the console, you can invoke `lith.css.v` passing `true` as its second argument, in which case an object with the error will be returned.
### litc helper functions
In this section we define two helper functions, `lith.css.media` and `lith.css.style`.
Writing media queries with litcs is not possible - at least not directly. For this purpose, you can use `lith.css.media`, which will transform your media query into a valid litc.
For example, if you want to write the following media query in the context of a litc:
```css
@media (max-width: 600px) {
.sidebar {
display: none;
}
}
```
You can create it with:
```javascript
var litc = [
lith.css.media ('(max-width: 600px)', ['.sidebar', {display: 'none'}]),
// rest of your litc goes here
]
```
`lith.css.media` takes two arguments: a `selector`, which is the media query selector. Notice that you should omit the `@media` part, since the function automatically adds it for you. The second argument is a litc (simple or nested), which will be inserted inside the media query. If you don't pass a valid `selector`, the function will return `false`. The litc is not validated here since it will be validated by `lith.css.g` later.
If you passed valid arguments to `lith.css.media`, the output will always be a litc, which you can use standalone or nest within another one.
The second helper, `lith.css.style`, is helpful if you want to generate a CSS string to directly place inside the `style` attribute of a lith. This function takes an object with litc attributes and returns either `false` (if the attributes are invalid) or a string with CSS which can be used as the `style` attribute of an element. Let's see some examples:
```javascript
// This invocation:
{style: lith.css.style ({color: 'red', margin: 'solid 1px white'})}
// will generate this `attributes` object:
{style: 'color:red;margin:solid 1px white;'}
// This invocation:
lith.css.style ({'height, width': 1});
// will generate this `attributes` object:
{style: 'height:100%;width:100%;'}
```
If you pass a `true` second argument to this function, it will generate the CSS string in `prod mode`.
## Source code
The complete source code is contained in `lith.js`. It is about 270 lines long.
Below is the annotated source.
```javascript
/*
lith - v6.0.7
Written by Federico Pereiro (fpereiro@gmail.com) and released into the public domain.
Please refer to readme.md to read the annotated source.
*/
```
### Setup
We wrap the entire file in a self-executing anonymous function. This practice is commonly named [the javascript module pattern](http://yuiblog.com/blog/2007/06/12/module-pattern/). The purpose of it is to wrap our code in a closure and hence avoid making the local variables we define here to be available outside of this module. A cursory test indicates that local variables exceed the scope of a script in the browser, but not in node.js. This means that this pattern is useful only on the browser.
```javascript
(function () {
```
Since this file must run both in the browser and in node.js, we define a variable `isNode` to check where we are. The `exports` object only exists in node.js.
```javascript
var isNode = typeof exports === 'object';
```
We require [dale](http://github.com/fpereiro/dale) and [teishi](http://github.com/fpereiro/teishi). Note that, in the browser, `dale` and `teishi` will be loaded as global variables.
```javascript
var dale = isNode ? require ('dale') : window.dale;
var teishi = isNode ? require ('teishi') : window.teishi;
```
This is the most succinct form I found to export an object containing all the public members (functions and constants) of a javascript module. Note that, in the browser, we use the global variable `lith` to export the library.
```javascript
if (isNode) var lith = exports;
else var lith = window.lith = {};
```
We create an alias to `teishi.type`, the function for finding out the type of an element. We do the same for `teishi.clog`, a function for printing logs that also returns `false`. We also do the same for `teishi.inc`, a function for checking whether a given element is contained in an array.
```javascript
var type = teishi.type, clog = teishi.clog, inc = teishi.inc;
```
### Constants
We define an object `lith.k` to hold some constants.
```javascript
lith.k = {
```
`lith.k.lithbagElements` will hold the possible types of a lithbag element.
```javascript
lithbagElements: ['string', 'integer', 'float', 'array', 'undefined'],
```
`lith.k.tags` contains [every valid HTML5 tag](http://www.w3.org/TR/html-markup/elements.html). Interestingly enough, there are 108 tags.
Although `'!DOCTYPE HTML'` is a declaration and not a tag, we add it to the list of tags anyway, so that we can also generate the doctype with lith. We will also add `'LITERAL'`, which is a pseudo-tag useful for inserting chunks of raw HTML into a lith.
```javascript
tags: ['!DOCTYPE HTML', 'LITERAL', 'a', 'abbr', 'address', 'area', 'article', 'aside', 'audio', 'b', 'base', 'bdi', 'bdo', 'blockquote', 'body', 'br', 'button', 'canvas', 'caption', 'cite', 'code', 'col', 'colgroup', 'command', 'datalist', 'dd', 'del', 'details', 'dfn', 'div', 'dl', 'dt', 'em', 'embed', 'fieldset', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header', 'hgroup', 'hr', 'html', 'i', 'iframe', 'img', 'input', 'ins', 'kbd', 'keygen', 'label', 'legend', 'li', 'link', 'map', 'mark', 'menu', 'meta', 'meter', 'nav', 'noscript', 'object', 'ol', 'optgroup', 'option', 'output', 'p', 'param', 'pre', 'progress', 'q', 'rp', 'rt', 'ruby', 's', 'samp', 'script', 'section', 'select', 'small', 'source', 'span', 'strong', 'style', 'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'textarea', 'tfoot', 'th', 'thead', 'time', 'title', 'tr', 'track', 'u', 'ul', 'var', 'video', 'wbr'],
```
`lith.k.voidTags` contains the list of [tags that do not need to be closed](http://www.w3.org/TR/html-markup/syntax.html#syntax-elements), also known as *self-closing tags*. The term "void" comes from the W3C specification.
Notice we also add `'!DOCTYPE HTML'` to this list.
```javascript
voidTags: ['!DOCTYPE HTML', 'area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr']
}
```
Below there's an `if` block that ensures that all the void tags are contained in `lith.k.tags`. If the check is not passed, the rest of lith will not be defined.
Every time I modify the tag constants, I run this code to ensure that there are no tag inconsistencies. However, in production this code is commented out, to save you a few milliseconds. To check that the `voidTags` and the `tags` are consistent, please uncomment the code and run it for yourself. Note we pass `true` as the fourth argument to the invocation of `teishi.stop`, to prevent teishi from validating the rule - this will save some execution time.
```javascript
/*
if (teishi.stop ([['HTML void tags', 'HTML tags'], lith.k.voidTags, lith.k.tags, 'eachOf', teishi.test.equal], undefined, true)) {
return false;
}
*/
```
### Helper functions
`lith.entityify` is a function that takes a string and escapes some characters with their corresponding [HTML entities](http://www.w3.org/TR/2008/WD-html5-20080122/#character).
This function was originally taken from [Douglas Crockford's `entityify`](http://javascript.crockford.com/remedial.html) and modified to replace quotes and backticks, using the approach in [John-David Dalton's lodash](https://github.com/lodash/lodash/blob/93b1e1f5ac72fad0507fc551704b88082a49fa48/lodash.js#L224).
Notice we validate the input but only if the second argument is falsy. When `prod mode` is on, we avoid the validation to improve performance. Note that, if we perform the validation, we pass `true` as the fourth argument to `teishi.stop` to prevent teishi from validating the rule itself (we know the rule to be correct already). The `undefined` as third argument is there simply to allow us to skip that argument and pass the fourth one instead.
```javascript
lith.entityify = function (string, prod) {
if (! prod && teishi.stop ('lith.entityify', ['Entityified string', string, 'string'], undefined, true)) return false;
return string
.replace (/&/g, '&')
.replace (//g, '>')
.replace (/"/g, '"')
.replace (/'/g, ''')
.replace (/`/g, '`');
}
```
### Lith validation
We will now proceed to handle the validation of liths.
`lith.v` is the main validation function for liths. It takes an `input`, presumably a lith. This function will return `Lith` if it found a lith, `Lithbag` if it found a lithbag, and `false` if the input is neither.
The function also takes a second argument, `returnError`, that can be used to make `lith.v` return an error if `input` is invalid.
```javascript
lith.v = function (input, returnError) {
```
We first note the type of the input and store it at `inputType`.
```javascript
var inputType = type (input);
```
If `input` is an array and its first element is a string which also happens to be a valid HTML tag, we will consider `input` to be a lith! In previous versions of lith, you could write lithbags that started with a valid HTML tag, but it was seldom useful. By explicitly prohibiting it, we can very quickly determine whether `input` is a lith or a lithbag. This also will help to implement a fast `prod mode` when we define `lith.g` later.
```javascript
if (inputType === 'array' && inc (lith.k.tags, input [0])) {
```
We define `attributes` and `contents`. `attributes` must either be an object or invalid. `contents` will be the second or third element of the `lith`, depending on whether we found `attributes` or not.
```javascript
var attributes = type (input [1]) === 'object' ? input [1] : undefined;
var contents = input [attributes ? 2 : 1];
```
We start validating the lith in earnest and store the result in a variable `result`.
```javascript
var result = teishi.v ([
```
A lith has a length of 1 to 3 elements.
```javascript
['lith length', input.length, {min: 1, max: 3}, teishi.test.range],
```
If, however, the lith has no attributes, its length can be at most 2, since it will only have a tag and contents.
```javascript
[attributes === undefined, ['length of lith without attributes', input.length, {max: 2}, teishi.test.range]],
```
We already know that `attributes` is either undefined or an object, because we ensured that when we defined the variable a few lines above. We now proceed to validate its keys.
Every attribute key must start with a ASCII letter, underscore or colon, and must follow with zero or more of the following:
- A letter.
- An underscore.
- A colon.
- A digit.
- A period.
- A dash.
- Any Unicode character with a code point of 129 (`0080` in hexadecimal) or above - these include all extended ASCII characters (the top half of the set) and every non-ASCII character.
This is the *abstruse rule* I talked about earlier in the readme. This arcana was kindly provided [by this article](http://razzed.com/2009/01/30/valid-characters-in-attribute-names-in-htmlxml/). The regex below was taken from the article and modified to add the permitted Unicode characters.
```javascript
[
['lith attribute keys', 'start with an ASCII letter, underscore or colon, and be followed by letters, digits, underscores, colons, periods, dashes, extended ASCII characters, or any non-ASCII characters.'],
dale.keys (attributes),
/^[a-zA-Z_:][a-zA-Z_:0-9.\-\u0080-\uffff]*$/,
'each', teishi.test.match
],
```
Attribute values can be strings, numbers (integers and floats). We also accept `undefined`, `null` and `false` as falsy values that invalidate the property, so we will also accept `undefined`, `null` or `boolean`.
```javascript
['lith attribute values', attributes, ['string', 'integer', 'float', 'undefined', 'null', 'boolean'], 'eachOf'],
```
Contents can be any lithbag element: string, integer, float, array and undefined. However, if we're dealing with a `LITERAL` pseudo-tag, the contents must be a string.
```javascript
input [0] === 'LITERAL' ? ['lith LITERAL contents', contents, 'string'] : ['lith contents', contents, lith.k.lithbagElements, 'oneOf']
```
If `returnError` is set, we pass `true` as an `apres` argument to `teishi.v`, so that if there's an error, the error itself is returned instead of being printed. Otherwise, we pass an `apres` function that will print an informative error. Note we print both the error and the original input, which provides more context. Note also we pass `true` as the last argument to `teishi.v`, to avoid validating the rules that we pass to the function and hence improve performance. We have done this with all invocations to `teishi.v` and `teishi.stop`, and we will keep on doing it without further comment on it.
```javascript
], returnError ? true : function (error) {
clog ('lith.v - Invalid lith', {error: error, 'original input': input});
}, true);
```
If `result` is true, we return the string `'Lith'`. Otherwise, we return either `false` (if `returnError` is not set) or an error message. Note we return the same error object that we printed in the `apres` function.
After this, we also close the conditional that deals with the case of a lith.
```javascript
return result === true ? 'Lith' : (returnError ? {error: result, 'original input': input} : false);
}
```
If we're here, we can only be dealing with a lithbag (or an invalid input). We proceed to check whether `input` is a valid lithbag and store the result in a variable `result`.
```javascript
var result = teishi.v ([
```
We check that `input` has a type matching those of a valid lithbag element.
```javascript
['lithbag', inputType, lith.k.lithbagElements, 'oneOf', teishi.test.equal],
[inputType === 'array', ['lithbag elements', input, lith.k.lithbagElements, 'eachOf']]
```
As with the case of a lith, we pass a `true` apres parameter in case `returnError` is enabled. Otherwise, if case a validation error was found, we will print an informative error. Note we print both the error and the original input, which provides more context.
```javascript
], returnError ? true : function (error) {
clog ('lith.v - Invalid lithbag', {error: error, 'original input': input});
}, true);
```
If the validation was successful, we return the string `'Lithbag'`. Otherwise, if `returnError` is enabled, we return an error object, or `false` otherwise. After this, there's nothing else to do, so we close the function.
```javascript
}) ? 'Lithbag' : false;
return result === true ? 'Lithbag' : (returnError ? {error: result, 'original input': input} : false);
}
```
### Lith generation
We now define `lith.g`, the main function of the library. This library takes an `input` (a lith or lithbag) and returns a string with the corresponding HTML. As a second optional argument, it takes an optional boolean flag, `prod`, to enable `prod mode`.
```javascript
lith.g = function (input, prod) {
```
`prod mode` is an option that makes `lith.g` to not validate its input. If either `lith.prod` is set to a truthy value (or a truthy value is passed as the second argument to `lith.g`, we will consider that `prod mode` is enabled.
```javascript
if (prod || lith.prod) {
```
We check that if either of `prod` or `lith.prod` are truthy, they are indeed `true`. We want to avoid a common usage error where multiple parameters are passed to `lith.g` in the hope of generating all of them - `lith.g` only accepts one `input`, and multiple parameters must be wrapped in an array. With this check, we prevent this error, which is compounded by the fact that validation is unwittingly turned off if a truthy second argument is passed.
```javascript
if ((prod || lith.prod) !== true) return clog ('lith.g', 'prod or lith.prod must be true or undefined.');
```
If we're here, bring on the `prod mode`. This means that *we will assume that `input` is either a valid lith or a valid lithbag*. We quickly determine whether `input` is a lith or not. For this we check that `input` is indeed an array with a valid HTML tag as its first element.
```javascript
if (type (input) === 'array' && inc (lith.k.tags, input [0])) {
```
If we're here, `input` is a lith. We return an invocation to `lith.generateLith`, passing it both `input` and `true`. The reason we pass a second argument is that because `lith.generateLith` can invoke `lith.g`, we need to preserve the `prod mode` flag in recursive calls.
```javascript
return lith.generateLith (input, true);
}
```
If we're here, `input` is a lithbag. We invoke `lith.generateLithbag`. The second argument of the invocation is `false`; we'll explain why below.
```javascript
return lith.generateLithbag (input, false, true);
}
```
If we're here, we need to validate our input. We do so and store the result in a variable `inputType`.
```javascript
var inputType = lith.v (input);
```
Now, because of how we defined `lith.v`, `inputType` can only be `false`, `'Lith'` or `'Lithbag'`. If it is `false`, we will want to return `false`, otherwise we will want to invoke the appropriate function (`lith.generateLith` or `lith.generateLithbag`).
```javascript
return inputType ? lith ['generate' + inputType] (input) : false;
```
At this point we're done, so we close the function.
```javascript
}
```
`lith.generateLithbag` takes three arguments: `lithbag`, `dontEntityify` and `prod` (the `prod mode` flag). We will explain the second argument below.
```javascript
lith.generateLithbag = function (lithbag, dontEntityify, prod) {
```
We initialize a local variable `output` to an empty string, on which we will concatenate the output of the function.
```javascript
var output = '';
```
We will now iterate through the elements of `lithbag`.
Notice that if `lithbag` is `undefined`, the entire function below will not be executed and `output` will remain being equal to an empty string.
We use `dale.stop` and pass `false` as the second argument because we want to detect invalid lithbag elements and stop if one is found. If an invalid element is found, the inner function passed as third argument to `dale.stop` will return `false`. Other return values will be ignored, because the valid outputs will be concatenated onto the `output` string.
```javascript
if (dale.stop (lithbag, false, function (v) {
```
If `v` is `undefined`, we return `undefined`.
```javascript
if (v === undefined) return;
```
We now deal with simple values that are not `undefined` (string, integer and float).
Depending on whether `dontEntityify` is truthy or not, we entityify the element. The reason for the existence of this option is that the contents of `