/ 
MarpaX-Hoonlint-1.001_002
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.

Description

Simple example

The command

hoonlint hoons/examples/toe.hoon

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.

* The rest of the line is a brief human-readable description of 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 in square brackets are additional details, if available. In this case, we are told that 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 with context

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

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

produces the following output:

1  |=  end/atom
2  =+  count=1
3  |-
4  ^-  (list tape)
5> ?:  =(end count)
[ fizzbuzz.hoon 6:4 Test::Whitespace wutcol:indent backdented element #2 @6:4; overindented by 1 ]
6!    ~
7  :-
8    ?:  =(0 (mod count 15))
9      "FizzBuzz"
10    ?:  =(0 (mod count 5))

Options

-C NUM, --context=NUM
--displayDetails=NUM --details=NUM
-P policy, --policy=policy

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. However, since many in hoonlint's intended audience will be new to Perl, here is what you do. By the way, CPAN.org has a page on installing modules, which contains more than you need to know.

If you are on UNIX, here is the TL;DR

* 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?

* 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.