cyclone-analyzer
v0.0.37
Published
A static analyzer library for Cyclone specification language
Downloads
17
Readme
Cyclone Analyzer
Cyclone analyzer is a static analyzer for Cyclone Specification Language. This library powers the cyclone online editor project.
The analyzer covers most of Cyclone's language features. This package also contains the language specification, an IR builder, some utility functions, a parser and a lexer based on ANTLR4 for Cyclone. This analyzer currently checks for 40+ kinds of semantic errors in a Cyclone spec, and would be helpful as a linter for Cyclone code editors.
Limitations: This analyzer performs a static analysis for each Cyclone specification. The semantic errors detected by this analyzer are not comprehensive: Certain errors can not be discovered by this analyzer. If this analyzer report no error on a certain specification, it doesn't mean the specification actually has no problem at all.
This project is a part of my final year project (CS440[A]) at Maynooth University.
TODO
- This document is unfinished and will be updated in the future.
Usage
Installation
Use npm or yarn to install:
npm install cyclone-analyzer
Import this library using import
or require
:
// ESM
import cycloneAnalyzer from "cyclone-analyzer"
// CJS
const cycloneAnalyzer = require("cyclone-analyzer")
Analyze a Cyclone Specification
Find errors in any Cyclone specification by simply using analyzeCycloneSpec
.
import {analyzer} from "cyclone-analyzer"
const cycloneSpec = `
graph G {
int i = 1;
start normal node S0 {
i ++;
}
final normal node S1 {
i --;
}
edge {S0 -> S1}
goal {
assert i == 1 in (S1);
check for 1
}
}
`
const result = analyzer.analyzeCycloneSpec(cycloneSpec)
if (result.hasSyntaxError()) {
console.log("This spec has syntax error:", result.parserErrors)
} else if (result.hasSemanticError()) {
console.log("Semantic errors detected:", result.semanticErrors)
} else {
console.log("This spec seems ok")
}
Parsing
Use utils.antlr.parseCycloneSyntax
to parse a Cyclone specification via ANTLR4:
import cycloneAnalyzer from "cyclone-analyzer"
const {parseCycloneSyntax} = cycloneAnalyzer.utils.antlr
const spec = `
graph G {
int i = 1 // syntax error: a semicolon is required here
}
`
const parsed = parseCycloneSyntax({input: spec})
if (parsed.syntaxErrorsCount > 0) {
console.log("This spec has syntax error")
}
Syntax Block Builder
There is an IR builder blockBuilder.SyntaxBlockBuilder
for building a tree-structured context for a Cyclone spec after semantic analysis:
import {analyzer, blockBuilder} from "cyclone-analyzer"
const cycloneSpec = `
graph G {
start final node A {}
edge {A -> A}
goal { check for 1 }
}
`
const irBuilder = new blockBuilder.SyntaxBlockBuilder()
const analysisResult = analyzer.analyzeCycloneSpec(cycloneSpec, {
analyzerExtensions: [irBuilder] // the builder is an extension of the analyzer
})
// the syntax block of the input Cyclone spec, as a tree
const program = irBuilder.getProgramBlock()
console.log(program)
Analyzer Extensions
The semantic analyzer defined series of events and can be listened with analyzer.on
method. In this way, extensions can be written by listening to analyzer events. Extensions can be objects or class instances that has an attach
method:
import {analyzer} from "cyclone-analyzer"
// defining an extension as class
class MyExtension {
// the required attach method
attach(analyzer) {
// this.analyzer = analyzer
analyzer.on("errors", (ctx, errors) => console.log("semantic errors discovered:", errors))
analyzer.on("block:enter", (ctx, payload) => console.log("entering a semantic context block"))
analyzer.on("block:exit", (ctx, payload) => console.log("exiting a semantic context block"))
analyzer.on("identifier:register", (ctx, {text}) => console.log("registering identifier: ", text))
analyzer.on("identifier:reference", (ctx, {references}) => console.log("referencing identifiers: ", references))
}
}
const cycloneSpec = `
graph G {
start final node A {}
edge {A -> A}
goal { check for 1 }
}
`
const ext = new MyExtension()
const analysisResult = analyzer.analyzeCycloneSpec(cycloneSpec, {
analyzerExtensions: [ext] // attach the extension
})
Modules
This package contains the following modules:
| Module | Description | Status |
|----------------|----------------------------------------------------------------------|----------|
| analyzer
| The semantic analyzer for Cyclone | Stable |
| blockBuilder
| An IR builder based on the semantic analyzer | Unstable |
| generated
| The generated lexer and parser based on ANTLR4 | Stable |
| language
| The language's definitions in enums & specifications | Stable |
| library
| Some libraries that has nothing to do with the language itself | Stable |
| utils
| Helper modules for analyzer and block builder to handle the language | Stable |
Analyzer
TODO
Block Builder
TODO
Generated Lexer & Parser
TODO
Language Definitions & Specifications
TODO
Library
TODO
Utilities
TODO
License
Published under the BSD-2 license