.Template() | .Template``

ISHML's text generation API facilitates the creation of complex text generation objects using a templating system based on JavaScript's template literal notation. Specifically, ishml.Template is a tag function that may be called with either template literal notation or standard function call notation. Instead of directly returning text, however, ishml.Template returns an instance of ishml.Phrase. The template defines the phrase; the phrase generates the text. See the text generation tutorial for detailed examples of templates in use.

It is common practice to assign ishml.Template to the underscore variable to make the templates easier to read. The API documentation follows this convention.

The built-in template prefixes require ishml.js. The English language prefixes require en-us.js.

Place the following scripts near the end of the HTML document, before the closing </body> tag. Then add your own script below this script.

<script src="{{ site.ishml }}"></script>			
<script src="{{ site.en_us }}"></script>
<script>
	var _ = ishml.Template 
	//etc.
</script>

_`template literal`
_(value1[, ...[, valueN]])
_([value1[, ...[, valueN]]])

Returns a new unmodified instance of ishml.Phrase. When the .say() method is called, the elements of phrase's array are concatenated together. This is the default text generation provided by the baseline template.

Prefixes

The baseline template also exposes a collection of additional templates through its properties. These templates are called prefixes and modify the default text generation behavior. Prefixes work a bit differently than standard functions. An unlimited number of prefixes may by chained together with dot notation to apply layer upon layer of modifications. However, only the last prefix in the chain takes arguments. This last prefix generates a ishml.Phrase and then that phrase is passed as the argument to the next to last prefix in the chain, which generates a new phrase. The process continues all the way up to the front of the chain. Therefore, prefixes are applied from right to left starting with the prefix closest to the left parenthesis or backtick. Chaining permits the creation of complex phrases from an uncluttered single line of code.

See the text generation tutorial for examples of prefix chaining.

.a

Modifies a phrase to prepend an indefinite article, a or a, to each item in the phrase's array based on whether the item is pronouced with an initial vowel sound according to standard American English. The .a prefix is identical to .an.

.A

Modifies a phrase to prepend a capitalized indefinite article, A or An, to each item in the phrase's array based on whether the item is pronouced with an initial vowel sound according to standard American English. The .A prefix is identical to .An.

.an

Modifies a phrase to prepend an indefinite article, a or an, to each item in the phrase's array based on whether the item is pronouced with an initial vowel sound according to standard American English. The .an prefix is identical to .a.

.An

Modifies a phrase to prepend a capitalized indefinite article, A or An, to each item in the phrase's array based on whether the item is pronouced with an initial vowel sound according to standard American English. The .An prefix is identical to .A.

.cap

Modifies a phrase to capitalizes the first letter of each item in the phrase's array.

.cycle

Modifies a phrase to select each item of the phrase's array in order. After each item has been selected in turn, the phrase resets again with the first item. Meta-data .index, .total, and .reset are available through the phrase's .data collection.

.favor

Modifies a phrase to select each item of the phrase's array in order of decreasing likelihood. For example, in an array with 5 elements, the first element is 5 times more likely to be selected than the last element, the second element is 4 times more likely than the last, and so on. Mathmatically, the odds of selecting the element at index i of an array of length n is ( n - i ) out of n * ( n + 1 ) / 2. In an array with 5 elements, this translates to odds of 5:15, 4:15, 3:15, 2:15, and 1:15 for each element respectively. Meta-data .index and .total are available through the phrase's .data collection.

.list

Modifies a phrase to join the contents of the phrase's array into an Oxford comma list of items.

.pick

Modifies a phrase to select an item from the phrase's array at random. If the item selected is the same as the previously selected item, the next item in the array is chosen. This prevents the same item from being selected twiced in a row. Meta-data .index and .total are available through the phrase's .data collection.

.pin

Prevent the reset signal from .cycle from propagating down the the prefix chain. Often paired with .shuffle and .cycle to prevent a phrase from reshuffling everytime .cycle resets. May also be used to pin the random prefixes, favor, pick, and roll to their first selection.

.roll

Modifies a phrase to select an item of the phrase's array completely at random like rolling dice. Meta-data .index and .total are available through the phrase's .data collection.

.series

Modifies a phrase to select each item of the phrase's array in order. After each item has been selected in turn, the phrase then generates the empty string. Meta-data .index and .total are available through the phrase's .data collection.

.shuffle

Shuffles the items of the phrase's array.

.tags.String

Returns the tagged phrase associated with the phrase id provide. See also the .tag() phrase suffix.

Static Methods

ishml.Template.define( String).as(Phrase Factory Function)

Defines a custom template prefix. See the text generation tutorial for a detailed example.