Base

This section contains a selection of the definitions declared in the chpl namespace. The entries may not be exhaustive.

using chpl::ChplEnvMap = std::unordered_map<std::string, std::string>
class CommentID

This class represents a unique ID for a comment It is separate from ID because it does not participate in the query system

Public Functions

CommentID() = default
inline CommentID(int index)
inline int index() const

Return the index of the comment id

inline void serialize(Serializer &ser) const

Public Static Functions

static inline CommentID deserialize(Deserializer &des)
class Context

This Context class stores the compilation-wide context. Another name for this compilation-wide context is program database. It handles unique’d strings and also stores the results of queries (so that they are are memoized). It tracks dependencies of queries in order to update them appropriately when a dependency changes.

Please see Query Framework for more information about how to implement queries and how the query framework functions.

Public Types

enum QueryStatus

Values:

enumerator NOT_CHECKED_NOT_CHANGED
enumerator REUSED
enumerator CHANGED

Public Functions

inline RecomputeMarker markRecomputing(bool isRecomputing)
Context()

Create a new Context without specifying chplHome or any other Configuration settings.

Context(Configuration config)

Create a new Context while specifying a Configuration.

Context(Context &consumeContext, Configuration newConfig)

Create a new Context by consuming the contents of another Context context while changing Configuration. The passed Context will no longer be usable. Assumes that any queries that have run so far do not depend on the Configuration settings that have changed.

This function is useful during compiler start up.

~Context()
inline const Configuration &configuration() const

Return the Configuration used by this Context

const std::string &chplHome() const

Return the configured CHPL_HOME directory

const std::string &tmpDir()

Return a temporary directory that can be used by this process. It is typically a subdirectory of ‘/tmp’ that will be removed when the Context is destroyed. If it does not exist yet, create it.

bool shouldSaveTmpDirFiles() const

Returns ‘true’ if this Context is configured to save the temporary directory (with keepTmpDir=true).

std::string tmpDirAnchorFile()

Return a path to a file within tmpDir that is not modified after it is created, to serve as a source for normalizing modification times

void cleanupTmpDirIfNeeded()

Delete the temporary directory if needed. This function can be called during program exit.

void setDetailedErrorOutput(bool useDetailed)

Change whether or not this Context is configured for detailed error/warning output (vs brief output).

UniqueString adjustPathForErrorMsg(UniqueString path)

Normalize a path for output in an error message by replacing any prefix with the value of CHPL_HOME with the string $CHPL_HOME

llvm::ErrorOr<const ChplEnvMap&> getChplEnv()

Run printchplenv, or return a cached result of doing so. To get output, CHPL_HOME must have been provided via the constructor; otherwise, the resulting map will be empty.

inline owned<ErrorHandler> installErrorHandler(owned<ErrorHandler> substitute)

Consume the currently installed error handler. If ‘substitute’ is not nullptr, the context will use the substitute error handler. Otherwise, the context will revert to using the default error handler.

inline ErrorHandler *errorHandler()

Get a mutable pointer to the currently installed error handler.

template<typename F>
inline RunResult<decltype(f(this))> runAndTrackErrors(F &&f)

Execute a function or lambda using the context, and track whether or not errors occurred while doing so. Errors emitted from inside the function are not shown to the user.

optional<std::vector<TraceElement>> recoverFromSelfRecursion() const
const char *uniqueCString(const char *s, size_t len)

Get or create a unique string and return it as a C string. If the passed string is NULL, this function will return an empty string.

Unique strings are limited to 2**31 bytes.

The returned string will store len bytes, even if there are interior NULL bytes. It will be NULL terminated either way.

Strings returned by this function will always be aligned to 2 bytes.

The function UniqueString::get returns such a string with a wrapper type. It should be preferred for type safety and to reduce redundant checks.

const char *uniqueCString(const char *s)

Calls uniqueCString with len=strlen(s). This simpler call can be used for C strings that don’t contain zero bytes other than the terminator.

const char *uniqueCStringConcatLen(const char *s1, size_t len1, const char *s2, size_t len2, const char *s3 = nullptr, size_t len3 = 0, const char *s4 = nullptr, size_t len4 = 0, const char *s5 = nullptr, size_t len5 = 0, const char *s6 = nullptr, size_t len6 = 0, const char *s7 = nullptr, size_t len7 = 0, const char *s8 = nullptr, size_t len8 = 0, const char *s9 = nullptr, size_t len9 = 0)

Get or create a unique string by concatenating up to 9 strings with lengths.

const char *uniqueCStringConcat(const char *s1, const char *s2, const char *s3 = nullptr, const char *s4 = nullptr, const char *s5 = nullptr, const char *s6 = nullptr, const char *s7 = nullptr, const char *s8 = nullptr, const char *s9 = nullptr)

