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 csv
import os import os
import re import re
@ -9,7 +17,7 @@ from typing import Iterator, List, Tuple
Item = Tuple[str, int] Item = Tuple[str, int]
def list_enums(filename: str) -> Iterator[Item]: 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: with open(filename, 'rb') as fp:
data = fp.read() data = fp.read()
for item in re.finditer( for item in re.finditer(
@ -19,15 +27,18 @@ def list_enums(filename: str) -> Iterator[Item]:
yield name.decode('ASCII'), int(value, 0) yield name.decode('ASCII'), int(value, 0)
def index_of(data: List[Item], key: str) -> int: 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): for i, (name, _) in enumerate(data):
if name == key: if name == key:
return i return i
raise ValueError('missing value: {!r}'.format(key)) raise ValueError('missing value: {!r}'.format(key))
def slice(data: List[Item], first: str, last: str) -> List[Item]: 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] return data[index_of(data, first):index_of(data, last)+1]
def write_csv(fname: str, data: List[Item]) -> None: def write_csv(fname: str, data: List[Item]) -> None:
"""Write a CSV file containing enum values."""
print('Writing', fname, file=sys.stderr) print('Writing', fname, file=sys.stderr)
with open(fname, 'w') as fp: with open(fname, 'w') as fp:
w = csv.writer(fp) w = csv.writer(fp)
@ -36,6 +47,7 @@ def write_csv(fname: str, data: List[Item]) -> None:
w.writerow(item) w.writerow(item)
def process_script(filename: str) -> None: def process_script(filename: str) -> None:
"""Process the <Script.h> header file."""
scripts: List[Item] = [] scripts: List[Item] = []
regions: List[Item] = [] regions: List[Item] = []
for name, value in list_enums(filename): 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')) write_csv('region.csv', slice(regions, 'verUS', 'verGreenland'))
def process_textcommon(filename: str) -> None: def process_textcommon(filename: str) -> None:
"""Process the <TextCommon.h> header file."""
encodings: List[Item] = [] encodings: List[Item] = []
for name, value in list_enums(filename): for name, value in list_enums(filename):
if name.startswith('kTextEncoding'): if name.startswith('kTextEncoding'):
@ -54,6 +67,7 @@ def process_textcommon(filename: str) -> None:
write_csv('encoding.csv', encodings) write_csv('encoding.csv', encodings)
def process(filename: str) -> None: def process(filename: str) -> None:
"""Process any header file."""
name = os.path.basename(filename).lower() name = os.path.basename(filename).lower()
if name == 'script.h': if name == 'script.h':
process_script(filename) process_script(filename)