Parsing

This section contains definitions declared in the chpl::parsing namespace.

namespace chpl::parsing

Typedefs

using ConfigSettingsList = std::vector<std::pair<std::string, std::string>>

using AttributeToolNamesList = std::vector<UniqueString>

using ModuleVec = std::vector<const uast::Module*>

Functions

const FileContents &fileText(Context *context, std::string path)

This query returns the contents of a file as the string field in the FileContents. In case there is an error reading the file, the error is stored in the error field of the FileContents.

const FileContents &fileText(Context *context, UniqueString path)

Convenience function to call fileText given a UniqueString.

void setFileText(Context *context, std::string path, FileContents result)

This function sets the FileContents that will be returned by the fileText query above.

void setFileText(Context *context, std::string path, std::string text)

This function sets the string that will be returned by the fileText query above. The FileContents stored will have an empty ErrorMessage field.

void setFileText(Context *context, UniqueString path, std::string text)

This function sets the string that will be returned by the fileText query above. The FileContents stored will have an empty ErrorMessage field.

bool hasFileText(Context *context, const std::string &path)

This function returns true if the current revision already has contents stored in the fileText query for the given path.

const uast::BuilderResult &parseFileToBuilderResult(Context *context, UniqueString path, UniqueString parentSymbolPath)

This query reads a file (with the fileText query) and then parses it.

The ‘parentSymbolPath’ is relevant for submodules that are in separate files with ‘module include’. When parsing the included module for a ‘module include’, ‘parentSymbolPath’ should match the symbolPath of the ID of the module containing the ‘module include’ statement.

When parsing a toplevel module, ‘parentSymbolPath’ should be “”.

const uast::BuilderResult &parseFileToBuilderResultAndCheck(Context *context, UniqueString path, UniqueString parentSymbolPath)

Like parseFileToBuilderResult but also runs post-parse checks on the resulting builder result.

const uast::BuilderResult *parseFileContainingIdToBuilderResult(Context *context, ID id)

Like parseFileToBuilderResult but parses whatever file contained ‘id’. Useful for projection queries.

void countTokens(Context *context, UniqueString path, ParserStats *parseStats)

A function for counting the tokens when parsing

const Location &locateId(Context *context, ID id)

This query returns the Location where a particular ID appeared. It cannot be used for Comments because Comments don’t have IDs set. If Locations for Comments are needed, use uast::BuilderResult::commentToLocation

const Location &locateAst(Context *context, const uast::AstNode *ast)

This function just runs locateId on ast->id(). Similarly to locateID, it cannot be used to get a Location for a Comment.

const ModuleVec &parse(Context *context, UniqueString path, UniqueString parentSymbolPath)

This query returns a vector of parsed modules given a file path.

The ‘parentSymbolPath’ is relevant for submodules that are in separate files with ‘module include’. When parsing the included module for a ‘module include’, ‘parentSymbolPath’ should match the symbolPath of the ID of the module containing the ‘module include’ statement.

When parsing a toplevel module, ‘parentSymbolPath’ should be “”.

Unlike ‘parseFileToBuilderResult’ this query will report any errors encountered while parsing to the context.

const ModuleVec &parseToplevel(Context *context, UniqueString path)

Convenience function to parse a file with parentSymbolPath=””. Any errors encountered while parsing are reported to the context.

const std::vector<UniqueString> &moduleSearchPath(Context *context)

Return the current module search path.

void setModuleSearchPath(Context *context, std::vector<UniqueString> searchPath)

Sets the current module search path.

const std::vector<UniqueString> &prependedInternalModulePath(Context *context)

Return a list of paths to be prepended to the internal module path. This is likely to be empty unless using prepend-internal-module-dir when compiling

void setPrependedInternalModulePath(Context *context, std::vector<UniqueString> paths)

Set a list of paths to be prepended to the internal module path. This is typically set using the compiler flag prepend-internal-module-dir and will be called during setupModuleSearchPaths

const std::vector<UniqueString> &prependedStandardModulePath(Context *context)

Return a list of paths to be prepended to the standard module path. This is likely to be empty unless using prepend-standard-module-dir when compiling

void setPrependedStandardModulePath(Context *context, std::vector<UniqueString> paths)

Set a list of paths to be prepended to the standard module path. This is typically set using the compiler flag prepend-standard-module-dir and will be called during setupModuleSearchPaths

UniqueString internalModulePath(Context *context)

Return the current internal module path, i.e. CHPL_HOME/modules/internal/

void setInternalModulePath(Context *context, UniqueString path)

Set the current internal modules directory, i.e. CHPL_HOME/modules/internal/ This should be formed in a consistent manner with setModuleSearchPath, so that this is a prefix for some module search paths.

UniqueString bundledModulePath(Context *context)

