attributes.cpp

// attributes.cpp: Rcpp R/C++ interface class library -- Rcpp attributes
//
// Copyright (C) 2012 - 2020  JJ Allaire, Dirk Eddelbuettel and Romain Francois
// Copyright (C) 2021 - 2025  JJ Allaire, Dirk Eddelbuettel, Romain Francois, Iñaki Ucar and Travers Ching
//
// This file is part of Rcpp.
//
// Rcpp 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 of the License, or
// (at your option) any later version.
//
// Rcpp 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Rcpp.  If not, see <http://www.gnu.org/licenses/>.

#define COMPILING_RCPP

#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>

#include <cstring>

#include <string>
#include <vector>
#include <map>
#include <set>
#include <algorithm>
#include <ostream> // for std::endl
#include <fstream>
#include <sstream>

#define RCPP_NO_SUGAR
#include <Rcpp.h>

/*******************************************************************
 * AttributesUtil.h
 *******************************************************************/

namespace Rcpp {
namespace attributes {

    // Utility class for getting file existence and last modified time
    class FileInfo {
    public:

        // create from path
        explicit FileInfo(const std::string& path);

        // create from R list
        explicit FileInfo(const List& fileInfo) {		// #nocov start
            path_ = as<std::string>(fileInfo["path"]);
            exists_ = as<bool>(fileInfo["exists"]);
            lastModified_ = as<double>(fileInfo["lastModified"]);
        }							// #nocov end

        // convert to R list
        List toList() const {
            List fileInfo;
            fileInfo["path"] = path_;
            fileInfo["exists"] = exists_;
            fileInfo["lastModified"] = lastModified_;
            return fileInfo;
        }

        std::string path() const { return path_; }
        bool exists() const { return exists_; }
        double lastModified() const { return lastModified_; }

        std::string extension() const {
            std::string::size_type pos = path_.find_last_of('.');
            if (pos != std::string::npos)
                return path_.substr(pos);
            else
                return "";					// #nocov
        }

        bool operator<(const FileInfo& other) const {
            return path_ < other.path_;
        };

        bool operator==(const FileInfo& other) const {
            return path_ == other.path_ &&
                   exists_ == other.exists_ &&
                   lastModified_ == other.lastModified_;
        };

        bool operator!=(const FileInfo& other) const {
            return ! (*this == other);
        };

        std::ostream& operator<<(std::ostream& os) const {
            os << path_;
            return os;
        }

    private:
        std::string path_;
        bool exists_;
        double lastModified_;
    };

    // Remove a file
    bool removeFile(const std::string& path);

    // Recursively create a directory
    void createDirectory(const std::string& path);

    // Known whitespace chars
    extern const char * const kWhitespaceChars;

    // Query whether a character is whitespace
    bool isWhitespace(char ch);

    // Trim a string
    void trimWhitespace(std::string* pStr);

    // Strip trailing line comments
    void stripTrailingLineComments(std::string* pStr);

    // Strip balanced quotes from around a string (assumes already trimmed)
    void stripQuotes(std::string* pStr);

    // is the passed string quoted?
    bool isQuoted(const std::string& str);

    // does a string end with another string?
    bool endsWith(const std::string& str, const std::string& suffix);

    // show a warning message
    void showWarning(const std::string& msg);

    // is the line a C++ roxygen comment? (started with //')
    bool isRoxygenCpp(const std::string& str);

} // namespace attributes
} // namespace Rcpp


/*******************************************************************
 * AttributesTypes.h
 *******************************************************************/

namespace Rcpp {
namespace attributes {

    // Known attribute names & parameters
    const char * const kExportAttribute = "export";
    const char * const kExportName = "name";
    const char * const kExportRng = "rng";
    const char * const kExportInvisible = "invisible";
    const char * const kExportSignature = "signature";
    const char * const kInitAttribute = "init";
    const char * const kDependsAttribute = "depends";
    const char * const kPluginsAttribute = "plugins";
    const char * const kInterfacesAttribute = "interfaces";
    const char * const kInterfaceR = "r";
    const char * const kInterfaceCpp = "cpp";
    const char * const kParamValueFalse = "false";
    const char * const kParamValueTrue = "true";
    const char * const kParamValueFALSE = "FALSE";
    const char * const kParamValueTRUE = "TRUE";
    const char * const kParamBlockStart = "{;";
    const char * const kParamBlockEnd = "}";

