Skip to content

Latest commit

 

History

History
74 lines (49 loc) · 3.54 KB

02-precompiler-overview.md

File metadata and controls

74 lines (49 loc) · 3.54 KB

Table of Contents

  1. Introduction
  2. Precompiler Overview
  3. Runtime Overview
  4. References
  5. Validators
  6. Runtime Compiler
  7. Initial Render
  8. Rerendering (Updating)
  9. The Environment
  10. Optimizations

Precompiler Overview

The precompilation step, which generally occurs at build time, takes a template string and turns it into an Intermediate Representation (also known as IR or WireFormat). The Intermediate Representation is a set of structured instructions that could be used directly for rendering, but is more appropriately further processed into optimized opcodes. The public interface for the precompilation is the precompile function from the @glimmer/compiler package.

import { precompile } from '@glimmer/compiler';

...

const wireFormat = precompile('<p>This string is my template</p>');

...

How the sausage is made

The precompilation process is relatively short and straightforward, and if you are satisfied with knowing that strings go in and Intermediate Representations come out, you can safely skip to the next guide. If you would like to know a little more about how the process works, read on.

Template examples

Hello, Glimmer!

or

<p>This string looks like HTML</p>

or

{{#ember-component as |compy386|}}This string looks like Ember{{/ember-component}}

or

<GlimmerComponent @args='are fun'>This string looks like Glimmer.js</GlimmerComponent>

Parsing the string with Handlebars

Though the examples above may look like HTML, Ember templates, or Glimmer templates, at the point of precompilation they are just strings. These strings are transformed into Abstract Syntax Trees (AST) by the Handlebars parser.

let ast = handlebars.parse('<p>This string looks like HTML</p>');

At this point in the process, parts of the string have meaning, but the Handlebars parser does not understand HTML syntax, so much of the template strings are still just strings.

Identifying HTML and angle components

From here, Glimmer further processes the AST, teasing meaning out of the strings that remain. When this preprocessing is complete, each part of the original template string is parsed and labeled. For example, the p and GlimmerComponent from the examples above are recognized as ElementNodes. The AST is ready for compilation.

Creating the Intermediate Representation

Glimmer's TemplateCompiler transforms the AST into an Intermediate Representation (IR) or WireFormat. The Intermediate Representation contains a list of statements or instructions which will eventually be used to render the template, and a symbolTable containing the variables created in the scope of a template block. For instance, in the ember-component example above, {{#ember-component as |compy386|}} ... {{/ember-component}} is the block, and compy386 is the variable created in the scope of the block.

When the Intermediate Representation is ready, the precompilation step is complete. At this point, paths diverge; the final compilation steps are either completed at build time or at run time, depending on the environment in which Glimmer is running. Read on!

Next: Runtime Overview »