Get or create a unique string by concatenating up to 9 strings.

void markUniqueCString(const char *s)

When the context is configured to run with garbage collection enabled, unique strings that are reused need to be marked. This function does that for a C string stored in the map. It will cause program crashes if called on a string that is not the result of one of the uniqueCString calls.

template<typename T>
inline void markUnownedPointer(const T *ptr)

This function can be called by a mark method to perform checking on pointers and any UniqueStrings that they contain when asserts are enabled.

Pointers available to a mark method should have already been returned by previous queries as owned objects and so markOwnedPointer should have been called on them if they have been reused.

template<typename T>
inline void markOwnedPointer(const T *ptr)

This function can be called by a mark method to mark UniqueStrings within an owned pointer.

template<typename T>
inline void markPointer(const owned<T> &ptr)

markPointer can be used to mark a pointer, where it is considered owned if the type is owned.

This overload just calls markOwnedPointer.

template<typename T>
inline void markPointer(const T *ptr)

markPointer can be used to mark a pointer, where it is considered owned if the type is owned.

This overload just calls markUnownedPointer.

bool filePathForId(ID id, UniqueString &pathOut, UniqueString &parentSymbolPathOut)

Return ‘true’ if the filePathForId was found (which can only happen because setFilePathForModuleID was already called for this ID).

Returns the path by setting ‘pathOut’. Returns the parent symbol path (relevant for ‘module include’) by setting ‘parentSymbolPathOut’.

bool filePathForId(ID id, UniqueString &pathOut)

Return ‘true’ if the filePathForId was found (which can only happen because setFilePathForModuleID was already called for this ID).

Returns the path by setting ‘pathOut’.

void setFilePathForModuleId(ID moduleID, UniqueString path)

Sets the file path for the given module ID. This is suitable to call from a parse query.

bool pathIsInLibrary(UniqueString filePath, UniqueString &pathOut)

Return ‘true’ if the given file path can be handled by a library file (experimental).

Returns the library’s path by setting ‘pathOut’.

bool moduleIsInLibrary(ID moduleId, UniqueString &pathOut)

Return ‘true’ if the given module ID is supported by a library file.

Returns the library’s path by setting ‘pathOut’.

void registerLibraryForModule(ID moduleId, UniqueString filePath, UniqueString libPath)

Register a module ID and file path to be supported by a library file.

void advanceToNextRevision(bool prepareToGC)

This function increments the current revision number stored in the context. After it is called, the setters below can be used to provide the input at that revision.

If the prepareToGC argument is true, when processing queries in that revision, will prepare to garbage collect UniqueStrings (by marking elements appropriately).

inline int numQueriesRunThisRevision() const

Returns the number of query bodies executed in this revision.

void collectGarbage()

This function runs garbage collection. It will collect UniqueStrings if the last call to advanceToNextRevision passed prepareToGC=true.

It is an implementation error to call this function while a query is running.

void report(owned<ErrorBase> error)

Note an error for the currently running query and report it with the error handler set by setErrorHandler.

If no query is currently running, it just reports the error.

void error(Location loc, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in a Location and a printf-style format string.

void error(ID id, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in an ID and a printf-style format string. The ID is used to compute a Location using parsing::locateId.

void error(const IdOrLocation &loc, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in an IdOrLocation and a printf-style format string.

void error(const uast::AstNode *ast, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in an AST node and a printf-style format string. The AST node is used to compute a Location by using a parsing::locateAst.

void error(const resolution::TypedFnSignature *inFn, const uast::AstNode *ast, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in a TypedFnSignature and an AST node and a printf-style format string. The AST node is used to compute a Location by using a parsing::locateAst. The TypedFnSignature is used to print out instantiation information.

void setDebugTraceFlag(const bool enable)

Sets the enableDebugTrace flag. This was needed because the context in main gets created before the arguments to the compiler are parsed.

void setBreakOnHash(const size_t hashVal)
inline void setQueryTimingFlag(bool enable)

Enables/disables timing each query execution. This does not output anything to stdout / a file / etc. To see the results, call queryTimingReport.

void beginQueryTimingTrace(const std::string &outname)

Begin query timing trace, sending the trace to outname

void endQueryTimingTrace()

End query timing trace, closes out stream

template<typename ResultType, typename ...ArgTs>
QueryStatus queryStatus(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns: 0 if the query was not checked or changed in this revision 1 if the query was checked but not changed in this revision 2 if the query was changed in this revision

This is intended only as a debugging aid.

template<typename ResultType, typename ...ArgTs>
bool hasCurrentResultForQuery(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns ‘true’ if the system already has a result for the passed query in the current revision. This can be useful for certain input queries - e.g. one reading a file that can both have the contents set and can also read the data from the filesystem.

template<typename ResultType, typename ...ArgTs>
bool isQueryRunning(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns ‘true’ if the query in question is currently running. This can be useful for avoiding recursion in certain cases.

template<typename ResultType, typename ...ArgTs>
const querydetail::QueryMap<ResultType, ArgTs...>::MapType *querySavedResults(const ResultType &(*queryFunction)(Context *context, ArgTs...))
inline bool isResultUpToDate(const querydetail::QueryMapResultBase &resultEntry) const

Public Static Functions

static void defaultReportError(Context *context, const ErrorBase *err)

Report the error to standard error output.

static size_t lengthForUniqueString(const char *s)

For a unique string, return the length of the string when it was created. It will cause program crashes if called on a string that is not the result of one of the uniqueCString calls.

struct Configuration

This struct stores configuration information to use when constructing a Context.

Public Functions

void swap(Configuration &other)

Public Members

std::string chplHome

Used for determining Chapel environment variables

std::unordered_map<std::string, std::string> chplEnvOverrides
std::string tmpDir

Temporary directory in which to store files. If it is “”, it will be set to something like /tmp/chpl-1234/. It will be deleted when the context is deleted, unless keepTmpDir is true.

bool keepTmpDir = false

If ‘true’, the tmpDir will not be deleted.

std::string toolName = "chpl"

Tool name (for use when creating the tmpDir in /tmp if needed)

bool includeComments = true

If ‘true’, some comments will be included in the uAST.

Note that, even when this is set, some comments are not included (for example, comments between actual arguments in a function call

bool disableErrorBreakpoints = false

Disable breakpoint in Context::report.

class ErrorCollectionEntry

Public Functions

inline const querydetail::QueryMapResultBase *collectingQuery() const
void storeError(owned<ErrorBase> toStore) const

Public Static Functions

static ErrorCollectionEntry createForTrackingQuery(std::vector<owned<ErrorBase>>*, const querydetail::QueryMapResultBase*)

When a parent query starts tracking errors, the tracking entry contains this parent query and the vector. Errors occurring within child queries are stored into the vector, and not reporter to the user.

static ErrorCollectionEntry createForRecomputing(const querydetail::QueryMapResultBase*)

When recomputing queries (to determine if a cached result should be used), a parent query may not be running that expects to receive an error list back, because computations are done bottom-up. Thus, simply track the query that enabled error collection, but do not store the errors anywhere. They will be added to a vector, if necessary, when the saved query result is used when the parent query is re-run.

class ErrorHandler

This ErrorHandler class is used by the context to report errors. It can be subclassed to override its behavior. The default subclass used by the context will print the errors.

Public Functions

virtual ~ErrorHandler() = default
virtual void report(Context *context, const ErrorBase *err) = 0
class RecomputeMarker

Public Functions

inline RecomputeMarker(RecomputeMarker &&other)
inline RecomputeMarker &operator=(RecomputeMarker &&other)
inline void restore()
inline ~RecomputeMarker()
template<typename T>
class RunResult : public chpl::Context::RunResultBase

Public Functions

inline T &result()

The result of the execution.

class RunResultBase

Subclassed by chpl::Context::RunResult< T >

Public Functions

~RunResultBase()
RunResultBase()
RunResultBase(const RunResultBase &other)
inline std::vector<owned<ErrorBase>> &errors()

The errors that occurred while running.

inline const std::vector<owned<ErrorBase>> &errors() const
bool ranWithoutErrors() const

Checks if any syntax errors or errors occurred while running. Warnings do not cause this method to return false.

class ErrorMessage : public chpl::IdOrLocation

This class represents an error/warning message. The message is saved (in the event it needs to be reported again).

Public Types

enum Kind

Values:

enumerator NOTE
enumerator WARNING
enumerator SYNTAX
enumerator ERROR

Public Functions

ErrorMessage(Kind kind, IdOrLocation idOrLoc, std::string message)
void addDetail(ErrorMessage err)

Add an ErrorMessage as detail information to this ErrorMessage.

inline bool isEmpty() const

Returns true is this error message has no message and no details. Even if the error is empty, it may still be meaningful in the case of e.g., a syntax error (where the location offers useful info).

inline const std::string &message() const
inline const std::vector<ErrorMessage> &details() const
inline Kind kind() const
inline bool operator==(const ErrorMessage &other) const
inline bool operator!=(const ErrorMessage &other) const
enum chpl::ErrorType

Enum representing the different types of errors in Dyno.

Values:

enumerator General
class ErrorWriterBase

ErrorWriterBase is the main way for error messages to output diagnostic information. It abstracts away writing code to output streams (in fact, some instances of ErrorWriterBase do not write to a stream at all), and provides functionality like printing and underlining code. The way data is formatted when fed to the various printing functions like ErrorWriterBase::heading and ErrorWriterBase::message is specified by specializations of the errordetail::Writer class.

The ErrorWriterBase expects that the ErrorWriterBase::heading function be called first by every error message; this function serves the double purpose of printing out the error heading, as well as setting the error message’s location.

Subclassed by chpl::CompatibilityWriter, chpl::ErrorWriter

Public Types

enum OutputFormat

The style of error reporting that the ErrorWriterBase should produce.

Values:

enumerator DETAILED

Specify that all information about the error should be printed.

enumerator BRIEF

Specify that only key parts of the error should be printed.

Public Functions

template<typename LocationType, typename ...Ts>
inline void heading(ErrorBase::Kind kind, ErrorType type, LocationType loc, Ts... ts)

Write the error heading, possibly with some color and text decoration. The location given to this function and its overloads is considered the error’s main location.

The variable arguments given to this function are automatically converted to strings.

template<typename LocationType, typename ...Ts>
inline void headingVerbatim(ErrorBase::Kind kind, ErrorType type, LocationType loc, Ts... ts)

Same as ErrorWriter::heading, but doesn’t tweak the resulting error message to remove punctuation.

template<typename ...Ts>
inline void message(Ts... ts)

Write a message about the error. Messages provide additional context or flow to detailed error output. They are ignored in brief mode.

The variable arguments given to this function are automatically converted to strings.

template<typename LocationType, typename ...Ts>
inline void note(LocationType loc, Ts... ts)

Write a note about the error. Unlike messages, notes are printed even in brief mode. Thus, notes can be used to provide information that is useful “in all cases” (e.g., the location of a duplicate definition).

The variable arguments given to this function are automatically converted to strings.

template<typename LocationType, typename ...Ts>
inline void noteVerbatim(ErrorBase::Kind kind, ErrorType type, LocationType loc, Ts... ts)

Same as ErrorWriter::note, but doesn’t tweak the resulting error message to remove punctuation.

template<typename LocHighlight = const uast::AstNode*, typename LocPlace>
inline void code(const LocPlace &place, const std::vector<LocHighlight> &toHighlight = {})

Prints the lines of code associated with the given location. Additional locations provided via toHighlight field are underlined when the code is printed.

This function accepts any type for which location can be inferred, for both the main location and the highlights.

template<typename LocPlace>
inline void codeForDef(const LocPlace &place)

Specialization of ErrorWriter::code for printing definitions. Since definitions may be fairly length (e.g., a variable with a multi-line initializer), this will only print the first line of the definition.

template<typename LocPlace>
inline void codeForLocation(const LocPlace &place)

Specialization of ErrorWriter::code for “bla bla defined here”. Doesn’t underline, but also doesn’t print the whole thing. This is important, for instance, in the case that a record declaration is being printed. We don’t want to dump all the fields / methods as part of the error.

class ErrorWriter : public chpl::ErrorWriterBase

Implementation of ErrorWriterBase that prints error output to a stream. This class’ output varies depending on if the error message is printed in brief or detailed mode, as well as if the useColor flag is set.

Public Functions

inline ErrorWriter(Context *context, std::ostream &oss, ErrorWriterBase::OutputFormat outputFormat, bool useColor)
void writeNewline()
class CompatibilityWriter : public chpl::ErrorWriterBase

Implementation of ErrorWriterBase that records calls to the various API functions in order to retrieve information from ErrorMessages.

Public Functions

inline CompatibilityWriter(Context *context)
inline virtual void writeHeading(ErrorBase::Kind kind, ErrorType type, IdOrLocation idOrLoc, const std::string &message) override

Write the error heading, possibly with some color and text decoration. The location given to this function and its overloads is considered the error’s main location.

inline virtual void writeMessage(const std::string &message) override

Write additional information about the error. This information is only included when the error is reported in detailed mode; when printed in brief mode, information printed via writeMessage is omitted.

inline virtual void writeCode(const Location &loc, const std::vector<Location> &hl) override

Prints the lines of code associated with the given location. Additional locations provided via toHighlight parameter are underlined when the code is printed.

inline virtual void writeNote(IdOrLocation loc, const std::string &message) override

Write a note about the error. Unlike messages, notes are printed even in brief mode. Thus, notes can be used to provide information that is useful “in all cases” (e.g., the location of a duplicate definition).

inline ID id() const

Get the error’s ID (could be empty in favor of the location).

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

inline Location location() const

Get the error’s location (could be empty in favor of the ID)

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

inline Location computedLocation() const

Return the location that should be reported to the user.

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

inline const std::string &message() const

Return the error’s brief message.

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

inline const std::vector<ErrorNote> &notes() const

Return the error’s notes / details.

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

inline const std::vector<ErrorCodeSnippet> &codeSnippets() const

Return the error’s code snippets.

This only works after ErrorBase::write was invoked with this CompatibilityWriter.

class ErrorBase

Parent class for all errors in Dyno.

The most important part of defining a new error is implementing the ErrorBase::write method; see its documentation for the implementation strategy.

Most sub-classes of ErrorBase should be defined by adding them to error-classes-list

Subclassed by chpl::BasicError

Public Types

enum Kind

Values:

enumerator NOTE
enumerator WARNING
enumerator SYNTAX
enumerator ERROR

Public Functions

virtual ~ErrorBase() = default
inline Kind kind() const

Get the error’s kind

inline ErrorType type() const

Get the error’s type

std::string message() const

Extract the error’s summary error message.

Location location(Context *context) const

Extract the error’s location.

ErrorMessage toErrorMessage(Context *context) const

Convert the error to an ErrorMessage. This is mostly needed for compatibility reasons, since the production compiler currently knows how to print ErrorMessage, and does it differently from our ErrorBase::write methods.

inline bool operator==(const ErrorBase &other) const
inline bool operator!=(const ErrorBase &other) const
virtual void write(ErrorWriterBase &wr) const = 0

Write information about this error to the given writer. See the ErrorWriterBase class for the API available to the error messages.

This method should call methods on the ErrorWriterBase class to provide information about the error. All ErrorBase::write implementations must call ErrorWriterBase::heading to provide a concise description of the error message. After this, ErrorWriterBase::note can be used to print notes, which are always shown to the user. ErrorWriterBase::message along with ErrorWriterBase::code can be used to print additional text and code, respectively, which is only shown when the error is printed in detail.

virtual void mark(Context *context) const = 0
virtual owned<ErrorBase> clone() const = 0

Public Static Functions

static const char *getKindName(Kind kind)
static const char *getTypeName(ErrorType type)
template<typename T>
static inline bool update(owned<T> &old, owned<T> &addin)
class BasicError : public chpl::ErrorBase

An error without a specific type, and lacking (typed) additional information about what happened.

Subclassed by chpl::GeneralError

Public Functions

virtual void write(ErrorWriterBase &eq) const override

Write information about this error to the given writer. See the ErrorWriterBase class for the API available to the error messages.

This method should call methods on the ErrorWriterBase class to provide information about the error. All ErrorBase::write implementations must call ErrorWriterBase::heading to provide a concise description of the error message. After this, ErrorWriterBase::note can be used to print notes, which are always shown to the user. ErrorWriterBase::message along with ErrorWriterBase::code can be used to print additional text and code, respectively, which is only shown when the error is printed in detail.

virtual void mark(Context *context) const override
class GeneralError : public chpl::BasicError

An error without specific information. Used when no error class has yet been specified for the specific error condition.

Public Functions

virtual owned<ErrorBase> clone() const override

Public Static Functions

static owned<GeneralError> vbuild(ErrorBase::Kind kind, ID id, const char *fmt, va_list vl)
static owned<GeneralError> vbuild(ErrorBase::Kind kind, Location loc, const char *fmt, va_list vl)
static owned<GeneralError> vbuild(ErrorBase::Kind kind, IdOrLocation loc, const char *fmt, va_list vl)
static owned<GeneralError> get(ErrorBase::Kind kind, Location loc, std::string msg)
static owned<GeneralError> error(Location loc, std::string msg)
class ID

This class represents an ID for an AST node. AST element IDs can be helpful for creating maps with AST elements as keys. All AST nodes have IDs.

Public Types

enum FabricatedIdKind

Values:

enumerator ExternBlockElement
enumerator Generated

Public Functions

ID() = default

Construct an empty ID

inline ID(UniqueString symbolPath, int postOrderId, int numChildIds)

Construct an ID with a symbol path and postorder traversal number

inline explicit ID(UniqueString symbolPath)

Construct an ID with specified symbol path, and default postorder traversal number.

inline UniqueString symbolPath() const

Return a path to the ID symbol scope. For example, a function ‘foo’ declared in a module M would have symbolPath M.foo.

Functions, class/record/union/enum declarations, and modules create new ID symbol scopes.

UniqueString symbolPathWithoutRepeats(Context *context) const

Return a path to the ID symbol scope, but without taking into account repeated names within a symbol. In particular, M.f#0 and M.f#1 would both return M.f.

This is useful for exposing a “user-facing” path, such as one that a user can specify from the command line.

inline int postOrderId() const

Returns the numbering of this node in a postorder traversal of a symbol’s nodes. When the AST node defines a new ID symbol scope, (as with Function or Module) this will return -1.

inline bool isSymbolDefiningScope() const

Returns ‘true’ if this symbol has a ‘postOrderId()’ value of == -1, which means this is an ID for something that defines a new symbol scope.

inline bool isFabricatedId() const

Some IDs are introduced during compilation and don’t represent something that is directly contained within the source code. This function will return ‘true’ for such IDs.

inline FabricatedIdKind fabricatedIdKind() const
inline int numContainedChildren() const

Return the number of ids contained in this node, not including itself. In the postorder traversal numbering, the ids contained appear before the node.

The node with postorder traversal ID postOrderId() - numChildIds() is the first node contained within this node.

E.g. in this notional AST: Node(LeafA LeafB)

LeafA has id 0 and numContainedIds 0 LeafB has id 1 and numContainedIds 0 Node has id 2 and numContainedIds 2

Note that the number of contained children does not include contained IDs with a different symbol scope. So, for example, a module consisting only of a function declaration would have numContainedChildren() == 0.

ID parentSymbolId(Context *context) const

Returns a new ID for the parent symbol ID.

if postOrderId is >= 0, returns the id with postOrderId == -1 if postOrderId is -1, returns the id from removing the last ‘.bla’ part from the symbolPath.

If this ID has no parent, returns an empty ID.

The returned ID always has numContainedChildren() of 0 and it cannot be used with contains(). However it is suitable for use in looking up an ID in a map.

UniqueString symbolName(Context *context) const

If the ID represents a symbol, return the name of that symbol. Otherwise, return the name of the symbol that contains the ID.

bool contains(const ID &other) const

returns ‘true’ if the AST node with this ID contains the AST node with the other ID, including if they refer to the same AST node.

int compare(const ID &other) const

compare this ID with another ID result < 0 if this < other result == 0 if this == other result > 0 if this > other

inline bool operator==(const ID &other) const
inline bool operator!=(const ID &other) const
inline bool operator<(const ID &other) const
inline bool operator<=(const ID &other) const
inline bool operator>(const ID &other) const
inline bool operator>=(const ID &other) const
inline bool isEmpty() const
inline explicit operator bool() const
inline size_t hash() const
inline void swap(ID &other)
inline void mark(Context *context) const
void stringify(std::ostream &ss, StringifyKind stringKind) const
std::string str() const

Return a string encoding this ID

inline void serialize(Serializer &ser) const

Public Static Functions

static ID fabricateId(Context *context, ID parentSymbolId, UniqueString name, FabricatedIdKind kind)

Create an ID that represents something that isn’t directly contained in the source code but rather something created during compilation. In order to keep postorder ID numbering intact, there are some constraints: Such an ID can only be added within another ID that is a symbol (e.g. within a Module, Function, Record; but not within a Block). Such an ID can itself only be a symbol

Also note that even though a fabricated ID will report as being contained within another ID (with ID::contains), uAST traversal will never find it.

static UniqueString parentSymbolPath(Context *context, UniqueString symbolPath)

Given a symbol path, return the parent symbol path. Returns an empty string if the symbol path was empty string.

static UniqueString innermostSymbolName(Context *context, UniqueString symbolPath)

Given a symbol path, return the name of the innermost symbol

static std::vector<std::pair<UniqueString, int>> expandSymbolPath(Context *context, UniqueString symbolPath)

Given a symbol path, expand it into a vector of pairs, containing the path component and the repeat number.

static bool update(ID &keep, ID &addin)
static ID fromString(Context *context, const char *idStr)

The inverse of str() &#8212; converts a string encoding an ID to an ID

static inline ID deserialize(Deserializer &des)
class Location

This class represents a source location.

Public Functions

Location() = default
inline explicit Location(UniqueString path, int firstLine = -1, int firstColumn = -1, int lastLine = -1, int lastColumn = -1)
inline explicit Location(UniqueString path, std::tuple<int, int> start, std::tuple<int, int> end)
inline bool isEmpty() const
inline explicit operator bool() const
inline bool isValid() const
inline UniqueString path() const
inline int firstLine() const
inline int firstColumn() const
inline int lastLine() const
inline int lastColumn() const
inline int line() const
inline std::tuple<int, int> start() const
inline std::tuple<int, int> end() const
inline bool operator==(const Location &other) const
inline bool operator!=(const Location &other) const
inline void swap(Location &other)
inline void mark(Context *context) const
inline size_t hash() const
inline bool contains(const Location &loc)

Returns ‘true’ if this contains ‘loc’ or if this and ‘loc’ are equal. Returns ‘false’ if either this or ‘loc’ are empty, or if paths do not match.

inline bool operator>(const Location &rhs)

Determine if this location is greater than the location ‘rhs’ without considering paths.

void stringify(std::ostream &os, StringifyKind stringifyKind) const
inline void serialize(Serializer &ser) const

Public Static Functions

static bool update(Location &keep, Location &addin)
static inline Location deserialize(Deserializer &des)
class IdOrLocation

Subclassed by chpl::ErrorMessage

Public Functions

IdOrLocation() = default
inline IdOrLocation(ID id)
inline IdOrLocation(Location location)
Location computeLocation(Context *context) const

Return the location in the source code where this error occurred.

inline const ID &id() const
inline const Location &location() const
inline bool operator==(const IdOrLocation &other) const
inline void mark(Context *context) const

Public Static Functions

static IdOrLocation createForCommandLineLocation(Context *context)
class UniqueString

This class represents a unique’d string. Unique’d strings allow: fast == and != not worrying about freeing them

Public Functions

inline UniqueString()

create a UniqueString storing the empty string

inline UniqueString(detail::PODUniqueString s)

create a UniqueString from a PODUniqueString. this constructor intentionally allows implicit conversion.

inline const char *c_str() const

Return the null-terminated string. The returned pointer may refer to invalid memory if the UniqueString goes out of scope.

inline size_t length() const

Return the length of the unique string.

inline const char *astr(Context *context) const

Return the null-terminated string as a pointer to an entry in Context’s string table. This pointer is safe to use after this UniqueString goes out of scope.

inline std::string str() const

return a std::string containing the string

inline llvm::StringRef stringRef()

Returns a reference to the string as an llvm::StringRef

void stringify(std::ostream &ss, chpl::StringifyKind stringKind) const
void serialize(Serializer &ser) const
inline bool isEmpty() const
inline detail::PODUniqueString podUniqueString() const
inline bool startsWith(const char *prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool startsWith(const UniqueString prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool startsWith(const std::string &prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool endsWith(const char *suffix) const

Checks to see if the string ends with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool endsWith(const UniqueString suffix) const

Checks to see if the string ends with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool endsWith(const std::string &suffix) const

Checks to see if the string ends with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool operator==(const UniqueString other) const
inline bool operator==(const char *other) const

Checks to see if the string contents match a C string.

Note

will only compare up to the first null byte.

inline bool operator==(const std::string &other) const

Checks to see if the string contents match a C++ std::string.

Note

will only compare up to the first null byte.

inline bool operator!=(const UniqueString other) const
inline bool operator!=(const char *other) const
inline bool operator!=(const std::string &other) const
inline bool operator<(const UniqueString other) const
inline bool operator<=(const UniqueString other) const
inline bool operator>(const UniqueString other) const
inline bool operator>=(const UniqueString other) const
int compare(const UniqueString other) const

Returns: -1 if this string is less than the passed string 0 if they are the same 1 if this string is greater

int compare(const char *other) const
inline size_t hash() const
inline void swap(UniqueString &other)
inline void mark(Context *context) const

Public Static Functions

static inline UniqueString get(Context *context, const char *s)

Get or create a unique string for a NULL-terminated C string. If NULL is provided, this function will return the UniqueString representing “”.

static inline UniqueString getConcat(Context *context, const char *s1, const char *s2, const char *s3 = nullptr, const char *s4 = nullptr, const char *s5 = nullptr, const char *s6 = nullptr, const char *s7 = nullptr, const char *s8 = nullptr, const char *s9 = nullptr)

Get or create a unique string by concatenating up to 9 input C strings. These input strings cannot contain null bytes other than the null terminator.

static UniqueString get(Context *context, const char *s, size_t len)

Get or create a unique string for a string from a pointer and a length. If the length is 0, this function will return the UniqueString representing “”. The length can be passed to truncate a string. The string can contain zero bytes.

static inline UniqueString get(Context *context, const std::string &s)

Get or create a unique string for a C++ string.

static inline UniqueString get(Context *context, llvm::StringRef s)

Get or create a unique string for an LLVM StringRef.

static UniqueString deserialize(Deserializer &des)
static bool update(UniqueString &keep, UniqueString &addin)
template<typename C>
class Iterable

Defines a read-only iterator over elements of a container type C

Public Functions

inline Iterable(const C &c)
inline C::const_iterator begin() const
inline C::const_iterator end() const
class Bitmap

Bitmap just stores a bunch of bits. It’s more or less like vector<bool> but we have a different type to make using it less confusing.

Public Functions

inline Bitmap()

Construct a Bitmap storing no bits

inline void resize(size_t n)

Resizes this Bitmap to store n bits

inline size_t size() const

Returns the number of bits stored in this Bitmap

inline bool operator[](size_t i) const

Returns the value of bit index i

inline void setBit(size_t i, bool value)

Set the value of bit index i

inline bool operator==(const Bitmap &other) const
inline bool operator!=(const Bitmap &other) const
inline void swap(Bitmap &other)
inline void mark(Context *context) const
size_t hash() const
void stringify(std::ostream &s, StringifyKind stringKind) const

Public Static Functions

static inline bool update(Bitmap &keep, Bitmap &addin)
template<typename T>
using chpl::optional = llvm::Optional<T>

optional<T> is just a synonym for ‘std::optional<T>’.

It allows for easy migration in the event that we switch underlying optional types.

template<typename T>
using chpl::owned = std::unique_ptr<T>

owned<T> is just a synonym for ‘std::unique_ptr<T>’. It is shorter and uses the Chapel term for it.

enum chpl::StringifyKind

Values:

enumerator DEBUG_SUMMARY
enumerator DEBUG_DETAIL
enumerator CHPL_SYNTAX
class Serializer

this class is what is passed to serialize methods & helps with the process

Public Types

using stringCacheType = std::map<const char*, std::pair<uint32_t, size_t>>

Public Functions

inline Serializer(std::ostream &os, libraries::LibraryFileSerializationHelper *helper)
inline const stringCacheType &stringCache()
template<typename T>
inline void write(const T &data)
inline void writeByte(unsigned char b)

write one byte

template<typename T>
inline void writeNumeric(T val)

write a numeric type

inline void writeData(const void *ptr, size_t n)

write ‘n’ bytes from the pointer ‘ptr’

inline bool checkStringLength(size_t len, size_t max = MAX_STRING_SIZE)

Check that a string length is OK. If it is, return ‘true’ and take no other action. If it is not, record an error in this Serializer and return ‘false’.

inline uint32_t saveLongString(const char *str, size_t len)

Save a string in the long string table

inline uint32_t nextStringIdx()
void beginAst(const uast::AstNode *ast)
void endAst(const uast::AstNode *ast)
inline bool ok() const

Return ‘false’ if an error was encountered

inline void writeVU64(uint64_t num)
inline void writeVI64(int64_t num)
inline void writeVUint(unsigned int num)
inline void writeVInt(int num)

Public Static Attributes

static const int LONG_STRING_SIZE = 20
static const int MAX_STRING_SIZE = 100000000
class Deserializer

this class is what is passed to deserialize methods & helps with the process

Public Types

using stringCacheType = std::vector<std::pair<size_t, const char*>>

Public Functions

inline Deserializer(Context *context, const void *data, size_t len)
inline Deserializer(Context *context, const void *start, const void *cur, const void *end, libraries::LibraryFileDeserializationHelper &helper)
inline Deserializer(Context *context, const void *data, size_t len, Serializer::stringCacheType serCache)
inline Context *context() const
std::pair<size_t, const char*> getString(int id)

Get a string from the long strings table by index

inline uint64_t position()

Return the current offset into the deserialization region

inline bool checkStringLength(size_t len, size_t max = MAX_STRING_SIZE)

Check that a string length is OK (but not assuming it will be read). If it is OK, return ‘true’ and take no other action. If it is not, record an error in this Deserializer and return ‘false’.

inline bool checkStringLengthAvailable(size_t len, size_t max = MAX_STRING_SIZE)

Check that a string length is OK & it would be valid to read ‘len’ bytes from here. If it is OK, return ‘true’ and take no other action. If it is not, record an error in this Deserializer and return ‘false’.

inline bool ok() const

Return ‘false’ if an error was encountered

void registerAst(const uast::AstNode *ast, uint64_t startOffset)
template<typename T>
inline T operator()()
template<typename T>
inline T read()
inline unsigned char readByte()

Gets a byte

template<typename T>
inline T readNumeric()

read a numeric type

inline void readData(void *ptr, size_t n)

read ‘n’ bytes into the pointer ‘ptr’

inline uint64_t readVU64()

Read a variable-length byte-encoded unsigned integer and return a ‘uint64_t’

inline int64_t readVI64()

Read a variable-length byte-encoded signed integer & return an ‘int64_t’

inline unsigned int readVUint()

Read a variable-length byte-encoded unsigned integer and return an ‘unsigned int’

inline int readVInt()

Read a variable-length byte-encoded signed integer & return an ‘int’

Public Static Attributes

static const int MAX_STRING_SIZE = 100000000