FilesExpand file tree

codeql-cli-2.27.2

/

opcode-qldoc.py

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

102 lines (95 loc) · 4.82 KB

codeql-cli-2.27.2

/

opcode-qldoc.py

Copy path

Top

File metadata and controls

• Code
• Blame

102 lines (95 loc) · 4.82 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

#!/usr/bin/env python3

import os

import re

path = os.path

needs_an_re = re.compile(r'^(?!Unary)[AEIOU]') # Name requiring "an" instead of "a".

start_qldoc_re = re.compile(r'^\s*/\*\*') # Start of a QLDoc comment

end_qldoc_re = re.compile(r'\*/\s*$') # End of a QLDoc comment

blank_qldoc_line_re = re.compile(r'^\s*\*\s*$') # A line in a QLDoc comment with only the '*'

instruction_class_re = re.compile(r'^class (?P<name>[A-Za-z0-9]+)Instruction\s') # Declaration of an `Instruction` class

opcode_base_class_re = re.compile(r'^abstract class (?P<name>[A-Za-z0-9]+)Opcode\s') # Declaration of an `Opcode` base class

opcode_class_re = re.compile(r'^ class (?P<name>[A-Za-z0-9]+)\s') # Declaration of an `Opcode` class

script_dir = path.realpath(path.dirname(__file__))

instruction_path = path.realpath(path.join(script_dir, '../cpp/ql/src/semmle/code/cpp/ir/implementation/raw/Instruction.qll'))

opcode_path = path.realpath(path.join(script_dir, '../cpp/ql/src/semmle/code/cpp/ir/implementation/Opcode.qll'))

# Scan `Instruction.qll`, keeping track of the QLDoc comment attached to each declaration of a class

# whose name ends with `Instruction`.

instruction_comments = {}

in_qldoc = False

saw_blank_line_in_qldoc = False

qldoc_lines = []

with open(instruction_path, 'r', encoding='utf-8') as instr:

for line in instr:

if in_qldoc:

if end_qldoc_re.search(line):

qldoc_lines.append(line)

in_qldoc = False

elif blank_qldoc_line_re.search(line):

# We're going to skip any lines after the first blank line, to avoid duplicating all

# of the verbose description.

saw_blank_line_in_qldoc = True

elif not saw_blank_line_in_qldoc:

qldoc_lines.append(line)

else:

if start_qldoc_re.search(line):

# Starting a new QLDoc comment.

saw_blank_line_in_qldoc = False

qldoc_lines.append(line)

if not end_qldoc_re.search(line):

in_qldoc = True

else:

instruction_match = instruction_class_re.search(line)

if instruction_match:

# Found the declaration of an `Instruction` class. Record the QLDoc comments.

instruction_comments[instruction_match.group('name')] = qldoc_lines

qldoc_lines = []

# Scan `Opcode.qll`. Whenever we see the declaration of an `Opcode` class for which we have a

# corresponding `Instruction` class, we'll attach a copy of the `Instruction`'s QLDoc comment.

in_qldoc = False

qldoc_lines = []

output_lines = []

with open(opcode_path, 'r', encoding='utf-8') as opcode:

for line in opcode:

if in_qldoc:

qldoc_lines.append(line)

if end_qldoc_re.search(line):

in_qldoc = False

else:

if start_qldoc_re.search(line):

qldoc_lines.append(line)

if not end_qldoc_re.search(line):

in_qldoc = True

else:

name_without_suffix = None

name = None

indent = ''

opcode_base_match = opcode_base_class_re.search(line)

if opcode_base_match:

name_without_suffix = opcode_base_match.group('name')

name = name_without_suffix + 'Opcode'

else:

opcode_match = opcode_class_re.search(line)

if opcode_match:

name_without_suffix = opcode_match.group('name')

name = name_without_suffix

# Indent by two additional spaces, since opcodes are declared in the

# `Opcode` module.

indent = ' '

if name_without_suffix:

# Found an `Opcode` that matches a known `Instruction`. Replace the QLDoc with

# a copy of the one from the `Instruction`.

if instruction_comments.get(name_without_suffix):

article = 'an' if needs_an_re.search(name_without_suffix) else 'a'

qldoc_lines = [

indent + '/**\n',

indent + ' * The `Opcode` for ' + article + ' `' + name_without_suffix + 'Instruction`.\n',

indent + ' *\n',

indent + ' * See the `' + name_without_suffix + 'Instruction` documentation for more details.\n',

indent + ' */\n'

]

output_lines.extend(qldoc_lines)

qldoc_lines = []

output_lines.append(line)

# Write out the updated `Opcode.qll`

with open(opcode_path, 'w', encoding='utf-8') as opcode:

opcode.writelines(output_lines)