Ruby: add an AST reference guide #11056
Conversation
|
👋 Docs first responder here! I've added this to our review board for a writer to have a look at. 🙇♂️ |
|
@alexrford - thanks for flagging this work for a writer review. Is there also a technical reviewer planned? |
There was a problem hiding this comment.
@alexrford - thanks for taking the time to write up this information for new query writers ✨
From a docs point of view, there isn't a great deal to say about this. I've left a few suggestions for formatting fixes and a couple of small text suggestions.
I wonder if it's worth adding a further reading section, similar to the ones in the Go and JavaScript
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Outdated
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Outdated
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Outdated
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Outdated
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Outdated
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Show resolved
Hide resolved
...odeql/codeql-language-guides/abstract-syntax-tree-classes-for-working-with-ruby-programs.rst
Show resolved
Hide resolved
Co-authored-by: Felicity Chapman <[email protected]>
|
Thanks for reviewing this @felicitymay.
Yep, I think this is a good idea.
It's had some light informal technical review on slack. One of the outcomes of that was that we should add a small section mentioning how we handle some desugaring (such as treating assignments to |
| +----------------------------+---------------------+----------------+-------------------------------+ | ||
| | ``yield`` «Expr_ ``,``»* | YieldCall_ | Call_ | | | ||
| +----------------------------+---------------------+----------------+-------------------------------+ | ||
| | ``&``IDENTIFIER | BlockArgument_ | Expr_ | Used as an argument to a call | |
There was a problem hiding this comment.
Sphinx says: Inline literal start-string without end-string. . Perhaps we need a space between & and IDENTIFIER
See: https://github.com/github/semmle-code/actions/runs/3395113988/jobs/5644570096#step:18:17
There was a problem hiding this comment.
You may well be right. I assumed that it would be okay because line 63 appeared to have a double-backtick followed by another symbol without a space.
There was a problem hiding this comment.
Hopefully fixed now.
|
I've made some additional changes to address review comments, and added a short section about desugaring and synthesized AST nodes. |
| @@ -414,6 +418,32 @@ All classes in this subsection are subclasses of VariableAccess_. | |||
| | ``self`` | SelfVariableReadAccess_ | VariableReadAccess_, SelfVariableAccess_ | | | |||
| +----------------------------+------------------------------+-----------------------------------------------+------------------+ | |||
|
|
|||
| Desugaring | |||
There was a problem hiding this comment.
Do we expect the target audience for this section to be confident of the meaning of "desugaring"? Would it be better to talk about simplifying and expanding the simplified syntax, or something along those lines?
There was a problem hiding this comment.
That is a good point. Not every user will be familiar with the terminology.
There was a problem hiding this comment.
True - I think we should mention the term "desugaring" as part of the text as we have a getDesugared predicate, but probably with a description of what it means. I think that "syntactic sugar" is a commonly understood term, though?
| @@ -10,6 +10,7 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat | |||
|
|
|||
| basic-query-for-ruby-code | |||
| codeql-library-for-ruby | |||
| abstract-syntax-tree-classes-for-working-with-ruby-programs | |||
There was a problem hiding this comment.
Should there be a - :doc: entry below? There are some for the other items.
There was a problem hiding this comment.
Yes please. 🤦🏻♀️ I missed that - great catch.
There was a problem hiding this comment.
Oops, thanks for catching that.
There was a problem hiding this comment.
no problem, i'll merge this PR and address this issue in a followup PR.
Adds a reference for CodeQL
Astmodule classes and associated Ruby syntax.The Ruby syntax provided is not complete. I used
parse.yas a reference, and the actual syntax is very complex and not really realistic to present in a table like this. What's here should hopefully be enough to give a flavour of the kinds of expressions that map onto the provided CodeQL classes.In some cases where it seemed clearer to do so, such as the
Literalssection, I've resorted to providing example expressions rather than a syntax definition. It may be that this approach would be better for some other sections as well.