    // Type info
    class Type {
    public:
        Type(): isConst_(false), isReference_(false) {}
        Type(const std::string& name, bool isConst, bool isReference)
            : name_(name), isConst_(isConst), isReference_(isReference)
        {
        }
        bool empty() const { return name().empty(); }

        bool operator==(const Type& other) const {		// #nocov start
            return name_ == other.name_ &&
                   isConst_ == other.isConst_ &&
                   isReference_ == other.isReference_;
        };							// #nocov end

        bool operator!=(const Type& other) const {
            return !(*this == other);
        };

        const std::string& name() const { return name_; }
        std::string full_name() const {
            std::string res ;
            if( isConst() ) res += "const " ;
            res += name() ;
            if( isReference() ) res += "&" ;
            return res ;
        }

        bool isVoid() const { return name() == "void"; }
        bool isConst() const { return isConst_; }
        bool isReference() const { return isReference_; }

    private:
        std::string name_;
        bool isConst_;
        bool isReference_;
    };

    // Argument info
    class Argument {
    public:
        Argument() {}
        Argument(const std::string& name,
                 const Type& type,
                 const std::string& defaultValue)
            : name_(name), type_(type), defaultValue_(defaultValue)
        {
        }

        bool empty() const { return type().empty(); }

        bool operator==(const Argument& other) const {		// #nocov start
            return name_ == other.name_ &&
                   type_ == other.type_ &&
                   defaultValue_ == other.defaultValue_;
        };							// #nocov end

        bool operator!=(const Argument& other) const {
            return !(*this == other);
        };


        const std::string& name() const { return name_; }
        const Type& type() const { return type_; }
        const std::string& defaultValue() const { return defaultValue_; }

    private:
        std::string name_;
        Type type_;
        std::string defaultValue_;
    };

    // Function info
    class Function {
    public:
        Function() {}
        Function(const Type& type,
                 const std::string& name,
                 const std::vector<Argument>& arguments)
            : type_(type), name_(name), arguments_(arguments)
        {
        }

        Function renamedTo(const std::string& name) const {	// #nocov start
            return Function(type(), name, arguments());
        }

        std::string signature() const { return signature(name()); }
        std::string signature(const std::string& name) const;

        bool isHidden() const {
            return name().find_first_of('.') == 0;
        }							// #nocov end

        bool empty() const { return name().empty(); }

        bool operator==(const Function& other) const {		// #nocov start
            return type_ == other.type_ &&
                   name_ == other.name_ &&
                   arguments_ == other.arguments_;
        };							// #nocov end

        bool operator!=(const Function& other) const {
            return !(*this == other);
        };

        const Type& type() const { return type_; }
        const std::string& name() const { return name_; }
        const std::vector<Argument>& arguments() const { return arguments_; }

    private:
        Type type_;
        std::string name_;
        std::vector<Argument> arguments_;
    };

    // Attribute parameter (with optional value)
    class Param {
    public:
        Param() {}
        explicit Param(const std::string& paramText);
        bool empty() const { return name().empty(); }

        bool operator==(const Param& other) const {		// #nocov start
            return name_ == other.name_ &&
                   value_ == other.value_;
        };							// #nocov end

        bool operator!=(const Param& other) const {
            return !(*this == other);
        };


        const std::string& name() const { return name_; }
        const std::string& value() const { return value_; }	// #nocov

    private:
        std::string name_;
        std::string value_;
    };

    // Attribute (w/ optional params and signature of function it qualifies)
    class Attribute {
    public:
        Attribute() {}
        Attribute(const std::string& name,
                  const std::vector<Param>& params,
                  const Function& function,
                  const std::vector<std::string>& roxygen)
            : name_(name), params_(params), function_(function), roxygen_(roxygen)
        {
        }

        bool empty() const { return name().empty(); }		// #nocov start

