calmjs.parse 1.3.1

手动安装和打包要求

本节面向开发人员和高级用户；包含有关包维护者（例如，Linux）的重要信息，可防止下游用户获得不理想的使用体验。

关于< span class="docutils literal">calmjs.parse 的开发仍在进行中，有关最新功能和错误修复，可以通过以下方式通过git安装开发版本：

$ pip install ply setuptools  # this MUST be done first; see below for reason
$ pip install -e git+https://github.com/calmjs/calmjs.parse.git#egg=calmjs.parse

请注意，所有依赖项都必须预先安装，以便运行< span class="docutils literal">setup.py build 步骤，否则创建预生成模块所需的构建步骤将导致失败。

如果尚未安装< span class="docutils literal">ply

$ python -m pip install -e .
...
running egg_info
...
WARNING: cannot find distribution for 'ply'; using default value,
assuming 'ply==3.11' for pre-generated modules
ERROR: cannot find pre-generated modules for the assumed 'ply'
version from above and/or cannot `import ply` to build generated
modules, aborting build; please either ensure that the source
archive containing the pre-generate modules is being used, or that
the python package 'ply' is installed and available for import
before attempting to use the setup.py to build this package; please
refer to the top level README for further details

如果 setuptools 未安装

$ python -m pip install -e .
...
running egg_info
...
Traceback (most recent call last):
  ...
ModuleNotFoundError: No module named 'pkg_resources'

当然，可以直接克隆 git 仓库，并在源目录的根目录下执行 python setup.py develop；同样，ply 和 setuptools 必须已经可用以便导入。

由于 git 仓库不包含任何预生成的模块或代码，上面的信息可能会在第一次尝试与此软件交互的开发人员或发行版维护人员那里看到。然而，从版本 1.3.0 开始，PyPI 上发布的 zip 存档确实包含这些完全预生成的模块，因此它们可以作为标准安装步骤的一部分使用，即在使用 setup.py 之前不需要导入 ply。虽然可能会显示关于 ply 缺失的相同警告信息，但预生成的模块将允许构建步骤按正常进行。

手动优化

由于 lex 和 yacc 需要生成符号表，优化性能的一种方法是对结果进行缓存。对于 ply，这是通过一个自动生成的模块来完成的。然而，生成的文件带有版本号，因为结果可能特定于安装的 ply 版本。在 calmjs.parse 中，这是通过为 ply 的版本和主要 Python 版本提供特定名称来处理的，因为两者结合会导致自动生成模块的输出和预期存在细微差异。

通常，这种优化的过程是自动的，并且会生成正确的符号表，但是也有一些情况下这会失败，因此出于这个原因，calmjs.parse 提供了一个可选调用的辅助模块和可执行文件，以确保使用正确的编码来生成该文件。其他可能需要这样做的情况是，允许系统管理员为他们的高级用户这样做，因为他们可能在该级别没有写入权限。

要从 shell 中执行优化器，可以使用提供的辅助脚本，如下所示

$ python -m calmjs.parse.parsers.optimize

如果出现警告，指出已定义但未使用的标记，可以安全地忽略。

此步骤通常是可选的，对于通过 PyPI 使用 Python 轮安装此包的用户来说，只要解决安装部分中概述的注意事项即可。

测试安装

为了确保 calmjs.parse 安装正确，可以通过以下方式执行内置测试套件

$ python -m unittest calmjs.parse.tests.make_suite

如果有失败，请在 问题跟踪器 上提交一个包含完整跟踪回溯和/或安装方法的工单。请还包括有关环境的信息，例如本软件的版本、Python 版本、操作系统环境、安装的 ply 版本，以及其他与问题相关的事项。

漂亮的/压缩的打印

还提供了一组漂亮的打印辅助函数，可以将抽象语法树（AST）转换回字符串。这些函数或类构造函数可通过在 calmjs.parse.unparsers 和相关模块中组合各种低级类来生成。

还有一个默认的简写辅助函数，可以将之前生成的AST转换回字符串，可以手动调用，并传递某些参数，例如缩进使用的字符：（注意，之前通过 print 显示的 __str__ 调用是通过这种方式实现的）。

>>> from calmjs.parse.unparsers.es5 import pretty_print
>>> print(pretty_print(program, indent_str='    '))
var main = function(greet) {
    var hello = "hello " + greet;
    return hello;
};
console.log(main('world'));

