Architecture¶
The Stilus compiler reads a Stylus source file an produces a ccs file.
Parser¶
The Lexer reads the source file and splits it into Tokens. The Parser uses these tokens to create an abstract syntax tree of nodes.
Nodes¶
Each node denotes a structure occurring in the Stylus language. For example
the media node contains the @media
atrule in css; or the boolean node
contains a True
and False
value; the each node contains the content
of a for loop.
All nodes are extensions of the parent Node class.
In the nodes directory you’ll find the complete list of all nodes.
Builtin functions¶
A set of builtin functions are available. For example, the clone()
and
convert()
builtins are available. See the functions directory for a
complete list. These builtin methods are plain Python methods.
Some method are raw methods; others are not.
The index.styl file¶
The index.styl file is automatically imported and becomes part of the ast. It contains an extra list of builtin functions, while the regular builtin functions are written in Python, these are written in Stylus.
The abstract syntax tree¶
The abstract syntax tree has a root. The first element is the index.styl file. The other elements are added by the Parser while it reads the source file(s).
When the source file is read successfully (i.e. when no parsing errors are raised), the visitors are called.
The visitor pattern¶
The visitors pattern is used to process each Node element. There are currently three visitors, and they are processed in this order:
- Evaluator
- Normalizer
- Compiler
The Evaluator¶
Evaluates the tree. This visitor visits each node and processes it. Some examples:
- If it visits an if node, it evaluates it and follows the true flow, the false flow is discared.
- If it visits a for loop it evaluates its body.
- If it visits an import node it imports the file into the tree.
- If it visits a call node to a (builtin or not) function, it calls it.
And so on until all nodes are visited.
This will result in a larger tree (e.g. imported files, for loops,…) with lots of nodes which will not be part of the resulting css.
The Normalizer¶
This visitor strips the garbage from the evaluated nodes, ditching null
rules, resolving ruleset selectors et caetera. This step performs the logic
necessary to facilitate the @extend
functionality, as these must be
resolved before buffering output.
The Compiler¶
Compile to css, and return a string of CSS.
Changes between Stylus and Stilus¶
This section is quite useless.
Nodes¶
Node is the root of all nodes. All node types are set via the
node_name
attribute. The value
attribute of a node is used to
denote its value, while in Stylus JavaScript implementation val
is
used.
Evaluator¶
globals vs commons: the Stylus globals
in the Evaluator
is called
commons
.
global vs common: the Styls global
in the Evaluator
is called
common
.