CXXR (C++ R)
Public Types | Public Member Functions | Static Public Member Functions
CXXR::ArgList Class Reference

Class encapsulating the argument list of a FunctionBase. More...

#include <ArgList.hpp>

List of all members.

Public Types

enum  Status { RAW, PROMISED, EVALUATED }
 Way (if any) in which ArgList has been processed. More...

Public Member Functions

 ArgList (const PairList *args, Status status)
 Constructor.
void evaluate (Environment *env, bool allow_missing=false)
 Evaluate the arguments in the ArgList.
std::pair< bool, RObject * > firstArg (Environment *env)
 Get the first argument.
const PairListlist () const
 Access the argument list as a PairList.
void merge (const ConsCell *extraargs)
 Merge in new argument values..
Status status () const
 How has this ArgList been processed?
void stripTags ()
 Remove argument names.
void wrapInPromises (Environment *env)
 Wrap elements of the argument list in Promise objects.

Static Public Member Functions

static const Symboltag2Symbol (const RObject *tag)
 Convert tag of supplied argument to a Symbol.

Detailed Description

Class encapsulating the argument list of a FunctionBase.

ArgList objects must be declared on the processor stack (i.e. as C++ automatic variables).

This class encapsulates a list of the argument supplied in a call to a FunctionBase object, and provides facilities for manipulating the list in the various ways required


Member Enumeration Documentation

Way (if any) in which ArgList has been processed.

Enumerator:
RAW 

Unprocessed.

PROMISED 

Argument values are wrapped in Promise objects, and non-null tags have been coerced to Symbols. This is the form expected by ArgMatcher::match().

EVALUATED 

Argument values have been evaluated, and ... arguments expanded.


Constructor & Destructor Documentation

CXXR::ArgList::ArgList ( const PairList args,
Status  status 
)
inline

Constructor.

Parameters:
argsPointer, possibly null, to a PairList of unevaluated arguments supplied in a call of a FunctionBase. The calling code must not modify args after calling this constructor.
statusThe Status of the argument list provided by args. No check is made that the args list is actually consistent with the value of status.

Member Function Documentation

void ArgList::evaluate ( Environment env,
bool  allow_missing = false 
)

Evaluate the arguments in the ArgList.

Except as regards the handling of ... and missing values described next, this function replaces the argument list with a list of the same length as the current list, and whose tags are the same as those of the current list, but whose elements ('car' values) are the result of evaluating the corresponding elements of the current list within env.

If an element of the list has value R_DotsSymbol, the binding of this Symbol within env is examined. If it is bound to NULL or to Symbol::missingArgument() (R_MissingArg), this element of the current list is discarded. If it is bound to a DottedArgs list, then this element of the current list is replaced by the one or more elements resulting from evaluating the elements of the DottedArgs list, and carrying across the corresponding tags. If the DottedArgs list contains any elements with value Symbol::missingArgument(), these are carried through unchanged into the resulting list, irrespective of the setting of allow_missing. Any other binding of R_DotsSymbol within env is an error.

If any element of the current list has the value Symbol::missingArgument(), then this element of the list is carried through unchanged into the resulting list, unless allow_missing is false, in which case an error is raised.

If any element of the current list has as value a Symbol missing within env, then this is converted in the resulting list into an element with the same tag but whose value is Symbol::missingArgument(). This applies unless allow_missing is false, in which case an error is raised.

After the call, the ArgList will have Status EVALUATED; it is an error to call this function if the ArgList already has Status EVALUATED.

Parameters:
envThe Environment in which evaluations are to take place. If firstArg() has previously been called for this ArgList, then env must be identical to the env argument of that firstArg() call.
allow_missingThis affects the handling of any elements of the current list whose value is either Symbol::missingArgument() or a Symbol which is missing within env. If allow_missing is true, such elements are carried through unchanged into the resulting list; otherwise, such elements cause an error to be raised.
Note:
This function is intended within CXXR to supersede CR's evalList() and evalListKeepMissing().
pair< bool, RObject * > ArgList::firstArg ( Environment env)

Get the first argument.

This function accesses the value of the first argument in the ArgList, evaluating it in env if the ArgList has not already been evaluated.