        bool operator==(const Attribute& other) const {
            return name_ == other.name_ &&
                   params_ == other.params_ &&
                   function_ == other.function_ &&
                   roxygen_ == other.roxygen_;
        };							// #nocov end

        bool operator!=(const Attribute& other) const {
            return !(*this == other);
        };


        const std::string& name() const { return name_; }

        const std::vector<Param>& params() const { return params_; }

        Param paramNamed(const std::string& name) const;

        bool hasParameter(const std::string& name) const {
            return !paramNamed(name).empty();
        }

        const Function& function() const { return function_; }

        bool isExportedFunction() const {
            return (name() == kExportAttribute) && !function().empty();
        }

        std::string exportedName() const {

            // check for explicit name parameter
            if (hasParameter(kExportName))
            {
                return paramNamed(kExportName).value();		// #nocov
            }
            // otherwise un-named parameter in the first slot
            else if (!params().empty() && params()[0].value().empty())
            {
                return params()[0].name();			// #nocov
            }
            // otherwise the actual function name
            {
                return function().name();
            }
        }

        std::string exportedCppName() const {			// #nocov start
            std::string name = exportedName();
            std::replace(name.begin(), name.end(), '.', '_');
            return name;
        }							// #nocov end

        bool rng() const {
            Param rngParam = paramNamed(kExportRng);
            if (!rngParam.empty())
                return rngParam.value() == kParamValueTrue ||	// #nocov
                       rngParam.value() == kParamValueTRUE;  	// #nocov
            else
                return true;
        }

        bool invisible() const {
            Param invisibleParam = paramNamed(kExportInvisible);
            if (!invisibleParam.empty())
                return invisibleParam.value() == kParamValueTrue ||	// #nocov
                       invisibleParam.value() == kParamValueTRUE;  	// #nocov
            else
                return false;
        }

        const std::vector<std::string>& roxygen() const { return roxygen_; }

        std::string customRSignature() const {
            Param sigParam = paramNamed(kExportSignature);
            std::string sig = sigParam.value();
            trimWhitespace(&sig);
            if (sig.empty()) return sig;
            if (sig.back() == '}')
                sig = sig.substr(0, sig.size()-1);
            // check sig.empty again since we deleted an element
            if (sig.empty()) return sig;
            if (sig.front() == '{')
                sig.erase(0,1);
            return sig;
        }

    private:
        std::string name_;
        std::vector<Param> params_;
        Function function_;
        std::vector<std::string> roxygen_;
    };

    // Operator << for parsed types
    std::ostream& operator<<(std::ostream& os, const Type& type);
    std::ostream& operator<<(std::ostream& os, const Argument& argument);
    std::ostream& operator<<(std::ostream& os, const Function& function);
    std::ostream& operator<<(std::ostream& os, const Param& param);
    std::ostream& operator<<(std::ostream& os, const Attribute& attribute);

    // interface to source file attributes
    class SourceFileAttributes
    {
    public:
        virtual ~SourceFileAttributes() {};
        virtual const std::string& sourceFile() const = 0;
        virtual bool hasInterface(const std::string& name) const = 0;

        typedef std::vector<Attribute>::const_iterator const_iterator;
        virtual const_iterator begin() const = 0;
        virtual const_iterator end() const = 0;

        virtual const std::vector<std::string>& modules() const = 0;

        virtual const std::vector<std::vector<std::string> >& roxygenChunks() const = 0;

        virtual bool hasGeneratorOutput() const = 0;

        virtual bool hasPackageInit() const = 0;
    };


} // namespace attributes
} // namespace Rcpp



/*******************************************************************
 * AttributesParser.h
 *******************************************************************/

namespace Rcpp {
namespace attributes {

    // Helper class for determining whether we are in a comment
    class CommentState {
    public:
        CommentState() : inComment_(false) {}
    private:
        // prohibit copying
        CommentState(const CommentState&);
        CommentState& operator=(const CommentState&);
    public:
        bool inComment() const { return inComment_; }
        void submitLine(const std::string& line);
        void reset() { inComment_ = false; }
    private:
        bool inComment_;
    };

