Garnet: a tiny template engine for Node.js
August 28, 2014
This afternoon I built Garnet: a fast and minimalistic template engine for Node. The syntax is like eRuby, so it will be familiar to Rails developers. It supports layouts, unlike EJS. And unlike Jade, it lets you write raw HTML and gives you full control over every character.
Installation
$ npm install garnet
Features
- Compatible with Express
- Performant due to precompilation and caching
- Evaluate JavaScript (e.g., for conditionals and loops):
<% code %> - Evaluate and embed (with sanitization):
<%= code %> - Evaluate and embed (without sanitization):
<%- code %> - Render a template from within a template:
<%- render(path, locals) %>
API
Compiling and rendering
To compile a template (or fetch an already-compiled template from cache):
var template = garnet.compile(path);
To render a template:
var output = template(locals);
To render a template from within another template (and compile it if necessary):
<%- render(path, locals) %>
Default template directory
By default, Garnet looks in
./views for unqualified template names. If you want to change the default path to ./templates, for example, use:garnet.templateDir = path.join(process.cwd(), 'templates');
Default template extension
If you refer to a view without a file extension, Garnet assumes
.garnet by default. You can change this like so:garnet.templateExt = '.html';
Caching
By default, Garnet will only load and compile a template once. If you want Garnet to reload and recompile templates whenever they are rendered, you can do so with:
garnet.enableCaching = false;
This is useful for development (you don’t need to restart the server for every change), but you should leave caching enabled in production.
Examples
Using Garnet with Express
To render a view with Express:
app.get('/', function(req, res) {
res.render('index.garnet');
}
If you want to omit the
.garnet extension from the line above, you can tell Express to assume it:app.set('view engine', 'garnet');
If you want to use a different file extension (e.g.,
.html) for views, use this:app.set('view engine', 'html'); // Tell Express to assume this extension
app.engine('html', garnet.__express); // Tell Express to use Garnet for this extension
garnet.templateExt = '.html'; // Tell Garnet to assume this extension
Locals
You can pass data to a view using the
locals argument.For example, in
app.js:res.render('user.garnet', { name: 'Stephan Boyer' });
In
views/user.garnet:Name: <%= locals.name %>
Conditionals
<% if (user) { %>
Name: <%= user.name %>
<% } %>
Loops
<% users.forEach(function(user) { %>
Name: <%= user.name %>
<% } %>
Layouts
We simply pass the name of the view to the layout as a local:
<!DOCTYPE html>
<html>
<head>
<title>Layout Demo</title>
</head>
<body>
<%- render(locals.view, locals) %>
</body>
</html>
In Express, you might render a view with this layout as follows:
app.get('/', function(req, res) {
res.render('layout.garnet', { view: 'index.garnet' });
});
Let It Go (Frozen) + Let Her Go (Passenger)
May 29, 2014
This evening I did a quick mashup of two similarly-entitled songs: Let It Go from Frozen and Let Her Go by Passenger. I didn’t have sheet music for either song, so I apologize for any wrong notes—my ears are not very trustworthy!
Visualizing data structures
May 27, 2014
For a class at MIT, I built an interactive tool for building and exploring data structures based on the pointer machine model of computation (e.g. linked lists, binary search trees, etc.). It features an integrated development environment for implementing data structures in JavaScript...
...and a highly animated interface for making them come to life:
It has a few built-in data structures, including linked lists, ordinary binary search trees, AVL trees, and splay trees.
The “safe” construct
May 20, 2014
Here’s a feature I wish existed in statically-typed programming languages.
Java has something called “checked exceptions”, which is a mechanism that forces you to handle errors (or explicitly declare them in the function signature). The consensus seems to be that this was a bad idea, but I find the concept somewhat appealing.
It does seem sloppy that some exceptions are deemed “checkworthy” and others are runtime errors, and I don’t get to choose which are which (unless I also wrote the code that throws them). What if I’m writing a quick-and-dirty program to run a one-off job and don’t care about exception handling? Or what if I’m writing an autopilot for a commercial airplane and want every exception to be checked (to completely eliminate runtime errors)?
In the functional programming world, there are other mechanisms for error handling, such as algebraic data types like
Either/Option/Maybe and friends, which are used very much like checked exceptions—the type checker forces you to handle the error case. Functional programmers have devised a few tricks to make errors propagate automatically behind the scenes, such as monads with the clever do notation in Haskell. Clever as it is, it still forces me to write all my code in the appropriate monad and glue it all together with monad transformers.Ideally we’d all just formally verify our programs (with smart tools to help us) and not worry about the possibility of any errors, ever. Maybe in 50 years.
Back on planet Earth, I’d rather have it be like this. Every exception is unchecked. But there should be a new language construct—let’s call it
safe. If any code within the safe block has the possibility of throwing an exception, then you get a compile-time error. Roughly:safe {
// code that can't throw an exception
}
And you can specify a whitelist of exceptions that are allowed to escape the
safe block:safe except FileDoesNotExist {
file = openFile("foo.txt") // might throw FileDoesNotExist but nothing else
}
Let me give some examples of why this is useful. Suppose I’m writing a web server. Check it out:
while (true) {
safe {
// accept new connection
// serve response
}
}
Now I can be confident that my web server will never crash. Of course I can still use normal exception handling throughout the program, but none of the exceptions are allowed to reach the outer loop and crash the program.
Back to the autopilot example—in that case I would just wrap the entire program in a
safe block. And if I were writing a quick-and-dirty script, I wouldn’t use safe at all.Library/API designers could also wrap each function in a
safe/except block, and the except part documents which exceptions may be thrown. But I don’t have to catch them.Now I, the lazy user of the library, can simply ignore any errors that might be thrown (and let them crash the program). Or, if I want the compiler to exhaustively check that I’ve handled every error, I can use
safe. It’s all up to me.Dynamic typing: an oxymoron?
March 19, 2014
In computer science and programming parlance, there are two distinct interpretations of the phrase type system, and it causes all kinds of squabbles that drive me insane. The interpretations are:
- A framework in which to categorize data.
- A formal system used to prove programs have meaning.
It is tempting to identify #1 with dynamic typing and #2 with static typing, but neither has any notion of static vs. dynamic.
Almost all programming languages, such as Python, Scheme, Ruby, Java, Haskell, C++, etc., have #1. Some say these are “typed” languages—but many reserve that description only for the ones which are statically-typed. Those who claim that dynamically-typed languages don’t have a true type system employ the term “tag system” instead. A few languages, such as FORTH, assembly languages, and early versions of FORTRAN, only support one sort of data (usually a machine word), and it is a bit barmy (but perhaps still correct) to say they are characterized by #1. These are called “untyped” or “unityped” languages.
Of the languages mentioned above, Java, Haskell, and C++ are typically said to also have #2. However, even this is a little suspect, because the proof systems for such languages are often not sound (even Haskell, often lauded for its type system, has an unsafe escape hatch). In the strictest sense, for almost any modern programming language, appeasing the proof checker (“type checker”) does not guarantee that the program won’t crash (e.g., usually these systems do not eliminate the possibility of running out of memory). It is worth mentioning that “type systems” in this camp can be used for both expressing proofs in mathematics and reasoning about computer programs (though they often take very different forms when used for these distinct purposes).
For those who do not obsess over programming language theory like I do, #2 typically shows up in academic papers as a set of funny-looking rules, e.g.,
\[ \frac{ \Gamma \vdash e_0 : \sigma \qquad \Gamma, x : \sigma \vdash e_1 : \tau }{\Gamma \vdash \text{ let } x = e_0 \text{ in } e_1 : \tau}, \]
which are used by the compiler to automatically check or infer the types of expressions in a program to prove that the program makes sense.
Those on this side of the fence might consider it an insult to say that languages like Python or Ruby have a “type system” (after all, type theory was originally designed to be a serious foundation for the entire field of mathematics), whereas those in the other camp might view their contenders as stubborn academic zealots trapped in an ivory tower.
The only reason we have these two contentious viewpoints is because we’ve been using one term to mean two different things. Should we use two distinct terms instead?