Return the current standard module path, i.e. CHPL_HOME/modules/

void setBundledModulePath(Context *context, UniqueString path)

Set the current bundled modules directory, i.e. CHPL_HOME/modules/ This should be formed in a consistent manner with setModuleSearchPath, so that this is a prefix for some module search paths.

void setupModuleSearchPaths(Context *context, const std::string &chplHome, bool minimalModules, const std::string &chplLocaleModel, bool enableTaskTracking, const std::string &chplTasks, const std::string &chplComm, const std::string &chplSysModulesSubdir, const std::string &chplModulePath, const std::vector<std::string> &prependInternalModulePaths, const std::vector<std::string> &prependStandardModulePaths, const std::vector<std::string> &cmdLinePaths, const std::vector<std::string> &inputFilenames)

Helper to call setModuleSearchPath, setInternalModulePath, standardModulePath. This function accepts the path to CHPL_HOME, and any additional module path components (from environment variable and command line).

Most of these arguments have corresponding env / printchplenv settings: chplHome CHPL_HOME chplLocaleModel CHPL_LOCALE_MODEL chplTasks CHPL_TASKS chplComm CHPL_COMM chplSysModulesSubdir CHPL_SYS_MODULES_SUBDIR chplModulePath CHPL_MODULE_PATH

The arguments ‘prependInternalModulePaths’ and ‘prependStandardModulePaths’, if non-empty, allow one to override where the context will search for internal and standard modules, respectively. It will search each successive path in the vector before consulting the default locations.

These arguments facilitate support for frontend flags with similar names, allowing users to diagnose problems with internal/standard modules in the field. Instead of upgrading their Chapel installation, patched versions of problematic modules can be swapped in instead.

void setupModuleSearchPaths(Context *context, bool minimalModules, bool enableTaskTracking, const std::vector<std::string> &cmdLinePaths, const std::vector<std::string> &inputFilenames)

Overload of the more general setupModuleSearchPaths that uses the context’s stored chplHome and chplEnv to determine the values of most arguments.

bool idIsInInternalModule(Context *context, ID id)

Returns true if the ID corresponds to something in an internal module. If the internal module path is empty, this function returns false.

Also considers paths from prepend-internal-module-dir, if any.

bool idIsInBundledModule(Context *context, ID id)

Returns true if the ID corresponds to something in a bundled module. If the bundled module path is empty, this function returns false.

Also considers paths, if any, from prepend-internal-module-dir and prepend-standard-module-dir.

bool idIsInStandardModule(Context *context, ID id)

Returns true if the ID corresponds to something in a standard module. A standard module is a bundled module, but it is not a package module (which may be contributed by users and are not subject to the same constraints as standard modules).

If the bundled module path is empty, this function returns false.

Also considers paths from prepend-standard-module-dir, if any.

bool filePathIsInInternalModule(Context *context, UniqueString filePath)

bool filePathIsInStandardModule(Context *context, UniqueString filePath)

bool filePathIsInBundledModule(Context *context, UniqueString filePath)

const uast::Module *getToplevelModule(Context *context, UniqueString name)

This query parses a toplevel module by name. Returns nullptr if no such toplevel module can be found in the module search path.

const uast::Module *getIncludedSubmodule(Context *context, ID includeModuleId)

This query parses a submodule for ‘include submodule’. Returns nullptr if no such file can be found.

const uast::AstNode *idToAst(Context *context, ID id)

Returns the uast node with the given ID.

uast::AstTag idToTag(Context *context, ID id)

Returns the tag for the node with the given ID.

bool idIsParenlessFunction(Context *context, ID id)

Returns true if the ID is a parenless function.

bool idIsPrivateDecl(Context *context, ID id)

Returns true if the ID refers to a private declaration.

bool idIsFunction(Context *context, ID id)

Returns true if the ID is a function.

bool idIsMethod(Context *context, ID id)

Returns true if the ID is a method.

UniqueString fieldIdToName(Context *context, ID id)

If the ID represents a field in a record/class/union, returns the name of that field. Otherwise, returns the empty string.

bool idIsField(Context *context, ID id)

Returns true if the ID is a field in a record/class/union.

const ID &idToParentId(Context *context, ID id)

Returns the parent ID given an ID

const uast::AstNode *parentAst(Context *context, const uast::AstNode *node)

Returns the parent AST node given an AST node

ID idToParentModule(Context *context, ID id)

Returns the ID for the module containing the given ID, or the empty ID when given a toplevel module.

uast::Function::ReturnIntent idToFnReturnIntent(Context *context, ID id)

Given an ID that represents a Function, get the declared return intent for that function.

bool idIsFunctionWithWhere(Context *context, ID id)

Returns ‘true’ if the passed ID represents a Function with a where clause, and ‘false’ otherwise.

ID idToContainingMultiDeclId(Context *context, ID id)

