CXXR (C++ R) API
Public Member Functions | Static Public Member Functions | Protected Member Functions
CXXR::ArgMatcher Class Reference

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

#include <ArgMatcher.hpp>

Inheritance diagram for CXXR::ArgMatcher:
Inheritance graph
[legend]
Collaboration diagram for CXXR::ArgMatcher:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 ArgMatcher (const PairList *formals)
 Constructor.
const PairListformalArgs () 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?

Static Public Member Functions

static void enableWarnOnPartialMatch (bool on)
 Enable/disable warning if tag partially matched.
static ArgMatchermake (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 ()

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

CXXR::ArgMatcher::ArgMatcher ( const PairList formals)
explicit

Constructor.

Parameters:
formalsPairList 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 CXXR::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:
ontrue 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 '...'.
static ArgMatcher* CXXR::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:
fml1Pointer to the Symbol representing the first formal argument. (It can be null, but this would probably make the created ArgMatcher pointless.)
fml2Pointer to the Symbol representing the second formal argument, or a null pointer.
fml3Pointer to the Symbol representing the third formal argument, or a null pointer.
fml4Pointer to the Symbol representing the fourth formal argument, or a null pointer.
fml5Pointer to the Symbol representing the fifth formal argument, or a null pointer.
fml6Pointer 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 CXXR::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:

  1. Bindings, other than to Symbol::missingArgument() (R_MissingArg), provided by the list of supplied arguments. The Binding will have origin EXPLICIT.

  2. 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 .

  3. Bindings already present in the Frame of target_env prior to the call of this function.

  4. Formal arguments not bound by the preceding clauses will be bound to Symbol::missingArgument(), and the Binding will have origin MISSING.
Parameters:
target_envNon-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.
suppliedNon-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 CXXR::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:
fromenvnon-null pointer to an Environment which must contain a Binding for every formal argument of this ArgMatcher.
toenvnon-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 CXXR::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_frameNon-null pointer to the Frame from which bindings are to be stripped.
void CXXR::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:
vPointer 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 file: