README

NAME
    capp_lint.py -- check formatting of Objective-J files

SYNOPSIS
    capp_lint.py [options] [file ... | -]

DESCRIPTION
    capp_lint.py is a formatting checker for Objective-J. It performs a number of checks that catch
    common formatting mistakes, as defined in the Cappuccino coding style guidelines
    (http://cappuccino.org/contribute/coding-style.php).

    capp_lint.py operates on a list of files and/or directory. You may pass one or more paths (relative to the
    current working directory) as arguments to capp_lint.py, or if the first path is "-", the
    list of paths is taken from stdin, in which case everything after the "-" is ignored.

    If a path is a directory, the directory is recursively scanned for *.j files to check. Symbolic links
    are not followed.

    The following options are available:

    -b/--basedir=BASEDIR
        The base directory relative to which filenames will be resolved. If not passed,
        it defaults to the current working directory.

    -d/--var-declarations=[none|single|strict]
        Determines the policy in flagging consecutive var declarations. The choices are:
            none - No checking is done.
            single - If two var blocks appear consecutively and one of them is
                     a single variable, the second var block will be flagged.
            strict - Any consecutive var declarations will be flagged.

        Given the following code:

            var foo = "bar",
                bar = "foo";

            var bow = "foobar",
                wow = "woof";

        The "none" policy will obviously not flag this. The "single" policy will not flag
        this because both blocks contain more than one declaration. The "strict" policy
        will flag this. Given the following code:

            var foo = "bar",
                bar = "foo";

            var bow = "foobar";

        The "single" policy will flag this because the second block is a single declaration.

    -f/--format=[text|html]
        Determines the format of the error output. See the OUTPUT section below for more information
        on the different formats.

    -q/--quiet
        Normally capp_lint.py will print a list of the errors it finds. If this option is passed,
        the error list is suppressed. This option is mutually exclusive with the -v option.

    -v/--verbose
        Displays each line as it is processed by capp_lint.py with a line number,
        along with some information about syntactic information it finds.

    --version
        Displays the current version and exits.

    -h/--help
        Shows a synopsis of the usage and options and exits.

    The following formatting errors are flagged by capp_lint.py:

    - Lines which contain one or more tabs.
    - Lines which contain non-ASCII characters not within quoted strings.
    - Lines which contain malformed UTF-8.
    - Missing space between control statements and their opening parentheses.
    - Trailing whitespace.
    - Binary operators without surrounding space.
    - Assignment operators without surrounding space.
    - Comparison operators without surrounding space.
    - Useless unary + operators.
    - Extra or missing space in a method declaration.
    - Superflous function names.
    - Unterminated variable blocks.
    - Consecutive var statements.
    - Incorrect indentation in a var block.
    - Missing statement separators in a var block.
    - Inadvertent global variables in a var block.
    - Unbalanced [, { or ( in a variable block.
    - Opening braces on the same line as a statement.
    - Code following a var block that is not outdented from the var block.

EXIT STATUS
    capp_lint.py exits with a return status of one if it finds any errors. If no errors are found,
    it exits with a return status of zero.

OUTPUT
    For each error that capp_lint.py finds, if the -q/--quiet option was not passed, capp_lint.py
    will output an error like the following if the error format is text:

    AppKit/CPObjectController.j:482: assignment operator without surrounding spaces.
    +    for (var i=0, count=[_observationProxies count]; i<count; i++)
                   ^        ^

    The filename (relative to the working directory), line number, and type of error are displayed
    first, followed by the offending line of source code. When possible and necessary (as in this example),
    the location of the errors is indicated below the source line. If only a single file was checked,
    the filename is suppressed.

    If the error format is html, the output is similar, but instead of using markers to indicate where
    the errors occurred, the character at that position is highlighted. In addition, clicking on the
    error open TextMate to the file and line number of the error.

WHITESPACE
    Cappuccino coding standards stipulate that there should be no trailing whitespace, and that tabs
    should consist of 4 spaces, not tab characters. capp_lint will report trailing whitespace and hard tabs.
    You should fix those errors before paying attention to any other errors, as the presence of hard tabs
    may cause some false positives.

TEXTMATE INTEGRATION
    To integrate capp_lint.py into TextMate, double-click capp_lint.tmbundle to install it into TextMate.
    Before the bundle can be used, you must make capp_lint.py available to TextMate. The bundle will
    look in the following places:

    - capp_lint.tmbundle/Support/bin/capp_lint.py
    - The path specified by the TextMate shell variable TM_CAPP_LINT (set in TextMate Preferences).
      The path should include the filename of the executable file.
    - capp_lint.py or capp_lint in your PATH.

    The bundle has four commands, accessed by default by pressing Control-L:

    - Check current document, show the results in HTML with clickable errors.
    - Check current document, show the results in a tooltip.
    - Recursively check the selected documents and/or directories in the project drawer.
    - Recursively check the entire project.

    VAR_DECLARATIONS POLICY
    You can set a value for --var-declarations by creating and enabling the TextMate
    shell variable TM_CAPP_LINT_VAR_DECLARATIONS in TextMate Preferences. The value should
    be one of [none|single|strict]. If not set, the default policy is single.


KNOWN BUGS
    capp_lint.py will currently flag false positives for the following cases I know of:

    var foo =
    [
        "bar"
    ]

    - missing statement separator

    var x, y, z;

    - unterminated var block. This is not actually a bug -- multiple variables are not supposed
      to be declared on a single line. The error condition is not properly described.

AUTHORS
    Aparajita Fishman, Victory-Heart Productions
    aparajita@aparajita.com