Given an ID for a Variable, returns the ID of the containing MultiDecl or TupleDecl, if any, and the ID of the variable otherwise.

bool idContainsFieldWithName(Context *context, ID typeDeclId, UniqueString fieldName)

Given an ID for a Record/Union/Class Decl, returns ‘true’ if the passed name is the name of a field contained in it.

ID fieldIdWithName(Context *context, ID typeDeclId, UniqueString fieldName)

Given an ID for a Record/Union/Class Decl, and a field name, returns the ID for the Variable declaring that field.

bool aggregateUsesForwarding(Context *context, ID typeDeclId)

Given an ID for a Record/Union/Class Decl, returns ‘true’ if that Record/Union/Class Decl directly contains one or more ‘forwarding’ declarations.

void setConfigSettings(Context *context, ConfigSettingsList keys)

Store config settings that were set from the command line using -s flags

const ConfigSettingsList &configSettings(Context *context)

Get any config settings that were set from the command line and stored

void setAttributeToolNames(Context *context, AttributeToolNamesList keys)

const AttributeToolNamesList &AttributeToolNames(Context *context)

const uast::AttributeGroup *idToAttributeGroup(Context *context, ID id)

Given an ID, returns the attributes associated with the ID. This is important to use or else attributes for children of MultiDecls or TupleDecls will not be found.

const uast::AttributeGroup *astToAttributeGroup(Context *context, const uast::AstNode *node)

Given an AstNode, returns the attributes associated with it. This is important to use or else attributes for children of MultiDecls or TupleDecls will not be found.

void reportDeprecationWarningForId(Context *context, ID idMention, ID idTarget)

Given an ID ‘idMention’ representing a mention of a symbol, and an ID ‘idTarget’ representing the symbol, determine if a deprecation warning should be produced for ‘idTarget’ at ‘idMention’. If so, the warning will be reported to the context.

A warning will be reported to the context only once per revision. It may not be reported if the context or compiler is configured to suppress deprecation warnings.

The ‘idMention’ may refer to any AST but will most often be an Identifier. The ‘idTarget’ should refer to a NamedDecl. If it does not, then nothing is reported.

bool shouldWarnUnstableForPath(Context *context, UniqueString filepath)

Returns the state of warn-unstable or -internal or -standard depending on which of these applies to ‘filepath’.

bool shouldWarnUnstableForId(Context *context, const ID &id)

Returns the state of warn-unstable or -internal or -standard depending on which of these applies to ‘id’.

void reportUnstableWarningForId(Context *context, ID idMention, ID idTarget)

Given an ID ‘idMention’ representing a mention of a symbol, and an ID ‘idTarget’ representing the symbol, determine if an unstable warning should be produced for ‘idTarget’ at ‘idMention’. If so, the warning will be reported to the context.

A warning will be reported to the context only once per revision. It may not be reported if the context or compiler is configured to suppress unstable warnings.

The ‘idMention’ may refer to any AST but will most often be an Identifier. The ‘idTarget’ should refer to a NamedDecl. If it does not, then nothing is reported.

uast::Module::Kind idToModuleKind(Context *context, ID id)

const uast::BuilderResult &parseFile(Context *context, UniqueString path)

class FileContents

#include <FileContents.h>

This class represents the result of reading a file.

Public Functions

inline FileContents()

Construct a FileContents containing empty text and no error

inline FileContents(std::string text)

Construct a FileContents containing the passed text and no error

inline FileContents(std::string text, const ErrorBase *error)

Construct a FileContents containing the passed text and error

inline const std::string &text() const

Return a reference to the contents of this file

inline const ErrorBase *error() const

Return a reference to an error encountered when reading this file

inline bool operator==(const FileContents &other) const

inline bool operator!=(const FileContents &other) const

inline void swap(FileContents &other)

inline void mark(Context *context) const

Public Static Functions

static inline bool update(FileContents &keep, FileContents &addin)

class Parser

#include <Parser.h>

A class for parsing

Public Functions

~Parser() = default

inline Context *context()

Return the AST Context used by this Parser.

uast::BuilderResult parseFile(const char *path, ParserStats *parseStats = nullptr)

Parse a file at a particular path.

uast::BuilderResult parseString(const char *path, const char *str, ParserStats *parseStats = nullptr)

Parse source code in a string. ‘path’ is only used for certain errors.

Public Static Functions

static Parser createForTopLevelModule(Context *context)

Construct a parser for parsing a top-level module

static Parser createForIncludedModule(Context *context, UniqueString parentSymbolPath)

Construct a parser for parsing an included module. ‘parentSymbolPath’ is the symbol path component of the ID of the module containing the ‘module include’ statement.

struct ParserStats

Public Functions

ParserStats()

ParserStats(bool printTokens)