#include <sub.h>

Public Member Functions
	~sub_context_ty ()
	sub_context_ty (const char *file=0, int line=0)
void	clear ()
void	var_set_format (const char name, const char fmt,...)
void	var_set_vformat (const char name, const char fmt, va_list args) ATTR_VPRINTF(3)
void	var_set_string (const char name, string_ty value)
void	var_set_string (const char *name, const nstring &value)
void	var_set_charstar (const char name, const char value)
void	var_set_long (const char *name, long value)
void	var_set_time (const char *name, time_t value)
void	var_optional (const char *name)
void	var_append_if_unused (const char *name)
void	var_override (const char *name)
void	var_resubstitute (const char *name)
void	errno_setx (int value)
string_ty *	substitute (change::pointer cp, string_ty *the_command)
string_ty *	substitute_p (project pp, string_ty the_command)
string_ty *	subst_intl (const char *substme)
void	subst_intl_project (struct project *pp)
void	subst_intl_change (change::pointer cp)
void	error_intl (const char *message)
void	fatal_intl (const char *message)
void	verbose_intl (const char *message)
void	error_set (const char *message)
project *	project_get ()
change::pointer	change_get ()
int	errno_sequester_get () const
wstring	subst (const wstring &msg)
wstring	subst_intl_wide (const char *msg)
Private Types
enum	getc_type { getc_type_control, getc_type_data }
Private Member Functions
void	diversion_close ()
wchar_t	getc_meta (getc_type &c)
void	getc_meta_undo (wchar_t c)
wchar_t	getch (getc_type &tr)
wchar_t	dollar ()
void	execute (const wstring_list &arg)
	sub_context_ty (const sub_context_ty &)
sub_context_ty &	operator= (const sub_context_ty &)
Private Attributes
sub_diversion_stack	diversion_stack
sub_functor_list	var_list
change::pointer	cp
project *	pp
const char *	suberr
int	errno_sequester
const char *	file_name
int	line_number

Detailed Description

The sub_context_ty class represents the context (variables &co) for a substitution.

Definition at line 39 of file sub.h.

Member Enumeration Documentation

enum sub_context_ty::getc_type [private]

Enumerator:

getc_type_control
getc_type_data

Definition at line 367 of file sub.h.

Constructor & Destructor Documentation

sub_context_ty::~sub_context_ty ( )

The destructor.

sub_context_ty::sub_context_ty	(	const char *	file = `0`,
		int	line = `0`
	)

The default constructor.

sub_context_ty::sub_context_ty ( const sub_context_ty & ) [private]

The copy constructor. Do not use.

Member Function Documentation

change::pointer sub_context_ty::change_get ( )

The change_get method is used to obtain a pointer to the change for this context.

Returns:: Pointer to the change, or NULL if no change is relevant at this point.

Note:: This method is only to be used by the built-in functions to obtain their context.

void sub_context_ty::clear ( )

The clear method is used to clear all of the substitution variables. Not usually needed manually, as this is done automatically at the end of every substitute().

void sub_context_ty::diversion_close ( ) [private]

The diversion_close method is used to release a diversion when it has been exhausted.

wchar_t sub_context_ty::dollar ( ) [private]

The dollar method is used to perform dollar ($) substitutions. On entry, the $ is expected to have been consumed.

The substitution is usually achieved as a side-effect, by using the diversion_stack.

Returns:: wchar_t a character to deliver as output, or a wide NUL charcater if none.

int sub_context_ty::errno_sequester_get ( ) const

The errno_sequester_get method is used to obtain the sequestered errno value. This method shall only be called by sub_errno().

void sub_context_ty::errno_setx ( int value )

The errno_setx method is used to set the $ERRNO value in the given substitition context.

Note:: There is no method to directly read errno and set it, because there is at least one malloc() library call and possibly several others before you get arround to calling this function. You *must* instead copy the value of errno immediatly after the offending system call, and before doing inything towards preparing the error message.

void sub_context_ty::error_intl ( const char * message )

The error_intl method is used to internationalize an error message (vis the gettext function) then substitute it, and then print it.

Parameters:

message The error message to be processed.

void sub_context_ty::error_set ( const char * message )

The error_set method is used to mark a substitution context as erroneous. This occurs when there is something wrong with the message being substituted.

Parameters:

message The error message describing what is wrong with the substitution message currently being processed.

Note:: This method is only to be used by the built-in functions as feedback when something goes wrong.

void sub_context_ty::execute ( const wstring_list & arg ) [private]

