/ 
MarpaX-Hoonlint-1.010000
River stage zero No dependents
/ hoonlint

NAME

hoonlint - lint utility for the Hoon language

SYNOPSIS

hoonlint [options] FILE ...

Status

This software is alpha -- it should be useable, but features are evolving and subject to change without notice.

Updates

Once MarpaX::Hoonlint leaves alpha, users should consult Marpa::R2's "updates" page, which contains notes, errata, etc., added since the most recent release. The "updates" page is UPDATES.md in the current repo. At this point, the link is https://github.com/jeffreykegler/hoonlint/blob/master/UPDATES.md.

Description

The hoonlint command runs checks on one or more hoon files. These may be specified on the command line, or via the -f option.

Simple example

The command

hoonlint hoons/examples/toe.hoon

lint the Tic-tac-toe example for Hoon (which can be found at https://github.com/jeffreykegler/hoonlint/blob/cf60f1d5eeb8a0270c9d5a80f096e17fabe6a8b8/cpan/hoons/examples/toe.hoon) and produces the following output:

hoons/examples/toe.hoon 58:16 Test::Whitespace wutcol:indent backdented element #2 @58:16; overindented by 1

In this

    * hoon/examples/toe.hoon is the name of the file.

    * 58:16 is the line number and column of the problem, both 1-based.

    * Test::Whitespace is the policy name.

    * wutcol:indent is the subpolicy name.

    * A human-readable description of the lint issue. The rest of the line is describes the lint issue. In this case, the 2nd runechild of a WUTCOL hoon statement (which is located at line 58, column 16) is overindented by 1.

Example with context

The message of the simple example becomes a little more understandable, if we ask hoonlint to show the code. The -C 5 option request 5 lines of context, so that the command

hoonlint -C 5 toe.hoon

produces the following output:

53              ==                                          ::  53
54      ++  mo  ^-  {(unit fact) ^game}                     ::  54
55              ?<  is                                      ::  55
56              =/  next/side  (~(set bo a.game) here)      ::  56
57>             ?:  ~(win bo next)                          ::  57
[ hoons/examples/toe.hoon 58:16 Test::Whitespace wutcol:indent backdented element #2 @58:16; overindented by 1
  anchor column is "?:" @57:13
]
58!                [[~ %win ?:(w.game %x %o)] nu]           ::  58
59              [~ game(w !w.game, a z.game, z next)]       ::  59
60      --                                                  ::  60
61    --                                                    ::  62
62  --                                                      ::  63

In the above, the original lint message is shown in square brackets, just before the line (58) to which it refers. Following the original lint message, also within the square brackets, are additional details:

anchor column is "?:" @57:13

Backdenting is relative to an anchor column, and this detail tells us where hoonlint thought the anchor column was.

Each line of code is preceded by its line number and an optional tag, either a zap (!) or a gar (>). A zap indicates a line with a lint issue. A gar indicates a "topic" line -- a lint which does not actually contain an issue, but which is relevant to a lint issue. In this case, line 57 contains the beginning of the hoon statement which has the backdenting issue.

Example without details

It is also possible to have context without details. The command

hoonlint -C 2 --details=0 fizzbuzz.hoon

runs on Hoon's fizzbuzz example. It asks for 2 context lines, with no details. (The fizzbuzz example can be found at https://github.com/jeffreykegler/hoonlint/blob/cf60f1d5eeb8a0270c9d5a80f096e17fabe6a8b8/cpan/hoons/examples/fizzbuzz.hoon.) It produces the following output:

4  ^-  (list tape)
5> ?:  =(end count)
[ fizzbuzz.hoon 6:4 Test::Whitespace wutcol:indent backdented element #2 @6:4; overindented by 1 ]
6!    ~
7  :-

Options

-C NUM, --context=NUM

Display NUM lines of context before and after the issue message. If NUM is 0, no context is displayed. By default, NUM is 0.

--displayDetails=NUM --details=NUM

Display NUM levels of detail for the error message. (Currently at most 1 level of detail is implemented.) Some issue messages have no details available. NUM defaults to 1 if more than one line of context is being displayed. NUM defaults to 0 is no lines of context are being displayed.

-f listFile, --filelist=listFile

Add the files in the file named listFile to the files to be processed by hoonlint. If listFile is -, read the list of files from STDIN.

-P policy, --policy=policy

Set the policy that hoonlint is running to policy. Test::Whitespace is the default.

Currently, Test::Whitespace is the only policy implemented. It's conventions are documented in a separate document.

SUPPORT

Support for and information about hoonlint can be found at:

FAQ

How do I install hoonlint?

MarpaX::Hoonlint is an ordinary Perl CPAN module, and installs in the usual ways. CPAN.org has a page on installing modules, which contains more than you need to know. However, since many in hoonlint's intended audience will be new to Perl, here is what most newcomers need to know:

    * First, install Perl. You need at least Perl 5.10.1. Almost every UNIX system will come with such a Perl.

    * Second, run this command:

    cpan App::cpanminus

    * Third, run this command:

    cpanm MarpaX::Hoonlint

That's it.

How do I install hoonlint from the Git repo?

Do the following:

    * First, clone the git repo.

    * Second, install Perl. You need at least Perl 5.10.1. Almost every UNIX system will come with such a Perl.

    * Third, download the cpanm command.

    cpan App::cpanminus

    * From the directory of the downloaded git repo, run this command

    cpanm ./cpan

ACKNOWLEDGEMENTS

hoonlint was made possible by the generous support of an anonymous member of the Hoon community.

AUTHOR

Jeffrey Kegler, <jkegl at cpan.org>

COPYRIGHT & LICENSE

The MIT License (MIT)

Copyright (c) 2018 Urbit

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.