30:Tf2c,svg` `31: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 ::= ( )* \`\`\``32: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_) `33:[] 2e:{"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"},{"id":96,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"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"},{"id":128,"value":"md`---\n\n## Usage`","pinned":false,"hidden":false,"mode":"ojs"},{"id":131,"value":"data = ({\n happy: true,\n hello: {\n world: 40\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":46,"value":"result = viscousjs.parseAndEvaluate(`hello.world + 2`, data)","pinned":true,"hidden":false,"mode":"ojs"},{"id":140,"value":"output = viscousjs.parseAndRender(`\n {%- if happy -%}\n clap your hands\n {%- end -%}\n`)","pinned":true,"hidden":false,"mode":"ojs"},{"id":167,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":148,"value":"md`---\n\n## Overview\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":158,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"viscousjs = require(\"@mywheels/viscousjs@1.1.2\")","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}