    // Class used to parse and return attribute information from a source file
    class SourceFileAttributesParser : public SourceFileAttributes {
    public:
        explicit SourceFileAttributesParser(const std::string& sourceFile,
                                            const std::string& packageFile,
                                            bool parseDependencies);

    private:
        // prohibit copying
        SourceFileAttributesParser(const SourceFileAttributesParser&);
        SourceFileAttributesParser& operator=(const SourceFileAttributesParser&);

    public:
        // implemetnation of SourceFileAttributes interface
        virtual const std::string& sourceFile() const {		// #nocov
            return sourceFile_;					// #nocov
        }
        virtual const_iterator begin() const { return attributes_.begin(); }
        virtual const_iterator end() const { return attributes_.end(); }

        virtual const std::vector<std::string>& modules() const
        {
            return modules_;
        }

        virtual const std::vector<std::vector<std::string> >& roxygenChunks() const {
            return roxygenChunks_;
        }

        virtual bool hasGeneratorOutput() const
        {
            return !attributes_.empty() ||
                   !modules_.empty() ||
                   !roxygenChunks_.empty();
        }

        virtual bool hasInterface(const std::string& name) const {

            for (const_iterator it=begin(); it != end(); ++it) {
                if (it->name() == kInterfacesAttribute) {
                    return it->hasParameter(name);		// #nocov
                }
            }

            // if there's no interfaces attrbute we default to R
            if (name == kInterfaceR)
                return true;
            else
                return false;
        }

        // Was a package init function found?
        bool hasPackageInit() const {
            return hasPackageInit_;
        }

        // Get lines of embedded R code
        const std::vector<std::string>& embeddedR() const {
            return embeddedR_;
        }

        // Get source dependencies
        const std::vector<FileInfo>& sourceDependencies() const {
            return sourceDependencies_;
        };

    private:

        // Parsing helpers
        Attribute parseAttribute(const std::vector<std::string>& match,
                                 int lineNumber);
        std::vector<Param> parseParameters(const std::string& input);
        Function parseFunction(size_t lineNumber);
        std::string parseSignature(size_t lineNumber);
        std::vector<std::string> parseArguments(const std::string& argText);
        Type parseType(const std::string& text);

        // Validation helpers
        bool isKnownAttribute(const std::string& name) const;
        void attributeWarning(const std::string& message,
                              const std::string& attribute,
                              size_t lineNumber);
        void attributeWarning(const std::string& message, size_t lineNumber);
        void rcppExportWarning(const std::string& message, size_t lineNumber);
        void rcppExportNoFunctionFoundWarning(size_t lineNumber);
        void rcppExportInvalidParameterWarning(const std::string& param,
                                               size_t lineNumber);
        void rcppInterfacesWarning(const std::string& message,
                                   size_t lineNumber);

    private:
        std::string sourceFile_;
        CharacterVector lines_;
        std::vector<Attribute> attributes_;
        std::vector<std::string> modules_;
        bool hasPackageInit_;
        std::vector<std::string> embeddedR_;
        std::vector<FileInfo> sourceDependencies_;
        std::vector<std::vector<std::string> > roxygenChunks_;
        std::vector<std::string> roxygenBuffer_;
    };

} // namespace attributes
} // namespace Rcpp


/*******************************************************************
 * AttributesGen.h
 *******************************************************************/

namespace Rcpp {
namespace attributes {

    // Abstract class which manages writing of code for compileAttributes
    class ExportsGenerator {
    protected:
        ExportsGenerator(const std::string& targetFile,
                         const std::string& package,
                         const std::string& commentPrefix);

    private:
        // prohibit copying
        ExportsGenerator(const ExportsGenerator&);
        ExportsGenerator& operator=(const ExportsGenerator&);

    public:
        virtual ~ExportsGenerator() {}

        // Name of target file and package
        const std::string& targetFile() const { return targetFile_; }
        const std::string& package() const { return package_; }
        const std::string& packageCpp() const { return packageCpp_; }
        const std::string packageCppPrefix() const { return "_" + packageCpp(); }

