Annie  Emard

Annie Emard

1653075360

HAML Lint: Tool For Writing Clean and Consistent HAML

HAML-Lint

haml-lint is a tool to help keep your HAML files clean and readable. In addition to HAML-specific style and lint checks, it integrates with RuboCop to bring its powerful static analysis tools to your HAML documents.

You can run haml-lint manually from the command line, or integrate it into your SCM hooks.

Requirements

  • Ruby 2.4+
  • HAML 4.0+

Installation

gem install haml_lint

If you'd rather install haml-lint using bundler, don't require it in your Gemfile:

gem 'haml_lint', require: false

Then you can still use haml-lint from the command line, but its source code won't be auto-loaded inside your application.

Usage

Run haml-lint from the command line by passing in a directory (or multiple directories) to recursively scan:

haml-lint app/views/

You can also specify a list of files explicitly:

haml-lint app/**/*.html.haml

haml-lint will output any problems with your HAML, including the offending filename and line number.

File Encoding

haml-lint assumes all files are encoded in UTF-8.

Command Line Flags

Command Line FlagDescription
--auto-gen-configGenerate a configuration file acting as a TODO list
--auto-gen-exclude-limitNumber of failures to allow in the TODO list before the entire rule is excluded
-c/--configSpecify which configuration file to use
-e/--excludeExclude one or more files from being linted
-i/--include-linterSpecify which linters you specifically want to run
-x/--exclude-linterSpecify which linters you don't want to run
-r/--reporterSpecify which reporter you want to use to generate the output
-p/--parallelRun linters in parallel using available CPUs
--fail-fastSpecify whether to fail after the first file with lint
--fail-levelSpecify the minimum severity (warning or error) for which the lint should fail
--[no-]colorWhether to output in color
--[no-]summaryWhether to output a summary in the default reporter
--show-lintersShow all registered linters
--show-reportersDisplay available reporters
-h/--helpShow command line flag documentation
-v/--versionShow haml-lint version
-V/--verbose-versionShow haml-lint, haml, and ruby version information

Configuration

haml-lint will automatically recognize and load any file with the name .haml-lint.yml as a configuration file. It loads the configuration based on the directory haml-lint is being run from, ascending until a configuration file is found. Any configuration loaded is automatically merged with the default configuration (see config/default.yml).

Here's an example configuration file:

linters:
  ImplicitDiv:
    enabled: false
    severity: error

  LineLength:
    max: 100

All linters have an enabled option which can be true or false, which controls whether the linter is run, along with linter-specific options. The defaults are defined in config/default.yml.

Linter Options

OptionDescription
enabledIf false, this linter will never be run. This takes precedence over any other option.
includeList of files or glob patterns to scope this linter to. This narrows down any files specified via the command line.
excludeList of files or glob patterns to exclude from this linter. This excludes any files specified via the command line or already filtered via the include option.
severityThe severity of the linter. External tools consuming haml-lint output can use this to determine whether to warn or error based on the lints reported.

Global File Exclusion

The exclude global configuration option allows you to specify a list of files or glob patterns to exclude from all linters. This is useful for ignoring third-party code that you don't maintain or care to lint. You can specify a single string or a list of strings for this option.

Skipping Frontmatter

Some static blog generators such as Jekyll include leading frontmatter to the template for their own tracking purposes. haml-lint allows you to ignore these headers by specifying the skip_frontmatter option in your .haml-lint.yml configuration:

skip_frontmatter: true

Inheriting from Other Configuration Files

The inherits_from global configuration option allows you to specify an inheritance chain for a configuration file. It accepts either a scalar value of a single file name or a vector of multiple files to inherit from. The inherited files are resolved in a first in, first out order and with "last one wins" precedence. For example:

inherits_from:
  - .shared_haml-lint.yml
  - .personal_haml-lint.yml

First, the default configuration is loaded. Then the .shared_haml-lint.yml configuration is loaded, followed by .personal_haml-lint.yml. Each of these overwrite each other in the event of a collision in configuration value. Once the inheritance chain is resolved, the base configuration is loaded and applies its rules to overwrite any in the intermediate configuration.

Lastly, in order to match your RuboCop configuration style, you can also use the inherit_from directive, which is an alias for inherits_from.

Linters

ยป Linters Documentation

