ArgMatcher.hpp

Go to the documentation of this file.

/*CXXR $Id: ArgMatcher.hpp 1348 2013-02-25 17:49:03Z arr $
 *CXXR
 *CXXR This file is part of CXXR, a project to refactor the R interpreter
 *CXXR into C++.  It may consist in whole or in part of program code and
 *CXXR documentation taken from the R project itself, incorporated into
 *CXXR CXXR (and possibly MODIFIED) under the terms of the GNU General Public
 *CXXR Licence.
 *CXXR 
 *CXXR CXXR is Copyright (C) 2008-13 Andrew R. Runnalls, subject to such other
 *CXXR copyrights and copyright restrictions as may be stated below.
 *CXXR 
 *CXXR CXXR is not part of the R project, and bugs and other issues should
 *CXXR not be reported via r-bugs or other R project channels; instead refer
 *CXXR to the CXXR website.
 *CXXR */

/*
 *  R : A Computer Language for Statistical Data Analysis
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2.1 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, a copy is available at
 *  http://www.r-project.org/Licenses/
 */

#ifndef ARGMATCHER_HPP
#define ARGMATCHER_HPP 1

#include <list>
#include <map>
#include <vector>
#include "CXXR/GCEdge.hpp"
#include "CXXR/String.h"

namespace CXXR {
    class ArgList;
    class Environment;
    class Frame;
    class PairList;
    class RObject;
    class Symbol;

    class ArgMatcher : public GCNode {
    public:
        explicit ArgMatcher(const PairList* formals);

        static void enableWarnOnPartialMatch(bool on)
        {
            s_warn_on_partial_match = on;
        }

        const PairList* formalArgs() const
        {
            return m_formals;
        }

        bool has3Dots() const
        {
            return m_has_dots;
        }

        static ArgMatcher* make(Symbol* fml1, Symbol* fml2 = 0,
                                Symbol* fml3 = 0, Symbol* fml4 = 0,
                                Symbol* fml5 = 0, Symbol* fml6 = 0);

        void match(Environment* target_env, const ArgList* supplied) const;

        size_t numFormals() const
        {
            return m_formal_data.size() + m_has_dots;
        }

        void propagateFormalBindings(const Environment* fromenv,
                                     Environment* toenv) const;

        void stripFormals(Frame* input_frame) const;

        static bool warnOnPartialMatch()
        {
            return s_warn_on_partial_match;
        }

        // Virtual function of GCNode:
        void visitReferents(const_visitor* v) const;
    protected:
        // Virtual function of GCNode:
        void detachReferents();
    private:
        static bool s_warn_on_partial_match;

        struct FormalData {
            const Symbol* symbol;
            bool follows_dots;  // true if ... occurs earlier in the
                                // formals list.
            RObject* value;
        };

        enum MatchStatus {UNMATCHED = 0, EXACT_TAG, PARTIAL_TAG, POSITIONAL};

        GCEdge<const PairList> m_formals;

        // Data on formals (other than "...") in order of occurrence:
        typedef std::vector<FormalData, Allocator<FormalData> > FormalVector;
        FormalVector m_formal_data;

        struct Comparator {
            bool operator()(const String* l, const String* r) const
            {
                return l->stdstring() < r->stdstring();
            }
        };

        // Mapping from tag names to index within m_formal_data:
        typedef std::map<const String*, unsigned int, Comparator,
                         Allocator<std::pair<const String*,
                                             unsigned int> > > FormalMap;
        FormalMap m_formal_index;

        bool m_has_dots;  // True if formals include "..."

        struct SuppliedData {
            const Symbol* tag;
            RObject* value;
            FormalMap::const_iterator fm_iter;
            unsigned int index;
        };

        // Data relating to supplied arguments that have not yet been
        // matched.
        typedef std::list<SuppliedData, Allocator<SuppliedData> > SuppliedList;

        // Turn remaining arguments, if any, into a DottedArgs object
        // bound to '...'.  Leave supplied_list empty.
        static void handleDots(Frame* frame, SuppliedList* supplied_list);

        // Return true if 'shorter' is a prefix of 'longer', or is
        // identical to 'longer':
        static bool isPrefix(const String* shorter, const String* longer);

        // Create a Binding in the Frame of target_env for the Symbol
        // in fdata, setting its Origin and applying default value
        // appropriately.  Default values are wrapped in Promises
        // keyed to target_env.
        static void makeBinding(Environment* target_env, const FormalData& fdata,
                                RObject* supplied_value);

        // Raise an error because there are unused supplied arguments,
        // as indicated in supplied_list.
        static void unusedArgsError(const SuppliedList& supplied_list);
    };
}

#endif  // ARGMATCHER_HPP