Update documentation comments in extract.py

This commit is contained in:
Dietrich Epp 2022-04-04 13:54:37 -04:00
parent 36ab91617c
commit 68665d1fff

View File

@ -1,4 +1,12 @@
"""Extract script and region constants from Script.h."""
"""Extract various constants from Mac OS header files.
This program reads Script.h and TextCommon.h from Macintosh headers. Pass the
paths to one or both of these files when invoking this program, and the program
will write out the corresponding CSV files.
It does not matter what line endings or character encodings the headers use, as
long as the encoding is ASCII-compatible.
"""
import csv
import os
import re
@ -9,7 +17,7 @@ from typing import Iterator, List, Tuple
Item = Tuple[str, int]
def list_enums(filename: str) -> Iterator[Item]:
"""List enum definitions in a file."""
"""List enum definitions in a header file."""
with open(filename, 'rb') as fp:
data = fp.read()
for item in re.finditer(
@ -19,15 +27,18 @@ def list_enums(filename: str) -> Iterator[Item]:
yield name.decode('ASCII'), int(value, 0)
def index_of(data: List[Item], key: str) -> int:
"""Return the index of the enum with the given name."""
for i, (name, _) in enumerate(data):
if name == key:
return i
raise ValueError('missing value: {!r}'.format(key))
def slice(data: List[Item], first: str, last: str) -> List[Item]:
"""Return a slice of enums, by giving the name of the first and last."""
return data[index_of(data, first):index_of(data, last)+1]
def write_csv(fname: str, data: List[Item]) -> None:
"""Write a CSV file containing enum values."""
print('Writing', fname, file=sys.stderr)
with open(fname, 'w') as fp:
w = csv.writer(fp)
@ -36,6 +47,7 @@ def write_csv(fname: str, data: List[Item]) -> None:
w.writerow(item)
def process_script(filename: str) -> None:
"""Process the <Script.h> header file."""
scripts: List[Item] = []
regions: List[Item] = []
for name, value in list_enums(filename):
@ -47,6 +59,7 @@ def process_script(filename: str) -> None:
write_csv('region.csv', slice(regions, 'verUS', 'verGreenland'))
def process_textcommon(filename: str) -> None:
"""Process the <TextCommon.h> header file."""
encodings: List[Item] = []
for name, value in list_enums(filename):
if name.startswith('kTextEncoding'):
@ -54,6 +67,7 @@ def process_textcommon(filename: str) -> None:
write_csv('encoding.csv', encodings)
def process(filename: str) -> None:
"""Process any header file."""
name = os.path.basename(filename).lower()
if name == 'script.h':
process_script(filename)