diff --git a/README.md b/README.md index 417f2df..e5856c6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,140 @@ -<<<<<<< HEAD -# mojofmt - -Formatter for Mojolicious Embedded Perl templates (.ep, .htm.ep, .html.ep) - -======= # Mojolicious Template Formatter + Formatter for Mojolicious Embedded Perl templates (.ep, .htm.ep, .html.ep) ->>>>>>> 59bfbde88e2686d25b7f6a14692814da8f440e05 -mojofmt formats HTML and Mojolicious EP templates without breaking embedded Perl. It understands line directives (% ...), inline tags (<% ... %>), raw HTML blocks, and can reformat multi-line Perl blocks inside <% ... %> using perltidy (with a safe fallback if perltidy isn’t available). +mojofmt formats HTML and Mojolicious EP templates without breaking embedded Perl. It understands line directives (% ...), inline tags (<% ... %>), raw HTML blocks, and can reformat multi-line Perl blocks inside <% ... %> using perltidy (with a safe fallback if perltidy isn't available). + +## Online Web Interface + +**Try it online:** [https://mojofmt.bjsystems.co.uk](https://mojofmt.bjsystems.co.uk) + +The web interface provides: +- Real-time formatting with syntax highlighting +- File upload support for .ep files +- Download formatted results +- No registration required +- Secure processing with rate limiting + +## API Access + +### REST API Endpoint + +The formatter is available as a REST API for integration into your development workflow: + +**Base URL:** `https://mojofmt.bjsystems.co.uk/api/format` + +**Authentication:** Bearer token required + +**Request API Token:** Please create an issue in this repository requesting an API token. Include: +- Your intended use case +- Expected usage volume +- Contact information + +### API Usage + +```bash +curl -X POST https://mojofmt.bjsystems.co.uk/api/format \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -d '{ + "text": "<% my $name = \"World\"; %>
<%= $x %>
' | ./format_mojolicious.sh +``` + +### Script Options + +- `-u, --url URL`: API base URL (default: https://mojofmt.bjsystems.co.uk) +- `-t, --token TOKEN`: API token (overrides .env and environment) +- `-r, --remove-empty`: Remove empty lines from output +- `-f, --file FILE`: Read input from file instead of interactive input +- `-o, --output FILE`: Write output to file instead of stdout +- `-h, --help`: Show help message + +### Authentication Priority + +The script looks for API tokens in this order: +1. Command line `--token` option +2. `.env` file (`FLASK_API_TOKEN=...`) +3. Environment variable `FLASK_API_TOKEN` +4. Environment variable `API_TOKEN` ## Features @@ -94,7 +220,7 @@ Increase logging: - Extended multi-line Perl blocks: - Detected when <% (or <%-) is on a line by itself, and %> (or -%>) is on a line by itself - The inner Perl is dedented, wrapped in do { ... } and run through perltidy; if that fails or perltidy is missing, a brace-aware fallback indenter is used - - Inner lines are re-indented to match the opening/closing delimiter’s indentation + - Inner lines are re-indented to match the opening/closing delimiter's indentation - EOL normalization: - Input CRLF/CR are normalized internally; output can be forced to lf/crlf or preserve the original @@ -165,7 +291,7 @@ Directories are walked recursively; only matching files are formatted. ## Tips and caveats -- perltidy recommended: For best results on complex Perl inside templates, install perltidy. mojofmt falls back to a brace-aware indenter for extended blocks, but won’t do token-level Perl formatting without perltidy. +- perltidy recommended: For best results on complex Perl inside templates, install perltidy. mojofmt falls back to a brace-aware indenter for extended blocks, but won't do token-level Perl formatting without perltidy. - Extended block detection: Only triggers when the opening <% (or <%-) and closing %> (or -%>) are on their own lines. Inline <% ... %> on the same line are handled by the inline path. - Raw blocks: Content inside pre/script/style/textarea is not changed. - Chomp markers: Left/right chomps (<%- and -%>) are preserved and not moved. @@ -177,7 +303,7 @@ Directories are walked recursively; only matching files are formatted. - perltidy non-zero exit N in debug logs: - mojofmt wraps extended blocks in do { ... } for perltidy; if it still fails, run perltidy manually on the wrapper to see the error. - Ensure perltidy is on PATH or pass --perltidy /path/to/perltidy. -- Extended block didn’t reformat: +- Extended block didn't reformat: - Confirm the delimiters are on their own lines (no code on the <% / %> lines). - Run with --log-level debug to see whether perltidy or the naive indenter handled the block. - Spaces around Perl keywords: @@ -200,12 +326,14 @@ Generate a diff without writing: - Open an issue or pull request with a clear description and a minimal repro template - Please include before/after snippets and your command-line flags - If you modify formatting rules, add/adjust a self-test where possible +- **For API access:** Create an issue requesting an API token with your use case details ## License -See LICENSE file in this repository. If you don’t have one yet, consider MIT or Apache-2.0. +See LICENSE file in this repository. If you don't have one yet, consider MIT or Apache-2.0. ## Acknowledgments - Mojolicious and Mojo::Template for the EP syntax -- Perl::Tidy for robust Perl formatting \ No newline at end of file +- Perl::Tidy for robust Perl formatting +