|
CXXR (C++ R) API
|
Class encapsulating the argument list of a FunctionBase. More...
#include <ArgList.hpp>
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 PairList * | list () 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 Symbol * | tag2Symbol (const RObject *tag) |
| Convert tag of supplied argument to a Symbol. | |
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
Way (if any) in which ArgList has been processed.
| 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.
| args | Pointer, 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. |
| status | The Status of the argument list provided by args. No check is made that the args list is actually consistent with the value of status. |
| void CXXR::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.
| env | The 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_missing | This 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. |
| std::pair<bool, RObject*> CXXR::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.
| env | Pointer to the Environment in which the first argument is to be evaluated. If the ArgList has already been evaluated, this pointer can be null. |
|
inline |
Access the argument list as a PairList.
| void CXXR::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.
| extraargs | Pointer, possibly null, to a list whose elements represent Promise-wrapped argument values. |
|
inline |
How has this ArgList been processed?
| void CXXR::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.
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.
| tag | Pointer (possibly null) to the tag to be processed. |
| void CXXR::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.
| env | Pointer 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. |
1.8.1