From 1e751983fdb8581c75f3c034613d3707c4b5f2fd Mon Sep 17 00:00:00 2001 From: Process-ing Date: Wed, 14 Aug 2024 17:32:20 +0100 Subject: [PATCH] Add README --- Lara-JS/src-api/visualization/README.md | 36 +++++++++++++++++++ .../compiler-abstracted-system.svg | 4 +++ 2 files changed, 40 insertions(+) create mode 100644 Lara-JS/src-api/visualization/README.md create mode 100644 Lara-JS/src-api/visualization/compiler-abstracted-system.svg diff --git a/Lara-JS/src-api/visualization/README.md b/Lara-JS/src-api/visualization/README.md new file mode 100644 index 000000000..55da94b03 --- /dev/null +++ b/Lara-JS/src-api/visualization/README.md @@ -0,0 +1,36 @@ +# LARA Visualization Tool + +Web tool for visualization and analysis of the AST and its source code. + +## Integration + +Internally, the tool follows a system for interaction with the compiler, to be able to apply code linkage and correction, among others, while still being independent of the specific compiler. This system is an implementation of the Factory Method pattern, and the integration with Clava is illustrated in the following diagram: + +![Compiler Abstracted System](./compiler-abstracted-system.svg) + +To integrate the tool in another compiler: + +1. Implement the `GenericAstConverter` interface, with its functions properly implemented. More information can be found in their documentation. +2. Create a class that extends `GenericVisualizationTool`, and override `getAstConverter` so that it returns an instance of the class declared in the previous step. +3. Use an instance of the previous class as the entry point of the visualization tool API, for the compiler in question. + +## Usage + +After integration, and being `VisualizationTool` the extended derived class of `GenericVisualizationTool`, to launch or update the visualization tool, execute the following statement: + +```js +await VisualizationTool.visualize(); +``` + +Once ready, Clava will provide the URL that should be opened in the browser to access the web interface. The function can also change the AST root and URL domain and port. + +Other properties will allow the user to know other important information from the server: + +```js +VisualizationTool.isLaunched; // true if the server is running +VisualizationTool.url; // URL where the server is running +VisualizationTool.port; // port to which the server is listening +VisualizationTool.hostname; // hostname to which the server is listening +``` + +For more details, refer to the `GenericVisualizationTool` documentation. \ No newline at end of file diff --git a/Lara-JS/src-api/visualization/compiler-abstracted-system.svg b/Lara-JS/src-api/visualization/compiler-abstracted-system.svg new file mode 100644 index 000000000..caaf5f448 --- /dev/null +++ b/Lara-JS/src-api/visualization/compiler-abstracted-system.svg @@ -0,0 +1,4 @@ + + + +
Compiler-Abstracted System Class Diagram
GenericVisualizationTool
+ visualize(): Promise<void>
+ get isLaunched(): bool
+ get hostname(): string | undefined
+ get port(): number | undefined
+ get url(): string | undefined
# getAstConverter(): GenericAstConverter
«interface»
GenericAstConverter
+ updateAst(): void
+ getToolAst(root: LaraJoinPoint): ToolJoinPoint
+ getPrettyHtmlCode(root: LaraJoinPoint): FilesCode
VisualizationTool
- astConverter: ClavaAstConverter
# getAstConverter(): GenericAstConverter
ClavaAstConverter
1
1
LARA
Clava
return this.astConverter;
 \ No newline at end of file