        // Abstract interface for code generation
        virtual void writeBegin() = 0;
        void writeFunctions(const SourceFileAttributes& attributes,
                            bool verbose); // see doWriteFunctions below
        virtual void writeEnd(bool hasPackageInit) = 0;

        virtual bool commit(const std::vector<std::string>& includes) = 0;

        // Remove the generated file entirely
        bool remove();

        // Allow generator to appear as a std::ostream&
        operator std::ostream&() {
            return codeStream_;
        }

    protected:

        // Allow access to the output stream
        std::ostream& ostr() {
            return codeStream_;
        }

        bool hasCppInterface() const {
            return hasCppInterface_;
        }

        // Shared knowledge about function namees
        std::string exportValidationFunction() {
            return "RcppExport_validate";
        }
        std::string exportValidationFunctionRegisteredName() {
            return packageCppPrefix() + "_" + exportValidationFunction();
        }
        std::string registerCCallableExportedName() {			// #nocov
            return packageCppPrefix() + "_RcppExport_registerCCallable";	// #nocov
        }

        // Commit the stream -- is a no-op if the existing code is identical
        // to the generated code. Returns true if data was written and false
        // if it wasn't (throws exception on io error)
        bool commit(const std::string& preamble = std::string());

        // Convert a dot in package name to underscore for use in header file name
        std::string dotNameHelper(const std::string & name) const;

    private:

        // Private virtual for doWriteFunctions so the base class
        // can always intercept writeFunctions
        virtual void doWriteFunctions(const SourceFileAttributes& attributes,
                                      bool verbose) = 0;

        // Check whether it's safe to overwrite this file (i.e. whether we
        // generated the file in the first place)
        bool isSafeToOverwrite() const {
            return existingCode_.empty() ||
                   (existingCode_.find(generatorToken()) != std::string::npos);
        }

        // UUID that we write into a comment within the file (so that we can
        // strongly identify that a file was generated by us before overwriting it)
        std::string generatorToken() const {
            return "10BE3573-1514-4C36-9D1C-5A225CD40393";
        }

    private:
        std::string targetFile_;
        std::string package_;
        std::string packageCpp_;
        std::string commentPrefix_;
        std::string existingCode_;
        std::ostringstream codeStream_;
        bool hasCppInterface_;
    };

    // Class which manages generating RcppExports.cpp
    class CppExportsGenerator : public ExportsGenerator {
    public:
        explicit CppExportsGenerator(const std::string& packageDir,
                                     const std::string& package,
                                     const std::string& fileSep);

        virtual void writeBegin() {};
        virtual void writeEnd(bool hasPackageInit);
        virtual bool commit(const std::vector<std::string>& includes);

    private:
        virtual void doWriteFunctions(const SourceFileAttributes& attributes,
                                      bool verbose);

        std::string registerCCallable(size_t indent,
                                      const std::string& exportedName,
                                      const std::string& name) const;

    private:
        // for generating calls to init functions
        std::vector<Attribute> initFunctions_;

        // for generating C++ interfaces
        std::vector<Attribute> cppExports_;

        // for generating Rcpp::export native routine registration
        std::vector<Attribute> nativeRoutines_;

        // for generating module native routine registration
        std::vector<std::string> modules_;
    };

    // Class which manages generating PackageName_RcppExports.h header file
    class CppExportsIncludeGenerator : public ExportsGenerator {
    public:
        CppExportsIncludeGenerator(const std::string& packageDir,
                                   const std::string& package,
                                   const std::string& fileSep);

        virtual void writeBegin();
        virtual void writeEnd(bool hasPackageInit);
        virtual bool commit(const std::vector<std::string>& includes);

    private:
        virtual void doWriteFunctions(const SourceFileAttributes& attributes,
                                      bool verbose);
        std::string getCCallable(const std::string& function) const;
        std::string getHeaderGuard() const;

    private:
        std::string includeDir_;
    };

    // Class which manages generating PackageName.h header file
    class CppPackageIncludeGenerator : public ExportsGenerator {
    public:
        CppPackageIncludeGenerator(const std::string& packageDir,
                                   const std::string& package,
                                   const std::string& fileSep);

