calfinated

v1.4.1

Published

3 years ago

Macro engine for token replacements in template strings

Downloads

1,587

0High
0Medium
0Low

pmarkert

calfinated

calfinated.js is a node module that provides string-based templating and token replacement.

The initial purpose is to replace the usage of the no longer maintained markup.js dependency for use by hyperpotamus, but the utility has since expanded and is now available as a standalone module.

Why the name?

Given the theme of hyperpotamus, a baby hippo is called a "calf".

How does it work?

var calfinated = require('calfinated')();

var data = {
   name: "hippos"
   favorite: {
     drink: "coffee"
     color: "brown"
     special: "I like M&M's"
     number: 6294
     current_time: new Date("2017-01-01")
   }
};

calfinated.process("<% name %>", data); // "hippos"
calfinated.process("<% favorite.color %>", data); // "brown"
calfinated.process("<% name %> drink <% favorite.drink %>", data); // "hippos drink coffee"
calfinated.process("<% favorite.number %>", data); // 6294 (typed as number)

Changing delimiters

You can even change the delimiters that calfinated uses if you don't like the <% ... %> syntax. The delimiters must be passed in as an array with the opening and closing values as a regular expression.

var calfinated = require("calfinated")();
calfinated.delimiters = [ "{{", "}}" ];

From the browser

calfinated can also be used in a browser, but requires lodash and moment-timezone as dependencies. In order to keep the size of the browser module small, references to both must be passed into the constructor. Lodash is required to function, however, if you do not plan to use any of the date/time manipulation pipes then you can omit the moment-timezone reference.

<html>
<head>
<script src="https://cdn.jsdelivr.net/lodash/4.17.4/lodash.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment-timezone/0.5.11/moment-timezone-with-data.min.js"></script>
<script src="../browser/calfinated.min.js"></script>
</head>
<body>
</body>
<script language="javascript">
 window.onload = function() {
   var calfinated = require("calfinated")(_, moment); // pass instances of lodash and moment-timezone to calfinated.
   var result = calfinated.process({ a : "This is a <% whatisit %> at <% now | utc_format %>", b: "And another" }, { whatisit: "test", now: new Date() });
   document.write(JSON.stringify(result));
 }
</script>
</html>

Processing objects and arrays

calfinated can also be used to process all values in an array or all values of an object recursively.

calfinated.process([ "<% first %> expression", "<% second %>" ], { first: "foo", second: "bar" }); // [ "foo expression", "bar" ]
calfinated.process({ a: "<% first %> expression", b: "<% second %>", c: "untouched value" ], { first: "foo", second: "bar" }); // { a: "foo expression", b: "bar", c: "untouched value" }

A third parameter can be passed into to list excluded properties which will not be processed.

Pipes

Plugable pipes that allow for powerful transformations of the data

