hohn/codeql-info
1
0
Fork 0
mirror of https://github.com/hohn/codeql-info.git synced 2025-12-16 20:53:04 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
codeql-info/ql/docs/language/learn-ql/build.html-5f4acb8/codeql-language-guides/codeql-library-for-ruby.html
Michael Hohn e52393de06 Build class-based dataflow documentation
2023-11-20 11:57:03 -08:00

1002 lines
62 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>CodeQL library for Ruby &#8212; CodeQL</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=93459777" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="QL language reference" href="../ql-language-reference/index.html" />
<link rel="prev" title="Basic query for Ruby code" href="basic-query-for-ruby-code.html" />
<title>CodeQL docs</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="stylesheet" href="../_static/primer.css" type="text/css" />
</head><body>
<header class="Header">
<div class="Header-item--full">
<a href="https://codeql.github.com/docs" class="Header-link f2 d-flex flex-items-center">
<!-- <%= octicon "mark-github", class: "mr-2", height: 32 %> -->
<svg height="32" class="octicon octicon-mark-github mr-2" viewBox="0 0 16 16" version="1.1" width="32"
aria-hidden="true">
<path fill-rule="evenodd"
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">
</path>
</svg>
<span class="hide-sm">CodeQL documentation</span>
</a>
</div>
<div class="Header-item hide-sm hide-md">
<script src="https://addsearch.com/js/?key=93b4d287e2fc079a4089412b669785d5&categories=!0xhelp.semmle.com,0xcodeql.github.com,1xdocs,1xcodeql-standard-libraries,1xcodeql-query-help"></script>
</div>
<div class="Header-item">
<details class="dropdown details-reset details-overlay d-inline-block">
<summary class="btn bg-gray-dark text-white border" aria-haspopup="true">
CodeQL resources
<div class="dropdown-caret"></div>
</summary>
<ul class="dropdown-menu dropdown-menu-se dropdown-menu-dark">
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-overview">CodeQL overview</a></li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL tools
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-for-visual-studio-code">CodeQL for VS Code</a>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-cli">CodeQL CLI</a>
</li>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
CodeQL guides
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/writing-codeql-queries">Writing CodeQL queries</a></li>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/codeql-language-guides">CodeQL language guides</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Reference docs
</div>
<li><a class="dropdown-item" href="https://codeql.github.com/docs/ql-language-reference/">QL language
reference</a>
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-standard-libraries">CodeQL
standard-libraries</a>
<li><a class="dropdown-item" href="https://codeql.github.com/codeql-query-help">CodeQL
query help</a>
<li class="dropdown-divider" role="separator"></li>
<div class="dropdown-header">
Source files
</div>
<li><a class="dropdown-item" href="https://github.com/github/codeql">CodeQL repository</a>
</ul>
</details>
</div>
</header>
<main class="bg-gray-light clearfix">
<nav class="SideNav position-sticky top-0 col-lg-3 col-md-3 float-left p-4 hide-sm hide-md overflow-y-auto">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../codeql-overview/index.html">CodeQL overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../codeql-for-visual-studio-code/index.html">CodeQL for Visual Studio Code</a></li>
<li class="toctree-l1"><a class="reference internal" href="../codeql-cli/index.html">CodeQL CLI</a></li>
<li class="toctree-l1"><a class="reference internal" href="../writing-codeql-queries/index.html">Writing CodeQL queries</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">CodeQL language guides</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="codeql-for-cpp.html">CodeQL for C and C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeql-for-csharp.html">CodeQL for C#</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeql-for-go.html">CodeQL for Go</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeql-for-java.html">CodeQL for Java</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeql-for-javascript.html">CodeQL for JavaScript</a></li>
<li class="toctree-l2"><a class="reference internal" href="codeql-for-python.html">CodeQL for Python</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="codeql-for-ruby.html">CodeQL for Ruby</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="basic-query-for-ruby-code.html">Basic query for Ruby code</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">CodeQL library for Ruby</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../ql-language-reference/index.html">QL language reference</a></li>
</ul>
</nav>
<div class="body col-sm-12 col-md-9 col-lg-9 float-left border-left">
<div class="hide-lg hide-xl px-4 pt-4">
<div class="related" role="navigation" aria-label="related navigation">
<ul>
<li class="nav-item nav-item-0"><a href="../contents.html">CodeQL</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="index.html"
>CodeQL language guides</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="codeql-for-ruby.html"
accesskey="U">CodeQL for Ruby</a> &#187;</li>
</ul>
</div>
</div>
<article class="p-4 col-lg-10 col-md-10 col-sm-12">
<section id="codeql-library-for-ruby">
<h1>CodeQL library for Ruby<a class="headerlink" href="#codeql-library-for-ruby" title="Link to this heading"></a></h1>
<p>When you’re analyzing a Ruby program, you can make use of the large collection of classes in the CodeQL library for Ruby.</p>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>CodeQL ships with an extensive library for analyzing Ruby code. The classes in this library present
the data from a CodeQL database in an object-oriented form and provide abstractions and predicates
to help you with common analysis tasks.</p>
<p>The library is implemented as a set of CodeQL modules, that is, files with the extension <code class="docutils literal notranslate"><span class="pre">.qll</span></code>. The
module <a class="reference external" href="https://github.com/github/codeql/blob/main/ruby/ql/lib/ruby.qll">ruby.qll</a> imports most other standard library modules, so you can include the complete
library by beginning your query with:</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
</pre></div>
</div>
<p>The CodeQL libraries model various aspects of Ruby code, depending on the type of query you want to write.
For example the abstract syntax tree (AST) library is used for locating program elements, to match syntactic
elements in the source code. This can be used to find values, patterns and structures.</p>
<p>The control flow graph (CFG) is imported using</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import codeql.ruby.CFG
</pre></div>
</div>
<p>The CFG models the control flow between statements and expressions, for example whether one expression can
flow to another expression, or whether an expression “dominates” another one, meaning that all paths to an
expression must flow through another expression first.</p>
<p>The data flow library is imported using</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import codeql.ruby.DataFlow
</pre></div>
</div>
<p>Data flow tracks the flow of data through the program, including through function calls (interprocedural data flow).
Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program
to exploit it. Related to data flow, is the taint-tracking library, which finds how data can <em>influence</em> other values
in a program, even when it is not copied exactly.</p>
<p>The API graphs library is used to locate methods in libraries. This is particuarly useful when locating
particular functions or parameters that could be used as a source or sink of data in a security query.</p>
<p>To summarize, the main Ruby modules are:</p>
<table class="docutils align-default" id="id1">
<caption><span class="caption-text">Main Ruby modules</span><a class="headerlink" href="#id1" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Import</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ruby</span></code></p></td>
<td><p>The standard Ruby library</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">codeql.ruby.AST</span></code></p></td>
<td><p>The abstract syntax tree library (also imported by <cite>ruby.qll</cite>)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">codeql.ruby.ApiGraphs</span></code></p></td>
<td><p>The API graphs library</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">codeql.ruby.CFG</span></code></p></td>
<td><p>The control flow graph library</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">codeql.ruby.DataFlow</span></code></p></td>
<td><p>The data flow library</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">codeql.ruby.TaintTracking</span></code></p></td>
<td><p>The taint tracking library</p></td>
</tr>
</tbody>
</table>
<p>The CodeQL examples in this article are only excerpts and are not meant to represent complete queries.</p>
</section>
<section id="abstract-syntax">
<h2>Abstract syntax<a class="headerlink" href="#abstract-syntax" title="Link to this heading"></a></h2>
<p>The abstract syntax tree (AST) represents the elements of the source code organized into a tree. The <a class="reference external" href="https://codeql.github.com/docs/codeql-for-visual-studio-code/exploring-the-structure-of-your-source-code/">AST viewer</a>
in Visual Studio Code shows the AST nodes, including the relevant CodeQL classes and predicates.</p>
<p>All CodeQL AST classes inherit from the <cite>AstNode</cite> class, which provides the following member predicates
to all AST classes:</p>
<table class="docutils align-default" id="id2">
<caption><span class="caption-text">Main predicates in <code class="docutils literal notranslate"><span class="pre">AstNode</span></code></span><a class="headerlink" href="#id2" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Predicate</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">getEnclosingModule()</span></code></p></td>
<td><p>Gets the enclosing module, if any.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">getEnclosingMethod()</span></code></p></td>
<td><p>Gets the enclosing method, if any.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">getLocation()</span></code></p></td>
<td><p>Gets the location of this node.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">getAChild()</span></code></p></td>
<td><p>Gets a child node of this node.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">getParent()</span></code></p></td>
<td><p>Gets the parent of this <cite>AstNode</cite>, if this node is not a root node.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">getDesugared</span></code></p></td>
<td><p>Gets the desugared version of this AST node, if any.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">isSynthesized()</span></code></p></td>
<td><p>Holds if this node was synthesized to represent an implicit AST node not
present in the source code.</p></td>
</tr>
</tbody>
</table>
<section id="modules">
<h3>Modules<a class="headerlink" href="#modules" title="Link to this heading"></a></h3>
<p>Modules represent the main structural elements of Ruby programs, and include modules (<code class="docutils literal notranslate"><span class="pre">Module</span></code>),
namespaces (<code class="docutils literal notranslate"><span class="pre">Namespace</span></code>) and classes (<code class="docutils literal notranslate"><span class="pre">ClassDeclaration</span></code>).</p>
<table class="docutils align-default" id="id3">
<caption><span class="caption-text">Callable classes</span><a class="headerlink" href="#id3" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and selected predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Module</span></code></p></td>
<td><p>A representation of a runtime <cite>module</cite> or <cite>class</cite> value.</p>
<ul class="simple">
<li><p><cite>getADeclaration()</cite> - Gets a declaration</p></li>
<li><p><cite>getSuperClass()</cite> - Gets the super class of this module, if any.</p></li>
<li><p><cite>getAPrependedModule()</cite> - Gets a prepended module.</p></li>
<li><p><cite>getAnIncludedModule()</cite> - Gets an included module.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Namespace</span></code></p></td>
<td><p>A class or module definition.</p>
<ul class="simple">
<li><p><cite>getName()</cite> - Gets the name of the module/class.</p></li>
<li><p><cite>getAMethod()</cite>, <cite>getMethod(name)</cite> - Gets a method in this namespace.</p></li>
<li><p><cite>getAClass()</cite>, <cite>getClass(name)</cite> - Gets a class in this namespace.</p></li>
<li><p><cite>getAModule()</cite>, <cite>getModule(name)</cite> - Gets a module in this namespace.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ClassDeclaration</span></code></p></td>
<td><p>A class definition.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SingletonClass</span></code></p></td>
<td><p>A definition of a singleton class on an object.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ModuleDeclaration</span></code></p></td>
<td><p>A module definition.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Toplevel</span></code></p></td>
<td><p>The node representing the entire Ruby source file.</p></td>
</tr>
</tbody>
</table>
<p>The following example lists all methods in the class <cite>ApiController</cite>:</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from ClassDeclaration m
where m.getName() = &quot;ApiController&quot;
select m, m.getAMethod()
</pre></div>
</div>
</section>
<section id="callables">
<h3>Callables<a class="headerlink" href="#callables" title="Link to this heading"></a></h3>
<p><cite>Callables</cite> are elements that can be called, including methods and blocks.</p>
<table class="docutils align-default" id="id4">
<caption><span class="caption-text">Callable classes</span><a class="headerlink" href="#id4" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Callable</span></code></p></td>
<td><p>A callable.</p>
<ul class="simple">
<li><p><cite>getAParameter()</cite> - gets a parameter of this callable.</p></li>
<li><p><cite>getParameter(n)</cite> - gets the nth parameter of this callable.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Private</span></code></p></td>
<td><p>A call to <code class="docutils literal notranslate"><span class="pre">private</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Method</span></code></p></td>
<td><p>A method.</p>
<ul class="simple">
<li><p><cite>getName()</cite> - gets the name of this method</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SingletonMethod</span></code></p></td>
<td><p>A singleton method.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Lambda</span></code></p></td>
<td><p>A lambda (anonymous method).</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Block</span></code></p></td>
<td><p>A block.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DoBlock</span></code></p></td>
<td><p>A block enclosed within <cite>do</cite> and <cite>end</cite>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BraceBlock</span></code></p></td>
<td><p>A block defined using curly braces.</p></td>
</tr>
</tbody>
</table>
<p><em>Parameters</em> are the values that are passed into callables. Unlike other CodeQL language models,
parameters in Ruby are not variables themselves, but can introduce variables into the
callable. The variables of a parameter are given by the <cite>getAVariable()</cite> predicate.</p>
<table class="docutils align-default" id="id5">
<caption><span class="caption-text">Parameter classes</span><a class="headerlink" href="#id5" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Parameter</span></code></p></td>
<td><p>A parameter.</p>
<ul class="simple">
<li><p><cite>getCallable()</cite> - Gets the callable that this parameter belongs to.</p></li>
<li><p><cite>getPosition()</cite> - Gets the zero-based position of this parameter.</p></li>
<li><p><cite>getAVariable()</cite>, <cite>getVariable(name)</cite> - Gets a variable introduced by this parameter.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">PatternParameter</span></code></p></td>
<td><p>A parameter defined using a pattern.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">TuplePatternParameter</span></code></p></td>
<td><p>A parameter defined using a tuple pattern.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">NamedParameter</span></code></p></td>
<td><p>A named parameter.</p>
<ul class="simple">
<li><p><cite>getName()</cite>, <cite>hasName(name)</cite> - Gets the name of this parameter.</p></li>
<li><p><cite>getAnAccess()</cite> - Gets an access to this parameter.</p></li>
<li><p><cite>getDefiningAccess()</cite> - Gets the access that defines the underlying local variable.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SimpleParameter</span></code></p></td>
<td><p>A simple (normal) parameter.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BlockParameter</span></code></p></td>
<td><p>A parameter that is a block.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">HashSplatParameter</span></code></p></td>
<td><p>A hash-splat (or double-splat) parameter.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">KeywordParameter</span></code></p></td>
<td><p>A keyword parameter, including a default value if the parameter is optional.</p>
<ul class="simple">
<li><p><cite>getDefaultValue()</cite> - Gets the default value, i.e. the value assigned to the parameter when one is not provided by the caller.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">OptionalParameter</span></code></p></td>
<td><p>An optional parameter.</p>
<ul class="simple">
<li><p><cite>getDefaultValue()</cite> - Gets the default value, i.e. the value assigned to the parameter when one is not provided by the caller.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SplatParameter</span></code></p></td>
<td><p>A splat parameter.</p></td>
</tr>
</tbody>
</table>
<p>Example</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from Method m
where m.getName() = &quot;show&quot;
select m.getParameter(0)
</pre></div>
</div>
</section>
<section id="statements">
<h3>Statements<a class="headerlink" href="#statements" title="Link to this heading"></a></h3>
<p>Statements are the elements of code blocks. Statements that produce a value are called <em>expressions</em>
and have CodeQL class <cite>Expr</cite>. The remaining statement types (that do not produce values) are listed below.</p>
<table class="docutils align-default" id="id6">
<caption><span class="caption-text">Statement classes</span><a class="headerlink" href="#id6" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Stmt</span></code></p></td>
<td><p>The base class for all statements.</p>
<ul class="simple">
<li><p><cite>getAControlFlowNode()</cite> - Gets a control-flow node for this statement, if any.</p></li>
<li><p><cite>getEnclosingCallable()</cite> - Gets the enclosing callable, if any.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">EmptyStmt</span></code></p></td>
<td><p>An empty statement.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BeginExpr</span></code></p></td>
<td><p>A <cite>begin</cite> statement.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BeginBlock</span></code></p></td>
<td><p>A <cite>BEGIN</cite> block.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">EndBlock</span></code></p></td>
<td><p>An <cite>END</cite> block.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">UndefStmt</span></code></p></td>
<td><p>An <cite>undef</cite> statement.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">AliasStmt</span></code></p></td>
<td><p>An <cite>alias</cite> statement.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ReturningStmt</span></code></p></td>
<td><p>A statement that may return a value: <cite>return</cite>, <cite>break</cite> and <cite>next</cite>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ReturnStmt</span></code></p></td>
<td><p>A <cite>return</cite> statement.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BreakStmt</span></code></p></td>
<td><p>A <cite>break</cite> statement.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">NextStmt</span></code></p></td>
<td><p>A <cite>next</cite> statement.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RedoStmt</span></code></p></td>
<td><p>A <cite>redo</cite> statement.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">RetryStmt</span></code></p></td>
<td><p>A <cite>retry</cite> statement.</p></td>
</tr>
</tbody>
</table>
<p>The following example finds all literals that are returned by a <cite>return</cite> statement.</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from ReturnStmt return, Literal lit
where lit.getParent() = return
select lit, &quot;Returning a literal &quot; + lit.getValueText()
</pre></div>
</div>
</section>
<section id="expressions">
<h3>Expressions<a class="headerlink" href="#expressions" title="Link to this heading"></a></h3>
<p>Expressions are types of statement that evaluate to a value. The CodeQL class <cite>Expr</cite> is the base class of all expression types.</p>
<table class="docutils align-default" id="id7">
<caption><span class="caption-text">Expressions</span><a class="headerlink" href="#id7" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Expr</span></code></p></td>
<td><p>An expression.</p>
<p>This is the root class for all expressions.</p>
<ul class="simple">
<li><p><cite>getValueText()</cite> - Gets the textual (constant) value of this expression, if any.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Self</span></code></p></td>
<td><p>A reference to the current object.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Pair</span></code></p></td>
<td><p>A pair expression.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RescueClause</span></code></p></td>
<td><p>A <cite>rescue</cite> clause.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">RescueModifierExpr</span></code></p></td>
<td><p>An expression with a <cite>rescue</cite> modifier.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">StringConcatenation</span></code></p></td>
<td><p>A concatenation of string literals.</p>
<ul class="simple">
<li><p><cite>getConcatenatedValueText()</cite> - Gets the result of concatenating all the string literals, if and only if they do not contain any interpolations.</p></li>
</ul>
</td>
</tr>
</tbody>
</table>
<table class="docutils align-default" id="id8">
<caption><span class="caption-text">Statement sequences</span><a class="headerlink" href="#id8" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">StmtSequence</span></code></p></td>
<td><p>A sequence of expressions.</p>
<ul class="simple">
<li><p><cite>getAStmt()</cite>, <cite>getStmt(n)</cite> - Gets a statement in this sequence.</p></li>
<li><p><cite>isEmpty()</cite> - Holds if this sequence has no statements.</p></li>
<li><p><cite>getNumberOfStatements()</cite> - Gets the number of statements in this sequence.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BodyStmt</span></code></p></td>
<td><p>A sequence of statements representing the body of a method, class, module, or do-block.</p>
<ul class="simple">
<li><p><cite>getARescue()</cite>, <cite>getRescue(n)</cite> - Gets a rescue clause in this block.</p></li>
<li><p><cite>getElse()</cite> - Gets the <cite>else</cite> clause in this block, if any.</p></li>
<li><p><cite>getEnsure()</cite> - Gets the <cite>ensure</cite> clause in this block, if any.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ParenthesizedExpr</span></code></p></td>
<td><p>A parenthesized expression sequence, typically containing a single expression.</p></td>
</tr>
</tbody>
</table>
<p>Literals are expressions that evaluate directly to the given value. The CodeQL Ruby library models all types of
Ruby literal.</p>
<table class="docutils align-default" id="id9">
<caption><span class="caption-text">Literals</span><a class="headerlink" href="#id9" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Literal</span></code></p></td>
<td><p>A literal. This is the base class for all literals.</p>
<ul class="simple">
<li><p><cite>getValueText()</cite> - Gets the source text for this literal, if this is a simple literal.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">NumericLiteral</span></code></p></td>
<td><p>A numerical literal. The literal types are <code class="docutils literal notranslate"><span class="pre">IntegerLiteral</span></code>, <code class="docutils literal notranslate"><span class="pre">FloatLiteral</span></code>, <code class="docutils literal notranslate"><span class="pre">RationalLiteral</span></code>, and <code class="docutils literal notranslate"><span class="pre">ComplexLiteral</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">NilLiteral</span></code></p></td>
<td><p>A <cite>nil</cite> literal.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BooleanLiteral</span></code></p></td>
<td><p>A Boolean value. The classes <code class="docutils literal notranslate"><span class="pre">TrueLiteral</span></code> and <code class="docutils literal notranslate"><span class="pre">FalseLiteral</span></code> match <cite>true</cite> and <cite>false</cite> respectively.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">StringComponent</span></code></p></td>
<td><p>A component of a string. Either a <code class="docutils literal notranslate"><span class="pre">StringTextComponent</span></code>, <code class="docutils literal notranslate"><span class="pre">StringEscapeSequenceComponent</span></code>, or <code class="docutils literal notranslate"><span class="pre">StringInterpolationComponent</span></code>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RegExpLiteral</span></code></p></td>
<td><p>A regular expression literal.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SymbolLiteral</span></code></p></td>
<td><p>A symbol literal.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SubshellLiteral</span></code></p></td>
<td><p>A subshell literal.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">CharacterLiteral</span></code></p></td>
<td><p>A character literal.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ArrayLiteral</span></code></p></td>
<td><p>An array literal.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">HashLiteral</span></code></p></td>
<td><p>A hash literal.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RangeLiteral</span></code></p></td>
<td><p>A range literal.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">MethodName</span></code></p></td>
<td><p>A method name literal.</p></td>
</tr>
</tbody>
</table>
<p>The following example defines a string literal class containing the text “username”:</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>class UsernameLiteral extends Literal
{
UsernameLiteral() { this.getValueText().toLowerCase().matches(&quot;%username%&quot;) }
}
</pre></div>
</div>
<p><em>Operations</em> are types of expression that typically perform some sort of calculation. Most operations are <code class="docutils literal notranslate"><span class="pre">MethodCalls</span></code> because often
there is an underlying call to the operation.</p>
<table class="docutils align-default" id="id10">
<caption><span class="caption-text">Operations</span><a class="headerlink" href="#id10" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Operation</span></code></p></td>
<td><p>An operation.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">UnaryOperation</span></code></p></td>
<td><p>A unary operation.</p>
<p>Types of unary operation include <code class="docutils literal notranslate"><span class="pre">UnaryLogicalOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">NotExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">UnaryPlusExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">UnaryMinusExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">SplatExpr</span></code>,
<code class="docutils literal notranslate"><span class="pre">HashSplatExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">UnaryBitwiseOperation</span></code>, and <code class="docutils literal notranslate"><span class="pre">ComplementExpr</span></code>.</p>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DefinedExpr</span></code></p></td>
<td><p>A call to the special <cite>defined?</cite> operator</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BinaryOperation</span></code></p></td>
<td><p>A binary operation, that includes many other operation categories such as <code class="docutils literal notranslate"><span class="pre">BinaryArithmeticOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">BinaryBitwiseOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">ComparisonOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">SpaceshipExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">Assignment</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BinaryArithmeticOperation</span></code></p></td>
<td><p>A binary arithmetic operation. Includes: <code class="docutils literal notranslate"><span class="pre">AddExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">SubExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">MulExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">DivExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">ModuloExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">ExponentExpr</span></code>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">BinaryLogicalOperation</span></code></p></td>
<td><p>A binary logical operation. Includes: <code class="docutils literal notranslate"><span class="pre">LogicalAndExpr</span></code> and <code class="docutils literal notranslate"><span class="pre">LogicalOrExpr</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BinaryBitwiseOperation</span></code></p></td>
<td><p>A binary bitwise operation. Includes: <code class="docutils literal notranslate"><span class="pre">LShiftExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">RShiftExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">BitwiseAndExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">BitwiseOrExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">BitwiseXorExpr</span></code>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ComparisonOperation</span></code></p></td>
<td><p>A comparison operation, including the classes <code class="docutils literal notranslate"><span class="pre">EqualityOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">EqExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">NEExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">CaseEqExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">RelationalOperation</span></code>, <code class="docutils literal notranslate"><span class="pre">GTExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">GEExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">LTExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">LEExpr</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">RegExpMatchExpr</span></code></p></td>
<td><p>A regexp match expression.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">NoRegExpMatchExpr</span></code></p></td>
<td><p>A regexp-doesn’t-match expression.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Assignment</span></code></p></td>
<td><p>An assignment. Assignments are simple assignments (<code class="docutils literal notranslate"><span class="pre">AssignExpr</span></code>), or assignment operations (<code class="docutils literal notranslate"><span class="pre">AssignOperation</span></code>).</p>
<p>The assignment arithmetic operations (<code class="docutils literal notranslate"><span class="pre">AssignArithmeticOperation</span></code>) are <code class="docutils literal notranslate"><span class="pre">AssignAddExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignSubExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignMulExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignDivExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignModuloExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">AssignExponentExpr</span></code>.</p>
<p>The assignment logical operations (<code class="docutils literal notranslate"><span class="pre">AssignLogicalOperation</span></code>) are <code class="docutils literal notranslate"><span class="pre">AssignLogicalAndExpr</span></code> and <code class="docutils literal notranslate"><span class="pre">AssignLogicalOrExpr</span></code>.</p>
<p>The assignment bitwise operations (<code class="docutils literal notranslate"><span class="pre">AssignBitwiseOperation</span></code>) are <code class="docutils literal notranslate"><span class="pre">AssignLShiftExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignRShiftExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignBitwiseAndExpr</span></code>, <code class="docutils literal notranslate"><span class="pre">AssignBitwiseOrExpr</span></code>, and <code class="docutils literal notranslate"><span class="pre">AssignBitwiseXorExpr</span></code>.</p>
</td>
</tr>
</tbody>
</table>
<p>The following example finds “chained assignments” (of the form <code class="docutils literal notranslate"><span class="pre">A=B=C</span></code>):</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from Assignment op
where op.getRightOperand() instanceof Assignment
select op, &quot;This is a chained assignment.&quot;
</pre></div>
</div>
<p>Calls pass control to another function, include explicit method calls (<code class="docutils literal notranslate"><span class="pre">MethodCall</span></code>), but also include other types of call such as <cite>super</cite> calls or <cite>yield</cite> calls.</p>
<table class="docutils align-default" id="id11">
<caption><span class="caption-text">Calls</span><a class="headerlink" href="#id11" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Call</span></code></p></td>
<td><p>A call.</p>
<ul class="simple">
<li><p><cite>getArgument(n)</cite>, <cite>getAnArgument()</cite>, <cite>getKeywordArgument(keyword)</cite> - Gets an argument of this call.</p></li>
<li><p><cite>getATarget()</cite> - Gets a potential target of this call, if any.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">MethodCall</span></code></p></td>
<td><p>A method call.</p>
<ul class="simple">
<li><p><cite>getReceiver()</cite> - Gets the receiver of this call, if any. This is the object being invoked.</p></li>
<li><p><cite>getMethodName()</cite> - Gets the name of the method being called.</p></li>
<li><p><cite>getBlock()</cite> - Gets the block of this method call, if any.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SetterMethodCall</span></code></p></td>
<td><p>A call to a setter method.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ElementReference</span></code></p></td>
<td><p>An element reference; a call to the <cite>[]</cite> method.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">YieldCall</span></code></p></td>
<td><p>A call to <cite>yield</cite>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SuperCall</span></code></p></td>
<td><p>A call to <cite>super</cite>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BlockArgument</span></code></p></td>
<td><p>A block argument in a method call.</p></td>
</tr>
</tbody>
</table>
<p>The following example finds all method calls to a method called <cite>delete</cite>.</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from MethodCall call
where call.getMethodName() = &quot;delete&quot;
select call, &quot;Call to &#39;delete&#39;.&quot;
</pre></div>
</div>
<p>Control expressions are expressions used for control flow. They are classed as expressions because they can produce a value.</p>
<table class="docutils align-default" id="id12">
<caption><span class="caption-text">Control expressions</span><a class="headerlink" href="#id12" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ControlExpr</span></code></p></td>
<td><p>A control expression, such as a <cite>case</cite>, <cite>if</cite>, <cite>unless</cite>, ternary-if (<cite>?:</cite>), <cite>while</cite>, <cite>until</cite> (including expression-modifier variants), and <cite>for</cite>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ConditionalExpr</span></code></p></td>
<td><p>A conditional expression.</p>
<ul class="simple">
<li><p><cite>getCondition()</cite> - Gets the condition expression.</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">IfExpr</span></code></p></td>
<td><p>An <cite>if</cite> or <cite>elsif</cite> expression.</p>
<ul class="simple">
<li><p><cite>getThen()</cite> - Gets the <cite>then</cite> branch.</p></li>
<li><p><cite>getElse()</cite> - Gets the <cite>elseif</cite> or <cite>else</cite> branch.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">UnlessExpr</span></code></p></td>
<td><p>An <cite>unless</cite> expression.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">IfModifierExpr</span></code></p></td>
<td><p>An expression modified using <cite>if</cite>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">UnlessModifierExpr</span></code></p></td>
<td><p>An expression modified using <cite>unless</cite>.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">TernaryIfExpr</span></code></p></td>
<td><p>A conditional expression using the ternary (<cite>?:</cite>) operator.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">CaseExpr</span></code></p></td>
<td><p>A <cite>case</cite> expression.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">WhenExpr</span></code></p></td>
<td><p>A <cite>when</cite> branch of a <cite>case</cite> expression.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Loop</span></code></p></td>
<td><p>A loop. That is, a <cite>for</cite> loop, a <cite>while</cite> or <cite>until</cite> loop, or their expression-modifier variants.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ConditionalLoop</span></code></p></td>
<td><p>A loop using a condition expression. That is, a <cite>while</cite> or <cite>until</cite> loop, or their expression-modifier variants.</p>
<ul class="simple">
<li><p><cite>getCondition()</cite> - Gets the condition expression of this loop.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">WhileExpr</span></code></p></td>
<td><p>A <cite>while</cite> loop.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">UntilExpr</span></code></p></td>
<td><p>An <cite>until</cite> loop.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">WhileModifierExpr</span></code></p></td>
<td><p>An expression looped using the <cite>while</cite> modifier.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">UntilModifierExpr</span></code></p></td>
<td><p>An expression looped using the <cite>until</cite> modifier.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ForExpr</span></code></p></td>
<td><p>A <cite>for</cite> loop.</p></td>
</tr>
</tbody>
</table>
<p>The following example finds <cite>if</cite>-expressions that are missing a <cite>then</cite> branch.</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from IfExpr expr
where not exists(expr.getThen())
select expr, &quot;This if-expression is redundant.&quot;
</pre></div>
</div>
</section>
<section id="variables">
<h3>Variables<a class="headerlink" href="#variables" title="Link to this heading"></a></h3>
<p><em>Variables</em> are names that hold values in a Ruby program. If you want to query <em>any</em> type
of variable, then use the <code class="docutils literal notranslate"><span class="pre">Variable</span></code> class, otherwise use one of the subclasses
<code class="docutils literal notranslate"><span class="pre">LocalVariable</span></code>, <code class="docutils literal notranslate"><span class="pre">InstanceVariable</span></code>, <code class="docutils literal notranslate"><span class="pre">ClassVariable</span></code> or <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code>.</p>
<p>Local variables have the scope of a single function or block, instance variables have the
scope of an object (like member variables), <em>class</em> variables have the scope of a class and are
shared between all instances of that class (like static variables), and <em>global</em> variables
have the scope of the entire program.</p>
<table class="docutils align-default" id="id13">
<caption><span class="caption-text">Variable classes</span><a class="headerlink" href="#id13" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Variable</span></code></p></td>
<td><p>A variable declared in a scope.</p>
<ul class="simple">
<li><p><cite>getName()</cite>, <cite>hasName(name)</cite> - Gets the name of this variable.</p></li>
<li><p><cite>getDeclaringScope()</cite> - Gets the scope this variable is declared in.</p></li>
<li><p><cite>getAnAccess()</cite> - Gets an access to this variable.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">LocalVariable</span></code></p></td>
<td><p>A local variable.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">InstanceVariable</span></code></p></td>
<td><p>An instance variable.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ClassVariable</span></code></p></td>
<td><p>A class variable.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code></p></td>
<td><p>A global variable.</p></td>
</tr>
</tbody>
</table>
<p>The following example finds all class variables in the class <cite>StaticController</cite>:</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from ClassDeclaration cd, ClassVariable v
where
v.getDeclaringScope() = cd and
cd.getName() = &quot;StaticController&quot;
select v, &quot;This is a static variable in &#39;StaticController&#39;.&quot;
</pre></div>
</div>
<p>Variable accesses are the uses of a variable in the source code. Note that variables, and <em>uses</em> of variables are different concepts.
Variables are modelled using the <code class="docutils literal notranslate"><span class="pre">Variable</span></code> class, whereas uses of the variable are modelled using the <code class="docutils literal notranslate"><span class="pre">VariableAccess</span></code> class.
<code class="docutils literal notranslate"><span class="pre">Variable.getAnAccess()</span></code> gets the accesses of a variable.</p>
<p>Variable accesses come in two types: <em>reads</em> of the variable (a <code class="docutils literal notranslate"><span class="pre">ReadAccess</span></code>), and <em>writes</em> to the variable (a <code class="docutils literal notranslate"><span class="pre">WriteAccess</span></code>).
Accesses are a type of expression, so extend the <code class="docutils literal notranslate"><span class="pre">Expr</span></code> class.</p>
<table class="docutils align-default" id="id14">
<caption><span class="caption-text">Variable access classes</span><a class="headerlink" href="#id14" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>CodeQL class</p></th>
<th class="head"><p>Description and main predicates</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">VariableAccess</span></code></p></td>
<td><p>An access to a variable.</p>
<ul class="simple">
<li><p><cite>getVariable()</cite> - Gets the variable that is accessed.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">VariableReadAccess</span></code></p></td>
<td><p>An access to a variable where the value is read.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">VariableWriteAccess</span></code></p></td>
<td><p>An access to a variable where the value is updated.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">LocalVariableAccess</span></code></p></td>
<td><p>An access to a local variable.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LocalVariableWriteAccess</span></code></p></td>
<td><p>An access to a local variable where the value is updated.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">LocalVariableReadAccess</span></code></p></td>
<td><p>An access to a local variable where the value is read.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">GlobalVariableAccess</span></code></p></td>
<td><p>An access to a global variable where the value is updated.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">InstanceVariableAccess</span></code></p></td>
<td><p>An access to a global variable where the value is read.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">InstanceVariableReadAccess</span></code></p></td>
<td><p>An access to an instance variable.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">InstanceVariableWriteAccess</span></code></p></td>
<td><p>An access to an instance variable where the value is updated.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ClassVariableAccess</span></code></p></td>
<td><p>An access to a class variable.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ClassVariableWriteAccess</span></code></p></td>
<td><p>An access to a class variable where the value is updated.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ClassVariableReadAccess</span></code></p></td>
<td><p>An access to a class variable where the value is read.</p></td>
</tr>
</tbody>
</table>
<p>The following example finds writes to class variables in the class <cite>StaticController</cite>:</p>
<div class="highlight-ql notranslate"><div class="highlight"><pre><span></span>import ruby
from ClassVariableWriteAccess write, ClassDeclaration cd, ClassVariable v
where
v.getDeclaringScope() = cd and
cd.getName() = &quot;StaticController&quot; and
write.getVariable() = v
select write, &quot;&#39;StaticController&#39; class variable is written here.&quot;
</pre></div>
</div>
</section>
</section>
</section>
</article>
<!-- GitHub footer, with links to terms and privacy statement -->
<div class="px-3 px-md-6 f6 py-4 d-sm-flex flex-justify-between flex-row-reverse flex-items-center border-top">
<ul class="list-style-none d-flex flex-items-center mb-3 mb-sm-0 lh-condensed-ultra">
<li class="mr-3">
<a href="https://twitter.com/github" title="GitHub on Twitter" style="color: #959da5;">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 273.5 222.3" class="d-block" height="18">
<path
d="M273.5 26.3a109.77 109.77 0 0 1-32.2 8.8 56.07 56.07 0 0 0 24.7-31 113.39 113.39 0 0 1-35.7 13.6 56.1 56.1 0 0 0-97 38.4 54 54 0 0 0 1.5 12.8A159.68 159.68 0 0 1 19.1 10.3a56.12 56.12 0 0 0 17.4 74.9 56.06 56.06 0 0 1-25.4-7v.7a56.11 56.11 0 0 0 45 55 55.65 55.65 0 0 1-14.8 2 62.39 62.39 0 0 1-10.6-1 56.24 56.24 0 0 0 52.4 39 112.87 112.87 0 0 1-69.7 24 119 119 0 0 1-13.4-.8 158.83 158.83 0 0 0 86 25.2c103.2 0 159.6-85.5 159.6-159.6 0-2.4-.1-4.9-.2-7.3a114.25 114.25 0 0 0 28.1-29.1"
fill="currentColor"></path>
</svg>
</a>
</li>
<li class="mr-3">
<a href="https://www.facebook.com/GitHub" title="GitHub on Facebook" style="color: #959da5;">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 15.3 15.4" class="d-block" height="18">
<path
d="M14.5 0H.8a.88.88 0 0 0-.8.9v13.6a.88.88 0 0 0 .8.9h7.3v-6h-2V7.1h2V5.4a2.87 2.87 0 0 1 2.5-3.1h.5a10.87 10.87 0 0 1 1.8.1v2.1h-1.3c-1 0-1.1.5-1.1 1.1v1.5h2.3l-.3 2.3h-2v5.9h3.9a.88.88 0 0 0 .9-.8V.8a.86.86 0 0 0-.8-.8z"
fill="currentColor"></path>
</svg>
</a>
</li>
<li class="mr-3">
<a href="https://www.youtube.com/github" title="GitHub on YouTube" style="color: #959da5;">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.17 13.6" class="d-block" height="16">
<path
d="M18.77 2.13A2.4 2.4 0 0 0 17.09.42C15.59 0 9.58 0 9.58 0a57.55 57.55 0 0 0-7.5.4A2.49 2.49 0 0 0 .39 2.13 26.27 26.27 0 0 0 0 6.8a26.15 26.15 0 0 0 .39 4.67 2.43 2.43 0 0 0 1.69 1.71c1.52.42 7.5.42 7.5.42a57.69 57.69 0 0 0 7.51-.4 2.4 2.4 0 0 0 1.68-1.71 25.63 25.63 0 0 0 .4-4.67 24 24 0 0 0-.4-4.69zM7.67 9.71V3.89l5 2.91z"
fill="currentColor"></path>
</svg>
</a>
</li>
<li class="mr-3 flex-self-start">
<a href="https://www.linkedin.com/company/github" title="GitHub on Linkedin" style="color: #959da5;">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19 18" class="d-block" height="18">
<path
d="M3.94 2A2 2 0 1 1 2 0a2 2 0 0 1 1.94 2zM4 5.48H0V18h4zm6.32 0H6.34V18h3.94v-6.57c0-3.66 4.77-4 4.77 0V18H19v-7.93c0-6.17-7.06-5.94-8.72-2.91z"
fill="currentColor"></path>
</svg>
</a>
</li>
<li>
<a href="https://github.com/github" title="GitHub's organization" style="color: #959da5;">
<svg version="1.1" width="20" height="20" viewBox="0 0 16 16" class="octicon octicon-mark-github"
aria-hidden="true">
<path fill-rule="evenodd"
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z">
</path>
</svg>
</a>
</li>
</ul>
<ul class="list-style-none d-flex text-gray">
<li class="mr-3">&copy;
<script type="text/javascript">document.write(new Date().getFullYear());</script> GitHub, Inc.</li>
<li class="mr-3"><a
href="https://docs.github.com/github/site-policy/github-terms-of-service"
class="link-gray">Terms </a></li>
<li><a href="https://docs.github.com/github/site-policy/github-privacy-statement"
class="link-gray">Privacy </a></li>
</ul>
</div>
</div>
</main>
<script type="text/javascript">
$(document).ready(function () {
$(".toggle > *").hide();
$(".toggle .name").show();
$(".toggle .name").click(function () {
$(this).parent().children().not(".name").toggle(400);
$(this).parent().children(".name").toggleClass("open");
})
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink