From 88a1cf16708a5859fb8dda3d197fa3bb65b8f1c8 Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 19 Dec 2023 14:55:02 +0800 Subject: [PATCH] Enhance README.md --- README.md | 130 ++++++++++++++++++++++++++++++-- cxx-parser/README.md | 11 +++ terra/src/base/terra_configs.ts | 32 ++++++++ 3 files changed, 167 insertions(+), 6 deletions(-) create mode 100644 cxx-parser/README.md diff --git a/README.md b/README.md index 2059e3d..c891bdb 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,152 @@ terra is a shell of the code-gen flow: Parse AST -> Generate codes. **Disclaimer**: This is not an officially supported Agora product. -## Get started +## Preparation -### Environment Setup +### Prerequisites [node](https://nodejs.org/en/download) >=18 [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) +Additional setup required for using [cxx-parser](cxx-parser/README.md#prerequisites) + ### Installing terra in your Project > Currently, we do not provide an npm package for this repository. You should depend on `terra` from the GitHub repository using [yarn berry](https://github.com/yarnpkg/berry) as the package manager. - + #### 1. Create a `.yarnrc.yml` file in your project directory: + ``` echo "nodeLinker: node-modules" >> .yarnrc.yml ``` + #### 2. Set `yarn` version to `berry`: -```yarn set version berry``` + +`yarn set version berry` + #### 3. Install `terra` from the GitHub repository: -``` + +``` yarn add # yarn add git@github.com:AgoraIO-Extensions/terra.git#head=main&workspace=terra # yarn add git@github.com:AgoraIO-Extensions/terra.git#head=main&workspace=terra-core ``` + #### 4. Install dependencies: - ```yarn``` + +`yarn` + +## Getting Started + +### Configuration Format + +The terra configuration uses a YAML format. Here's an example: + +```yaml +# List of parser configurations +parsers: + # Configuration for the first parser + - name: 'my-custom-parser' # Name of the parser, optional + package: 'parser-package-name' # Package name where the parser is located + # path: 'relative/path/to/parser' # Or specify the relative path to the parser + args: # Arguments to pass to the parser + option1: 'value1' + option2: 'value2' + + # Configuration for the second parser + - name: 'default-parser' # Default export parser, name can be omitted + path: 'relative/path/to/default-parser' + # package: 'another-parser-package' # Or specify the package name + args: + setting1: 'abc' + setting2: 123 + +# List of renderer configurations +renderers: + # Configuration for the first renderer + - name: 'example-renderer' + package: 'renderer-package-name' + args: + param1: 'foo' + param2: 'bar' + + # Configuration for the second renderer + - path: 'path/to/another-renderer' + args: + config1: true + config2: 'xyz' +``` + +### Custom `Parser` and `Renderer` + +#### Writing a `Parser` + +```ts +import { + ParseResult, + TerraContext, + TerraNode, +} from '@agoraio-extensions/terra-core'; + +export interface MyTerraNode extends TerraNode { + myProperty1: string; + myProperty2: string; +} + +export default function MyParser( + terraContext: TerraContext, + args: any, + parseResult?: ParseResult +): ParseResult | undefined { + let myTerraNode = { + myProperty1: 'myProperty1', + myProperty2: 'myProperty2', + } as MyTerraNode; + let myParserResult = new ParseResult(); + myParserResult.nodes = [myTerraNode]; + return myParserResult; +} +``` + +### Writing a `Renderer` + +```ts +import { ParseResult, RenderResult } from '@agoraio-extensions/terra-core'; + +import { MyTerraNode } from './test_parser'; + +export default function (parseResult: ParseResult): RenderResult[] { + let fileContent = parseResult.nodes + .map((node) => { + let myTerraNode = node as MyTerraNode; + return `${myTerraNode.myProperty1}\n${myTerraNode.myProperty2}`; + }) + .join('\n'); + + return [{ file_name: 'test_renderer.txt', file_content: fileContent }]; +} +``` + +### Running `terra` + +Add a config file (e.g., `my_terra_config.yaml``) and execute terra: + +```yaml +# my_terra_config.yaml +parsers: + - path: test_parser.ts + +renderers: + - path: test_renderer.ts +``` + +``` +npm exec terra -- run --config my_terra_config.yaml --output-dir= +``` ## Examples + - https://github.com/AgoraIO-Extensions/iris_web/blob/main/scripts/terra - https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/tree/main/tool/terra diff --git a/cxx-parser/README.md b/cxx-parser/README.md new file mode 100644 index 0000000..6187abe --- /dev/null +++ b/cxx-parser/README.md @@ -0,0 +1,11 @@ +# cxx-parser + +The `cxx-parser`` is a terra parser that parse C/C++ Abstract Syntax Trees (ASTs), leveraging libraries from [cppast](https://github.com/foonathan/cppast) and [clang AST](https://clang.llvm.org/docs/IntroductionToTheClangAST.html). + +## Prerequisites +> The [cppast](https://github.com/foonathan/cppast) only work on llvm@15 at this time, you can install it using homebrew +> ``` +> brew install llvm@15 +> ``` + +- Install llvm@15 diff --git a/terra/src/base/terra_configs.ts b/terra/src/base/terra_configs.ts index e0aaf0f..8f732f4 100644 --- a/terra/src/base/terra_configs.ts +++ b/terra/src/base/terra_configs.ts @@ -4,16 +4,48 @@ import { resolvePath } from '@agoraio-extensions/terra-core'; import YAML from 'yaml'; +/** + * Configuration settings for a terra Parser or Renderer. + */ export interface TerraLoaderConfig { + /** + * The name of the Parser or Renderer. Optional if the Parser or Renderer is defined + * as a default export. + */ name?: string; + /** + * The package name where the Parser or Renderer is located. + * Note: Specify either `package` or `path`, but not both. + */ package?: string; + /** + * The relative file system path to the parser or renderer, relative to + * current configuration path. + * Note: Specify either `path` or `package`, but not both. + */ path?: string; + /** + * Arguments to be passed to the Parser or Renderer. + * Can be of any type. + */ args?: any; } +/** + * Configuration for terra, including parsers and renderers. + */ export interface TerraConfigs { + /** + * Path to the base configuration file for terra, which will be merged with the current configuration, but the same configurations in the current configuration will be overrided the base configuration if the keys are same. + */ include: string; + /** + * List of parser configurations to be used in terra. + */ parsers: Array; + /** + * List of renderer configurations to be used in terra. + */ renderers: Array; }