update docs

Author: matronator

config.json

@@ -1,3 +1,3 @@
 {
-    "debug": false
+    "debug": true
 }

docs/Gemfile.lock

@@ -212,6 +212,8 @@ GEM
     minitest (5.19.0)
     nokogiri (1.18.9-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.9-x86_64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.9-x86_64-linux-gnu)
       racc (~> 1.4)
     octokit (4.25.1)
@@ -251,6 +253,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  x86_64-darwin-20
   x86_64-linux
 
 DEPENDENCIES

docs/assets/images/.step-1-signup-button.png.icloud

@@ -7,129 +7,128 @@ parent: API
 
 # `Generator` class
 
-This code provides a `Generator` class for parsing, generating, and manipulating PHP files. It handles various PHP constructs such as namespaces, classes, interfaces, traits, and more. Additionally, it can detect reserved keywords and make names safe for use in generated code.
+{: .warning }
+> This page documents the modern `Generator` class for parsing templates of any file format. For legacy PHP generation from JSON/YAML/NEON templates, see the `ClassicGenerator` class.
+
+The `Generator` class provides functionality for parsing modern templates (any file format) and generating files. It uses [Pars'Em](https://github.com/matronator/parsem) for template parsing and variable substitution.
 
 - [Important Classes](#important-classes)
-  - [FileObject](#fileobject)
-  - [PhpFile](#phpfile)
+  - [GenericFileObject](#genericfileobject)
+  - [TemplateHeader](#templateheader)
 - [Constants](#constants)
 - [Methods](#methods)
-  - [`isBundle`](#isbundlestring-path-string-contents--null-bool)
-  - [`parse`](#parsestring-filename-string-contents-array-arguments-fileobject)
-  - [`parseFile`](#parsefilestring-path-array-arguments-fileobject)
-  - [`generateFile`](#generatefileobject-parsed-array-arguments-fileobject)
-  - [`getName`](#getnamestring-path-string-contents--null-string)
-  - [`generate`](#generateobject-body-array-args-phpfile)
-  - [`is`](#ismixed-subject-bool)
-  - [`isReservedKeyword`](#isreservedkeywordstring-name-bool)
-  - [`makeNameSafe`](#makenamesafestring-name-string)
+  - [`parseAnyFile`](#parseanyfilestring-path-array-arguments--bool-usec commentsyntax--false-genericfileobject)
+  - [`writeFiles`](#writefilesgenericfileobject--genericfileobject-files-void)
+  - [`getName`](#getnamestring-content--null-string-path--null-string)
+  - [`getTemplateHeader`](#gettemplateheaderstring-content-templateheader)
+  - [`removeHeader`](#removeheaderstring-content-string)
 
 ## Important Classes
 
-### FileObject
+### GenericFileObject
 
-`Matronator\Mtrgen\FileObject` is the main data structure for the parsed templates. It contains all the information about the file that is needed for writing it to the disk.
+`Matronator\Mtrgen\GenericFileObject` is the main data structure for parsed modern templates. It contains all the information about the file that is needed for writing it to the disk.
 
 ```php
-class FileObject
-{
-    public PhpFile $contents;
-
-    public string $filename;
+namespace Matronator\Mtrgen;
 
-    public string $directory;
-
-    public ?string $entity = null;
+class GenericFileObject
+{
+    public string $contents;  // The file contents as a string
+    public string $filename;  // The output filename (including extension)
+    public string $directory; // The output directory path
 
-    public function __construct(string $directory, string $filename, PhpFile $contents, ?string $entity = null) {
-        $this->filename = $filename . '.php';
+    public function __construct(string $directory, string $filename, string $contents) {
+        $this->filename = $filename;
         $this->contents = $contents;
         $this->directory = $directory;
-        $this->entity = $entity;
     }
 }
 ```
 
-### PhpFile
-
-`Nette\PhpGenerator\PhpFile` is a class from the [Nette](https://nette.org) [PHP Generator library](https://github.com/nette/php-generator). It is used to represent a PHP file and its contents. It is used by the `Generator` class for generating the parsed templates.
-
-Constants
----------
-
--   `RESERVED_KEYWORDS`: An array of reserved keywords in PHP.
--   `RESERVED_CONSTANTS`: An array of reserved constants in PHP.
-
-Methods
--------
+### TemplateHeader
 
-### `isBundle(string $path, ?string $contents = null): bool`
+`Matronator\Mtrgen\Template\TemplateHeader` represents the metadata header of a template file.
 
-Checks if a given template is a bundle.
+```php
+namespace Matronator\Mtrgen\Template;
 
--   `$path`: The path of the template file.
--   `$contents`: (optional) The contents of the template file.
--   Returns: A boolean indicating whether the template is a bundle.
+class TemplateHeader
+{
+    public string $name;     // Template name (for storage/identification)
+    public string $filename;  // Output filename (can use template variables)
+    public string $path;     // Output directory path (can use template variables)
 
-### `parse(string $filename, string $contents, array $arguments): FileObject`
+    public function __construct(string $name, string $filename, string $path);
+    public static function fromArray(array $array): static;
+}
+```
 
-Parses and generates a `FileObject` from string content and a filename.
+## Constants
 
--   `$filename`: The filename of the file to parse.
--   `$contents`: The contents of the file to parse.
--   `$arguments`: An array of arguments for parsing.
--   Returns: A `FileObject` representing the parsed file.
+-   `HEADER_PATTERN`: Regular expression pattern for matching the template header block (`/^--- MTRGEN ---(.+)--- \/MTRGEN ---/ms`).
+-   `COMMENT_PATTERN`: Regular expression pattern for matching comment-based template variables (for use with `useCommentSyntax` option).
 
-### `parseFile(string $path, array $arguments): FileObject`
+## Methods
 
-Parses and generates a `FileObject` from a file.
+### `parseAnyFile(string $path, array $arguments = [], bool $useCommentSyntax = false): GenericFileObject`
 
--   `$path`: The path to the file to parse.
--   `$arguments`: An array of arguments for parsing.
--   Returns: A `FileObject` representing the parsed file.
+Parses a template file of any format and returns a `GenericFileObject` ready to be written to disk.
 
-### `generateFile(object $parsed, array $arguments): FileObject`
+-   `$path`: The path to the template file.
+-   `$arguments`: (optional) An array of arguments to pass to the template variables.
+-   `$useCommentSyntax`: (optional) If `true`, uses comment-based syntax (`/*variable*/`) instead of `<%variable%>` syntax.
+-   Returns: A `GenericFileObject` representing the parsed file.
 
-Generates a `FileObject` from a parsed object.
+**Example:**
 
--   `$parsed`: The parsed object.
--   `$arguments`: An array of arguments for generating the file.
--   Returns: A `FileObject` representing the generated file.
+```php
+$file = Generator::parseAnyFile('component.js.mtr', [
+    'name' => 'MyComponent',
+    'event' => 'click'
+]);
+// $file->filename will be "MyComponent.js" (from header)
+// $file->directory will be the path from header
+// $file->contents will be the parsed template content
+```
 
-### `getName(string $path, ?string $contents = null): string`
+### `writeFiles(GenericFileObject|GenericFileObject[] $files): void`
 
-Gets the name of the template from a file.
+Writes one or more parsed file objects to disk. Creates directories if they don't exist.
 
--   `$path`: The path of the template file.
--   `$contents`: (optional) The contents of the template file.
--   Returns: The name of the template.
+-   `$files`: A single `GenericFileObject` or an array of `GenericFileObject` instances.
 
-### `generate(object $body, array $args): PhpFile`
+**Example:**
 
-Generates a `PhpFile` from a parsed object.
+```php
+// Write a single file
+Generator::writeFiles($file);
 
--   `$body`: The parsed object.
--   `$args`: An array of arguments for generating the file.
--   Returns: A `PhpFile` representing the generated file.
+// Write multiple files
+Generator::writeFiles([$file1, $file2, $file3]);
+```
 
-### `is(mixed &$subject): bool`
+### `getName(?string $content = null, ?string $path = null): string`
 
-Shorthand for checking if a variable is set and not empty.
+Gets the template name from the header. Either `$content` or `$path` must be provided.
 
--   `$subject`: The variable to check.
--   Returns: A boolean indicating whether the variable is set and not empty.
+-   `$content`: (optional) The template file contents.
+-   `$path`: (optional) The path to the template file.
+-   Returns: The template name from the header.
+-   Throws: `RuntimeException` if neither `$content` nor `$path` is provided, or if the header is missing required fields.
 
-### `isReservedKeyword(string $name): bool`
+### `getTemplateHeader(string $content): TemplateHeader`
 
-Checks if the given name is a reserved keyword.
+Extracts and parses the template header from the file content.
 
--   `$name`: The name to check.
--   Returns: A boolean indicating whether the name is a reserved keyword.
+-   `$content`: The template file contents (including the header).
+-   Returns: A `TemplateHeader` object with `name`, `filename`, and `path` properties.
+-   Throws: `RuntimeException` if the header is missing required properties.
 
-### `makeNameSafe(string $name): string`
+### `removeHeader(string $content): string`
 
-Makes the given name safe by adding an underscore if it is a reserved keyword.
+Removes the template header block from the file content, returning only the template body.
 
--   `$name`: The name to make safe.
--   Returns: A safe name that doesn't conflict with reserved keywords or constants.
+-   `$content`: The template file contents (including the header).
+-   Returns: The template content without the header block.
 

docs/assets/images/step-1-signup-button.png

@@ -7,7 +7,7 @@ title: Introduction
 
 ![MTRGen Logo](assets/images/logo.png)
 
-File generator engine that can generate PHP files from JSON/YAML/NEON templates.
+File generator engine that can generate files of any format from templates. Templates can be any file format (JavaScript, PHP, TypeScript, Python, etc.) and will generate files in the same format. MTRGen also supports legacy JSON/YAML/NEON templates for generating PHP files.
 
 ## Requirements
 
@@ -48,19 +48,19 @@ vendor/bin/mtrgen list
 vendor/bin/mtrgen generate --help
 vendor/bin/mtrgen gen -h
 
-# Generate from file
-vendor/bin/mtrgen generate --path=my/folder/template.json
-vendor/bin/mtrgen gen -p my/folder/template.json
+# Generate from file (any format)
+vendor/bin/mtrgen generate --path=my/folder/component.js.mtr
+vendor/bin/mtrgen gen -p my/folder/template.php.mtr
 
 # Generate from the local store
 vendor/bin/mtrgen generate TemplateName
 
 # Save a template to the local store
-vendor/bin/mtrgen save path/to/template.json
-vendor/bin/mtrgen s path/to/template.json
+vendor/bin/mtrgen save path/to/template.js.mtr
+vendor/bin/mtrgen s path/to/template.php.mtr
 
 # Optionally provide an alias to save the template under
-vendor/bin/mtrgen save path/to/template.json --alias=NewName
+vendor/bin/mtrgen save path/to/template.js.mtr --alias=NewName
 
 # Remove a template from the local store
 vendor/bin/mtrgen remove TemplateName
@@ -69,7 +69,7 @@ vendor/bin/mtrgen r TemplateName
 
 ## Acknowledgement
 
-This project would not be possible without [Nette](https://nette.org)'s [`php-generator`](https://github.com/nette/php-generator) package, which is used for the final code generation itself to output the finished PHP file.
+This project uses [Pars'Em](https://github.com/matronator/parsem) for template parsing and variable substitution. For legacy PHP file generation, it uses [Nette](https://nette.org)'s [`php-generator`](https://github.com/nette/php-generator) package.
 
 ## License
 

docs/code-api/generator.md

@@ -31,7 +31,7 @@ vendor/bin/mtrgen generate vendor/template
 
 If you just want to generate a file from a template in the online registry one-time only and don't want to add it to your local store, you can use the `use` command. This command works just like the `generate` command, except it takes an identifier as an argument and searches the online registry instead of your local store.
 
-When it finds the template, it will prompt you to provide arguments for the template (if there are any) and generates the PHP file without saving the template in your local store. This is useful if you just want to use a template one time and know you won't be needing it in the future again.
+When it finds the template, it will prompt you to provide arguments for the template (if there are any) and generates the file without saving the template in your local store. This is useful if you just want to use a template one time and know you won't be needing it in the future again. The generated file format depends on the template (modern templates can generate any format, legacy templates generate PHP files).
 
 ### Using the `use` command
 

docs/index.md

@@ -64,11 +64,14 @@ Now that your account is created and you've successfully logged in, it's time yo
 Publishing a template is as simple as just running a single command:
 
 ```bash
-vendor/bin/mtrgen publish --path=path/to/your/template.json
+vendor/bin/mtrgen publish --path=path/to/your/template.js.mtr
 # Or a shorter alias
-vendor/bin/mtrgen pub -p path/to/your/template.json
+vendor/bin/mtrgen pub -p path/to/your/template.php.mtr
 ```
 
+{: .note }
+> You can publish templates of any format (modern templates) or legacy JSON/YAML/NEON templates. The template format doesn't matter - as long as it has a valid header, it can be published.
+
 Alternatively if you want to publish a template you already have saved in your local store, just provide the template name instead of the `--path` option, like this:
 
 ```bash

docs/online-registry/index.md

@@ -9,10 +9,14 @@ has_children: true
 
 ## Introduction
 
-Generator templates (or just templates) describe the structure of the generated file. Templates can be either YAML, JSON or NEON files and they have to conform to a JSON schema. We will talk more about the schema in the next chapter (*see [mtrgen-template-schema.json](template-structure.md#mtrgen-template-schema)*).
+Generator templates (or just templates) describe the structure of the generated file. MTRGen supports two types of templates:
+
+1. **Modern templates**: Any file format (JavaScript, PHP, TypeScript, Python, etc.) that can generate files in the same format. These templates use a header block to define metadata and use template variables for dynamic content.
+
+2. **Legacy templates**: JSON/YAML/NEON files that generate PHP files. These templates conform to a JSON schema and are used for generating PHP classes, interfaces, and traits. (*See [Template Structure](template-structure.md) for more details on legacy templates.*)
 
 {: .tip }
-> It is recommended to name your templates with a `.mtr` suffix after the name right after the extension (eg. `entity.yaml.mtr`). If you do that, the [MTRGen Templates Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=matronator.mtrgen-yaml-templates) VSCode extension, will add syntax highlighting and snippets to all `*.mtr` files.
+> It is recommended to name your templates with a `.mtr` extension (eg. `component.js.mtr`, `entity.php.mtr`). The `.mtr` extension helps identify template files and enables syntax highlighting in editors. The [MTRGen Templates Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=matronator.mtrgen-yaml-templates) VSCode extension provides syntax highlighting and snippets for `*.mtr` files.
 
 ## Template syntax
 
@@ -27,15 +31,18 @@ The header block looks like this:
 ```
 --- MTRGEN ---
 name: template-name
-filename: <% name|firstUpper %>.php
-path: ./app/Controllers
---- MTRGEN ---
+filename: <% name|upperFirst %>.js
+path: ./src/components
+--- /MTRGEN ---
 
-// Rest of the template
+// Rest of the template content
 ```
 
 You can use template variables for the header values, except for the `name` field, which must be known beforehand to be able to correctly save and use the template later.
 
+{: .note }
+> The output filename is defined in the `filename` field of the header. The generated file will have exactly the name you specify here, including the extension. For example, if your template is `component.js.mtr` and the header specifies `filename: <% name %>.js`, the generated file will be `MyComponent.js` (assuming `name` is "MyComponent").
+
 #### Header fields
 
 ##### `name`
@@ -44,7 +51,7 @@ A unique name of the template to be saved under in the local store. If published
 
 ##### `filename`
 
-The filename of the generated file. Can use template variables to make the filename dynamic.
+The filename of the generated file, including the extension. Can use template variables to make the filename dynamic. The generated file will have exactly this name - for example, if you specify `filename: <% name %>.js`, the output will be a JavaScript file with that name.
 
 ##### `path`
 
@@ -154,6 +161,31 @@ There are a few built-in filters that you can use:
 
 `truncate` - Truncates the variable to the specified length
 
+## Examples
+
+### Modern Template Example
+
+Here's an example of a modern JavaScript template (`component.js.mtr`):
+
+```javascript
+--- MTRGEN ---
+name: js-component
+filename: <% name|upperFirst %>.js
+path: src/components
+--- /MTRGEN ---
+
+document.addEventListener('<% event="click" %>', function() {
+    var component = document.querySelector('#<% id="myId" %>');
+    component.classList.add('<% className="active"|lower %>');
+});
+```
+
+When you generate this template with arguments like `name=Button event=click id=btn1 className=ACTIVE`, it will create `Button.js` in the `src/components` directory with the variables replaced.
+
+### Legacy Template Example
+
+Legacy templates are JSON/YAML/NEON files that generate PHP files. See the [Template Structure](template-structure.md) page for details on legacy template format.
+
 ## VSCode Extension
 
 To get syntax highlighting for template files (highlight/colorize `<% variable|filter %>` and `<% if %><% endif %>` even inside strings) and some helper snippets (like `---` to insert the template header), you can download the [MTRGen Templates Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=matronator.mtrgen-yaml-templates) extension for VS Code.

docs/online-registry/publishing-templates.md

@@ -7,7 +7,13 @@ parent: Templates
 
 # Template structure
 
-As mentioned earlier, the template parser supports YAML, JSON and NEON files, so you can write your templates using any of these formats. All templates must follow the same structure, which is defined in a JSON schema. You can find the full schema here: [mtrgen-template-schema.json](https://www.mtrgen.com/storage/schemas/template/latest/mtrgen-template-schema.json)
+{: .warning }
+> This page describes **legacy templates** - JSON/YAML/NEON files that generate PHP files. For modern templates (any file format), see the [Templates Overview](../templates/index.md).
+
+Legacy templates are YAML, JSON or NEON files that generate PHP files. All legacy templates must follow the same structure, which is defined in a JSON schema. You can find the full schema here: [mtrgen-template-schema.json](https://www.mtrgen.com/storage/schemas/template/latest/mtrgen-template-schema.json)
+
+{: .note }
+> Modern templates (any file format) don't use this schema. They simply use a header block and template variables directly in the file content. See the [Templates Overview](../templates/index.md) for more information.
 
 Here is a simplified version of the schema in YAML format for better readability.