However, if the first argument is DotsSymbol (...), the binding of this Symbol within env is examined. If it is bound to a DottedArgs list, the return value is the value of the first element is this DottedArgs list, evaluated if necessary.

In seeking the first argument of the ArgList, the function ignores any initial elements of the ArgList whose value is DotsSymbol (...) if the binding of this Symbol within env is NULL or Symbol::missingArgument(). Any other binding of DotsSymbol is an error; it is also an error is a DotsSymbol argument is encountered but DotsSymbol is unbound within env.

If evaluation of the first argument takes place, the class records this fact, and takes steps to ensure that it is not subsequently reevaluated.

Parameters:
envPointer to the Environment in which the first argument is to be evaluated. If the ArgList has already been evaluated, this pointer can be null.
Returns:
If, following the procedure described above, no first argument was found, then the first element of the pair is false and the second element null. Otherwise, the first element is true and the second element is a pointer to the value of the first argument.
const PairList* CXXR::ArgList::list ( ) const
inline

Access the argument list as a PairList.

Returns:
pointer, possibly null, to the list of arguments in their current state.
void ArgList::merge ( const ConsCell extraargs)

Merge in new argument values..

This function is used in implementing NextMethod. If any element of the ArgList has the same non-null tag as an element of extraargs, then the value (car) of that element of the ArgList is replaced by the value of the corresponding element of extraargs.

Any elements of extraargs that do not override existing arguments as described in the previous paragraph are appended in order to the ArgList.

It is an error to call this function unless the ArgList has PROMISED status.

Parameters:
extraargsPointer, possibly null, to a list whose elements represent Promise-wrapped argument values.
Note:
This behavior conforms to the R manpage for NextMethod. However, the White Book says that unnamed arguments in extraargs should be prepended to the ArgList.
Status CXXR::ArgList::status ( ) const
inline

How has this ArgList been processed?

Returns:
The current Status of the Arglist.
void ArgList::stripTags ( )

Remove argument names.

This function removes any tags from the ArgList. This will force any subsequent argument matching to be based on argument position alone.

static const Symbol* CXXR::ArgList::tag2Symbol ( const RObject tag)
inlinestatic

Convert tag of supplied argument to a Symbol.

If tag is a null pointer or already points to a Symbol, then tag itself is returned.

If tag points to a StringVector with at least one element, and the first element is a String of length at least one, then the function returns a pointer to a Symbol with that first element, translated in the current locale, as its name.

In all other cases the function returns a Symbol whose name is obtained by an abbreviated SIMPLEDEPARSE of tag.

Parameters:
tagPointer (possibly null) to the tag to be processed.
Returns:
pointer to the representation of tag as a Symbol.
Todo:
This function probably ought to be fussier about what it accepts as input.
void ArgList::wrapInPromises ( Environment env)

Wrap elements of the argument list in Promise objects.

Basically, this function wraps any argument in the ArgList whose value is not Symbol::missingArgument() in a Promise to be evaluated in env. However, if the ArgList currently has Status EVALUATED, the env parameter is ignored, and the function simply wraps the argument values in pre-forced Promise objects.

If any argument has the value CXXR::DotsSymbol, the action depends on what this Symbol is bound to within env (and its enclosing environments). If it is unbound, or bound to a null pointer or to Symbol::missingArgument(), then this element of the ArgList is discarded. If it is bound to a DottedArgs list, then the elements of that list are added to the ArgList as arguments in their own right, with each argument value being wrapped in a Promise to be evaluated in env. Any other binding of DotsSymbol is an error.

Any tags in the ArgList or in a DottedArgs list are carried across to the corresponding element of the modified list, but coerced using tag2Symbol() into a form suitable for argument matching.

After the call, the ArgList will have Status PROMISED; it is an error to call this function if the ArgList already has Status PROMISED.

Parameters:
envPointer to the Environment to which Promises in the output list are to be keyed. As noted above, this parameter is ignored if the ArgList has Status EVALUATED. Otherwise, if firstArg() has previously been called for this ArgList, then env must be identical to the env argument of that firstArg() call.
Note:
It would be desirable to avoid producing a new PairList, and to absorb this functionality directly into the ArgMatcher::match() function. But at present the Promise-wrapped list is recorded in the context set up by Closure::apply(), and used for other purposes.

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