{"id":19976399,"url":"https://github.com/agoraio-extensions/terra","last_synced_at":"2026-03-15T09:18:42.443Z","repository":{"id":206955901,"uuid":"688842651","full_name":"AgoraIO-Extensions/terra","owner":"AgoraIO-Extensions","description":"terra is a shell of the code-gen flow","archived":false,"fork":false,"pushed_at":"2025-02-21T09:16:43.000Z","size":915,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T18:51:43.254Z","etag":null,"topics":["ast","cpp","ts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgoraIO-Extensions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-08T08:11:39.000Z","updated_at":"2025-02-21T09:16:44.000Z","dependencies_parsed_at":"2024-01-08T08:27:13.898Z","dependency_job_id":"6ea1ce95-dedb-43c5-8565-1a68218ee801","html_url":"https://github.com/AgoraIO-Extensions/terra","commit_stats":null,"previous_names":["agoraio-extensions/terra"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AgoraIO-Extensions/terra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgoraIO-Extensions%2Fterra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgoraIO-Extensions%2Fterra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgoraIO-Extensions%2Fterra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgoraIO-Extensions%2Fterra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgoraIO-Extensions","download_url":"https://codeload.github.com/AgoraIO-Extensions/terra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgoraIO-Extensions%2Fterra/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261823755,"owners_count":23215142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","cpp","ts"],"created_at":"2024-11-13T03:23:34.370Z","updated_at":"2025-12-25T12:57:36.605Z","avatar_url":"https://github.com/AgoraIO-Extensions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# terra\n\nterra is a shell of the code-gen flow: Parse AST -\u003e Generate codes.\n\n**Disclaimer**: This is not an officially supported Agora product.\n\n## Preparation\n\n### Prerequisites\n\n[node](https://nodejs.org/en/download) \u003e=18\n\n[yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable)\n\nAdditional setup required for using [cxx-parser](cxx-parser/README.md#prerequisites)\n\n## Getting Started\n\n### Installing terra in your Project\n\n\u003e 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.\n\n#### 1. Create a `.yarnrc.yml` file in your project directory:\n\n```\necho \"nodeLinker: node-modules\" \u003e\u003e .yarnrc.yml\n```\n\n#### 2. Set `yarn` version to `berry`:\n\n`yarn set version berry`\n\n#### 3. Install `terra` from the GitHub repository:\n\n```\nyarn add \u003cterra repo url\u003e\n# yarn add git@github.com:AgoraIO-Extensions/terra.git#head=main\u0026workspace=terra\n# yarn add git@github.com:AgoraIO-Extensions/terra.git#head=main\u0026workspace=terra-core\n```\n\n#### 4. Install dependencies:\n\n`yarn`\n\n### Configuration Format\n\nThe terra configuration uses a YAML format. Here's an example:\n\n```yaml\n# List of parser configurations\nparsers:\n  # Configuration for the first parser\n  - name: 'my-custom-parser' # Name of the parser, optional\n    package: 'parser-package-name' # Package name where the parser is located\n    # path: 'relative/path/to/parser' # Or specify the relative path to the parser\n    args: # Arguments to pass to the parser\n      option1: 'value1'\n      option2: 'value2'\n\n  # Configuration for the second parser\n  - name: 'default-parser' # Default export parser, name can be omitted\n    path: 'relative/path/to/default-parser'\n    # package: 'another-parser-package' # Or specify the package name\n    args:\n      setting1: 'abc'\n      setting2: 123\n\n# List of renderer configurations\nrenderers:\n  # Configuration for the first renderer\n  - name: 'example-renderer'\n    package: 'renderer-package-name'\n    args:\n      param1: 'foo'\n      param2: 'bar'\n\n  # Configuration for the second renderer\n  - path: 'path/to/another-renderer'\n    args:\n      config1: true\n      config2: 'xyz'\n      \n# List of global args\nglobalArgs:\n  type: 'rtc'\n```\n\n### Custom `Parser` and `Renderer`\n\n#### Writing a `Parser`\n\n```ts\nimport {\n  ParseResult,\n  TerraContext,\n  TerraNode,\n} from '@agoraio-extensions/terra-core';\n\nexport interface MyTerraNode extends TerraNode {\n  myProperty1: string;\n  myProperty2: string;\n}\n\nexport default function MyParser(\n  terraContext: TerraContext,\n  args: any,\n  parseResult?: ParseResult\n): ParseResult | undefined {\n  let myTerraNode = {\n    myProperty1: 'myProperty1',\n    myProperty2: 'myProperty2',\n  } as MyTerraNode;\n  let myParserResult = new ParseResult();\n  myParserResult.nodes = [myTerraNode];\n  return myParserResult;\n}\n```\n\n### Writing a `Renderer`\n\n```ts\nimport { ParseResult, RenderResult } from '@agoraio-extensions/terra-core';\n\nimport { MyTerraNode } from './test_parser';\n\nexport default function (parseResult: ParseResult): RenderResult[] {\n  let fileContent = parseResult.nodes\n    .map((node) =\u003e {\n      let myTerraNode = node as MyTerraNode;\n      return `${myTerraNode.myProperty1}\\n${myTerraNode.myProperty2}`;\n    })\n    .join('\\n');\n\n  return [{ file_name: 'test_renderer.txt', file_content: fileContent }];\n}\n```\n\n### Running `terra`\n\nAdd a config file (e.g., `my_terra_config.yaml``) and execute terra:\n\n```yaml\n# my_terra_config.yaml\nparsers:\n  - path: test_parser.ts\n\nrenderers:\n  - path: test_renderer.ts\n```\n\n```\nnpm exec terra -- run --config my_terra_config.yaml --output-dir=\u003cYOUR_OUTPUT_PATH\u003e\n```\n\n### prebuilt\n\nif you set CPPAST_BACKEND_BUILD=true in your environments, cppast_backend will build. otherwise,\ncppast_backend will use prebuilt version.\n\nCurrently, we provide macos and ubuntu prebuilt version.\n\n## Examples\n\n- https://github.com/AgoraIO-Extensions/iris_web/blob/main/scripts/terra\n- https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/tree/main/tool/terra\n\n## License\n\nThe project is under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagoraio-extensions%2Fterra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagoraio-extensions%2Fterra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagoraio-extensions%2Fterra/lists"}