Skip to main content

Known Limitations

CodeBaker keeps most templates valid for your IDE, but not all of them, and a few of its rules surprise people. Each entry here is one line of what you see, why, and what to do. The reasoning behind the trade-off is in Why Templates Are Plain Files.

In the IDE, while you edit the template​

A placeholder is underlined in a CSS value, or in another place that accepts no identifier. ___color___ is a valid identifier in most languages, not in background: ___color___;. Keep a real value in the file and describe the swap with replace, or hide the declaration in a /* CodeBaker: ... */ comment (Keeping the Template Valid for Your IDE).

"Duplicate declaration" in a template with a condition. The IDE reads both branches of the condition. The generated file has only one. Add a throwaway suffix such as ___alt1___ to silence it. The cost: the IDE sees two different names, so rename and find usages do not connect them.

A loop variable is reported as undefined. The IDE does not know about a //CodeBaker: {% for %} loop. Only the template is affected: the generated code does not contain the directive comments.

//CodeBaker: does nothing in a CSS file, and JSON cannot hold a directive. // is not a CSS comment: write /* CodeBaker: ... */. Plain JSON has no comments at all: write the template as .json5 (Generating JSON).

In the generated file​

A directive is ignored, or text after it disappears. A CodeBaker: directive has to be the last thing on its line: anything after it is part of the directive. The word and the colon are both required and the word is case-sensitive, so // codebaker: x is an ordinary comment. See the rules.

The text that replaced a directive is not indented. The text starts at the beginning of the line, whatever the comment's indentation was. Reformat the output if that matters.

A comment that starts with replace, regex, on, off or reset is eaten. Those words are commands when they come first after CodeBaker:. Write your own note with another first word.

The text of a replace comment shows up in the generated file. A replace that CodeBaker cannot parse (for example replace x with no replacement) is not consumed, and it is not an error. Check the syntax in Replacing Real Values.

Quotes in a replace replacement are lost. Directive arguments go through a tokenizer that consumes " and ', so {{ x | default('n/a') }} breaks. Compute such a value in a vars entry and use {{ name }} in the replacement.

A parse error on {{ }} or {% %} in a comment or a text. Pebble reads a literal {{ }} or {% %} anywhere, including inside ordinary comments. Wrap the text in a raw block, print one string with {{ 'text' }}, or choose other delimiters: Escaping Text.

A filter or an if in a file name stays as written. A name takes only a plain value ({{ name }}, {{ user.name }}). Compute the value in vars, or set the output name with a target in the mapping file: Values and Variables.

{% include %}, {% extends %}, {% import %}, {% embed %} and {% from %} stop the generation. A template file is a single text, so there is no other template to load. Share text through a variable (vars or the json section), $ref, $file or the mapping's data. {% macro %} still works inside one file.

Behavior that surprises​

A typo in a variable name prints nothing instead of failing. An undefined variable renders as empty text. It is what makes the suffix trick work, and it also hides a misspelt name. Look at the preview.

loop.index starts at 0. Use loop.index + 1 to count from 1.

The text true or false in a field becomes a boolean, and digits become a number. That is what makes {% if flag %} work. A field that must stay the text true cannot.

A range with more than a million numbers is refused, and a template that writes more than 32 million characters is stopped. Pebble builds a range in memory, so {% for i in 1..2000000000 %} would take the memory of the IDE. A range whose end is a variable cannot be checked before it runs.

A file that is not text is copied as it is, and the IDE's Undo cannot revert it. Nothing in it is read or replaced. A text file that is not valid UTF-8 counts as binary too, so it gets no placeholders. Use Git to go back.

Next​