Format Specifiers on Template Tags - v0.9.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.9.0

This release introduces the ability to include a printf format-specifier in your Text Tags.

Full Changelog: v0.8.0...v0.9.0

Quick Example

By default, all Text Tags are rendered with the printf %s format specifier:

default_format.tpl

% myint=123
<% ${myint} %>

process the template

$ bash-tpl default_format.tpl

myint=123
printf "%s\n" "${myint}"

Now you can include a custom format specifier in your tags:

integer_format.tpl

% myint=123
<%| %d | ${myint} %>

process the template

$ bash-tpl integer_format.tpl

myint=123
printf "%d\n" "${myint}"

To learn about format specifiers, including customizing the delimiters, see the README

Posix-Compatible Text Escaping [ Breaking Change ] - v0.8.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.8.0

Previously, Bash-TPL used bash's printf -q "string" technique to escape text strings. I was not aware that the $'' string-encoding is not posix and is not supported on many shells.

User @0xEAB encountered a bug when trying to run scripts that contained escaped TABS within Dash:

• Generated dollar-quote escape sequences are Bash-specific (in practice) #25
  

After some research, I learned that the posix-compatible way to print strings with escape sequences is %b.

Bash-TPL now utilizes a new encoding technique and uses %b to print text line strings.

Full Changelog: v0.7.1...v0.8.0

Breaking Changes

Technically this is a breaking change as Bash-TPL now generates vastly different looking printf statements than previous versions.

Example of Changes

Below is an example of encoding outputs before / after this change:

tabs.tpl

one	two	three

output from v0.7.1

printf "%s\n" $'one\ttwo\tthree'

output from v0.8.0

printf "%b\n" 'one\ttwo\tthree'

No Negative Impact Expected

In practice, I don't expect there to be any negative impact from the change, but please do create an issue if something doesn't work for you.

Exit Code 0 On Success - v0.7.1

Small bugfix to ensure that script exits with code 0 on success.

I think I fell victim to forgetting that BATS run helper always succeeds and requires caller to explicitly check the result in $status.

This check has now been added as part of the tpl.bats.bats tests.

Core Logic Re-Write; A Few Breaking Changes - v0.7.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.7.0

This is mostly an internal update, working to simplify the indentation-tracking logic, while also making it more accurate.

The result is code that is easier to understand and also hopefully easier to enhance in the future.

It does also have the benefit of reducing the total script size by about 60 lines.

Full Changelog: v0.6.0...v0.7.0

Breaking Changes

Although targeted as an internal update, it does introduce several breaking changes:

Printf Indentation

Given the following input file:

test.tpl

one
	two
		three
	four
five

The previous versions would generate the following script:

printf "%s\n" one
	printf "%s\n" $'\ttwo'
		printf "%s\n" $'\t\tthree'
	printf "%s\n" $'\tfour'
printf "%s\n" five

Having the indentation of the printf match the indentation of the text seemed like a useful feature that would provide added context to the user when reviewing/debugging the script.

User feedback suggested that the opposite was true; That the added indentation made reviewing the script more difficult.

So this version makes the indentation of the printf statements more predictable.

printf "%s\n" one
printf "%s\n" $'\ttwo'
printf "%s\n" $'\t\tthree'
printf "%s\n" $'\tfour'
printf "%s\n" five

Missing Stmt-Block Close

In this new version, and un-closed stmt-block will generate an error:

test.tpl

%
    echo "Hello, world"

compile

$ bash-tpl test.tpl

Error: Missing stmt-block close ('%')

Un-Balanced Stmt-Block Close

In this new version, an error is generated if the stmt-block close does not have the same indentation as the stmt-block open:

test.tpl

    %
        echo "Hello, world"
  %

compile

$ bash-tpl test.tpl

Error: stmt-block close indentation does not match open

Un-Indented Stmt-Block Content

Regarding the following template, which contains stmt-block lines which are not indented beyond the stmt-block start:

test.tpl

  %
   #1
  #2
 #3
#4
  %

Since bash-tpl encourages you to utilize indentation, not-doing so results in "undefined" behavior.

Thats still true in spirit, but this release tries to make the resulting output a bit more predictable.

That is, it tries to make the output match the input, by ignoring the stmt-block indentation and disabling indentation-correction:

output

   #1
  #2
 #3
#4

Empty-Line In == Empty Line Out

This is actually more of a bug fix.

Previously, some scenarios could result in leading whitespace on a line that was indented to be empty.

This version tries harder to ensure that an empty line in your input templates yields an appropriately empty line in the output.

Feature: Text Lines Within Statement Blocks - v0.6.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.6.0

feat: Text lines within Statement Blocks

This release introduces the ability to easily insert text lines within statement block bodies, without having close/re-open the blocks.

previously.tpl

%
    # ...
    if (condition); then
%
condition text ...
%
    else
%
else text ...
%
    fi
    # ...
%

now.tpl

%
    # ...
    if (condition); then
        % condition text ...
    else
        % else text ...
    fi
    # ...
