Stream which performs variable-value substitution on-the-fly. More...

#include <TemplateStream.h>

Inheritance diagram for TemplateStream:

Collaboration diagram for TemplateStream:

Public Types
using	Variables = HashMap< String, String >
	Maps variable names to values. More...

using	GetValueDelegate = Delegate< String(const char *name)>
	Callback type to return calculated or externally stored values. More...

Public Member Functions
	TemplateStream (IDataSourceStream *stream, bool owned=true)
	Create a template stream. More...

	~TemplateStream ()

StreamType	getStreamType () const override
	Get the stream type. More...

uint16_t	readMemoryBlock (char *data, int bufSize) override
	Read a block of memory. More...

int	seekFrom (int offset, SeekOrigin origin) override
	Change position in stream. More...

bool	isFinished () override
	Check if all data has been read. More...

void	setVar (const String &name, const String &value)
	Set value of a variable in the template file. More...

void	setVars (const Variables &vars)
	Set multiple variables in the template file. More...

Variables &	variables ()
	Get the template variables. More...

String	getName () const override
	Returns name of the resource. More...

void	onGetValue (GetValueDelegate callback)
	Set a callback to obtain variable values. More...

void	enableOutput (bool enable)
	During processing applications may suppress output of certain sections by calling this method from within the getValue callback. More...

bool	isOutputEnabled () const
	Determine if stream output is active. More...

void	setDoubleBraces (bool enable)
	Use two braces {{X}} to mark tags. More...

virtual String	evaluate (char *&expr)
	Evaluate a template expression. More...

String	eval (String expr)
	Evaluate an expression in-situ. More...

virtual String	getValue (const char *name)
	Fetch a templated value. More...

Public Member Functions inherited from IDataSourceStream
virtual bool	isValid () const
	Determine if the stream object contains valid data. More...

size_t	readBytes (char *buffer, size_t length) override
	Read chars from stream into buffer. More...

int	read () override
	Read one character and moves the stream pointer. More...

int	peek () override
	Read a character without advancing the stream pointer. More...

virtual bool	seek (int len)
	Move read cursor. More...

virtual int	available ()
	Return the total length of the stream. More...

size_t	write (uint8_t charToWrite) override
	From Stream class: We don't write using this stream. More...

void	flush () override

virtual String	id () const
	Returns unique id of the resource. More...

virtual MimeType	getMimeType () const
	Get MIME type for stream content. More...

String	readString (size_t maxLen) override
	Overrides Stream method for more efficient reading. More...

virtual bool	moveString (String &s)
	Memory-based streams may be able to move content into a String. More...

virtual size_t	readBytes (char *buffer, size_t length)
	Read chars from stream into buffer. More...

size_t	readBytes (uint8_t *buffer, size_t length)

Public Member Functions inherited from Stream
	Stream ()

void	setTimeout (unsigned long timeout)
	Set maximum milliseconds to wait for stream data, default is 1 second. More...

bool	find (const char *target)
	Read data from the stream until the target string is found. More...

bool	find (const char *target, size_t length)
	Read data from the stream until the target string of given length is found. More...

bool	findUntil (const char target, const char terminator)
	As `find()` but search ends if the terminator string is found. More...

bool	findUntil (const char target, size_t targetLen, const char terminate, size_t termLen)
	As `findUntil(const char, const char)` but search ends if the terminate string is found. More...

long	parseInt ()
	Returns the first valid (long) integer value from the current position. More...

float	parseFloat ()
	float version of parseInt More...

size_t	readBytes (uint8_t *buffer, size_t length)

size_t	readBytesUntil (char terminator, char *buffer, size_t length)
	As `readBytes()` with terminator character. More...

String	readStringUntil (char terminator)

virtual int	indexOf (char c)

Public Member Functions inherited from Print
virtual	~Print ()

int	getWriteError ()
	Gets last error. More...

void	clearWriteError ()
	Clears the last write error. More...

size_t	write (const char *str)
	Writes a c-string to output stream. More...

