From c734db64698fe61ad938249b22a1be73e7d2d7d8 Mon Sep 17 00:00:00 2001 From: "yilun.sun" Date: Thu, 7 Mar 2024 10:58:39 +0800 Subject: [PATCH] fix: adjust the help documentation for the transpiler --- src/phpdoc-parser/transpiler/README.md | 38 ++++++++++++-------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/src/phpdoc-parser/transpiler/README.md b/src/phpdoc-parser/transpiler/README.md index 1b49bf90..10dfa1f5 100644 --- a/src/phpdoc-parser/transpiler/README.md +++ b/src/phpdoc-parser/transpiler/README.md @@ -1,10 +1,10 @@ # How to Use the PHPDoc Parser Transpiler -This document provides a guide on how to use the PHPDoc Parser Transpiler to convert PHPDoc comments into TypeScript type annotations. We'll go through a example demonstrating how to set up and execute the transpilation process. +This document provides a guide on how to use the PHPDoc Parser Transpiler to convert PHPDoc comments into TypeScript type definitions. We'll go through a example demonstrating how to set up and execute the transpilation process. ## Setting Up the Environment -Before you begin, ensure you have a TypeScript project setup where you can run the example code. Your project should include the necessary files and dependencies related to the PHPDoc Parser and the transpiler. +Before you begin, ensure you have a TypeScript project setup where you can run the example code. Your project should include the necessary files and dependencies related to the PHPDoc Parser. ## Example Code Overview @@ -13,22 +13,22 @@ The example provided demonstrates how to parse a PHPDoc comment, extract node in 1. **Tokenization**: Convert a PHPDoc comment string into tokens. 2. **Parsing**: Transform the tokens into an Abstract Syntax Tree (AST) representing the PHPDoc structure. 3. **Transpilation**: Convert the PHPDoc AST nodes into TypeScript type nodes. -4. **Rendering**: Convert the TypeScript nodes into strings representing TypeScript type annotations. +4. **Rendering**: Convert the TypeScript nodes into strings representing TypeScript type definitions. ## Step 1: Import Necessary Classes and Types ```TypeScript import { renderTsNodeToString } from './helpers'; -import { PHPDocTypeNodeToTypescriptTypeNodeTranspiler } from './php-doc-to-typescript-type-transpiler'; +import { PhpDocTypeNodeToTypescriptTypeNodeTranspiler } from './php-doc-to-typescript-type-transpiler'; import type { ParamTagValueNode, PropertyTagValueNode, ReturnTagValueNode } from '../ast/php-doc'; -import { Lexer, ConstExprParser, PHPDocParser, TokenIterator, TypeParser } from '../lexer/parser'; +import { Lexer, ConstExprParser, PhpDocParser, TokenIterator, TypeParser } from '../lexer/parser'; ``` ## Step 2: Define a Custom Transpiler Class ```TypeScript -class ExtendedTranspiler extends PHPDocTypeNodeToTypescriptTypeNodeTranspiler { - public isSnakeCase: boolean = true; +class ExtendedTranspiler extends PhpDocTypeNodeToTypescriptTypeNodeTranspiler { + public customProperty: boolean = true; constructor(public resolver: NameNodePathResolver) { super((nodeParts: string[]) => resolver.call(this, nodeParts) as { @@ -40,7 +40,7 @@ class ExtendedTranspiler extends PHPDocTypeNodeToTypescriptTypeNodeTranspiler { } ``` -By extending the `PHPDocTypeNodeToTypescriptTypeNodeTranspiler` class to create a custom `ExtendedTranspiler` class, you gain the flexibility to add custom properties like `isSnakeCase`. This allows you to tailor the transpiler's behavior to your project's needs. For example, the `isSnakeCase` property can be used to determine how names are transformed or resolved within the `NameNodePathResolver`, catering to specific naming conventions with ease. +By extending the `PhpDocTypeNodeToTypescriptTypeNodeTranspiler` class to create a custom `ExtendedTranspiler` class, you gain the flexibility to add custom properties like `customProperty`. This allows you to tailor the transpiler's behavior to your project's needs. For example, the `customProperty` property can be used to determine how names are transformed or resolved within the `NameNodePathResolver`, catering to specific naming conventions with ease. ## Step 3: Parse the PHPDoc Comment @@ -50,20 +50,16 @@ const transpileCommentText = (commentText: string) => { const lexer = new Lexer(); const constExprParser = new ConstExprParser(); const typeParser = new TypeParser(constExprParser); - const PHPDocParser = new PHPDocParser(typeParser, constExprParser); + const phpDocParser = new PhpDocParser(typeParser, constExprParser); // Tokenize and parse the PHPDoc comment to create the AST. const tokens = new TokenIterator(lexer.tokenize(commentText)); - const astRootNode = PHPDocParser.parse(tokens); // Produces a PHPDocNode + const astRootNode = phpDocParser.parse(tokens); // Produces a PHPDocNode // Extract property, return, or parameter nodes from the AST. const propertyTagValueNodes = astRootNode .getTags() - .map((node) => node.value) as ( - | PropertyTagValueNode - | ReturnTagValueNode - | ParamTagValueNode - )[]; + .map((node) => node.value) return propertyTagValueNodes; }; @@ -73,7 +69,7 @@ const transpileCommentText = (commentText: string) => { ```TypeScript const commentText = `/** -* @property-read array|null $person +* @property-read array|null $person */`; // Parse the PHPDoc comment text to get node structures. @@ -82,7 +78,7 @@ const tsTypeNode = transpileCommentText(commentText); // Define a resolver function for path resolving in the transpiler. const nameNodePathResolver: NameNodePathResolver = function (this: ExtendedTranspiler, nodeParts: string[]) { - console.log(nodeParts, this.isSnakeCase); + console.log(nodeParts, this.customProperty); return { name: '', @@ -94,8 +90,8 @@ const nameNodePathResolver: NameNodePathResolver = // Map through the nodes, transpile each, and render to TypeScript type strings. tsTypeNode.map((node) => { const transpiler = new ExtendedTranspiler(nameNodePathResolver); - transpiler.isSnakeCase = false; // Set your configurations - transpiler.beforeTranspile(); // Initialize transpilation state + transpiler.customProperty = 'this is a custom property'; // Set your configurations + transpiler.beforeTranspile(); // Initialize transpilation state(reset the state of importDeclarations) const transpiledNode = transpiler.transpile(node.type); // Transpile the node // Render the TypeScript node to a string @@ -103,8 +99,8 @@ tsTypeNode.map((node) => { }); ``` -The `nameNodePathResolver` function is defined as a `NameNodePathResolver` for the `ExtendedTranspiler` class. Within this function, by using the `this` keyword typed as `ExtendedTranspiler`, it gains direct access to properties and methods of `ExtendedTranspiler`, including the custom property `isSnakeCase`. +The `nameNodePathResolver` function is defined as a `NameNodePathResolver` for the `ExtendedTranspiler` class. Within this function, by using the `this` keyword typed as `ExtendedTranspiler`, it gains direct access to properties and methods of `ExtendedTranspiler`, including the custom property `customProperty`. ## Conclusion -This guide presented a simplistic way to bridge PHPDoc comments and TypeScript type annotations using a transpiler. By parsing, transpiling, and rendering, you can automate the conversion of types from PHP to TypeScript, enhancing interoperability between the two languages in your project. +This guide presented a simplistic way to bridge PHPDoc comments and TypeScript type definitions using a transpiler. By parsing, transpiling, and rendering, you can automate the conversion of types from PHP to TypeScript, enhancing interoperability between the two languages in your project.