13 unstable releases (6 breaking)
0.8.3 | Mar 1, 2024 |
---|---|
0.8.0 | Sep 13, 2023 |
0.7.0 | Jul 21, 2023 |
0.6.1 | May 23, 2021 |
0.5.1 | Feb 18, 2021 |
#79 in Development tools
92 downloads per month
745KB
18K
SLoC
Ludtwig
Linter / Formatter for Twig template files which respects HTML and your time.
Features
- Fast
- written in Rust
- works on files concurrently
- Helpful
- provides rich error messages and suggestions most of the time
- Rule based
- Rules can annotate syntax and make suggestions
- Suggestions can be applied automatically with
--fix
- Configurable
- Rules can be ignored for the whole file or next line (which ignores the whole next SyntaxNode)
.ludtwig-ignore
to ignore whole files completely (like your.gitignore
)ludtwig-config.toml
(use-C
to create one) to configure the rules for your project / adjust the code style- Environment variables can override config values
- The Parser is not HTML Spec compliant, but
- Almost all Twig syntax is supported
- all input is parsed into a Syntax tree
- even invalid syntax does not stop the parsing, and it tries to parse as much valid syntax as possible
Current limitations
- Twig syntax is still not fully supported
{%- ... -%}
whitespace removal braces are not yet supported- Usage of PHP closures as function arguments is currently not supported
- You may encounter other edge cases that result in parsing errors. Please create issues for them.
- The list of rules is still quite small so many things besides the syntax aren't checked / suggested
Installation
Cargo (rust toolchain)
Run the following cargo command to install or update ludtwig:
cargo install ludtwig
You can install cargo here
If you don't want to install the rust toolchain / cargo you can still use the other methods below.
Manual
Download the latest release binary for your operating system and put it in your PATH for easy access.
Docker
Have a look at the docker image or try it with the following command to lint the current working directory:
docker run --rm -v $(pwd):/ludtwig maltejanz/ludtwig:latest ludtwig .
Nix / DevEnv
You can also use the nix package.
How to use Ludtwig?
After the installation have a look at ludtwig --help
for more information. It should be self-explanatory.
Also have a look at the default config file if you want to customize the way how ludtwig analyses your files.
To create it in your current working directory run ludtwig -C
.
Allowed syntax
To prevent the creation of invalid / dirty HTML by Twig ludtwig only allows the Twig syntax in certain places. Without this restriction it wouldn't be possible to parse the combined syntax in a single hierarchical syntax tree. Have a look at the example below to get the general idea where Twig syntax is allowed:
{% block my_component %}
{% set isActive = true %}
<div id="my-component"
class="my-component {% if isLarge %}large{% endif %}"
{{ dataAttribute }}="data"
{# Single word attributes don't strictly require quotes #}
data-active={{ isActive }}
>
{% block my_component_inner %}
<span id="my-span"
{% if isActive %}
style="color: red"
{% endif %}
>
hello {{ name }}
</span>
{% endblock %}
</div>
{% endblock %}
License
Copyright (c) 2024 Malte Janz
ludtwig
is distributed under the terms of the MIT License.
See the LICENSE file for details.
For testing purposes this repository also includes code from the following sources (not included in distributed binary):
Dependencies
~10–19MB
~228K SLoC