Skip to content

Commit fe78e68

Browse files
tausbntausbn
committed
Python: Document a bunch of hasLocationInfo methods.
If only we had been _somewhat consistent in how we named the parameters for these...
1 parent 682e1b6 commit fe78e68

File tree

11 files changed

+206
-60
lines changed

11 files changed

+206
-60
lines changed

‎python/ql/src/Lexical/CommentedOutCode.qll

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -191,10 +191,19 @@ class CommentedOutCodeBlock extends @py_comment {
191191
/** The length of this comment block (in comments) */
192192
int length() { result = count(Comment c | this.contains(c)) }
193193

194-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
195-
this.(Comment).getLocation().hasLocationInfo(filepath, bl, bc, _, _) and
194+
/**
195+
* Holds if this element is at the specified location.
196+
* The location spans column `startcolumn` of line `startline` to
197+
* column `endcolumn` of line `endline` in file `filepath`.
198+
* For more information, see
199+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
200+
*/
201+
predicate hasLocationInfo(
202+
string filepath, int startline, int startcolumn, int endline, int endcolumn
203+
) {
204+
this.(Comment).getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
196205
exists(Comment end | commented_out_code_block(this, end) |
197-
end.getLocation().hasLocationInfo(_, _, _, el, ec)
206+
end.getLocation().hasLocationInfo(_, _, _, endline, endcolumn)
198207
)
199208
}
200209

‎python/ql/src/Metrics/Internal/Extents.qll

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,17 @@ import python
1515
* including the body (if any), as opposed to the location of its name only.
1616
*/
1717
class RangeFunction extends Function {
18-
predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
19-
super.getLocation().hasLocationInfo(path, sl, sc, _, _) and
20-
this.getBody().getLastItem().getLocation().hasLocationInfo(path, _, _, el, ec)
18+
/**
19+
* Holds if this element is at the specified location.
20+
* The location spans column `startcolumn` of line `startline` to
21+
* column `endcolumn` of line `endline` in file `filepath`.
22+
* For more information, see
23+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
24+
*/
25+
predicate hasLocationInfo(
26+
string filepath, int startline, int startcolumn, int endline, int endcolumn
27+
) { super.getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
28+
this.getBody().getLastItem().getLocation().hasLocationInfo(filepath, _, _, endline, endcolumn)
2129
}
2230
}
2331

@@ -26,8 +34,16 @@ class RangeFunction extends Function {
2634
* including the body (if any), as opposed to the location of its name only.
2735
*/
2836
class RangeClass extends Class {
29-
predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
30-
super.getLocation().hasLocationInfo(path, sl, sc, _, _) and
31-
this.getBody().getLastItem().getLocation().hasLocationInfo(path, _, _, el, ec)
37+
/**
38+
* Holds if this element is at the specified location.
39+
* The location spans column `startcolumn` of line `startline` to
40+
* column `endcolumn` of line `endline` in file `filepath`.
41+
* For more information, see
42+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
43+
*/
44+
predicate hasLocationInfo(
45+
string filepath, int startline, int startcolumn, int endline, int endcolumn
46+
) { super.getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
47+
this.getBody().getLastItem().getLocation().hasLocationInfo(filepath, _, _, endline, endcolumn)
3248
}
3349
}

‎python/ql/src/analysis/DefinitionTracking.qll

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -468,7 +468,13 @@ Definition getUniqueDefinition(Expr use) {
468468
/** Helper class to get suitable locations for attributes */
469469
class NiceLocationExpr extends @py_expr {
470470
string toString() { result = this.(Expr).toString() }
471-
471+
/**
472+
* Holds if this element is at the specified location.
473+
* The location spans column `bc` of line `bl` to
474+
* column `ec` of line `el` in file `f`.
475+
* For more information, see
476+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
477+
*/
472478
predicate hasLocationInfo(string f, int bl, int bc, int el, int ec) {
473479
/* Attribute location for x.y is that of 'y' so that url does not overlap with that of 'x' */
474480
exists(int abl, int abc | this.(Attribute).getLocation().hasLocationInfo(f, abl, abc, el, ec) |

‎python/ql/src/external/DefectFilter.qll

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ class DefectResult extends int {
2626

2727
/** Gets the file in which this query result was reported. */
2828
File getFile() {
29-
exists(string path | defectResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path)
29+
exists(string path |
30+
defectResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path
31+
)
3032
}
3133

3234
/** Gets the file path in which this query result was reported. */
@@ -47,8 +49,17 @@ class DefectResult extends int {
4749
/** Gets the message associated with this query result. */
4850
string getMessage() { defectResults(this, _, _, _, _, _, _, result) }
4951

50-
predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
51-
defectResults(this, _, path, sl, sc, el, ec, _)
52+
/**
53+
* Holds if this element is at the specified location.
54+
* The location spans column `startcolumn` of line `startline` to
55+
* column `endcolumn` of line `endline` in file `filepath`.
56+
* For more information, see
57+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
58+
*/
59+
predicate hasLocationInfo(
60+
string filepath, int startline, int startcolumn, int endline, int endcolumn
61+
) {
62+
defectResults(this, _, filepath, startline, startcolumn, endline, endcolumn, _)
5263
}
5364

5465
/** Gets the URL corresponding to the location of this query result. */

‎python/ql/src/external/Thrift.qll

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,21 @@ class ThriftElement extends ExternalData {
3333

3434
private int column() { result = this.getFieldAsInt(6) }
3535

36-
predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
37-
fp = this.getPath() and
38-
bl = this.line() and
39-
bc = this.column() and
40-
el = this.line() and
41-
ec = this.column() + this.getValue().length() - 1
36+
/**
37+
* Holds if this element is at the specified location.
38+
* The location spans column `startcolumn` of line `startline` to
39+
* column `endcolumn` of line `endline` in file `filepath`.
40+
* For more information, see
41+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
42+
*/
43+
predicate hasLocationInfo(
44+
string filepath, int startline, int startcolumn, int endline, int endcolumn
45+
) {
46+
filepath = this.getPath() and
47+
startline = this.line() and
48+
startcolumn = this.column() and
49+
endline = this.line() and
50+
endcolumn = this.column() + this.getValue().length() - 1
4251
or
4352
exists(ThriftElement first, ThriftElement last |
4453
first = this.getChild(min(int l | exists(this.getChild(l)))) and
@@ -62,11 +71,11 @@ abstract class ThriftNamedElement extends ThriftElement {
6271
not exists(this.getName()) and result = this.getKind() + " ???"
6372
}
6473

65-
override predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
74+
override predicate hasLocationInfo(string filepath, int startline, int startcolumn, int endline, int endcolumn) {
6675
exists(ThriftElement first |
6776
first = this.getChild(min(int l | exists(this.getChild(l)))) and
68-
first.hasLocationInfo(fp, bl, bc, _, _) and
69-
this.getNameElement().hasLocationInfo(fp, _, _, el, ec)
77+
first.hasLocationInfo(filepath, startline, startcolumn, _, _) and
78+
this.getNameElement().hasLocationInfo(filepath, _, _, endline, endcolumn)
7079
)
7180
}
7281
}
@@ -142,9 +151,9 @@ class ThriftFunction extends ThriftNamedElement {
142151

143152
ThriftType getReturnType() { result = this.getChild(1).getChild(0) }
144153

145-
override predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
146-
this.getChild(1).hasLocationInfo(fp, bl, bc, _, _) and
147-
this.getChild(2).hasLocationInfo(fp, _, _, el, ec)
154+
override predicate hasLocationInfo(string filepath, int startline, int startcolumn, int endline, int endcolumn) {
155+
this.getChild(1).hasLocationInfo(filepath, startline, startcolumn, _, _) and
156+
this.getChild(2).hasLocationInfo(filepath, _, _, endline, endcolumn)
148157
}
149158

150159
ThriftService getService() { result.getAFunction() = this }

‎python/ql/src/semmle/python/Comment.qll

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,9 +56,17 @@ class CommentBlock extends @py_comment {
5656
/** The length of this comment block (in comments) */
5757
int length() { result = max(int i | comment_block_part(this, _, i)) }
5858

59-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
60-
this.(Comment).getLocation().hasLocationInfo(filepath, bl, bc, _, _) and
61-
exists(Comment end | end = this.last() | end.getLocation().hasLocationInfo(_, _, _, el, ec))
59+
/**
60+
* Holds if this element is at the specified location.
61+
* The location spans column `startcolumn` of line `startline` to
62+
* column `endcolumn` of line `endline` in file `filepath`.
63+
* For more information, see
64+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
65+
*/
66+
predicate hasLocationInfo(
67+
string filepath, int startline, int startcolumn, int endline, int endcolumn
68+
) { this.(Comment).getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
69+
exists(Comment end | end = this.last() | end.getLocation().hasLocationInfo(_, _, _, endline, endcolumn))
6270
}
6371

6472
predicate contains(Comment c) {

‎python/ql/src/semmle/python/Files.qll

Lines changed: 55 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,21 @@ class File extends Container {
1010
/** DEPRECATED: Use `getAbsolutePath` instead. */
1111
deprecated string getFullName() { result = this.getAbsolutePath() }
1212

13-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
14-
this.getAbsolutePath() = filepath and bl = 0 and bc = 0 and el = 0 and ec = 0
13+
/**
14+
* Holds if this element is at the specified location.
15+
* The location spans column `startcolumn` of line `startline` to
16+
* column `endcolumn` of line `endline` in file `filepath`.
17+
* For more information, see
18+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
19+
*/
20+
predicate hasLocationInfo(
21+
string filepath, int startline, int startcolumn, int endline, int endcolumn
22+
) {
23+
this.getAbsolutePath() = filepath and
24+
startline = 0 and
25+
startcolumn = 0 and
26+
endline = 0 and
27+
endcolumn = 0
1528
}
1629

1730
/** Whether this file is a source code file. */
@@ -79,8 +92,21 @@ class Folder extends Container {
7992
/** DEPRECATED: Use `getBaseName` instead. */
8093
deprecated string getSimple() { folders(this, _, result) }
8194

82-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
83-
this.getAbsolutePath() = filepath and bl = 0 and bc = 0 and el = 0 and ec = 0
95+
/**
96+
* Holds if this element is at the specified location.
97+
* The location spans column `startcolumn` of line `startline` to
98+
* column `endcolumn` of line `endline` in file `filepath`.
99+
* For more information, see
100+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
101+
*/
102+
predicate hasLocationInfo(
103+
string filepath, int startline, int startcolumn, int endline, int endcolumn
104+
) {
105+
this.getAbsolutePath() = filepath and
106+
startline = 0 and
107+
startcolumn = 0 and
108+
endline = 0 and
109+
endcolumn = 0
84110
}
85111

86112
override string getAbsolutePath() { folders(this, result, _) }
@@ -371,23 +397,39 @@ class Location extends @location {
371397
result = this.getPath().getAbsolutePath() + ":" + this.getStartLine().toString()
372398
}
373399

374-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
375-
exists(File f | f.getAbsolutePath() = filepath |
376-
locations_default(this, f, bl, bc, el, ec)
400+
/**
401+
* Holds if this element is at the specified location.
402+
* The location spans column `startcolumn` of line `startline` to
403+
* column `endcolumn` of line `endline` in file `filepath`.
404+
* For more information, see
405+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
406+
*/
407+
predicate hasLocationInfo(
408+
string filepath, int startline, int startcolumn, int endline, int endcolumn
409+
) { exists(File f | f.getAbsolutePath() = filepath |
410+
locations_default(this, f, startline, startcolumn, endline, endcolumn)
377411
or
378-
exists(Module m | m.getFile() = f | locations_ast(this, m, bl, bc, el, ec))
412+
exists(Module m | m.getFile() = f | locations_ast(this, m, startline, startcolumn, endline, endcolumn))
379413
)
380414
}
381415
}
382416

383417
/** A non-empty line in the source code */
384418
class Line extends @py_line {
385-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
386-
exists(Module m |
419+
/**
420+
* Holds if this element is at the specified location.
421+
* The location spans column `startcolumn` of line `startline` to
422+
* column `endcolumn` of line `endline` in file `filepath`.
423+
* For more information, see
424+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
425+
*/
426+
predicate hasLocationInfo(
427+
string filepath, int startline, int startcolumn, int endline, int endcolumn
428+
) { exists(Module m |
387429
m.getFile().getAbsolutePath() = filepath and
388-
el = bl and
389-
bc = 1 and
390-
py_line_lengths(this, m, bl, ec)
430+
endline = startline and
431+
startcolumn = 1 and
432+
py_line_lengths(this, m, startline, endcolumn)
391433
)
392434
}
393435

‎python/ql/src/semmle/python/Flow.qll

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1079,9 +1079,17 @@ class BasicBlock extends @py_flow_node {
10791079
this.getASuccessor().reachesExit()
10801080
}
10811081

1082-
predicate hasLocationInfo(string file, int line, int col, int endl, int endc) {
1083-
this.startLocationInfo(file, line, col) and
1084-
this.endLocationInfo(endl, endc)
1082+
/**
1083+
* Holds if this element is at the specified location.
1084+
* The location spans column `startcolumn` of line `startline` to
1085+
* column `endcolumn` of line `endline` in file `filepath`.
1086+
* For more information, see
1087+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
1088+
*/
1089+
predicate hasLocationInfo(
1090+
string filepath, int startline, int startcolumn, int endline, int endcolumn
1091+
) { this.startLocationInfo(filepath, startline, startcolumn) and
1092+
this.endLocationInfo(endline, endcolumn)
10851093
}
10861094

10871095
/** Gets a true successor to this basic block */

‎python/ql/src/semmle/python/dataflow/TaintTracking.qll

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -378,8 +378,16 @@ abstract class TaintSource extends @py_flow_node {
378378

379379
Location getLocation() { result = this.(ControlFlowNode).getLocation() }
380380

381-
predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
382-
this.getLocation().hasLocationInfo(fp, bl, bc, el, ec)
381+
/**
382+
* Holds if this element is at the specified location.
383+
* The location spans column `startcolumn` of line `startline` to
384+
* column `endcolumn` of line `endline` in file `filepath`.
385+
* For more information, see
386+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
387+
*/
388+
predicate hasLocationInfo(
389+
string filepath, int startline, int startcolumn, int endline, int endcolumn
390+
) { this.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
383391
}
384392

385393
/** Gets a TaintedNode for this taint source */
@@ -482,8 +490,16 @@ abstract class TaintSink extends @py_flow_node {
482490

483491
Location getLocation() { result = this.(ControlFlowNode).getLocation() }
484492

485-
predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
486-
this.getLocation().hasLocationInfo(fp, bl, bc, el, ec)
493+
/**
494+
* Holds if this element is at the specified location.
495+
* The location spans column `startcolumn` of line `startline` to
496+
* column `endcolumn` of line `endline` in file `filepath`.
497+
* For more information, see
498+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
499+
*/
500+
predicate hasLocationInfo(
501+
string filepath, int startline, int startcolumn, int endline, int endcolumn
502+
) { this.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
487503
}
488504
}
489505

‎python/ql/src/semmle/python/objects/ObjectAPI.qll

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,15 +73,28 @@ class Value extends TObject {
7373
*/
7474
predicate isBuiltin() { this.(ObjectInternal).isBuiltin() }
7575

76-
predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
77-
this.(ObjectInternal).getOrigin().getLocation().hasLocationInfo(filepath, bl, bc, el, ec)
76+
/**
77+
* Holds if this element is at the specified location.
78+
* The location spans column `startcolumn` of line `startline` to
79+
* column `endcolumn` of line `endline` in file `filepath`.
80+
* For more information, see
81+
* [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
82+
*/
83+
predicate hasLocationInfo(
84+
string filepath, int startline, int startcolumn, int endline, int endcolumn
85+
) {
86+
this
87+
.(ObjectInternal)
88+
.getOrigin()
89+
.getLocation()
90+
.hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
7891
or
7992
not exists(this.(ObjectInternal).getOrigin()) and
8093
filepath = "" and
81-
bl = 0 and
82-
bc = 0 and
83-
el = 0 and
84-
ec = 0
94+
startline = 0 and
95+
startcolumn = 0 and
96+
endline = 0 and
97+
endcolumn = 0
8598
}
8699

87100
/**

0 commit comments

Comments
 (0)