        virtual void writeBegin() {}
        virtual void writeEnd(bool hasPackageInit);
        virtual bool commit(const std::vector<std::string>& includes);

    private:
        virtual void doWriteFunctions(const SourceFileAttributes&, bool) {}
        std::string getHeaderGuard() const;

    private:
        std::string includeDir_;
    };


    // Class which manages generator RcppExports.R
    class RExportsGenerator : public ExportsGenerator {
    public:
        RExportsGenerator(const std::string& packageDir,
                          const std::string& package,
                          bool registration,
                          const std::string& fileSep);

        virtual void writeBegin() {}
        virtual void writeEnd(bool hasPackageInit);
        virtual bool commit(const std::vector<std::string>& includes);

    private:
        virtual void doWriteFunctions(const SourceFileAttributes& attributes,
                                      bool verbose);

        bool registration_;

    };

    // Class to manage and dispatch to a list of generators
    class ExportsGenerators {
    public:
        typedef std::vector<ExportsGenerator*>::iterator Itr;

        ExportsGenerators() {}
        virtual ~ExportsGenerators();

        void add(ExportsGenerator* pGenerator);

        void writeBegin();
        void writeFunctions(const SourceFileAttributes& attributes,
                            bool verbose);
        void writeEnd(bool hasPackageInit);

        // Commit and return a list of the files that were updated
        std::vector<std::string> commit(
                                const std::vector<std::string>& includes);

        // Remove and return a list of files that were removed
        std::vector<std::string> remove();

    private:
        // prohibit copying
        ExportsGenerators(const ExportsGenerators&);
        ExportsGenerators& operator=(const ExportsGenerators&);

    private:
        std::vector<ExportsGenerator*> generators_;
    };

    // Standalone generation helpers (used by sourceCpp)

    std::string generateRArgList(const Function& function);

    bool checkRSignature(const Function& function, std::string args);

    void initializeGlobals(std::ostream& ostr);

    void generateCpp(std::ostream& ostr,
                     const SourceFileAttributes& attributes,
                     bool includePrototype,
                     bool cppInterface,
                     const std::string& contextId);

} // namespace attributes
} // namespace Rcpp


/*******************************************************************
 * AttributesParser.cpp
 *******************************************************************/

namespace Rcpp {
namespace attributes {

    namespace {

        Rcpp::List regexMatches(Rcpp::CharacterVector lines,
                                const std::string& regex)
        {
            Rcpp::Environment base("package:base");
            Rcpp::Function regexec = base["regexec"];
            Rcpp::Function regmatches = base["regmatches"];
            Rcpp::RObject result =  regexec(regex, lines);
            Rcpp::List matches = regmatches(lines, result);
            return matches;
        }

        template <typename Stream>
        void readFile(const std::string& file, Stream& os) {
            std::ifstream ifs(file.c_str());
            if (ifs.fail())
                throw Rcpp::file_io_error(file);		// #nocov
            os << ifs.rdbuf();
            ifs.close();
        }

        template <typename Collection>
        void readLines(std::istream& is, Collection* pLines) {
            pLines->clear();
            std::string line;
            while(std::getline(is, line)) {
                // strip \r (for the case of windows line terminators on posix)
                if (line.length() > 0 && *line.rbegin() == '\r')
                    line.erase(line.length()-1, 1);
                stripTrailingLineComments(&line);
                pLines->push_back(line);
            }
        }

        bool addUniqueDependency(Rcpp::CharacterVector include,
                                 std::vector<FileInfo>* pDependencies) {

            // return false if we already have this include
            std::string path = Rcpp::as<std::string>(include);
            for (size_t i = 0; i<pDependencies->size(); ++i) {
                if (pDependencies->at(i).path() == path)
                    return false;
            }

            // add it and return true
            pDependencies->push_back(FileInfo(path));
            return true;
        }

