diff --git a/src/phpdoc-parser/transpiler/README.md b/src/phpdoc-parser/transpiler/README.md index 1b49bf90..5df265fc 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,7 +13,7 @@ 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 @@ -28,7 +28,7 @@ import { Lexer, ConstExprParser, PHPDocParser, TokenIterator, TypeParser } from ```TypeScript class ExtendedTranspiler extends PHPDocTypeNodeToTypescriptTypeNodeTranspiler { - public isSnakeCase: boolean = true; + 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 @@ -59,11 +59,7 @@ const transpileCommentText = (commentText: string) => { // 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.