>>>

还有一个用于打印不带任何不必要的空白字符的辅助函数，它充当源压缩器。

>>> from calmjs.parse.unparsers.es5 import minify_print
>>> print(minify_print(program))
var main=function(greet){var hello="hello "+greet;return hello;};...
>>> print(minify_print(program, obfuscate=True, obfuscate_globals=True))
var a=function(b){var a="hello "+b;return a;};console.log(a('world'));

请注意，在第二个例子中，obfuscate_globals 选项仅启用以演示全局作用域的源混淆，这通常不是在生产库代码上启用的选项，该代码旨在由其他包（其他引用原始未混淆名称的源）重用（引用原始未混淆名称的其他源将无法这样做）。

或者，可以使用与最初导入的基对象同名的属性在原始字符串上直接调用。相关关键字参数将被重定向到适当的底层函数，例如

>>> # pretty print without comments being parsed
>>> print(es5.pretty_print(program_source))
var main = function(greet) {
  var hello = "hello " + greet;
  return hello;
};
console.log(main('world'));

>>> # pretty print with comments parsed
>>> print(es5.pretty_print(program_source, with_comments=True))
// simple program
var main = function(greet) {
  var hello = "hello " + greet;
  return hello;
};
console.log(main('world'));

>>> # minify print
>>> print(es5.minify_print(program_source, obfuscate=True))
var main=function(b){var a="hello "+b;return a;};console.log(main('world'));

生成源映射

对于生成源映射，可以通过打印工厂函数之一构建一个低级反解析器实例。传入一个AST节点将产生一个生成器，该生成器生成包含生成的文本片段和其他信息的元组，这些信息将有助于生成源映射。可以使用来自 calmjs.parse.sourcemap 模块的辅助函数以这种方式写入重生的源代码到某个流中，并将结果处理成源映射文件。示例