virtual size_t	write (const uint8_t *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

size_t	write (const char *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

size_t	print (char c)
	Prints a single character to output stream. More...

size_t	print (const char str[])
	Prints a c-string to output stream. More...

size_t	print (double num, int digits=2)
	Print a floating-point number to output stream. More...

template<typename T >
std::enable_if< has_printTo< T >::value, size_t >::type	print (const T &obj)
	Prints a Printable object to output stream. More...

size_t	print (const String &s)
	Prints a String to output stream. More...

template<typename E >
std::enable_if< std::is_enum< E >::value &&!std::is_convertible< E, int >::value, size_t >::type	print (E value)
	enums can be printed as strings provided they have a `toString(E)` implementation. More...

size_t	println ()
	Prints a newline to output stream. More...

template<typename... Args>
size_t	println (const Args &... args)
	Print value plus newline to output stream. More...

size_t	printf (const char *fmt,...)
	Prints a formatted c-string to output stream. More...

size_t	print (unsigned long num, uint8_t base=DEC)

template<typename... Args>
size_t	print (unsigned long num, Args... args)

template<typename... Args>
size_t	print (const unsigned long long &num, Args... args)

size_t	print (long num, uint8_t base=DEC)

template<typename... Args>
size_t	print (long num, Args... args)

template<typename... Args>
size_t	print (const long long &num, Args... args)

template<typename... Args>
size_t	print (unsigned int num, Args... args)

template<typename... Args>
size_t	print (unsigned char num, Args... args)

template<typename... Args>
size_t	print (int num, Args... args)

Additional Inherited Members
Protected Member Functions inherited from Stream
int	timedRead ()

int	timedPeek ()

int	peekNextDigit ()
	returns the next numeric digit in the stream or -1 if timeout More...

long	parseInt (char skipChar)
	Like regular `parseInt()` but the given skipChar is ignored. More...

float	parseFloat (char skipChar)
	Like `parseInt(skipChar)` for float. More...

Protected Member Functions inherited from Print
void	setWriteError (int err=1)

Protected Attributes inherited from Stream
uint16_t	receiveTimeout = 1000
	number of milliseconds to wait for the next char before aborting timed read More...

Detailed Description

Stream which performs variable-value substitution on-the-fly.

Template uses {varname} style markers which are replaced as the stream is read.

Note: There must be no whitespace after the opening brace. For example, { varname } will be emitted as-is without modification.

This allows inclusion of CSS fragments such as td { padding: 0 10px; } in HTML.

If necessary, use double-braces {{varname}} in templates and enable by calling setDoubleBraces(true).

Invalid tags, such as {"abc"} will be ignored, so JSON templates do not require special treatment.

Member Typedef Documentation

◆ GetValueDelegate

using TemplateStream::GetValueDelegate = Delegate<String(const char* name)>

Callback type to return calculated or externally stored values.

◆ Variables

using TemplateStream::Variables = HashMap<String, String>

Maps variable names to values.

Constructor & Destructor Documentation

◆ TemplateStream()

TemplateStream::TemplateStream	(	IDataSourceStream *	stream,
		bool	owned = `true`
	)

inline

Create a template stream.

Parameters

stream	source of template data
owned	If true (default) then stream will be destroyed when complete

◆ ~TemplateStream()

TemplateStream::~TemplateStream ( )

inline

Member Function Documentation

◆ enableOutput()

void TemplateStream::enableOutput ( bool enable )

inline

During processing applications may suppress output of certain sections by calling this method from within the getValue callback.

◆ eval()

String TemplateStream::eval ( String expr )

inline

Evaluate an expression in-situ.

Parameters

expr	Expression to evaluate

Return values

String

◆ evaluate()

virtual String TemplateStream::evaluate ( char *& expr )

virtual

Evaluate a template expression.

Parameters

expr	IN: First character after the opening brace(s) OUT: First character after the closing brace(s)

Return values

String Called internally and an opening brace ("{" or "{{") has been found. Default behaviour is to locate the closing brace(s) and interpret the bounded text as a variable name, which is passed to getValue.

This method is overridden by SectionTemplate to support more complex expressions.

Reimplemented in SectionTemplate.

◆ getName()

String TemplateStream::getName ( ) const

inlineoverridevirtual

Returns name of the resource.

Return values

String

Note: Commonly used to obtain name of file

Reimplemented from IDataSourceStream.

◆ getStreamType()

StreamType TemplateStream::getStreamType ( ) const

inlineoverridevirtual

Get the stream type.

Return values

StreamType The stream type.

Reimplemented from IDataSourceStream.

◆ getValue()

virtual String TemplateStream::getValue ( const char * name )

virtual

Fetch a templated value.

Parameters

name	The variable name

Return values

String value, invalid to emit tag unprocessed

Reimplemented in SectionTemplate, IFS::HtmlDirectoryTemplate, and IFS::DirectoryTemplate.

◆ isFinished()

bool TemplateStream::isFinished ( )

inlineoverridevirtual

Check if all data has been read.

Return values

bool	True on success.

Implements IDataSourceStream.

◆ isOutputEnabled()

bool TemplateStream::isOutputEnabled ( ) const

inline

Determine if stream output is active.

Used by SectionTemplate class when processing conditional tags.

◆ onGetValue()

void TemplateStream::onGetValue ( GetValueDelegate callback )

inline

Set a callback to obtain variable values.

Parameters

callback Invoked only if variable name not found in map

◆ readMemoryBlock()

uint16_t TemplateStream::readMemoryBlock	(	char *	data,
		int	bufSize
	)

overridevirtual

Read a block of memory.

Parameters

data	Pointer to the data to be read
bufSize	Quantity of chars to read

Return values

uint16_t Quantity of chars read

Todo:: Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Implements IDataSourceStream.

◆ seekFrom()

int TemplateStream::seekFrom	(	int	offset,
		SeekOrigin	origin
	)

overridevirtual

Change position in stream.

Parameters

offset
origin

Return values

New	position, < 0 on error

Note: This method is implemented by streams which support random seeking, such as files and memory streams.

Reimplemented from IDataSourceStream.

◆ setDoubleBraces()

void TemplateStream::setDoubleBraces ( bool enable )

inline

Use two braces {{X}} to mark tags.

Parameters

enable true: use two braces, false (default): single brace only

◆ setVar()

void TemplateStream::setVar	(	const String &	name,
		const String &	value
	)

inline

Set value of a variable in the template file.

Parameters

name	Name of variable
value	Value to assign to the variable

Note: Sets and existing variable or adds a new variable if variable does not already exist

◆ setVars()

void TemplateStream::setVars ( const Variables & vars )

inline

Set multiple variables in the template file.

Parameters

vars	Template Variables

◆ variables()

Variables& TemplateStream::variables ( )

inline

Get the template variables.

Return values

TemplateVariables Reference to the template variables

The documentation for this class was generated from the following file:

TemplateStream.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ GetValueDelegate

◆ Variables

Constructor & Destructor Documentation

◆ TemplateStream()

◆ ~TemplateStream()

Member Function Documentation

◆ enableOutput()

◆ eval()

◆ evaluate()

◆ getName()

◆ getStreamType()

◆ getValue()

◆ isFinished()

◆ isOutputEnabled()

◆ onGetValue()

◆ readMemoryBlock()

◆ seekFrom()

◆ setDoubleBraces()

◆ setVar()

◆ setVars()

◆ variables()