The execute method is used to perform a substitution once all the arguments are known. The firsdt (0'th) argument is the name of the substitution to perform.

void sub_context_ty::fatal_intl ( const char * message )

The fatal_intl method is used to internationalize an error message (vis the gettext function) then substitute it, then print it, and then exit with exist status 1.

Parameters:

message The error message to be processed.

Note:: This method does not return.

wchar_t sub_context_ty::getc_meta ( getc_type & c ) [private]

The getc_meta method is used to get a character from the current input string. When the current string is exhaused, the previous string is resumed.

Returns:: the chacater, or NUL to indicate end of input

void sub_context_ty::getc_meta_undo ( wchar_t c ) [private]

The getc_meta_undo function is used to give back a character output by getc_meta.

Parameters:

c	character being given back

Note:: Only push back what was read.

wchar_t sub_context_ty::getch ( getc_type & tr ) [private]

The getch method is used to get the next character of input from the diversion stack and characterize it appropriately.

It calls the dollar() method at the appropriate times.

sub_context_ty& sub_context_ty::operator= ( const sub_context_ty & ) [private]

The assignment operator. Do not use.

project* sub_context_ty::project_get ( )

The project_get method is used to obtain a pointer to the project for this context.

Returns:: Pointer to the project, or NULL if no project is relevant at this point.

Note:: This method is only to be used by the built-in functions to obtain their context.

wstring sub_context_ty::subst ( const wstring & msg )

The subst method is used to substitute the given string.

Parameters:

msg	The string to be substituted into.

Returns:: The string result of the substitution.

string_ty* sub_context_ty::subst_intl ( const char * substme )

The sub_intl method is used to substitute into the given string.

Parameters:

substme The string to be sustituted into. See aesub(5) for valid substitutions.

void sub_context_ty::subst_intl_change ( change::pointer cp )

The subst_intl_change method is used to set the change for the substitution context.

Parameters:

cp	The change for context.

void sub_context_ty::subst_intl_project ( struct project * pp )

The subst_intl_project method is used to set the project for the substitution context.

Parameters:

pp	The project for context.

wstring sub_context_ty::subst_intl_wide ( const char * msg )

The subst_inst_wide method is used to substitute the given string. The message will be passed through gettext before being substituted.

Parameters:

msg	The string to be substituted into.

Returns:: The string result of the substitution.

string_ty* sub_context_ty::substitute	(	change::pointer	cp,
		string_ty *	the_command
	)

The substitute method is used to perform substitutions on strings. Usually command strings, but not always.

The format of substitutions, and the commonly available substitutions, are described in aesub(5).

Parameters:

cp	The change to provide context for the substitution.
the_command	The string to be sustituted into.

string_ty* sub_context_ty::substitute_p	(	project *	pp,
		string_ty *	the_command
	)

The substitute_p method is used to substitute into the given string.

Parameters:

pp	The project to provide context for the substitution.
the_command	The string to be sustituted into. See aesub(5) for valid substitutions.

void sub_context_ty::var_append_if_unused ( const char * name )

The var_append_if_unused method is used to mark a substitution variable as one which is appended if it is not used anywhere in the substituition.

Parameters:

name	The name of the substitution variable.

void sub_context_ty::var_optional ( const char * name )

The var_optional method is used to mark a substitution variable as optional, meaning that is doesn't have to be used.

Parameters:

name	The name of the optional variable.

void sub_context_ty::var_override ( const char * name )

The var_override method is used to mark a substitution variable as one which is to override a built-in substitution.

Parameters:

name	The name of the substitution variable.

Note:: Use sparingly.

void sub_context_ty::var_resubstitute ( const char * name )

The var_resubstitute method is used to mark a substitution variable as one which is to have its substitution value re-interpreted for more substitutions. The default is not to do this.

Parameters:

name	The name of the substitution variable.

Note:: Use sparingly.

void sub_context_ty::var_set_charstar	(	const char *	name,
		const char *	value
	)

The var_set_charstar method is used to set a substitution variable.

Parameters:

name	The name of the variable to be set.
value	The value of the variable to be set.

void sub_context_ty::var_set_format	(	const char *	name,
		const char *	fmt,
			...
	)

The var_set_format method is used to set the value of a substitution variable. These variables are command specific, as opposed to the functions which are always present. The user documentation does NOT make this distinction by using the names "variable" and "function", they are always referred to as "substitutions".

Parameters:

name	The name of the variable to be set.
fmt	The format string for the value (see printf(3) fdor more information) and the format parameters follow in the succeeding arguments.

void sub_context_ty::var_set_long	(	const char *	name,
		long	value
	)

The var_set_long method is used to set a substitution variable.

Parameters:

name	The name of the variable to be set.
value	The value of the variable to be set.

void sub_context_ty::var_set_string	(	const char *	name,
		string_ty *	value
	)

The var_set_string method is used to set a substitution variable.

Parameters:

name	The name of the variable to be set.
value	The value of the variable to be set.

void sub_context_ty::var_set_string	(	const char *	name,
		const nstring &	value
	)

The var_set_string method is used to set a substitution variable.

Parameters:

name	The name of the variable to be set.
value	The value of the variable to be set.

void sub_context_ty::var_set_time	(	const char *	name,
		time_t	value
	)

The var_set_time method is used to set a substitution variable.

Parameters:

name	The name of the variable to be set.
value	The value of the variable to be set.

void sub_context_ty::var_set_vformat	(	const char *	name,
		const char *	fmt,
		va_list	args
	)

The var_set_vformat method is used to set a substitution variable with a formatted value.

Parameters:

name	The name of the variable to be set.
fmt	The format string for the value (see vprintf(3) for more information).
args	The format parameters.

void sub_context_ty::verbose_intl ( const char * message )

The verbose_intl method is used to internationalize an error message (vis the gettext function) then substitute it, and then print it. If the verbose option is not in effect, nothing will be printed.

Parameters:

message The error message to be processed.