haml-lint is an opinionated tool that helps you enforce a consistent style in your HAML files. As an opinionated tool, we've had to make calls about what we think are the "best" style conventions, even when there are often reasonable arguments for more than one possible style. While all of our choices have a rational basis, we think that the opinions themselves are less important than the fact that haml-lint provides us with an automated and low-cost means of enforcing consistency.

Custom Linters

Add the following to your configuration file:

require:
  - './relative/path/to/my_first_linter.rb'
  - 'absolute/path/to/my_second_linter.rb'

The files that are referenced by this config should have the following structure:

module HamlLint
  # MyFirstLinter is the name of the linter in this example, but it can be anything
  class Linter::MyFirstLinter < Linter
    include LinterRegistry

    def visit_tag
      return unless node.tag_name == 'div'
      record_lint(node, "You're not allowed divs!")
    end
  end
end

For more information on the different types on HAML node, please look through the HAML parser code: https://github.com/haml/haml/blob/master/lib/haml/parser.rb

Keep in mind that by default your linter will be disabled by default. So you will need to enable it in your configuration file to have it run.

Disabling Linters within Source Code

One or more individual linters can be disabled locally in a file by adding a directive comment. These comments look like the following:

-# haml-lint:disable AltText, LineLength
[...]
-# haml-lint:enable AltText, LineLength

You can disable all linters for a section with the following:

-# haml-lint:disable all

Directive Scope

A directive will disable the given linters for the scope of the block. This scope is inherited by child elements and sibling elements that come after the comment. For example:

-# haml-lint:disable AltText
#content
  %img#will-not-show-lint-1{ src: "will-not-show-lint-1.png" }
  -# haml-lint:enable AltText
  %img#will-show-lint-1{ src: "will-show-lint-1.png" }
  .sidebar
    %img#will-show-lint-2{ src: "will-show-lint-2.png" }
%img#will-not-show-lint-2{ src: "will-not-show-lint-2.png" }

The #will-not-show-lint-1 image on line 2 will not raise an AltText lint because of the directive on line 1. Since that directive is at the top level of the tree, it applies everywhere.

However, on line 4, the directive enables the AltText linter for the remainder of the #content element's content. This means that the #will-show-lint-1 image on line 5 will raise an AltText lint because it is a sibling of the enabling directive that appears later in the #content element. Likewise, the #will-show-lint-2 image on line 7 will raise an AltText lint because it is a child of a sibling of the enabling directive.

Lastly, the #will-not-show-lint-2 image on line 8 will not raise an AltText lint because the enabling directive on line 4 exists in a separate element and is not a sibling of the it.

Directive Precedence

If there are multiple directives for the same linter in an element, the last directive wins. For example:

-# haml-lint:enable AltText
%p Hello, world!
-# haml-lint:disable AltText
%img#will-not-show-lint{ src: "will-not-show-lint.png" }

There are two conflicting directives for the AltText linter. The first one enables it, but the second one disables it. Since the disable directive came later, the #will-not-show-lint element will not raise an AltText lint.

You can use this functionality to selectively enable directives within a file by first using the haml-lint:disable all directive to disable all linters in the file, then selectively using haml-lint:enable to enable linters one at a time.

Onboarding Onto a Preexisting Project

Adding a new linter into a project that wasn't previously using one can be a daunting task. To help ease the pain of starting to use Haml-Lint, you can generate a configuration file that will exclude all linters from reporting lint in files that currently have lint. This gives you something similar to a to-do list where the violations that you had when you started using Haml-Lint are listed for you to whittle away, but ensuring that any views you create going forward are properly linted.

To use this functionality, call Haml-Lint like:

haml-lint --auto-gen-config

This will generate a .haml-lint_todo.yml file that contains all existing lint as exclusions. You can then add inherits_from: .haml-lint_todo.yml to your .haml-lint.yml configuration file to ensure these exclusions are used whenever you call haml-lint.

By default, any rules with more than 15 violations will be disabled in the todo-file. You can increase this limit with the auto-gen-exclude-limit option:

haml-lint --auto-gen-config --auto-gen-exclude-limit 100

Editor Integration

Vim

If you use vim, you can have haml-lint automatically run against your HAML files after saving by using the Syntastic plugin. If you already have the plugin, just add let g:syntastic_haml_checkers = ['haml_lint'] to your .vimrc.

Vim 8 / Neovim

If you use vim 8+ or Neovim, you can have haml-lint automatically run against your HAML files as you type by using the Asynchronous Lint Engine (ALE) plugin. ALE will automatically lint your HAML files if it detects haml-lint in your PATH.

