New! Story Templates Enhanced

[tjlee]

I've been trying to convince tj he should come on one of your streams
Of course, you would have to make the offer...

I’m game - let me know what to expect and when.

Update: looks like the ball is in my court - I discussed this with Laerun and I'm to prep a Story Template scenario to demonstrate.
I've been busy releasing the Table Edit extension as well as adding features to this extension. Perhaps the demonstration will make use of both extensions in a 2-fer.

[tjlee]

This release adds the following:

• Added logic to remove empty text blocks in Advanced Stories generated from Advanced Story Templates.
• Formalized support for use of Link IDs in place of Table names and Story Template names (see Story Template Enhanced - examples).
• Added a click action to the Toolbar Drag Record Link button (top left corner) to report the Link ID associated with the window to chat.

Additionally, the Story Template Enhanced - examples have been updated to clarify existing examples and add examples to illustrate the above.

[tjlee]

I went ahead and re-tested the extension with the 2024 D&D Ruleset update to make sure everything works as expected.

If you do experience any issues, please reply to this thread with a description of the issue and I'll try to reproduce and address it in a timely manner.

[tjlee]

This release adds functions!

Story Template Enhanced extension now supports function invocations with a syntax of functionName(stringExpression). The six functions supported are:

• capitalize - the first letter of the string expression is made uppercase.
• date - the system date according to the [DATE:format] callout is evaluated. Ex. date(format)
• fgdate - the game date (based upon selected calendar) according to the [FGDate:format] callout is evaluated.
• lower - the string expression is made all lower case. Ex. LOWER(Hi) is substituted by hi.
• titlecase - the string expression is made title case. Ex. titlecase(hello there) is substituted by Hello There
• upper - the string expression is made all lower case. Ex. upper(hi) is substituted by Hi.

These functions can be nested and can be co-mingled with the other template syntax elements where it makes sense. The results of the function are substituted in place of the function callout.

Example:

• capitalize([NPC Name]) - capitalizes the result of calling the table named NPC Name (first letter is capitalized).

Note: if the results of the table callout is not a string expression (such as formatted text), the function may produce unexpected results.

2024.10.01 Update: Story Template Enhanced (examples module) has been updated to include examples for functions (Story Template 2.2).

[tjlee]

Update: The following has been released 2024/10/02. Documentation and examples follow this post.

I'm excited to tease a more fully fleshed out function-based syntax for story templates that might be easier for folks to learn.

In total, there are 41 functions across 6 categories that include the 6 formatting functions already released (and soon to be enhanced with the next release).

The categories of Story Template Enhanced function syntax include:

• Control Functions (delim, get, set, setg, xget, xset, xsetg)
• String Functions (capitalize, cat, date, dcat, dice, fgdate, lower, pre, post, reverse, rsort, sort, titlecase, uniq, upper)
• Number Functions (avg, count, max, min, total)
• Formatting Functions (bold, bullets, italic, lines, underline, znum)
• Access Functions (head, pick, select, tail)
• Table and Template Functions (import, mult_import, mult_table, table)

Teaser: With the above, you can implement a counter to include in your template.

set(a,1) - iniitailze alias 'a' to 1
setg(a,total(get(a),1))

The above computes a + 1 (total of get(a) and 1) and assigns it back to 'a' (setg), then returns the new value 2 (setg). setg is short for "set get". The xset/xget/xsetg are the cross-template versions for values you want to persist across template evaluations.