calfinated.process("<% drink | upcase()" %>", data); // "COFFEE"

Pipes can be chained.

calfinated.process("<% drink | upcase | urlencode %>", data); // I%20LIKE%20M%26M'S

Some pipes support parameters

calfinated.process("<% current_time | date_format('MM/DD/YYYY') %>", data); // 01/01/2017

Pipes reference

string

Converts the value to a string representation

calfinated.process("<% age | string %>", { age: 18 }); // "18"

boolean

Parses the string values "true" or "false" as a boolean (case insensitive).

calfinated.process("<% happy | boolean %>", { happy: "true" }); // true

integer

Parses the string value as an integer.

calfinated.process("<% age | integer %>", { age: "18" }); // 18

number

Parses the string value as a number.

calfinated.process("<% age | integer %>", { age: "18.3" }); // 18.3

json

Converts the value to the JSON equivalent as a string

calfinated.process("<% element | json %>", { element: { symbol: "au", number: 79, weight: 196.966 }); // '{\n  "symbol": "au",\n  "number": 79,\n  "weight": 196.966\n}'

json_parse

Parses the string value into a JSON object

calfinated.process("<% element | json %>", { au: '{\n  "symbol": "au",\n  "number": 79,\n  "weight": 196.966\n}' }); // { element: { symbol: "au", number: 79, weight: 196.966 }

is_null

Returns true if the value is null; otherwise false.

calfinated.process("<% SSN | is_null %>", { SSN: null }); // true

is_empty

Returns true if the value is null, undefinecd, or an empty string; otherwise false.

calfinated.process("<% SSN | is_empty %>", { ssn: "" }); // true

String operations

toUpperCase [alias: upcase]

Converts a string to all uppercase characters.

calfinated.process("<% name | toUpperCase %>", { name: "John Jingleheimer" }); // JOHN JINGLEHEIMER

toLowerCase [alias: downcase]

Converts a string to all lowercase characters.

calfinated.process("<% name | toUpperCase %>", { name: "John Jingleheimer" }); // john jingleheimer

csv_safe

Escapes a string value to replace any double-quote(") characters to prefix them with a backslash (). If the value has a comma, it will be surrounded by double-quotes.

calfinated.process("<% field | csv_safe %>", { field: "candy, cookies, and popcorn" }); // '\"candy, cookies, and popcorn\"'

substr(start, length)

Extracts the specified portion of the string value starting at start and continuing for at most length characters.

calfinated.process("<% field | substr(3,8) %>", { field: "candy, cookies, and popcorn" }); // "dy, cook"

substring(start, end)

Extracts the specified portion of the string value starting at start and ending at end.

calfinated.process("<% field | substring(3,8) %>", { field: "candy, cookies, and popcorn" }); // "dy, c"

encodeURIComponent [alias: urlencode]

Encodes the specified string according to the URL percent-encoding specification.

calfinated.process("<% field | encodeURIComponent %>", { field: "candy, cookies, and popcorn" }); // "candy%2C%20cookies%2C%20and%20popcorn"

decodeURIComponent [alias: urldecode]

Decodes the specified string according to the URL percent-encoding specification.

calfinated.process("<% field | urldecode %>", { field: "candy%2C%20cookies%2C%20and%20popcorn" }); // "candy, cookies, and popcorn"

match(pattern/options, group)

Executes the specified RegExp pattern (with the specified "gim" options) to the value and returns the matched value. If group is specified, it should be the 1-based index of the capturing group to be returned.

// Note, the double "\" because this is still a javascript string.
calfinated.process("<% field | match(/\\d+/) %>", { field: "This is my 35th attempt" }); // "35"
calfinated.process("<% field | match(/my (\\d+)th/) %>", { field: "This is my 35th attempt" }); // "my 35th"
calfinated.process("<% field | match(/my (\\d+)th/,1) %>", { field: "This is my 35th attempt" }); // "35"

replace(pattern/options, replacement)

Returns a new string with instances of the specified RegExp pattern (with the specified "gim" options) within the value replaced using the provided replacement value.

calfinated.process("<% field | replace(/a/,A) %>", { field: "abc" }); // "Abc"

trim

Converts the value to a string, trimming any leading or trailing whitespace.

calfinated.process("<% field | trim %>", { field: " field with lots of space  " }); // "field with lots of space"

Array operations

join(delimiter)

Joins all elements in the value, which must be an array, into a string using the specified delimiter. If no delimiter is specified, the default delimiter is a comma (,) character. To join the values using an empty delimiter or whitespace, surround the delimiter with single or double-quotes.

calfinated.process("<% fruit | join() %>", { fruit: [ "apples", "bananas", "cherries" ] }); // "apples,bananas,cherries"
calfinated.process("<% fruit | join('') %>", { fruit: [ "apples", "bananas", "cherries" ] }); // "applesbananascherries"
calfinated.process("<% fruit | join(' ') %>", { fruit: [ "apples", "bananas", "cherries" ] }); // "apples bananas cherries"

split

Splits a string value into an array of elements between each instance of delimiter.

calfinated.process("<% fruit | split %>", { fruit: "apples,bananas,cherries" }); // [ "apples", "bananas", "cherries" ]
calfinated.process("<% fruit | split(' ') %>", { fruit: "apples bananas cherries" }); // [ "apples", "bananas", "cherries" ]

Utility operations

optional(default_value)

If the value is undefined, returns default_value (or an empty string) instead of throwing a MissingKey error.

calfinated.process("<% foo | optional %>", { fruit: "apples,bananas,cherries" }); // ""
calfinated.process("<% foo | optional('bar') %>", { fruit: "apples bananas cherries" }); // "bar"

not

Reverses the value of a boolean.

calfinated.process("<% SSN | is_null | not %>", { SSN: null }); // false

random(min, max, asFloat)

Either selects a random element from an array value, (do not values for min, max, or asInteger)

calfinated.process("<% fruit | random %>", { fruit: [ "apples", "bananas", "cherries" ] }); // one of "apples", "bananas", or "cherries"

Or when a value is specified for the min parameter, then the passed in pipeline value is ignored and it returns a random number in the range [ min , max ], or [ 0, min ] if max is not specified.

calfinated.process("<% | random(1,6) %>"); // integer between 1 and 6
calfinated.process("<% | random(6) %>"); // integer between 0 and 6

NOTE: as shown here, if the min value is specified, then the pipeline value is ignored and can be omitted from the expression altogether.

Mathematical operations

add(number) [alias: plus, sum]

Adds number to the value.

calfinated.process("<% age | add(3) %>", { age: 18 }); // 21

Or calculates the sum of all of the elements in an array value. (The number parameter is ignored)

calfinated.process("<% ages | add %>", { ages: [ 18, 21 ] }); // 39

subtract(number) [alias: minus, difference]

Subtracts number from the value.

calfinated.process("<% age | subtract(3) %>", { age: 18 }); // 15

Or calculates the running difference all of the elements in an array value. (The number parameter is ignored)

calfinated.process("<% ages | add %>", { ages: [ 18, 21, 3 ] }); // -6

multiplied_by(number) [alias: product, times]

Multiplies the value by a number.

calfinated.process("<% age | multiplied_by(3) %>", { age: 6 }); // 18

Or calculates the product of all of the elements in an array value. (The number parameter is ignored)

calfinated.process("<% ages | product %>", { ages: [ 2, 3, 5] }); // 30

divided_by, quotient: divided_by

Divides the value by a number.

calfinated.process("<% age | divided_by(3) %>", { age: 6 }); // 2

Or calculates the running quotient of all of the elements in an array value. (The number parameter is ignored)

calfinated.process("<% ages | product %>", { ages: [ 100, 10, 2] }); // 5

average

Calculates the average of all elements in the array.

calfinated.process("<% ages | average %>", { ages: [ 15, 30, 42] }); // 29

Date-time operations

now [alias: date_now]

Returns the current time, in the local timezone as a moment object.

today

Returns the start of the current day, in the local timezone as a moment object.

day

Returns the date only (start of day) of the given date/time.

date_parse(format, timezone) [alias: parse_date]

Parses the value as a moment using the optionally specified format string and timezone. Defaults to guessing the format and local timezone.

date_format(format, timezone) [alias: format_date]

Formats the provided date/moment value as a string using the specified format and timezone. Defaults to ISO-8601 format and local timezone.

utc_parse(format) [alias: parse_utc]

Parses the value as a moment using the optionally specified format string and UTC. Defaults to guessing the format.

utc_format [alias: format_utc]

Formats the provided date/moment value as a string using UTC. Defaults to ISO-8601 format.

date_add(count, interval)

Adds count intervals to the date value and returns the resulting date/moment. See http://momentjs.com/docs/#/manipulating/add/ for valid interval values.

date_subtract

Subtracts count intervals from the date value and returns the resulting date/moment. See http://momentjs.com/docs/#/manipulating/add/ for valid interval values.

start_of(interval)

Returns the start of the specified interval for the given date value. See http://momentjs.com/docs/#/manipulating/start-of/ for valid interval values.

end_of(interval)

Returns the end of the specified interval for the given date value. See http://momentjs.com/docs/#/manipulating/start-of/ for valid interval values.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

calfinated

Why the name?

How does it work?

Changing delimiters

From the browser

Processing objects and arrays

Pipes

Pipes reference

string

boolean

integer

number

json

json_parse

is_null

is_empty

String operations

toUpperCase [alias: upcase]

toLowerCase [alias: downcase]

csv_safe

substr(start, length)

substring(start, end)

encodeURIComponent [alias: urlencode]

decodeURIComponent [alias: urldecode]

match(pattern/options, group)

replace(pattern/options, replacement)

trim

Array operations

join(delimiter)

split

Utility operations

optional(default_value)

not

random(min, max, asFloat)

Mathematical operations

add(number) [alias: plus, sum]

subtract(number) [alias: minus, difference]

multiplied_by(number) [alias: product, times]

divided_by, quotient: divided_by

average

Date-time operations

now [alias: date_now]

today

day

date_parse(format, timezone) [alias: parse_date]

date_format(format, timezone) [alias: format_date]

utc_parse(format) [alias: parse_utc]

utc_format [alias: format_utc]

date_add(count, interval)

date_subtract

start_of(interval)

end_of(interval)