>>> import json
>>> from io import StringIO
>>> from calmjs.parse.unparsers.es5 import pretty_printer
>>> from calmjs.parse.sourcemap import encode_sourcemap, write
>>> stream_p = StringIO()
>>> print_p = pretty_printer()
>>> rawmap_p, _, names_p = write(print_p(program), stream_p)
>>> sourcemap_p = encode_sourcemap(
...     'demo.min.js', rawmap_p, ['custom_name.js'], names_p)
>>> print(json.dumps(sourcemap_p, indent=2, sort_keys=True))
{
  "file": "demo.min.js",
  "mappings": "AAEA;IACI;IACA;AACJ;AACA;",
  "names": [],
  "sources": [
    "custom_name.js"
  ],
  "version": 3
}
>>> print(stream_p.getvalue())
var main = function(greet) {
...

同样，这同样适用于压缩打印器，它提供了创建带有不必要的空白字符去除和以最短可能的值混淆标识符的压缩输出的能力。

请注意，在先前的例子中，写入方法中的第二个返回值未被使用，并且传递了一个自定义值。这仅仅是因为程序是从字符串生成的，因此 sourcepath 属性没有分配一个可用于填充结果源映射中 "sources" 列表的可用的值。对于下面的例子，直接在程序上分配一个值给该属性。

>>> from calmjs.parse.unparsers.es5 import minify_printer
>>> program.sourcepath = 'demo.js'  # say this was opened there
>>> stream_m = StringIO()
>>> print_m = minify_printer(obfuscate=True, obfuscate_globals=True)
>>> sourcemap_m = encode_sourcemap(
...     'demo.min.js', *write(print_m(program), stream_m))
>>> print(json.dumps(sourcemap_m, indent=2, sort_keys=True))
{
  "file": "demo.min.js",
  "mappings": "AAEA,IAAIA,CAAK,CAAE,SAASC,CAAK,CAAE,CACvB,...,YAAYF,CAAI",
  "names": [
    "main",
    "greet",
    "hello"
  ],
  "sources": [
    "demo.js"
  ],
  "version": 3
}
>>> print(stream_m.getvalue())
var a=function(b){var a="hello "+b;return a;};console.log(a('world'));

由 io 模块的 read 和 write 函数提供了一个用于处理命名流（即已打开的文件或具有名称属性的流对象，如 io.StringIO）的高级API。下面的示例展示了如何使用该函数从流中读取并将相关项目写回只写流。

>>> from calmjs.parse import io
>>> h4_program_src = open('/tmp/html4.js')
>>> h4_program_min = open('/tmp/html4.min.js', 'w+')
>>> h4_program_map = open('/tmp/html4.min.js.map', 'w+')
>>> h4_program = io.read(es5, h4_program_src)
>>> print(h4_program)
var bold = function(s) {
  return '<b>' + s + '</b>';
};
var italics = function(s) {
  return '<i>' + s + '</i>';
};
>>> io.write(print_m, h4_program, h4_program_min, h4_program_map)
>>> pos = h4_program_map.seek(0)
>>> print(h4_program_map.read())
{"file": "html4.min.js", "mappings": ..., "version": 3}
>>> pos = h4_program_min.seek(0)
>>> print(h4_program_min.read())
var b=function(a){return'<b>'+a+'</b>';};var a=function(a){...};
//# sourceMappingURL=html4.min.js.map

对于将多个源简单连接到单个文件，并带有内联源映射（即，sourceMappingURL 是 JSON 字符串的 base64 编码的 data: URL），可以这样做

>>> files = [open('/tmp/html4.js'), open('/tmp/legacy.js')]
>>> combined = open('/tmp/combined.js', 'w+')
>>> io.write(print_p, (io.read(es5, f) for f in files), combined, combined)
>>> pos = combined.seek(0)
>>> print(combined.read())
var bold = function(s) {
    return '<b>' + s + '</b>';
};
var italics = function(s) {
    return '<i>' + s + '</i>';
};
var marquee = function(s) {
    return '<marquee>' + s + '</marquee>';
};
var blink = function(s) {
    return '<blink>' + s + '</blink>';
};
//# sourceMappingURL=data:application/json;base64;...

在这个例子中，io.write 函数提供了漂亮的反解析器，一个生成器表达式，将产生两个来自两个源文件的AST，然后目标和源映射参数相同，这强制源映射生成器生成base64编码。

请注意，如果向混淆全局变量的minifying打印机提供多个AST，则生成的脚本将具有较早混淆的全局名称被后来的混淆名称破坏，因为unparse操作是由io.write函数分别进行的。

将AST提取到dict

为了帮助从ast中提取值到dict，calmjs.parse.unparsers.extractor模块提供了一个名为ast_to_dict的辅助函数来帮助完成这项工作。此函数将接受任何有效的ast作为参数，该ast被解析为：

>>> from calmjs.parse.unparsers.extractor import ast_to_dict
>>> configuration = es5('''
... var config = module.exports = {};
...
... var name = "Morgan"
... msg = "Hello, " + name + "! " + "Welcome to the host.";
...
... config.server = {
...   host: '0.0.0.0',
...   port: process.env.PORT || 8000,
...   threads: 4 + 4,
...   columns: ['id', 'name', 'description'],
...   memory: 1 << 15,
...   msg: msg
... };
...
... // default proxy stub
... config.proxy = {
...   host: 'localhost',
...   port: 8080,
...   options: {
...     "https": !1,
...     "threshold": -100
...   }
... };
... ''')
>>> baseconf = ast_to_dict(configuration)

访问值只需要像映射一样进行

>>> print(baseconf['name'])
Morgan

赋值绑定到整个表达式，即不会解释到单独的现有赋值。

>>> baseconf['config']
{}
>>> baseconf['config.server']['columns']
['id', 'name', 'description']
>>> baseconf['config.server']['msg']
'msg'
>>> baseconf['config.proxy']['options']['threshold']
-100

请注意，-100值涉及使用-运算符折叠一元表达式，并且默认情况下，其他此类表达式将简单地按原样写回。

>>> baseconf['config.proxy']['options']['https']
'!1'
>>> baseconf['msg']
'"Hello, " + name + "! " + "Welcome to the host."'
>>> baseconf['config.server']['threads']
'4 + 4'

为了帮助更广泛地使用，ast_to_dict提供了一个额外的fold_ops参数。当设置为True时，将启用对支持类型的运算符折叠；例如，将尝试将常量折叠为单个值，如下所述ECMAScript规范中运算符的处理。这通常非常有用，可以确保合并连接的字符串，并通过!0或!1来规范化布尔值的简写定义，以及其他常见表达式。

>>> foldedconf = ast_to_dict(configuration, fold_ops=True)
>>> foldedconf['config.server']['threads']
8
>>> foldedconf['config.server']['memory']
32768
>>> foldedconf['config.server']['port']
8000
>>> foldedconf['config.proxy']['options']['https']
False
>>> # variables will remain as is
>>> foldedconf['config.server']['msg']
'msg'
>>> # however, in the context of a concatenated string, it will form
>>> # a format string instead.
>>> foldedconf['msg']
'Hello, {name}! Welcome to the host.'

如前所述，任何有效的AST都可以作为输入参数，任何悬垂表达式（即那些没有分配或绑定到名称的表达式）将简单地追加到其最外层asttype的键下。

>>> from calmjs.parse.asttypes import (
...     Identifier, FuncExpr, UnaryExpr)
>>> dict_of_ast = ast_to_dict(es5(u"""
... var i;
... i;
... !'ok';
... function foo(bar) {
...     baz = true;
... }
... (function(y) {
...     x = 1;
... });
... """), fold_ops=True)
>>> dict_of_ast['i']
>>> dict_of_ast[Identifier]
['i']
>>> dict_of_ast[UnaryExpr]  # not simply string or boolean
[False]
>>> dict_of_ast['foo']  # named function resolved
[['bar'], {'baz': True}]
>>> dict_of_ast[FuncExpr]
[[['y'], {'x': 1}]]

更低级别的unparse API

当然，前面演示的打印机是使用底层的Unparser类构建的，该类反过来又结合了walker模块中找到的walk函数和Dispatcher类。walk函数使用Dispatcher类的实例遍历AST节点，该实例为特定类型的AST节点提供所有节点类型的描述以及相关处理程序。可以通过现有的规则提供函数来设置这些处理程序。例如，可以构建一个用于混淆标识符名称的同时保持ES5 AST输出缩进的打印机，如下所示：

>>> from calmjs.parse.unparsers.es5 import Unparser
>>> from calmjs.parse.rules import indent
>>> from calmjs.parse.rules import obfuscate
>>> pretty_obfuscate = Unparser(rules=(
...     # note that indent must come after, so that the whitespace
...     # handling rules by indent will shadow over the minimum set
...     # provided by obfuscate.
...     obfuscate(obfuscate_globals=False),
...     indent(indent_str='    '),
... ))
>>> math_module = es5('''
... (function(root) {
...   var fibonacci = function(count) {
...     if (count < 2)
...       return count;
...     else
...       return fibonacci(count - 1) + fibonacci(count - 2);
...   };
...
...   var factorial = function(n) {
...     if (n < 1)
...       throw new Error('factorial where n < 1 not supported');
...     else if (n == 1)
...       return 1;
...     else
...       return n * factorial(n - 1);
...   }
...
...   root.fibonacci = fibonacci;
...   root.factorial = factorial;
... })(window);
...
... var value = window.factorial(5) / window.fibonacci(5);
... console.log('the value is ' + value);
... ''')
>>> print(''.join(c.text for c in pretty_obfuscate(math_module)))
(function(b) {
    var a = function(b) {
        if (b < 2) return b;
        else return a(b - 1) + a(b - 2);
    };
    var c = function(a) {
        if (a < 1) throw new Error('factorial where n < 1 not supported');
        else if (a == 1) return 1;
        else return a * c(a - 1);
    };
    b.fibonacci = a;
    b.factorial = c;
})(window);
var value = window.factorial(5) / window.fibonacci(5);
console.log('the value is ' + value);

每个规则（函数）都有特定选项，这些选项使用特定关键字参数设置，详细信息请参阅各自的docstrings。

在更低级别，ruletypes子模块包含构成当前可用的每个Dispatcher实现的基础定义的原始操作。关于如何将其扩展到仅返回文本的unparse之外的示例，请参阅extractor unparser模块的源代码。

树遍历

在适当的命名模块calmjs.parse.walkers下定义了AST（抽象语法树）通用遍历类。提供了两个默认的遍历类。其中一个是之前演示的ReprWalker类。另一个是Walker类，它提供了一组通用的树遍历方法，用于AST节点树。以下是如何从给定的脚本文件中提取所有对象赋值的示例：

>>> from calmjs.parse import es5
>>> from calmjs.parse.asttypes import Object, VarDecl, FunctionCall
>>> from calmjs.parse.walkers import Walker
>>> walker = Walker()
>>> declarations = es5('''
... var i = 1;
... var s = {
...     a: "test",
...     o: {
...         v: "value"
...     }
... };
... foo({foo: "bar"});
... function bar() {
...     var t = {
...         foo: "bar",
...     };
...     return t;
... }
... foo.bar = bar;
... foo.bar();
... ''')
>>> # print out the object nodes that were part of some assignments
>>> for node in walker.filter(declarations, lambda node: (
...         isinstance(node, VarDecl) and
...         isinstance(node.initializer, Object))):
...     print(node.initializer)
...
{
  a: "test",
  o: {
    v: "value"
  }
}
{
  foo: "bar"
}
>>> # print out all function calls
>>> for node in walker.filter(declarations, lambda node: (
...         isinstance(node, FunctionCall))):
...     print(node.identifier)
...
foo
foo.bar

有关更多详细信息和使用示例，请参阅模块中找到的各种docstrings。

解析器类实例化失败，出现UnicodeEncodeError

对于未将utf8配置为默认编码的平台或系统，在构建解析器实例时，自动表生成可能会失败。例如

>>> from calmjs.parse.parsers import es5
>>> parser = es5.Parser()
Traceback (most recent call last):
  ...
  File "c:\python35\....\ply\lex.py", line 1043, in lex
    lexobj.writetab(lextab, outputdir)
  File "c:\python35\....\ply\lex.py", line 195, in writetab
    tf.write('_lexstatere   = %s\n' % repr(tabre))
  File "c:\python35\lib\encodings\cp1252.py", line 19, in encode
    return codecs.charmap_encode(input,self.errors,encoding_table)[0]
UnicodeEncodeError: 'charmap' codec can't encode character '\u02c1' ...

提供了一个工作区辅助脚本，可以像这样执行

$ python -m calmjs.parse.parsers.optimize

关于此主题的更多详细信息，请参阅本文件的手动优化部分。

警告：导入时存在未使用的标记

这表明导入此包的方法或源没有优化。一种快速解决方法是按照本文件的手动优化部分的说明操作，以确保不再生成这些消息（如果此警告每次导入模块时都会出现，这意味着符号表每次都会被重新生成，并且应该通过生成优化模块来纠正这种额外的计算开销）。

优化模块包含在PyPI上的wheel发行版和源发行版中，但它们不是源存储库的一部分，因为生成的代码从未被提交。如果第三方制作的二进制发行版在导入时导致此警告，则应将其修复以包含优化模块。

此外，还实施了安全措施，以防止从1.3.1版本开始的发行版生成此警告，通过在构建时更严格地执行此优化步骤。但持续的（或粗心的）行为者可能在构建过程中规避此限制，但通过PyPI发布的官方版本应包含对所有支持的ply版本（包括版本3.6至3.11）所需的所有优化。

或者，此问题也可能通过使用pyinstaller发生，如果在使用版本在calmjs.parse-1.3.1之前的版本时未复制ply的包元数据，并且如果未声明这些优化模块的隐藏导入，则始终会发生。以下钩子可以确保在编译的二进制文件中calmjs.parse正确运行

from PyInstaller.utils.hooks import collect_data_files, copy_metadata
from calmjs.parse.utils import generate_tab_names

datas = []
datas.extend(collect_data_files("ply"))
datas.extend(copy_metadata("ply"))
datas.extend(collect_data_files("calmjs.parse"))
datas.extend(copy_metadata("calmjs.parse"))

hiddenimports = []
hiddenimports.extend(generate_tab_names('calmjs.parse.parsers.es5'))

# if running under Python 3 with ply-3.11, above is equivalent to
# hiddenimports = [
#     "calmjs.parse.parsers.lextab_es5_py3_ply3_11",
#     "calmjs.parse.parsers.yacctab_es5_py3_ply3_11",
# ]

性能慢

由于此程序基本上完全分解成非常小的函数，因此与其他实现相比，由于函数调用是Python中最昂贵的操作之一，这导致巨大的性能损失。可能可以通过在分发器描述中将每个asttype Node类型的解析器函数组合在一起进一步优化定义，但这可能需要标记和布局函数没有命名冲突的参数，并且新函数将一次性接收所有这些参数。

尝试安装时的导入错误信息

如错误信息所示，在缺少预生成的模块的情况下尝试安装构建包之前，必须安装ply和setuptools包。这种情况可能是由于直接使用源代码库提供的源代码构建，或者没有与已安装的ply版本匹配的预生成的模块。请确保在从源安装之前，ply已安装并可用，如果遇到此错误信息。