Sublime Text 3

If you use SublimeLinter 3 with Sublime Text 3 you can install the SublimeLinter-haml-lint plugin using Package Control.

Atom

If you use atom, you can install the linter-haml plugin.

TextMate 2

If you use TextMate 2, you can install the Haml-Lint.tmbundle bundle.

Visual Studio Code

If you use Visual Studio Code, you can install the Haml Lint extension

Git Integration

If you'd like to integrate haml-lint into your Git workflow, check out our Git hook manager, overcommit.

Rake Integration

To execute haml-lint via a Rake task, make sure you have rake included in your gem path (e.g. via Gemfile) add the following to your Rakefile:

require 'haml_lint/rake_task'

HamlLint::RakeTask.new

By default, when you execute rake haml_lint, the above configuration is equivalent to running haml-lint ., which will lint all .haml files in the current directory and its descendants.

You can customize your task by writing:

require 'haml_lint/rake_task'

HamlLint::RakeTask.new do |t|
  t.config = 'custom/config.yml'
  t.files = ['app/views', 'custom/*.haml']
  t.quiet = true # Don't display output from haml-lint to STDOUT
end

You can also use this custom configuration with a set of files specified via the command line:

# Single quotes prevent shell glob expansion
rake 'haml_lint[app/views, custom/*.haml]'

Files specified in this manner take precedence over the task's files attribute.

Documentation

Code documentation is generated with YARD and hosted by RubyDoc.info.

Contributing

We love getting feedback with or without pull requests. If you do add a new feature, please add tests so that we can avoid breaking it in the future.

Speaking of tests, we use Appraisal to test against both HAML 4 and 5. We use rspec to write our tests. To run the test suite, execute the following from the root directory of the repository:

appraisal bundle install
appraisal bundle exec rspec

Community

All major discussion surrounding HAML-Lint happens on the GitHub issues page.

Changelog

If you're interested in seeing the changes and bug fixes between each version of haml-lint, read the HAML-Lint Changelog.

Author: sds
Source Code: https://github.com/sds/haml-lint
License: MIT license

#haml #lint 

HAML Lint: Tool For Writing Clean and Consistent HAML
Veronica  Roob

Veronica Roob

1649142840

MtHAML: A PHP Implementation Of The HAML Language

Multi target HAML

MtHaml is a PHP implementation of the HAML language which can target multiple languages.

Currently supported targets are PHP and Twig, and new ones can be added easily.

Mt-Haml implements the exact same syntax as ruby-haml; the only difference is that any supported language can be used everywhere HAML expects Ruby code:

HAML/Twig:

%ul#users
  - for user in users
    %li.user
      = user.name
      Email: #{user.email}
      %a(href=user.url) Home page

Rendered:

<ul id="users">
  {% for user in users %}
    <li class="user">
      {{ user.name }}
      Email: {{ user.email }}
      <a href="{{ user.url }}">Home page</a>
    </li>
  {% endfor %}
</ul>

HAML/PHP:

%ul#users
  - foreach($users as $user)
    %li.user
      = $user->getName()
      Email: #{$user->getEmail()}
      %a(href=$user->getUrl()) Home page

Rendered:

<ul id="users">
  <?php foreach($users as $user) { ?>
    <li class="user">
      <?php echo $user->getName(); ?>
      Email: <?php echo $user->getEmail(); ?>
      <a href="<?php echo $user->getUrl(); ?>">Home page</a>
    </li>
  <?php } ?>
</ul>

Usage

PHP:

<?php
$haml = new MtHaml\Environment('php');
$executor = new MtHaml\Support\Php\Executor($haml, array(
    'cache' => sys_get_temp_dir().'/haml',
));

// Compiles and executes the HAML template, with variables given as second
// argument
$executor->display('template.haml', array(
    'var' => 'value',
));

Twig:

<?php
$haml = new MtHaml\Environment('twig', array('enable_escaper' => false));

// Use a custom loader, whose responsibility is to convert HAML templates
// to Twig syntax, before handing them out to Twig:
$hamlLoader = new MtHaml\Support\Twig\Loader($haml, $twig->getLoader());
$twig->setLoader($hamlLoader);

// Register the Twig extension before executing a HAML template
$twig->addExtension(new MtHaml\Support\Twig\Extension());

// Render templates as usual
$twig->render('template.haml', ...);

