Documentation updates and related feedback

[kastiglione]

I tried NEAL today and in short time I had a "working" rule. I wanted to provide some feedback on the issues I hit

1. The readme talks about a rules config file, but doesn't mention a file name. I searched the repo and saw a mention of .rules so I tried that, but it didn't work. At first I thought NEAL was crazy fast but it turns out it just wasn't running any rules.
2. There is no documentation on > and >> which I found info on through the source and commits. There's one example that uses them, and not many tests that use them.
3. There is no documentation on var and condition which I noticed in a test, and eventually found more info on in Example of how to write a rule with sibling nodes #9.
4. I was also looking for how to do cross tree sibling/cousin matches, and I think I now have something working, but there was a bunch of trial and error.
5. I could not get match() to work, and I wasn't able to debug my use of it since I didn't know what the (generated) string it was matching against would look like.
6. In the examples/tests, I saw one or two uses of property.access syntax, but it's not documented so I'm not clear what it's used for.
7. I'm getting a number of swift parsing errors, but it doesn't tell me which syntax NEAL is failing on and the error message is funky: SyntaxError}: satisfy.
8. As a beginner, it's not clear how to mix where clauses with properties that are lists of nodes, or conversely, how properties mix with matchers.
9. When there is a syntax error in a .rules file, only a line and column number are shown. It would be nice to show the line and a ^ label just like how warnings/errors in source files are shown.
10. Wish: Print the number of warnings/errors at the end of processing. Even better if it listed counts by rule name.

[tadeuzagallo]

Hey, thanks so much for the feedback! I started working on updating the docs and I'll try to address all these points. Just wanted to update the issue, as I couldn't push it today yet.

1 - the name of the file is neal.json, I'll push a commit with the fix for the readme soon, but in the meantime, there's more info about it here if you need.
2 & 3 - I'm finishing updating the docs soon.
4 - You got that working with vars + condition? Let me know if you want to share your rule and I can try to help.
5 - I'll see if I can add another "action", for debugging values of variables currently matched.
6 - Will add that to the docs. The way it works is it just access the property of the matched node. If it's an array, it basically does flatMap.
7 - Yeah, I messed that up when I was improving the performance of the swift parser, not a great tradeoff though :/ If you want to share the files that had syntax errors, I'm happy to debug and fix the parser. I'll also see what I can do about the errors, but that might take a bit longer.
8 - I'll try to explain that better in the docs, but the idea is that if it's a list, it'll execute the rule against each item in the list, i.e. list == "string" will be the same as there exists some x in list such that x == "string".
9 - Will update that! I have to fix it so that the code for printing it in failures can be shared with the core of the framework (which prints syntax errors for rules). Right now the build for NEAL is a bit sketchy, which makes it hard.
10 - You can set the NEAL_STATS=1 when running neal and it will print some info, e.g. the number of failures, warnings and parser failures. There's no number per rule unfortunate, but I can look into adding it. There's documentation about the runtime flags which can be set with environment variables here.

Thanks again for the feedback, I'll push a commit soon referencing this diff.

[kastiglione]

I was also looking for how to do cross tree sibling/cousin matches, and I think I now have something working, but there was a bunch of trial and error.

You got that working with vars + condition? Let me know if you want to share your rule and I can try to help.

I thought I had it working, but nope, it wasn't correct. tl;dr I was trying to identify nested closures that weakly captured self where the outer closure did not capture self weakly. I didn't describe it correctly, it's a ancestor/descendent relationship, not sibling/cousin. This is what led to the > operator, because I want to restrict the weak self check to a closure's direct child CaptureList, not those of nested closures.

[kastiglione]

Thanks for all the answers.

[keith]

Here's one case where we see the SyntaxError when handling double optionals:

final class Foo {
    func bar(string: String??) {
        if case let string?? = string {}
    }
}

[keith]

Here's another case:

final class Foo {
    func bar() {
        switch "" {
        case "foo":
            return
        default:
            break
        }
    }
}

[keith]

Here's another case with multi-line strings:

final class Foo {
    func bar() {
        """
        Shouldn't be able to update a pickup location if there is no
        current ride, or the map isn't fully initialized
        """
    }
}

[keith]

Another case with some weird characters for variable names:

final class Foo {
    func bar() {
        let sinφ = sin(0)
    }
}

[keith]

Another case if you add a newline between your function name and the arguments 🙃

final class Foo {
    func bar
        (completion: @escaping () -> Void) {}
}

[keith]

I think that's most of the case we have, happy to provide more info if that would be useful! This was with neal from homebrew with --HEAD at c40036d

[tadeuzagallo]

Thanks for all the examples. Some of these issues are known: we have to add support for Swift 4 features (keypaths will also fail to parse) and there's no unicode support (OCaml doesn't like it). The issue with newlines is a bit more unfortunate indeed, but sadly Swift cares about newlines and (to the best of my knowledge) is not well documented where it's valid to have a newline or not, so it was implement based on trial and error (luckily I had a decent-sized codebase to test it). I'll get working on some of these errors, but let me know if you'd like to contribute :)