| chigraph master Systems programming language written for beginners in LLVM

Classes | Public Member Functions | Public Attributes | List of all members
chi::Result Struct Reference

The result object, used for identifiying errors with good diagnostics. More...

`#include <chi/Support/Result.hpp>`

Collaboration diagram for chi::Result:
[legend]

## Classes
struct | ScopedContext
| A helper object for contexts that should be removed at the end of a scope. More...

## Public Member Functions
| Result ()
| Default constructor; defaults to success.
int | addContext (const nlohmann::json &data)
| Add some json that will ALWAYS be merged with entries that are added and when results are added to this Result. More...
void | addEntry (const char *ec, const char *overview, nlohmann::json data)
| Add a entry to the result, either a warning or an error. More...
ScopedContext | addScopedContext (const nlohmann::json &data)
| Add a context with a scope Example usage: chi::Result res; res.contextJson(); // returns {} { auto scopedCtx = res.addScopedContext({{"Module", "lang"}}); res.contextJson(); // returns {"module": "lang"} } res.contextJson(); // returns {} . More...
nlohmann::json | contextJson () const
| Get the JSON associated with the context that's been added. More...
std::string | dump () const
| Dump to a pretty-printed error message. More...
| operator bool () const
| Success test. More...
bool | operator! () const
| !Success test More...
void | removeContext (int id)
| Removes a previously added context. More...
bool | success () const
| Success test. More...

## Public Attributes
bool | mSuccess = true
| If it's successful.
nlohmann::json | result_json
| The result JSON.

## Related Functions
(Note that these are not member functions.)
Result operators
Result | operator+ (const Result &lhs, const Result &rhs)
| Append two Result objects. More...
Result & | operator+= (Result &lhs, const Result &rhs)
| Append one result to an existing one. More...
std::ostream & | operator<< (std::ostream &lhs, const Result &rhs)
| Stream operator. More...

## Detailed Description

The result object, used for identifiying errors with good diagnostics.

## Usage:

If you want to construct a default result object, just call the default constructor:

`res` is the most common name for an error object, prefer it to other names.

When constructed, results are successful by default:

assert(res.success());

When an error, warning, or just some event that requries logging needs to be added to the result object, call `Result::addEntry`:

res.addEntry("W123", "Just a warning, don't fret.", {{"Probably here", 21}});

note the `W` at the beginning of the error code, this is important. If it's an `W`, it's considered an warning and the result will still be considered successful:

assert(res.success());

If that leading character to the error code is an 'E', then it's considered an error

res.addEntry("E231", "Some error occured", {{"Line Number", 34}});

And the result is not successful anymore:

assert(!res.success());

If you're calling another operation that emits a Result object, then there's an easy to integrate that result object: the opeartor+=

res += thisWillFail();

## Standardized names in data:

In order to have good parsing of errors, some standards are good. If you are trying to represent this data in your error, use these standards so it can be parsed later on and presented to the user in a nice way

Name in JSON | Description
--- | ---
`Node ID` | The ID of the node that errored

# What is EUKN?

Not every error in chigraph is documented and tested. Errors with numbers are tested and possibly documented. EUKN errors are just undocumented errors.

## Implementation Details:

Result objects store a json object that represents the error metadata. It's an array, each being an object containing three objects:

- `errorcode`: The errorcode. This is an identifier representng the error: a character followed by a number. The value of the character changes the behaviour:

  - `E`: it's an error and sets `success` to false.
  - `W`: it's a warning
  - `I`: it's just info

  If it's anything else, that it will cause an assertion

- `overview`: A simple string representing the generics of the problem. It shouldn't differ from error to error, if you need to include specifics use the `data` element
- `data`: Extra metadata for the error, including context and how the error occured.

Examples:
  ResultExample.cpp, and SubprocessExample.cpp.

Definition at line 72 of file Result.hpp.

## Member Function Documentation

## ◆ addContext()

int chi::Result::addContext | ( | const nlohmann::json & | data | ) |

Add some json that will ALWAYS be merged with entries that are added and when results are added to this Result.

Parameters

  data | The json to merge with every entry

Precondition
  data.is_object()

Returns
  The ID for this context, use this value with removeContext to remove it

Definition at line 84 of file Result.cpp.

Referenced by addScopedContext(), and Result().

Here is the caller graph for this function:

## ◆ addEntry()

void chi::Result::addEntry | ( | const char * | ec,
|  | const char * | overview,
|  | nlohmann::json | data
| ) |  |

Add a entry to the result, either a warning or an error.

Parameters

  ec | The error/warning code. If it starts with E, then it is an error and success is set to false, if it starts with a W it's a warning and success can stay true if it is still true.
  overview | Basic overview of the error, this shouldn't change based on the instance of the error
  data | The detailed description this instance of the error.

Precondition
  `data.is_object() == true`

Examples:
  ResultExample.cpp.

Definition at line 52 of file Result.cpp.

References contextJson(), mSuccess, and result_json.

