Class to match formal and supplied arguments. More...

#include <ArgMatcher.hpp>

Inheritance diagram for CXXR::ArgMatcher:

Collaboration diagram for CXXR::ArgMatcher:

Public Member Functions
	ArgMatcher (const PairList *formals)
	Constructor.
const PairList *	formalArgs () const
	Formal arguments.
bool	has3Dots () const
	Do the formals include '...'?
void	match (Environment target_env, const ArgList supplied) const
	Match formal and supplied arguments.
size_t	numFormals () const
	Number of formal arguments.
void	propagateFormalBindings (const Environment fromenv, Environment toenv) const
	Copy formal bindings from one Environment to another.
void	stripFormals (Frame *input_frame) const
	Strip formal argument bindings from a Frame.
void	visitReferents (const_visitor *v) const
	Conduct a visitor to the nodes referred to by this one.
Public Member Functions inherited from CXXR::GCNode
void	expose () const
	Record that construction of a node is complete.
bool	isExposed () const
	Has this node been exposed to garbage collection?
Public Member Functions inherited from CXXR::HeterogeneousListBase::Link
	Link ()
	Default constructor.
	Link (HeterogeneousListBase *list)
	Appending constructor.
void	freeLink ()
	Detach Link from any list.

Static Public Member Functions
static void	enableWarnOnPartialMatch (bool on)
	Enable/disable warning if tag partially matched.
static ArgMatcher *	make (Symbol fml1, Symbol fml2=0, Symbol fml3=0, Symbol fml4=0, Symbol fml5=0, Symbol fml6=0)
	Create ArgMatcher with specified formal argument names.
static bool	warnOnPartialMatch ()
	Give warning if tag partially matched?
Static Public Member Functions inherited from CXXR::GCNode
static void *	operator new (size_t bytes)
	Allocate memory.
static void *	operator new (size_t, void *where)
	Placement new for GCNode.
static void	operator delete (void *p, size_t bytes)
	Deallocate memory.
static bool	check ()
	Integrity check.
template<class T >
static T *	expose (T *node)
	Record that construction of a node is complete.
static void	gc ()
	Initiate a garbage collection.
static void	gclite ()
	Lightweight garbage collection.
static void	maybeCheckExposed (const GCNode *node)
	Subject to configuration, check that a GCNode is exposed.
static size_t	numNodes ()
	Number of GCNode objects in existence.

Protected Member Functions
void	detachReferents ()
	Null out all references from this node to other nodes.
Protected Member Functions inherited from CXXR::GCNode
virtual	~GCNode ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

Detailed Description

Class to match formal and supplied arguments.

This class encapsulates a list of formal arguments, each possibly with a default binding, and provides (via match()) facilities to match the formal arguments to a list of supplied arguments and place the resulting bindings within a specified Frame.

The class also provides other services relating to the formal arguments and their default values.

Constructor & Destructor Documentation

ArgMatcher::ArgMatcher ( const PairList * formals )

explicit

Constructor.

Parameters:

formals PairList of formal arguments, possibly empty. The elements of this list must have distinct Symbol objects as their tags. At most one element may have '...' as its tag.

Member Function Documentation

void ArgMatcher::detachReferents ( )

protectedvirtual

Null out all references from this node to other nodes.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object. This function changes all GCEdges within this object to encapsulate a null pointer. It is used during the sweep phase of a mark-sweep garbage collection to break up unreachable subgraphs, and in particular to remove reference loops from them. After the application of this method, the GCNode should be regarded as a 'zombie', kept in existence only so other nodes can detach their references to it cleanly (using decRefCount()).

Note:: If this method is reimplemented in a derived class, the reimplemented version must remember to invoke detachReferents() for the immediate base class of the derived class, to ensure that all referents of the object get detached.

Reimplemented from CXXR::GCNode.

static void CXXR::ArgMatcher::enableWarnOnPartialMatch ( bool on )

inlinestatic

Enable/disable warning if tag partially matched.

Parameters:

on	true iff the class is to be configured to raise a warning if a supplied argument is matched to a formal argument by virtue of partial matching on the tag. The default is not to raise such warnings.

const PairList* CXXR::ArgMatcher::formalArgs ( ) const

inline

Formal arguments.

Returns:: Pointer to the formal argument list of this ArgMatcher object.

bool CXXR::ArgMatcher::has3Dots ( ) const

inline

Do the formals include '...'?

Returns:: true iff the formals list includes '...'.

ArgMatcher * ArgMatcher::make	(	Symbol *	fml1,
		Symbol *	fml2 = `0`,
		Symbol *	fml3 = `0`,
		Symbol *	fml4 = `0`,
		Symbol *	fml5 = `0`,
		Symbol *	fml6 = `0`
	)

static

Create ArgMatcher with specified formal argument names.

This function creates an ArgMatcher object to match a sequence of formal arguments whose names are given by Symbols supplied as arguments to the function. The function makes no provision for default values to be supplied for the formals.

