[Summary view] [Print] [Text view]

   1  @title Arcanist User Guide: Customizing Existing Linters
   2  @group userguide
   3  
   4  Explains how to customize existing linters.
   5  
   6  This is a configuration guide that helps you set up advanced features. If you're
   7  just getting started, you don't need to look at this yet. Instead, start with
   8  the @{article:Arcanist User Guide}.
   9  
  10  This guide explains how to refine lint behavior. To configure lint in the first
  11  place, see @{article:Arcanist User Guide: Configuring a New Project} and
  12  @{article:Arcanist User Guide: Lint}.
  13  
  14  = Overview =
  15  
  16  Arcanist ships with a number of linters which you may want to reuse in whole
  17  or in part in other projects. This document explains how to customize existing
  18  linters for use in new engines.
  19  
  20  First, you should set up an engine by following the instructions in
  21  @{article:Arcanist User Guide: Lint} and possibly
  22  @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
  23  Then, follow this guide to customize linters.
  24  
  25  = General Guidelines =
  26  
  27  You should customize linters by configuring or composing them, not by extending
  28  them -- their implementations are not necessarily stable. If a linter's
  29  configuration options aren't flexible enough to meet your needs, sending a patch
  30  which improves its configurability is better than one that makes it
  31  nonfinal.
  32  
  33  = Changing Rule Severities =
  34  
  35  By default, most linters raise lint messages as errors. You may want to reduce
  36  the severity of some messages (e.g., reduce errors to warnings). Do this by
  37  calling ##setCustomSeverityMap()##:
  38  
  39    $linter = new ArcanistTextLinter();
  40  
  41    // Change "missing newline at end of file" message from error to warning.
  42    $linter->setCustomSeverityMap(
  43      array(
  44        ArcanistTextLinter::LINT_EOF_NEWLINE
  45          => ArcanistLintSeverity::SEVERITY_WARNING,
  46      ));
  47  
  48  See @{class@arcanist:ArcanistLintSeverity} for a list of available severity
  49  constants.
  50  
  51  = Disabling Rules =
  52  
  53  To disable rules entirely, set their severities to ##SEVERITY_DISABLED##:
  54  
  55    $linter = new ArcanistTextLinter();
  56  
  57    // Disable "Tab Literal" message.
  58    $linter->setCustomSeverityMap(
  59      array(
  60        ArcanistTextLinter::LINT_TAB_LITERAL
  61          => ArcanistLintSeverity::SEVERITY_DISABLED,
  62      ));
  63  
  64  = Running Multiple Rulesets =
  65  
  66  If you want to run the same linter on different types of files but vary the
  67  configuration based on the file type, just instantiate it twice and configure
  68  each instance appropriately. For instance, this will enforce different column
  69  widths on different languages:
  70  
  71    $linters = array();
  72  
  73    // Warn on JS/CSS lines longer than 80 columns.
  74    $linters['TextLinter80Col'] = id(new ArcanistTextLinter())
  75      ->setPaths(preg_grep('/\.(js|css)$/', $paths));
  76  
  77    // Warn on Java lines longer than 120 columns.
  78    $linters['TextLinter120Col'] = id(new ArcanistTextLinter())
  79      ->setMaxLineLength(120)
  80      ->setPaths(preg_grep('/\.(java)$/', $paths));
  81  
  82    // ...
  83  
  84    return $linters;
  85  
  86  = Customizing Specific Linters =
  87  
  88  Some linters are specifically customizable or configurable. Some common
  89  options are documented here, consult class documentation for complete
  90  information.
  91  
  92  == ArcanistTextLinter ==
  93  
  94    - Use ##setMaxLineLength()## to change the 80-column warning to something
  95      else.
  96  
  97  == ArcanistXHPASTLinter ==
  98  
  99    - Use ##lint.xhpast.naminghook## in ##.arcconfig## to override naming
 100      convention rules. See @{class@arcanist:ArcanistXHPASTLintNamingHook}
 101      for details.
 102    - Use ##getXHPASTTreeForPath()## to reuse the AAST in other linters.