        void parseSourceDependencies(const std::string& sourceFile,
                                     std::vector<FileInfo>* pDependencies) {

            // import R functions
            Rcpp::Environment baseEnv = Rcpp::Environment::base_env();
            Rcpp::Function dirname = baseEnv["dirname"];
            Rcpp::Function filepath = baseEnv["file.path"];
            Rcpp::Function normalizePath = baseEnv["normalizePath"];
            Rcpp::Function fileExists = baseEnv["file.exists"];
            Rcpp::Environment toolsEnv = Rcpp::Environment::namespace_env(
                                                                    "tools");
            Rcpp::Function filePathSansExt = toolsEnv["file_path_sans_ext"];

            // get the path to the source file's directory
            Rcpp::CharacterVector sourceDir = dirname(sourceFile);

            // read the source file into a buffer
            std::stringstream buffer;
            readFile(sourceFile, buffer);

            // Now read into a list of strings (which we can pass to regexec)
            // First read into a std::deque (which will handle lots of append
            // operations efficiently) then copy into an R chracter vector
            std::deque<std::string> lines;
            readLines(buffer, &lines);
            Rcpp::CharacterVector linesVector = Rcpp::wrap(lines);

            // look for local includes
            Rcpp::List matches = regexMatches(
                            linesVector, "^\\s*#include\\s*\"([^\"]+)\"\\s*$");

            // accumulate local includes (skip commented sections)
            CommentState commentState;
            std::vector<FileInfo> newDependencies;
            for (int i = 0; i<matches.size(); i++) {
                std::string line = lines[i];
                commentState.submitLine(line);
                if (!commentState.inComment()) {
                    // get the match
                    const Rcpp::CharacterVector match = matches[i];
                    if (match.size() == 2) {
                        // compose a full file path for the match
                        Rcpp::CharacterVector include =
                            filepath(sourceDir, std::string(match[1]));
                        // if it exists then normalize and add to our list
                        LogicalVector exists = fileExists(include);
                        if (exists[0]) {
                            include = normalizePath(include, "/");
                            if (addUniqueDependency(include, pDependencies)) {
                                newDependencies.push_back(
                                    FileInfo(Rcpp::as<std::string>(include)));
                            }

                            std::vector<std::string> exts;
                            exts.push_back(".cc");
                            exts.push_back(".cpp");
                            for (size_t i = 0; i<exts.size(); ++i) {

                                // look for corresponding cpp file and add it
                                std::string file = Rcpp::as<std::string>(		// #nocov
                                    filePathSansExt(include)) + exts[i];

                                exists = fileExists(file);
                                if (exists[0]) {
                                    if (addUniqueDependency(file,
                                                            pDependencies)) {
                                        FileInfo fileInfo(file);
                                        newDependencies.push_back(fileInfo);
                                    }
                                }
                            }
                        }
                    }
                }
            }

            // look for dependencies recursively
            for (size_t i = 0; i<newDependencies.size(); i++) {
                FileInfo dependency = newDependencies[i];
                parseSourceDependencies(dependency.path(), pDependencies);
            }
        }

        // parse the source dependencies from the passed lines
        std::vector<FileInfo> parseSourceDependencies(
                                         std::string sourceFile) {

            // normalize source file
            Rcpp::Environment baseEnv = Rcpp::Environment::base_env();
            Rcpp::Function normalizePath = baseEnv["normalizePath"];
            sourceFile = Rcpp::as<std::string>(normalizePath(sourceFile, "/"));

            // parse dependencies
            std::vector<FileInfo> dependencies;
            parseSourceDependencies(sourceFile, &dependencies);

            // remove main source file
            dependencies.erase(std::remove(dependencies.begin(),	// #nocov
                                           dependencies.end(),
                                           FileInfo(sourceFile)),
                               dependencies.end());

            return dependencies;
        }

        // Parse embedded R code chunks from a file (receives the lines of the
        // file as a CharcterVector for using with regexec and as a standard
        // stl vector for traversal/insepection)
        std::vector<std::string> parseEmbeddedR(
                                        Rcpp::CharacterVector linesVector,
                                        const std::deque<std::string>& lines) {
            Rcpp::List matches = regexMatches(linesVector,
                                              "^\\s*/\\*{3,}\\s*[Rr]\\s*$");
            bool withinRBlock = false;