助长了卑鄙行为¶
感谢您对投稿的兴趣!请阅读以下指南。
发牌¶
该代码在BSD 2条款许可下分发。提出拉取请求的贡献者必须同意他们能够并愿意将他们的贡献放在该许可证下。
一般捐款核对表¶
查看文档以了解如何编写 a new lexer , a new formatter , a new style 或 a new filter 。如果添加词法分析器,请确保您已阅读 常见陷阱和最佳实践 。
使用以下命令运行测试套件
tox
,并确保它通过。确保为您的新功能添加测试,并在适用的情况下编写文档。有关如何测试词法分析器的信息,请参阅下面的内容。
使用标准导入约定:
from token import Punctuation
如何添加词法分析器¶
要添加词法分析器,您必须执行以下步骤:
在下选择匹配模块
pygments/lexers
或者为Lexer类创建一个新模块。备注
我们鼓励您将lexer类放入它自己的模块中,除非它是现有lexer的一个非常小的派生。
接下来,确保可以从模块外部获知词法分析器。中的所有模块
pygments.lexers
包指定__all__
。例如,esoteric.py
设置::__all__ = ['BrainfuckLexer', 'BefungeLexer', ...]
将lexer类的名称添加到此列表中(如果lexer是模块中唯一的类,则创建该列表)。
最后,通过重新构建词法分析器映射,可以将词法分析器公之于众。
$ tox -e mapfiles
如何测试词法分析器¶
要添加新的词法分析器测试,请在下面创建一个仅包含您的代码片段的文件 tests/snippets/<lexer_alias>/
。那就跑吧 tox -- --update-goldens <filename.txt>
以自动填充当前预期的令牌。检查它们是否看起来很好,然后检入文件。
词法分析器测试使用 tox
,像所有其他测试一样。在使用词法分析器时,还可以使用以下命令仅运行该词法分析器的测试 tox -- tests/snippets/language-name/
和/或 tox -- tests/examplefiles/language-name/
。
使用运行测试套件 tox
将在测试输入上运行词法分析器,并检查输出是否与预期的令牌匹配。如果您正在改进一个词法分析器,那么令牌输出发生变化是正常的。要更新测试的预期令牌输出,请再次使用 tox -- --update-goldens <filename.txt>
。检查更改并检查它们是否符合预期,然后将它们与建议的代码更改一起提交。
应该放入大的测试文件 tests/examplefiles
。其工作原理类似于 snippets
,但令牌输出存储在单独的文件中。还可以使用以下命令重新生成输出 --update-goldens
。
皮吉斯的目标与非目标¶
对Python的支持¶
Pygments支持所有支持的Python版本 Python Developer's Guide 。此外,还支持最新稳定版本的RHEL、Ubuntu LTS和Debian的默认Python版本,即使它们已正式停产。支持其他生命周期结束的版本并不是Pygments的目标。
验证¶
Pygments不会尝试验证输入。接受对于给定语言来说不合法的代码是可以接受的,只要它简化了代码库,并且不会导致令人惊讶的行为。例如,在C89中,接受 // 基于注释将是很好的,因为事实上所有的编译器都支持它,并且为它拥有单独的词法分析器是不值得的。