set/xset happen quietly and are similar to the original template syntax: [:?1:a] (except that this doesn't work). ? means quiet (no value is returned)
setg is equivalent to [:1:a] (except that it doesn't work either - the value '1' has to come from a table in order for it to work).
get is equivalent to <a>.

Teaser: You can also format dates beyond what CoreRPG supports.

dcat(/,znum(2,date(mm),date(dd)),date(yyyy))

The above is broken down as:

• Concatenate (dcat) the values and delimit the results with /
• Zero left pad (znum) date(mm) and date(dd) to two places
• Include date(yyyy)

The result looks something like: 09/01/2024, depending on the system date of course. The CoreRPG [Date:mm/dd/yyyy] produces 9/1/2024 (without the leading zeros).

From the list of functions above, you can speculate how you might make use of them in your creative endeavors. These and the original plus enhanced story template syntax may be co-mingled in your story templates. Yes, they inter-operate. For example, you can store values in aliases using the original syntax and retrieve the values using the function syntax and vice versa!

If you have ideas for additional functions, feel free to message me or reply to this thread. The rewritten story template parser allows me to support these and future enhancements relatively easily (even though the code is densely complicated).

Everyone who has purchased this extension through the Forge - thank you! You will automatically get the new version once I release it along with the Story Template Enhanced Examples that will be updated with new documentation and examples to illustrate the above.

[tjlee]

Part 1
Forward to Part 2
Functional Equivalence

The following is included in the Story Template Enhanced (examples module).
You will need the extension enabled in order to use the new syntax.

Functions

Story Template Enhanced extension now supports function invocations with a syntax of functionName(values).

These functions can be nested and can be co-mingled with the other template syntax elements where it makes sense.
The results of the function are substituted in place of the function call (sometimes with an empty string).

Reference

Control Functions

The values stored may be individual values or a list of values separated by the delimiter (defaults to comma).

Function	Description	Example	Result
default	Returns the first non-empty value. Empty is a zero length string or the empty() function.	1 - default(empty(),a,b) 2 - default(, , ,a) 3 - default()]	1 - Returns a 2 - Returns a 3 - Returns empty()
delim	Sets the function delimiter. Only the first character is used.	1 - delim( ) 2 - delim(/) 3 - delim()	1 - Sets the delimiter to space. 2 - Sets the delimiter to forward slash. 3 - Resets the delimiter to the comma default.
ifvalue	When the first parameter is not the empty string, return the second non-empty value or the first value or empty().	1 - ifvalue(a,b,c) 2 - ifvalue(empty(),b,c) 3 - ifvalue()	1 - Returns b 2 - Returns c 3 - Returns empty()

Accessor Functions

Function	Description	Example	Result
get	Retrieves the named values.	get(a,b)	Returns a delimited string whose values are determined by named values a and b.
set	Sets the named value.	set(a,1,2,3)	Sets the named value a to: 1,2,3
setg	Sets the named value and returns the value stored.	setg(a,1,2,3)	Sets the named value a to: 1,2,3 and returns the values: 1,2,3
xget	Retrieves the named cross template value.	xget(a,b)	Returns a delimited string whose values are determined by the named cross template values a and b.
xset	Sets the named cross template value.	xset(a,sample,data)	Sets the named cross template value a to: sample,data
xsetg	Sets the named cross template value and returns the value stored.	xsetg(a,example)	Sets the named cross template value a to: example and returns the value: example

Markers

Function	Description	Example	Result
comma	Inserts a comma. Useful when the default delimiter is a comma.	comma()	Returns ,
empty	Inserts an empty string. Useful as a place holder.	empty()	Returns zero length string.
newline	Inserts a newline character.	newline()	Returns &$13;
space	Inserts a space character.	space()	Returns a single space.

String Functions

The values passed to the functions depend on the function. Usually, each function accepts one or more values. Sometimes the first value has special meaning to the function.

Function	Description	Example	Result
capitalize	The first letter of each string is made uppercase.	capitalize(hello there)	Hello there
cat	Returns a string value with the values concatonated and separated by a space character.	cat(Hello,there)	Hello there
date	Returns the system date according to the DATE:format syntax.	date(mm/dd/yyyy)	9/30/2024
dcat	Returns a string value with the values concatonated separated by the specified first character in the the list of values.	dcat(/,09,30,2024)	09/30/2024
dice	Returns a set of values of dice evaluations.	dice(2d4,2d4+10,hi)	8,13,0
fgdate	Returns the game date according to the FGDate:format syntax.	fgdate(mm/dd/yyyy)	Similar to date example. OR No Calendar Mod Loaded
lower	Each string expression is made all lower case.	lower(HELLO,THERE)	hello,there
post	Returns a list of values with the first parameter appended to each of the remaining values.	post(:,1,2,3)	1:,2:,3:
pre	Returns a list of values with the first parameter prepended to each of the remaining values.	pre(-,1,2,3)	-1,-2,-3
reverse	Returns a list of values in reverse order.	reverse(1,2,3)	3,2,1
rsort	Returns a list of reverse sorted values.	rsort(01,2,003)	003,2,01
sort	Returns a list of sorted values.	sort(hello,10,02,hi)	hello,hi,02,10
titlecase	Each string expression is made title case.	titlecase(hello there)	Hello There
uniq	Returns a list of unique values in sorted order.	uniq(1,1,2,3,3,3,4,4)	1,2,3,4
upper	Each string expression is made all upper case.	upper(hello,hi,bonjour)	HELLO,HI,BONJOUR

Forward to Part 2

[tjlee]

The following is included in the Story Template Enhanced (examples module).
You will need the extension enabled in order to use the new syntax.

Functional Equivalence

The following tables illustrate functional equivalence between the traditional CoreRPG-style syntax and the Function-style syntax.

Purpose	CoreRPG Extended Syntax	Function syntax
Dice Expression	[1d4+10]	dice(1d4+10)
Table Multiplier	[1d4+1x][Female Name]	mult_table(1d4+1x,Female Name) Mixed syntax: [1d4+1x]table(Female Name)
Table Callout	[a]	cat(table(a)) Assuming default delimiter is a comma, use cat() to concatenate the values with a space instead.
Column Referencing	#a|1#	select(1,get(a))
Custom Naming	[:Colors:eyes] <eyes> [:?Colors:teeth] <teeth>	setg(eyes,table(Colors)) get(eyes) set(teeth,table(Colors)) get(teeth)
Callout Internal Rolling	[:[Race] [Gender] Name:Bartender] <Race> <Gender> #<Race> <Gender> Name|3#	setg(Bartender,table(table(Race) table(Gender) Name)) get(Race) get(Gender) select(3,get(get(Race) get(Gender) Name))
Hidden rolls (using "?") and Cross Template Referencing	[:NPC:first] <first> [:?NPC:TavernKeep] <TavernKeep> [?NPC] {:?NPC:theruler}	setg(first,table(NPC)) get(first) set(TavernKeep,table(NPC)) get(TavernKeep) xset(theruler,table(NPC))
Date Calls with formatting	[Date:mm/dd/yyyy] [FGDate:mm/dd/yyyy]	date(mm/dd/yyyy) fgdate(mm/dd/yyyy) Better formatting (month and day with leading zeros): dcat(/,znum(2,date(mm),date(dd)),date(yyyy)) Results: 09/01/2024 intead of 9/1/2024
Cross Template Referencing	{theruler}	xget(theruler)
Story Template Enhanced extension only:
Simple Template Includes	[2d4+2u]!^Drink^!	mult_include(2d4+2u,Drink) Mixed syntax: [2d4+2u]include(Drink)

Function Documentation - Part 1
Function Documentation - Part 2

[tjlee]

After adding a bunch of code for the last release, this effort was all about tidying up the code and examples.

• Code: the extension got some rework and optimizations to bring the CoreRPG syntax execution and the Function-based syntax execution in proper alignment.
• Examples: I fixed a few typos and elaborated on some of the existing examples.

Other than that, nothing groundbreaking this time.

You should pick up the new versions next time you perform a live update.

Enjoy!

[tjlee]

Part 2
Back to Part 1
Functional Equivalence

Number Functions

Function	Description	Example	Result
avg	Returns the average of the numeric values. Non numeric values are ignored.	avg(1,2,3,hello)	2
count	Returns a count of values.	count(1,2,3)	3
max	Returns the largest of the numeric values or the value list if there are no numbers in the list.	max(1,2,Hello,5)	5
min	Returns the smallest of the numeric values or the value list if there are no numbers in the list.	min(10,02,-1)	-1
total	Returns the sum of the numeric values or zero if there are no numbers in the list.	total(1,2,3)	6

Formatting Functions

Function	Descrption	Example	Result
bold	Returns the values bolded.	bold(hello,there)	hello, there
bullets	Returns the values as a bullet list.	bullets(item 1,item2)	item 1 item 2
italic	Returns the values italicized.	italic(bonjour)	bonjour
lines	Returns the values separated by newline.	lines(line 1,line 2)	line 1 line 2
text	Returns only the text of a link or quoted text.	1 - text(get(StoredValue)) StoredValue might be a record link returned from a table. 2 - text("Hello")	1 - Returns the text label associated with the StoredValue. 2 - Returns Hello
underline	Returns the values underlined.	underline(hi)	hi
znum	Returns the numeric values left padded with zeros. The default is 2 places. When more than one value is supplied, the first numeric value specifies the amount of padding.	znum(4,1,2,3)	0001,0002,0003

Transformation Functions

Function	Description	Example	Result
head	Returns the first n values based on the first value.	head(2,1,2,3)	1,2
index	Returns the index of the remaining arguments starting with base value 1 of the first argnument that matches the first, otherwise zero.	1 - index(a,c,b,a) 2 - index(a,b,c,d)	1 - Returns 3 1 - Returns 0
map	Returns the mapped value that matches the first value. A mapping in the list of parameters uses = or : as the separator. If there's no match, the last value is returned as a defualt value.	1 - map(a,a=b,b=c,c=d) 2 - map(v,key:value,v:second) 3 - map(a,b:c,d=e,f:g,a) 4 - map(b,1=2,3=4,5)	1 - Returns b 2 - Returns second 3 - Returns a 4 - Returns 5
pick	Returns a randomly selected value from the values.	pick(1,2,3,4,5,6)	One of: 1,2,3,4,5,6
select	Returns a specificly selected value from the values based on the first value.	select(3,a,b,c,d,e)	c
tail	Returns the last n values based on the first value.	tail(3,A,b,C,d,E,f,G)	E,f,G

Table and Template Functions

Function	Description	Example*	Result
import	Imports a simple template.	import(dateFormat)	09/30/2024
include	Synonymous with import. It's useful to use this to indicate that we're including story template code that has been separated into a separate story template to keep the main story template less cluttered.	include(Drink)	The contents of the simple named template Drink is included and evaluated.
lookup	Returns the specified row and column from the specified table.	lookup(Herbs,5,2)	Returns Oregano
mult_import	Imports a simple template with the first value specifying a multiplier.	mult_import(3ud,Drink)	Something like: Bashful Porter,Cobbler's Ale,Yellow Camel Stout
mult_table	Makes a table callout with the first value specifying a multiplier.	mult_table(3ud,Drinks)	Equivalent to: [3ud][Drinks]
table	Makes a table callout.	table(Drinks)	Something like: Sneezy Thatcher's,Lager

Note: * the "3ud" parameter specifies a multiple of up to 3 unique values using the system delimiter (default is comma) to separate the multiples in the output. See the delim() function above to set the delimiter to some other value. When 'd' is not specified (as in '3u'), the output delimiter defaults to a space instead of the delimiter specified by the delim() function to better support interoperability with the traditional CoreRPG story template syntax.

Back to Part 1

[tjlee]

Version 0.1.7 - Released 2024.11.10

Added the following functions:

Control Functions

• default
• ifvalue

Markers

• comma
• empty
• newline
• space

Formatting Functions

• text

Transformation Functions

• index
• map

Table and Template Functions

• include
• lookup

Split the Function documentation into two parts:

• Part 1
• Part 2

Previous documentation that illustrates Functional Equivalence between the CoreRPG traditional story template syntax with the new Function-based syntax.