Referenced by chi::Subprocess::closeStdIn(), chi::compileCToLLVM(), chi::Context::compileModule(), chi::connectData(), chi::connectExec(), chi::createGraphFunctionDeclarationFromJson(), chi::GraphModule::createNodeTypeFromCCode(), chi::disconnectData(), chi::disconnectExec(), chi::FunctionCompiler::initialize(), chi::GraphFunction::insertNode(), chi::interpretLLVMIR(), chi::interpretLLVMIRAsMain(), chi::jsonToGraphFunction(), chi::jsonToGraphModule(), chi::jsonToGraphStruct(), chi::Context::nodeTypeFromModule(), chi::LangModule::nodeTypeFromName(), chi::GraphModule::nodeTypeFromName(), chi::parseBitcodeFile(), chi::Debugger::pause(), chi::Debugger::processContinue(), chi::Subprocess::pushToStdIn(), Result(), chi::GraphModule::saveToDisk(), chi::Debugger::setBreakpoint(), chi::Debugger::start(), chi::Subprocess::start(), chi::Debugger::terminate(), chi::Context::typeFromModule(), chi::validateFunctionConnectionsAreTwoWay(), chi::validateFunctionEntryType(), chi::validateFunctionExecOutputs(), chi::validateFunctionExitTypes(), and chi::validateFunctionMainSignature().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ addScopedContext()

ScopedContext chi::Result::addScopedContext | ( | const nlohmann::json & | data | ) |
| inline

Add a context with a scope Example usage:

chi::Result res;
res.contextJson(); // returns {}
{
auto scopedCtx = res.addScopedContext({{"Module", "lang"}});
res.contextJson(); // returns {"module": "lang"}
}
res.contextJson(); // returns {}

.

Parameters

  data | The data to add to each entry

Precondition
  data.is_object()

Returns
  The ScopedContext object. Shouldn't be discarded.

Definition at line 123 of file Result.hpp.

References addContext(), contextJson(), and removeContext().

Referenced by chi::Context::addModuleFromJson(), chi::compileCToLLVM(), chi::Context::compileModule(), chi::FunctionCompiler::initialize(), chi::jsonToGraphModule(), chi::Context::loadModule(), chi::validateFunctionConnectionsAreTwoWay(), chi::validateFunctionExecOutputs(), and chi::validateFunctionNodeInputs().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ contextJson()

nlohmann::json chi::Result::contextJson | ( |  | ) | const

Get the JSON associated with the context that's been added.

Returns
  The context JSON

Definition at line 95 of file Result.cpp.

Referenced by addEntry(), addScopedContext(), operator+(), and operator+=().

Here is the caller graph for this function:

## ◆ dump()

std::string chi::Result::dump | ( |  | ) | const

Dump to a pretty-printed error message.

Returns
  The human-readable error message

Definition at line 65 of file Result.cpp.

References result_json.

Referenced by operator!(), and operator<<().

Here is the caller graph for this function:

## ◆ operator bool()

chi::Result::operator bool | ( |  | ) | const
| inline explicit

Success test.

Returns
  True if successful

Definition at line 137 of file Result.hpp.

References success().

Here is the call graph for this function:

## ◆ operator!()

bool chi::Result::operator! | ( |  | ) | const
| inline

!Success test

Returns
  If it's not successful

Definition at line 145 of file Result.hpp.

References dump(), and success().

Here is the call graph for this function:

## ◆ removeContext()

void chi::Result::removeContext | ( | int | id | ) |

Removes a previously added context.

Parameters

  id | The ID for the context added with addContext

Definition at line 93 of file Result.cpp.

Referenced by addScopedContext(), and chi::Result::ScopedContext::~ScopedContext().

Here is the caller graph for this function:

## ◆ success()

bool chi::Result::success | ( |  | ) | const
| inline

Success test.

Returns
  If it's successful

Examples:
  ResultExample.cpp.

Definition at line 141 of file Result.hpp.

References mSuccess.

Referenced by operator bool(), operator!(), operator+(), and operator+=().

Here is the caller graph for this function:

## Friends And Related Function Documentation

## ◆ operator+()

Result operator+ | ( | const Result & | lhs,
|  | const Result & | rhs
| ) |  |
| related

Append two Result objects.

Both of the contexts are merged. The entires in lhs have the rhs context applied to them, and viceversa as well

Parameters

  lhs | The left Result
  rhs | The right Result

Returns
  The concatinated Result

Definition at line 106 of file Result.cpp.

References contextJson(), mSuccess, result_json, and success().

Here is the call graph for this function:

## ◆ operator+=()

Result & operator+= | ( | Result & | lhs,
|  | const Result & | rhs
| ) |  |
| related

Append one result to an existing one.

Both of the contexts are merged. The entires in lhs have the rhs context applied to them, and viceversa as well

Parameters

  lhs | The existing Result to add to
  rhs | The (usually temporary) result to be added into lhs.

Returns
  *this

Definition at line 127 of file Result.cpp.

References contextJson(), mSuccess, result_json, and success().

Here is the call graph for this function:

## ◆ operator<<()

std::ostream & operator<< | ( | std::ostream & | lhs,
|  | const Result & | rhs
| ) |  |
| related

Stream operator.

Parameters

  lhs | The stream
  rhs | The Result to print to lhs

Returns
  lhs after printing

Definition at line 187 of file Result.hpp.

References dump().

Here is the call graph for this function:

The documentation for this struct was generated from the following files:

- lib/support/include/chi/Support/Result.hpp
- lib/support/src/Result.cpp