Enhance README.md (#46)

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 <terra repo url>
 # yarn add [email protected]:AgoraIO-Extensions/terra.git#head=main&workspace=terra
 # yarn add [email protected]: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=<YOUR_OUTPUT_PATH>
+```
 
 ## Examples
+
 - https://github.com/AgoraIO-Extensions/iris_web/blob/main/scripts/terra
 - https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/tree/main/tool/terra
 

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

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<TerraLoaderConfig>;
+  /**
+   * List of renderer configurations to be used in terra.
+   */
   renderers: Array<TerraLoaderConfig>;
 }