class SarifDocumentWriter

Declaration

class SarifDocumentWriter { /* full declaration omitted */ };

Description

This class handles creating a valid SARIF document given various input attributes. However, it requires an ordering among certain method calls: 1. Because every SARIF document must contain at least 1 \c run, callers must ensure that \ref SarifDocumentWriter::createRun is is called before any other methods. 2. If SarifDocumentWriter::endRun is called, callers MUST call SarifDocumentWriter::createRun, before invoking any of the result aggregation methods such as SarifDocumentWriter::appendResult etc.

Declared at: clang/include/clang/Basic/Sarif.h:307

Member Variables

private const llvm::StringRef SchemaURI = {"https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json"}

private const llvm::StringRef SchemaVersion = {"2.1.0"}

private const clang::SourceManager& SourceMgr

Source Manager to use for the current SARIF document.

private bool Closed = true

Flag to track the state of this document: A closed document is one on which a new runs must be created. This could be a document that is freshly created, or has recently finished writing to a previous run.

private llvm::json::Array Runs

Reference: run object

private llvm::SmallVector<SarifRule, 32> CurrentRules

Reference: rules property

private llvm::StringMap<detail::SarifArtifact> CurrentArtifacts

The list of artifacts that have been encountered on the most recent active run. An artifact is defined in SARIF as a sequence of bytes addressable by a URI. A common example for clang's case would be files named by filesystem paths.

Method Overview

• public SarifDocumentWriter()
• public SarifDocumentWriter(const clang::SourceManager & SourceMgr)
• public void appendResult(const clang::SarifResult & SarifResult)
• private llvm::json::Object createCodeFlow(const llvm::ArrayRef<ThreadFlow> ThreadFlows)
• public llvm::json::Object createDocument()
• private llvm::json::Object createPhysicalLocation(const clang::CharSourceRange & R)
• public size_t createRule(const clang::SarifRule & Rule)
• public void createRun(const llvm::StringRef ShortToolName, const llvm::StringRef LongToolName, const llvm::StringRef ToolVersion = "15.0.2")
• private llvm::json::Array createThreadFlows(const llvm::ArrayRef<ThreadFlow> ThreadFlows)
• public void endRun()
• private llvm::json::Object & getCurrentRun()
• private llvm::json::Object & getCurrentTool()
• private bool hasRun() const
• private void reset()
• public ~SarifDocumentWriter()

Methods

¶SarifDocumentWriter()

Declared at: clang/include/clang/Basic/Sarif.h:353

¶SarifDocumentWriter(
    const clang::SourceManager& SourceMgr)

Description

Create a new empty SARIF document with the given source manager.

Declared at: clang/include/clang/Basic/Sarif.h:356

Parameters

const clang::SourceManager& SourceMgr

¶void appendResult(
    const clang::SarifResult& SarifResult)

Description

Append a new result to the currently in-flight run.

Declared at: clang/include/clang/Basic/Sarif.h:398

Parameters

const clang::SarifResult& SarifResult

¶llvm::json::Object createCodeFlow(
    const llvm::ArrayRef<ThreadFlow> ThreadFlows)

Description

Create a code flow object for the given threadflows. See \ref ThreadFlow.

Declared at: clang/include/clang/Basic/Sarif.h:342

Parameters

const llvm::ArrayRef<ThreadFlow> ThreadFlows

¶llvm::json::Object createDocument()

Description

Return the SARIF document in its current state. Calling this will trigger a copy of the internal state including all reported diagnostics, resulting in an expensive call.

Declared at: clang/include/clang/Basic/Sarif.h:403

¶llvm::json::Object createPhysicalLocation(
    const clang::CharSourceRange& R)

Description

Add the given \ref CharSourceRange to the SARIF document as a physical location, with its corresponding artifact.

Declared at: clang/include/clang/Basic/Sarif.h:350

Parameters

const clang::CharSourceRange& R

¶size_t createRule(const clang::SarifRule& Rule)

Description

Associate the given rule with the current run. Returns an integer rule index for the created rule that is unique within the current run, which can then be used to create a \ref SarifResult to add to the current run. Note that a rule must exist before being referenced by a result.

Declared at: clang/include/clang/Basic/Sarif.h:387

Parameters

const clang::SarifRule& Rule

¶void createRun(
    const llvm::StringRef ShortToolName,
    const llvm::StringRef LongToolName,
    const llvm::StringRef ToolVersion = "15.0.2")

Description

Create a new run with which any upcoming analysis will be associated. Each run requires specifying the tool that is generating reporting items.

Declared at: clang/include/clang/Basic/Sarif.h:363

Parameters

const llvm::StringRef ShortToolName

const llvm::StringRef LongToolName

const llvm::StringRef ToolVersion = "15.0.2"

¶llvm::json::Array createThreadFlows(
    const llvm::ArrayRef<ThreadFlow> ThreadFlows)

Description

Add the given threadflows to the ones this SARIF document knows about.

Declared at: clang/include/clang/Basic/Sarif.h:346

Parameters

const llvm::ArrayRef<ThreadFlow> ThreadFlows

¶void endRun()

Description

If there is a current run, end it. This method collects various book-keeping required to clear and close resources associated with the current run, but may also allocate some for the next run. Calling \ref endRun before associating a run through \ref createRun leads to undefined behaviour.

Declared at: clang/include/clang/Basic/Sarif.h:375

¶llvm::json::Object& getCurrentRun()

Declared at: clang/include/clang/Basic/Sarif.h:334

¶llvm::json::Object& getCurrentTool()

Declared at: clang/include/clang/Basic/Sarif.h:316

¶bool hasRun() const

Declared at: clang/include/clang/Basic/Sarif.h:322

¶void reset()

Declared at: clang/include/clang/Basic/Sarif.h:327

¶~SarifDocumentWriter()

Description

Release resources held by this SARIF document.

Declared at: clang/include/clang/Basic/Sarif.h:359