2c:null 2d:["$","title",null,{"children":"Viscous.js | Kelley van Evert | Observable"}] 32:Tf2c,svg` `33:T613,md`--- # Parsimmon Parsimmon is just great, it's a [parser combinators](https://en.wikipedia.org/wiki/Parser_combinator) library written in JavaScript that allow you to write your parser as elegantly as this: \`\`\`js const _ = P.regexp(/[ \\n\\t]*/); // optional whitespace // produce a boolean indicating whether to twim whitespace const Open = P.regexp(/\{\{-?/).map((str) => str.length === 3); const Close = P.regexp(/-?\}\}/).map((str) => str.length === 3); // produces Array<{ filter: string; args: ExprNode[] }> const Filter = P.string("|").then(_).then(P.alt( // filter with arguments P.seq(Id, P.string(":"), _, Expression.sepBy1(P.regexp(/,\s*/))).map(...), // just an filter Id.map(...) )); // produces [ExprNode, Filter[]] const Interpolation = P.seq( Expression.skip(_), Filter.skip(_).many() ) .wrap(Open.skip(_), _.then(Close)); \`\`\` Parser combinators are a wonderful way of writing a parser closely resembling a BNF grammer, but then in an API. (Instead of having to work with the overhead and complexity of an parser-generating library that needs its own intermediate grammar languages and processing steps etc.) Here's what the BNF would look like: \`\`\` Open ::= "{{" "-"? Close ::= "-"? "}}" Filter ::= "|" FilterApp ::= ":" | MoreArgs ::= "," ? Interpolation ::= ( )* \`\`\``34:Tce9,md`### Control flow - **if** - \`{% if %}\` - \`{% elsif %}\` - or \`{% elseif %}\` - or \`{% else if %}\` - \`{% else %}\` - \`{% endif %}\` - or just \`{% end %}\` - **unless** - \`{% unless %}\` - \`{% endunless %}\` - or just \`{% end %}\` - **for** - \`{% for in %}\` - or \`{% for of %}\` - \`{% endfor %}\` - or just \`{% end %}\` ### Interpolation - \`{{ }}\` - \`{{ | }}\` - \`{{ | : }}\` - \`{{ | ... | ... | ... }}\` ### Whitespace control Both interpolation and control flow blocks accept whitespace trimmers at either end, for example \`{% if true -%}\` or \`{{- expr -}}\`. These trim whitespace off of the preceding and/or succeeding raw template pieces. ### Expressions You can form expressions with all the ordinary mathematical operators and comparators, double and triple (in)equality, and \`contains\` (which works for strings as well as arrays). Also, you can use helper functions in expressions like \`max(a, b)\` or \`cond(d, a, b)\`. ### Filters Interpolation blocks accept filters, which transform the evaluated expression before interpolating it into the output. - \`{{ name | upper }}\` might become "ROSE" - \`{{ 8 | max: 4 }}\` becomes "4" You can use multiple filters: - \`{{ 3.14 | min: 0 | ceil }}\` becomes "4" You can pass multiple arguments: - \`{{ 8 | clamp: 4, 6 }}\` becomes "6" You can use expressions in filters: - \`{{ fuelLevel | clamp: config.minLevel, config.maxLevel }}\` ### Providing your own helpers and filters Filters are just helpers which are passed the interpolated value as first argument. For example, \`{{ 8 | max: 4 }}\` evaluates as \`max(8, 4)\`. You can register additional helper functions in the \`helpers\` config key: \`\`\`js parseAndRender(\` {{ hello | world }} {{ dino | raise: food, love }} \`, data, { helpers: { world(hello) { ... }, raise(dino, food, love) { ... }, }, } ); \`\`\` ### Truthiness Like Liquid, an expression is considered truthy whenever it's a \`true\`, a number, a string or an object. So, also \`""\` and \`0\` and \`[]\` are considered truthy. You can also provide your own ### Failure If the template fails to parse or render, \`parseAndEvaluate\` will return \`undefined\`, and \`parseAndRender\` will return an empty string. If you want parse or runtime errors to be thrown instead, you pass the config key \`throwOnError: true\`. ### Configuration \`\`\`ts type ViscousConfig = { helpers?: Record; isTruthy?: (data: any) => boolean; throwOnError?: boolean; evaluate?: (expr: ExprNode, env?: any) => any; }; \`\`\` ### Known helpers and filters More will be added soon. (And just make a PR if you want to contribute yours :)) - **general purpose** - \`default\` (_fallback_) - **numeric** - \`abs\` (_num_) - \`ceil\` (_num_) - \`floor\` (_num_) - \`at_least\` (_min_) - \`at_most\` (_max_) - \`clamp\` (_min, max_) - **strings** - \`append\` (_str_) - \`upcase\` (_str_) - \`upper\` (_str_) - \`downcase\` (_str_) - \`lower\` (_str_) - **control** - \`if\` (_cond, a, b_) - \`cond\` (_cond, a, b_) `35:[] 30:{"id":"399852c9df23826d","slug":"viscous-js","title":"Viscous.js","thumbnail":"2395e890b8e99b42a0c90b86698b97a88197b7b3f664dc31e65f8b8d7dfefd45","access_level":"public","create_time":"$D2020-12-02T22:23:51.714Z","update_time":"$D2020-12-05T11:37:44.387Z","view_time":null,"first_public_time":"$D2020-12-05T11:16:55.952Z","has_unpublished_edits":null,"fork":false,"stars":2,"starred":false,"owner":{"type":"team","id":"cdda271b76654961","login":"kelleyvanevert","name":"Kelley van Evert","avatar_url":"https://avatars-next.observableusercontent.com/86df2bc54dd099fad6826dfcf7ae3dd97c5e0cdcf0cf3e0ac85ecd13e1938db2","tier":"starter_2024"},"version":225,"publish_version":225,"role":null,"authored":false,"authors":[{"type":"individual","id":"a35690ff73833989","login":"kelleyvanevert","name":"Kelley van Evert","avatar_url":"https://avatars-next.observableusercontent.com/86df2bc54dd099fad6826dfcf7ae3dd97c5e0cdcf0cf3e0ac85ecd13e1938db2","tier":null}],"members":[{"type":"individual","id":"a35690ff73833989","login":"kelleyvanevert","name":"Kelley van Evert","avatar_url":"https://avatars-next.observableusercontent.com/86df2bc54dd099fad6826dfcf7ae3dd97c5e0cdcf0cf3e0ac85ecd13e1938db2","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":1,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Viscous.js","cells":[{"id":0,"value":"md`# Viscous.js\n\nCheck it out on [npm](https://www.npmjs.com/package/@mywheels/viscousjs) | [github](https://github.com/mywheels/viscousjs).`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":96,"value":"$32","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":102,"value":"md`I had been happily using [Liquid.js](https://liquidjs.com/) for a while, but then got a bit annoyed when I suddenly found out they don't support parenthesized sub-expressions, and don't even follow operator precedence. Also.. the choice for elsif instead of elseif, or elif, or just else if ?!\n\nSo, I decided this was my time to play around with the wonderful [Parsimmon](https://github.com/jneen/parsimmon), and created my own variation of the templating engine—[Viscous.js](https://www.npmjs.com/package/@mywheels/viscousjs) was born :)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":128,"value":"md`---\n\n## Usage`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"data = ({\n happy: true,\n hello: {\n world: 40\n }\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":46,"value":"result = viscousjs.parseAndEvaluate(`hello.world + 2`, data)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":140,"value":"output = viscousjs.parseAndRender(`\n {%- if happy -%}\n clap your hands\n {%- end -%}\n`)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":167,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":148,"value":"md`---\n\n## Overview\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":158,"value":"$34","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":15,"value":"viscousjs = require(\"@mywheels/viscousjs@1.1.2\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W35","stdlib":"1"}} 31:"$30:body"