%

NOTES:

• The indentation of the printed text lines will always match that of the statement block start tag
• This is to encourage you to format your text lines within the context of your script
• All whitespce after the text line tag ('% ') will be printed as-as

Better-Formatted Scripts

In addition to being less-verbose, the generated scrips are also formatted better:

previously.sh

# ...
if (condition); then
printf "%s\n" condition\ text\ ...
else
printf "%s\n" else\ text\ ...
fi
# ...

now.sh

# ...
if (condition); then
    printf "%s\n" condition\ text\ ...
else
    printf "%s\n" else\ text\ ...
fi
# ...

bug: Indentation not tacked if first line of statement block not indented

There's been a long-standing bug where indentation tracking within statement blocks is not accurate if the first line of the block is not indented.

Essentially, bash-tpl was using the first line as the basis indentation tracking for the block, which broke down if that first line was not actually indented.

Now, the code keep searching for the first indented line, and uses that line as the basis.

This should provide more consistent behavior to otherwise well-indented scripts in the case where the first line of the block happens to not be indented.

Breaking Change

Due to the possible changes in leading whitespace in template output, this is considered a breaking change.

Full ChangeLog

Full Changelog: v0.5.0...v0.6.0

Fixed: Else Indentation; Dropping Unindented Directives - v0.5.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.5.0

chore: GitHub workflow to run tests against various Bash versions

Added a github worfkflow to execute the bats tests against multiple versions of Bash

I even wrote a blog post about it.

chore: Apply newly reported shellcheck recommendations

I updated shellcheck at some point after my last release and it started reporting a new error:

• SC2184 - Quote arguments to unset so they're not glob expanded.

Although this SC has been around for a long time, I'm certain that seeing it in my shellcheck report is new.

fix: Track indentation after all statement lines, not just between logical "open"/"close"

I was writing a template with an if/else/fi block and realized that bash-tpl wasn't correctly tracking indentation on the else section.

% # one
	1: This text should be indent-tracked
% # two
	2: This text should be indent-tracked
% # three
	3: This text should be indent-tracked

Previously, section 2 was not being correctly tracked.

I was treating the first encountered statement line as an maybe-open and any subsequent line as a cose, when in fact they should always be seen as a maybe-open and a maybe-close

Breaking Change

Due to the possible changes in leading whitespace in template output, this is considered a breaking change.

fix: Stop ignoring unindented directives in text blocks

There was a real bug that was dropping directive statements when were part of a text block, but did not exist at the same (or deeper) indentation of the text block.

I only discovered this by accident while writing a test for the indentation fix above.

Full ChangeLog

Full Changelog: v0.4.0...v0.5.0

Support for Older Bash Versions (3.2, 4.4, etc) - v0.4.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.4.0

• Adds support for Bash versions 3.2+

Thanks to @flaix for pointing out that I inadvertently broke support for older bash versions by using constructs that were only available in newer versions.

I re-worked the code the also ran the existing BATS tests against multiple Bash versions: 3.2, 4.4, 5.0, and 5.1

Commit Log (since previous release)

ef3b2ab feat: Re-worked to support Bash v3.2 and v4.4 (#7)
232a28d docs: Firm up README
6261feb docs: Feature callouts, Similar Tools

Full Changelog: v0.3.0...v0.4.0

STDIN, Pipes, and Heredocs; Template tests - v0.3.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.3.0

• Adds support for reading from stdin, including pipes, herestrings and heredocs.

• Updates tests with ability to render a template file and compare it to a shell script file.

Commit Log (since previous release)

fa57897 Docs for stdin, usage to top of file
37dc9da main, -, --, |, tpl tests !
867616a Fixes s/script/statement/ in TOC; Bumps version to v0.3.0-SNAPSHOT

Regexes and Readmes - v0.2.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

Release - v0.2.0

Adds tests to better-validate the regexes and tag parsers - Fixes discovered bugs accordingly :)

Greatly fleshes out the README

Adding bash-tpl into your project

The bash-tpl script has an embedded MIT SPDX header, as well as a license header, and should be safe for you to extract and add to your own projects for easy template generation.

Commit Log (since previous release)

2ddfd67 - Fix tag regexes; s/script/statement/ tag|line
71bbbf5 - Fleshes out README
37f792b - Fleshes out README
7271534 - Flesh out Text Tag docs a bit; typos (delimIter)
9c17288 - Reduces subshells using globals or var refs
c7177b8 - Adds --reset-delims; Lets .INCLUDE pass args

First Release - v0.1.0

Bash-TPL

A Smart, Lightweight shell script templating engine, written in Bash.

First Release - v0.1.0

I believe Bash-TPL is ready for its first release!

• Casual usage shows it to be working as intended
• Some BATS tests have been written and all tests pass
• Usage (bash-tpl --help) command has been added
• Version (bash-tpl --version) command has been added
• Minimally useful README
• Need to create a release in order to create a brew tap :)