See examples and MtHaml with Twig

Escaping

MtHaml escapes everything by default. Since Twig already supports auto escaping it is recommended to enable it in Twig and disable it in MtHaml:

new MtHaml\Environment('twig', array('enable_escaper' => false));

HAML/PHP is rendered like this when auto escaping is enabled:

Email #{$user->getEmail()}
%a(href=$user->getUrl()) Home page
Email <?php echo htmlspecialchars($user->getEmail(), ENT_QUOTES, 'UTF-8'); ?>
<a href="<?php echo htmlspecialchars($user->getUrl(), ENT_QUOTES, 'UTF-8'); ?>">Home page</a>

Twig

Using Twig in HAML gives more control over what can be executed, what variables and functions are exposed to the templates, etc. This also allows to use all of Twig's awesome features like template inheritance, macros, blocks, filters, functions, tests, ...

- extends "some-template.haml"

- macro printSomething()
  %p something

- block body
  %h1 Title
  = _self.printSomething()

Integration in Twig

MtHaml comes with an example Twig_Loader that will automatically convert HAML into Twig at loading time (Twig will then compile the resulting Twig script and cache it). Templates with a .haml extension, or whose source starts with {% haml %} will be converted, and the others will be left untouched.

The loader acts as a proxy and takes an other loader as parameter:

<?php

$haml = new MtHaml\Environment(...);

$twig_loader = new Twig_Loader_Filesystem(...);
$twig_loader = new MtHaml\Support\Twig\Loader($haml, $twig_loader);

Runtime support

Compiled MtHaml/Twig templates need support from MtHaml at runtime in some cases. Because of this, a Twig extension must be loaded before executing the templates.

<?php
// Register the MtHaml extension before executing the template:
$twig->addExtension(new MtHaml\Support\Twig\Extension());
$twig->render("rendered_twig_template.twig");

Syntax

The syntax is the same as HAML/Ruby's syntax, except that PHP or Twig have to be used where Ruby is expected.

See the tutorial and the reference

Performance

MtHaml converts HAML to PHP or Twig code. The resulting code can be cached and executed any number of times, and doesn't depend on HAML at runtime.

MtHaml has no runtime overhead.

Helpers

Helpers in HAML/Ruby are just ruby functions exposed to templates. Any function can be made available to HAML templates by the target language (the function only have to be available at runtime).

In HAML/Twig you can use all of Twig's functions, filters, and tags. In HAML/PHP, you can use all PHP functions.

Filters

Filters take plain text input (with support for #{...} interpolations) and transform it, or wrap it.

Example with the javascript filter:

%p something
:javascript
  some.javascript.code("#{var|escape('js')}");
<p>something</p>
<script type="text/javascript">
//<![CDATA[
  some.javascript.code("{{ var|escape('js') }}");
//]]>
</script>

The following filters are available:

  • css: wraps with style tags
  • cdata: wraps with CDATA markup
  • coffee*: compiles coffeescript to javascript
  • escaped: html escapes
  • javascript: wraps with script tags
  • less*: compiles as Lesscss
  • markdown*: converts markdown to html
  • php: executes the input as php code
  • plain: does not parse the filtered text
  • preseve: preserves preformatted text
  • scss*: converts scss to css
  • twig: executes the input as twig code

Filter marked with * have runtime dependencies and are not enabled by default. Such filters need to be provided to MtHaml\Environment explicitly.

Example with the Coffee filter:

<?php

$coffeeFilter = new MtHaml\Filter\CoffeeScript(new CoffeeScript\Compiler);

$env = new MtHaml\Environment('twig', array(
    'enable_escaper' => false,
), array(
    'coffee' => $coffeeFilter,
));

Sass

Sass can be used in PHP projects without problem. It only depends on Ruby and does not need to be installed on production servers. So MtHaml will not re-implement Sass.

Frameworks and CMS support

Add yours: https://github.com/arnaud-lb/MtHaml/edit/master/README.markdown

License

MtHaml is released under the MIT license (same as HAML/Ruby).

Author: arnaud-lb
Source Code: https://github.com/arnaud-lb/MtHaml
License: View license

#php #haml 

MtHAML: A PHP Implementation Of The HAML Language

How To Make A Simple Mac Keyboard Using Haml And Sass

In this article, I will show you how to create a simple Mac keyboard using Haml And Sass
#haml  #sass 

How To Make A Simple Mac Keyboard Using Haml And Sass