Download the PHP package hershel-theodore-layton/pragma without Composer
On this page you can find all versions of the php package hershel-theodore-layton/pragma. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download hershel-theodore-layton/pragma
More information about hershel-theodore-layton/pragma
Files in hershel-theodore-layton/pragma
Package pragma
Short Description A structured way of embedding source analyzer metadata in Hack
License MIT
Informations about the package pragma
Pragma
A structured way of embedding source analyzer metadata in Hack.
How to use
For details on the strings passed to pragma(...)
and Pragmas(vec[...])
,
read the documentation of the source analyzer.
For implementers
This package contains one class and one function:
- The
pragma
function, also known as thepragma
directive. - The
Pragmas
class, also known as thePragmas
attribute.
They are general replacements for structured comments.
@lint-ignore
isn't a normal comment from the perspective of some tool.
It suppresses a lint error from being raised for an unused pure expression.
I subscribe wholehartedly to the following quote from the CppCoreGuidelines:
If over half of the comments in a project are to silence some tool, be it the Hack typechecker or a linter, programmers will be even more inclined to skip reading the comments. It will instill fear for removing useless comments, since some tool might rely on them.
The idea behind the pragma(...)
directive is to eliminate these comments.
The following code block expersses the same intent.
Q: Why would this string-based system be better than actual attributes?
- A: If your source code analyzer is a dev-dependency, you'd need to either:
- Publish the attributes in a different package, to make production code typecheck without the source analyzer in the vendor/ directory.
- Deploy the source analyzer code to production.
- The first user of this standard is PhaLinters
This is a dev-dependency with a single directive at the time of writing.
The
pragma(...)
directive is preferred over thePragmas
annotation. By shippingpragma
as standalone, PhaLinters can be a proper dev-dependency.
If you wish to accept pragma(...)
directives and <<Pragmas(vec[...])>>
attributes in your own source analyzers, read pragma.hack
for the details for this informal standard.