If any parameter to the function is a null, this signifies that there are not that many formal arguments, and all subsequent parameters must also be null.

Parameters:

fml1	Pointer to the Symbol representing the first formal argument. (It can be null, but this would probably make the created ArgMatcher pointless.)
fml2	Pointer to the Symbol representing the second formal argument, or a null pointer.
fml3	Pointer to the Symbol representing the third formal argument, or a null pointer.
fml4	Pointer to the Symbol representing the fourth formal argument, or a null pointer.
fml5	Pointer to the Symbol representing the fifth formal argument, or a null pointer.
fml6	Pointer to the Symbol representing the sixth formal argument, or a null pointer.

Returns:: Pointer to a newly create ArgMatcher object to match the specified formals.

void ArgMatcher::match	(	Environment *	target_env,
		const ArgList *	supplied
	)		const

Match formal and supplied arguments.

Argument matching is carried out as described in Sec. 4.3.2 of the 'R Language Definition' document.

Following the call, the bindings in the Frame of target_env will be set according to the following decreasing order of precedence:

Bindings, other than to Symbol::missingArgument() (R_MissingArg), provided by the list of supplied arguments. The Binding will have origin EXPLICIT.
Bindings (other than to Symbol::missingArgument()) supplied as default values to the formal parameters in the constructor to this ArgMatcher object. The Binding will have origin DEFAULTED. The default value will be wrapped in a Promise object keyed to target_env .
Bindings already present in the Frame of target_env prior to the call of this function.
Formal arguments not bound by the preceding clauses will be bound to Symbol::missingArgument(), and the Binding will have origin MISSING.

Parameters:

target_env	Non-null pointer to the Environment in whose Frame bindings will be inserted as a result of the argument matching process. Any default arguments used will be wrapped in Promise objects keyed to this Environment.
supplied	Non-null pointer to the ArgList containing the supplied arguments, which must have had ArgList::wrapInPromises() applied.

size_t CXXR::ArgMatcher::numFormals ( ) const

inline

Number of formal arguments.

Returns:: the number of formal arguments. '...' is counted as a single argument.

void ArgMatcher::propagateFormalBindings	(	const Environment *	fromenv,
		Environment *	toenv
	)		const

Copy formal bindings from one Environment to another.

This function is used in dispatching S4 methods to create the working environment for the method. In the function, fromenv points to an Environment which must contain a Binding for every formal argument of this ArgMatcher. toenv points to another Environment (which will become the working environment of the method).

The function works through the Bindings in fromenv in turn. If a Binding has Origin EXPLICIT the function will simply create a copy of the Binding in toenv.

If a Binding has Origin DEFAULTED, it is treated as if it had Origin MISSING, as described next.

If a Binding has Origin MISSING, then it is handled in the same way as a missing argument in ordinary argument matching. That is to say, if this ArgMatcher provides a default for the formal argument in question, that default is used in created a Binding in toenv. (The value of this Binding will be a Promise to be evaluated in toenv.) Otherwise the Binding created in toenv will have Origin MISSING and value Symbol::missingArgument().

Parameters:

fromenv	non-null pointer to an Environment which must contain a Binding for every formal argument of this ArgMatcher.
toenv	non-null pointer to another (unlocked) Environment.

Note:: If, prior to the call, toenv already contains one of more Bindings of the formal arguments of this ArgMatcher, it is at present undefined whether or not these Bindings are replaced by those propagated from fromenv.

void ArgMatcher::stripFormals ( Frame * input_frame ) const

Strip formal argument bindings from a Frame.

This function removes from input_frame any bindings of the formal arguments of this Argmatcher. It is used in creating the working environment of an S3 method from the working environment of its generic.

Parameters:

input_frame Non-null pointer to the Frame from which bindings are to be stripped.

void ArgMatcher::visitReferents ( const_visitor * v ) const

virtual

Conduct a visitor to the nodes referred to by this one.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object.

Parameters:

v	Pointer to the visitor object.

Note:: If this method is reimplemented in a derived class, the reimplemented version must remember to invoke visitReferents() for the immediate base class of the derived class, to ensure that all referents of the object get visited. It is suggested that implementations set up stack-based pointers to all the referents of a node before visiting any of them; in that case, if the (recursive) visiting pushes the node out of the processor cache, there is no need to fetch it back in.

Reimplemented from CXXR::GCNode.

static bool CXXR::ArgMatcher::warnOnPartialMatch ( )

inlinestatic

Give warning if tag partially matched?

Returns:: true iff the class is configured to raise a warning if a supplied argument is matched to a formal argument by virtue of partial matching on the tag.

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

ArgMatcher.hpp ($Id: ArgMatcher.hpp 1348 2013-02-25 17:49:03Z arr $)
ArgMatcher.cpp ($Id: ArgMatcher.cpp 1348 2013-02-25 17:49:03Z arr $)
match.cpp ($Id: match.cpp 1348 2013-02-25 17:49:03Z arr $)

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation