编程语言编译器【免费下载链接】CarpA statically typed lisp, without a GC, for real-time applications.项目地址https://gitcode.com/gh_mirrors/ca/Carp点击查看免费下载Carp 是一个无 GC、静态类型、面向实时应用场景的 Lisp 方言参见仓库根目录的 README.md 中的项目定位。本文围绕仓库中 docs/core/README.md 这份官方指引系统讲解 Carp 标准库 API 文档的三种使用方式在线浏览、使用安装目录内置的本地副本、以及通过内置的generate_core_docs.carp程序一键刷新本地文档。读完本文你将掌握carp -x脚本执行模式、Project.config文档相关配置项、save-docs/save-docs-ex文档生成命令的完整用法并能自行产出与官方同构的标准库 API 文档站点。一、文档获取的两种途径在线版与本地版Carp 标准库参考文档有两条官方获取途径在线版本官方在线文档托管于 Carp 官方文档站点原文档中的链接http://carp-lang.github.io/carp-docs/core/core_index.html为外部链接仅作背景说明。本地版本你的 Carp 安装目录中自带一份与在线版同源的本地副本存放于docs/core/目录下即当前仓库中的 docs/core 目录。两者的内容完全一致都由同一套源码生成机制产出。区别仅在于在线版由官方维护者定期发布本地版则随你的 Carp 安装一同分发。由于本地副本可以直接用浏览器打开docs/core/core_index.html为入口索引页即使处于离线环境你依然可以完整查阅标准库 API。二、一键刷新本地文档运行生成程序本地文档副本并非一成不变——当你在core/目录中修改了标准库模块例如新增函数、更新doc字符串或者安装的 Carp 版本与文档副本存在差异时都可以通过官方提供的短小程序重新生成。刷新命令如下摘自 docs/core/README.md 原文carp -x ./docs/core/generate_core_docs.carp必须注意该命令要求从 Carp 安装目录运行而不是从./docs/core目录内部运行。这是因为生成程序内部使用相对路径./docs/core/作为文档输出目录详见下文源码分析只有以安装目录为工作目录时这些相对路径才能正确解析。-x是 Carp 编译器的命令行标志表示“构建并立即运行代码随后退出编译器”。关于该标志及-b仅构建不运行等更多编译器旗标的说明参见官方手册 docs/Manual.md 中的“Compiler flags”一节-x的常规用法在 docs/HowToRunCode.md 中也有示例$ carp some_file.carp -x。生成脚本做了什么以仓库中的 docs/core/generate_core_docs.carp 为例脚本内容如下; runs this from the Carp installation directory, NOT current directory! (Project.config title core) (Project.config docs-directory ./docs/core/) (Project.config docs-logo logo.png) (Project.config docs-prelude Welcome to the documentation for the Carp standard library. Please select a library from the menu on the right to browse its documentation. Carp is available for download [here](https://github.com/carp-lang/carp).) (Project.config docs-url https://github.com/carp-lang/carp) (load SafeInt.carp) (load Vector.carp) (load Geometry.carp) (load Statistics.carp) (load Test.carp) (load Bench.carp) (load Phantom.carp) (save-docs-ex [Array Bench Bool Byte Char Control Debug Derive Double Dynamic Float Function Geometry Quasiquote Int Introspect Unit IO Long Map Maybe Opaque Pair Pattern Quadruple Phantom Pointer Result StaticArray System Statistics String Test Triple Vector2 Vector3 VectorN] [Macros.carp ControlMacros.carp]) (quit)脚本的执行流程清晰分为三步配置项目与文档元信息通过(Project.config ...)设置标题、文档输出目录、Logo、序言prelude文字与站内链接等。加载辅助模块load若干标准库模块SafeInt、Vector、Geometry、Statistics、Test、Bench、Phantom确保后续要生成文档的模块及其依赖都处于已加载状态。生成文档调用save-docs-ex第一个参数是一个模块符号数组本次共 36 个标准库模块第二个参数是一个字符串数组列出要“以全局符号形式”并入文档的源文件名这里是Macros.carp与ControlMacros.carp最后(quit)退出。仓库中还提供了一份同构的 SDL 文档生成脚本 docs/sdl/generate_sdl_docs.carp用于为官方 SDL 绑定SDL、SDLApp、IMG、GFX、Mixer、TTF生成文档可作为自定义文档站点的第二份参考模板。三、文档生成的底层原理从配置项到 HTML 渲染要深入理解上述脚本需要知道文档生成链路中每个环节的实现。这条链路贯穿了编译器源码中的三个文件Project.config命令入口src/Commands.hs、项目配置注册表src/ProjectConfig.hs、以及最终的 HTML 渲染器src/RenderDocs.hs。3.1Project.config配置项的查表与设置Project.config是 REPL / 脚本中配置当前“项目”的命令。其底层实现是commandProjectConfigsrc/Commands.hs它先以字符串键在projectKeyMap中查找对应配置项找不到键时报CONFIG ERROR找到但为只读时报 “is read-only”随后调用该键对应的 setter 更新项目状态与之对应的Project.get-configsrc/Commands.hs则调用 getter 读回配置值。projectKeyMap位于 src/ProjectConfig.hs其中与文档生成直接相关的键有配置键含义对应 getter/setter 实现docs-directory生成的 HTML 文档输出目录src/ProjectConfig.hsdocs-logo文档页面右上角 Logo 图片路径src/ProjectConfig.hsdocs-prelude索引页顶部以 CommonMark 渲染的序言文字src/ProjectConfig.hsdocs-urlLogo 链接到的外部 URL如项目主页src/ProjectConfig.hsdocs-generate-index是否生成xxx_index.html总索引页布尔值src/ProjectConfig.hsdocs-styling文档页面引用的 CSS 文件路径src/ProjectConfig.hstitle项目标题用作文档页标题与索引文件名前缀src/ProjectConfig.hs这些字段最终被存储为Project记录类型的属性定义见 src/Project.hsshow Project实例src/Project.hs会把Docs directory、Docs logo、Docs prelude、Docs Project URL、Docs generate index、Docs CSS URL全部打印出来便于调试。官方手册 docs/Manual.md 的“Configuring a project”一节同样列出这些配置项如docs-directory— Where to put generated docs与源码实现一一对应。值得说明的是Project.config支持远不止文档相关键位还包括cflag、libflag、pkgconfigflag、compiler、target、output-directory、prompt、search-path、print-ast等编译与构建配置完整列表见 src/ProjectConfig.hs。此外core/Project.carp提供了便利宏defproject批量设置多个配置键以及Project.append-cflag、Project.append-libflag、Project.append-pkgflag向已有配置追加标志。3.2save-docs与save-docs-ex两条生成命令Carp 提供两级文档生成命令save-docs最简单的一层封装定义于 core/Project.carp接受一组未加引号的模块符号例如(save-docs Int Float String)官方手册 docs/Manual.md 与 docs/Libraries.md 中均有此示例。其内部实现为(defmacro save-docs [:rest modules] (list save-docs-ex (list quote (collect-into modules array)) []))即把模块符号收集成数组后转交给save-docs-ex且第二个参数文件名数组恒为空——因此它不处理“全局符号”的收录。save-docs-ex完整版本底层实现为commandSaveDocsExsrc/Commands.hs。它接收两个数组第一个参数模块符号数组。每个符号必须在全局环境中解析为模块Mod否则分别报 “I can’t generate documentation for … because it isn’t a module” 或 “I can’t find the module …”见 src/Commands.hs。第二个参数文件名字符串数组。用于把散落在这些文件中的“全局符号”即未被模块包裹的顶层绑定收集进一个名为Globals in filename的伪模块中一并生成文档见 src/Commands.hs 与createFauxModule实现。这正是generate_core_docs.carp把Macros.carp、ControlMacros.carp作为第二参数传入的原因——这两个文件中的全局宏如defproject、save-docs本身、thread-first-internal等也需要被文档化。save-docs-ex最终调用saveDocssrc/Commands.hs再由saveDocsForEnvssrc/RenderDocs.hs执行实际生成。3.3 HTML 渲染管线saveDocsForEnvssaveDocsForEnvs是整个生成过程的枢纽src/RenderDocs.hs其行为如下以projectDocsDir为输出目录projectTitle为标题递归收集所有传入模块的子模块作为依赖getEnvDependencies保证嵌套模块也被生成对每个模块调用saveDocsForEnvBindersrc/RenderDocs.hs自动创建输出目录createDirectoryIfMissing False dir将每个模块渲染为独立的模块名.html文件若projectDocsGenerateIndex为真则额外生成title_index.html总索引页并在控制台打印Generated docs to dir。页面的具体内容由envBinderToHtmlsrc/RenderDocs.hs与binderToHtmlsrc/RenderDocs.hs渲染索引页index page由projectIndexPagesrc/RenderDocs.hs生成包含 Logo 图片docs-logo、指向docs-url的链接、标题title、以 CommonMark 渲染的docs-prelude序言以及由moduleIndexsrc/RenderDocs.hs生成的模块导航树支持details/summary折叠分组。模块页module page每个 binder函数、类型、宏等渲染为一个带锚点的条目包含名称、类型签名beautifyType美化后的类型、参数列表、doc元数据中的文档字符串同样以 CommonMark 渲染。deprecated元数据为真的绑定会附加 “deprecated” 标记及弃用说明src/RenderDocs.hs。过滤规则shouldEmitDocsForBindersrc/RenderDocs.hs只跳过hidden元数据为真的绑定其余全部进入文档。标准库源码中有大量hidden与deprecated用法实例例如 core/Bench.carp 的(hidden get-time-elapsed)、core/Box.carp 的(hidden heap-alloc)、core/ControlMacros.carp 的(deprecated deprecated in favor of-.)。这解释了为什么生成的文档中只会出现公开 API而内部辅助函数不可见。3.4 文档内容的来源doc元数据文档页面上每个条目的说明文字来源于标准库源码中的(doc 绑定 ...)元数据形式。例如 core/Array.carp 中(doc Array is the indexable collection data structure. ...)定义了Array模块自身的模块级文档而(doc reduce ...)、(doc scan ...)等则为具体函数提供说明。这套元数据系统在官方手册 docs/Manual.md 的 “Metadata” 一节有完整介绍(doc path …)用于写文档、(sig path (Fn …))用于类型注解、(private path)用于隐藏。也就是说标准库文档并非手写 HTML而是从源码中的 doc 字符串自动生成——这也正是“刷新本地副本”这一操作的意义所在源码注释更新后重新运行生成脚本即可得到同步的 API 文档。3.5 样式carp_style.css生成出的 HTML 页面通过docs-styling配置引用样式表。仓库的 docs/core/carp_style.css 定义了文档站点样式包括页面字体、.logo右浮动、150px Logo 图片、.index模块索引列表、.args参数块浅灰背景、以及details summary折叠交互等。若想定制自己的文档站点外观可仿照该文件提供自定义 CSS 并设置(Project.config docs-styling 你的样式.css)。四、从 README 到自己的项目自定义文档生成实战理解了上述机制后你可以完全照搬这套流程为自己的项目生成文档。综合官方指引docs/core/README.md、docs/Libraries.md 的 “Documentation” 一节以及 docs/Manual.md 的 “Metadata” 一节推荐的完整做法如下4.1 为单个模块快速生成在 REPL 中直接调用save-docs即可官方示例 (save-docs Int Float String)该命令会把Int、Float、String三个模块的文档渲染到当前docs-directory配置指向的目录默认见Project初始化逻辑可通过Project.get-config查看。4.2 编写完整的生成脚本参考官方模板为你的项目创建一份生成脚本以下为仿照 docs/core/generate_core_docs.carp 的最小示例; 从项目根目录运行而非脚本所在子目录 (Project.config title MyLib) (Project.config docs-directory ./docs/mylib/) (Project.config docs-logo logo.png) (Project.config docs-prelude Welcome to the MyLib documentation.) (Project.config docs-url https://example.org/mylib) (load MyLib.carp) (save-docs-ex [MyLib MyLib.Helper] ; 需要文档化的模块可含嵌套模块 [MyLibGlobals.carp]) ; 需要并入文档的全局符号所在文件 (quit)运行方式与官方一致carp -x ./docs/mylib/generate_mylib_docs.carp4.3 生成行为速查需求做法改变输出目录(Project.config docs-directory ./docs/core/)更换 Logo(Project.config docs-logo logo.png)配合 docs/core/carp_style.css 中的.logo img样式自定义首页序言(Project.config docs-prelude …支持 CommonMark)控制索引页开关(Project.config docs-generate-index true)布尔值隐藏内部函数在源码中标注(hidden 绑定)例如 core/Box.carp标记弃用 API在源码中标注(deprecated 绑定 原因)例如 core/ControlMacros.carp收录文件级全局符号把文件名加入save-docs-ex第二参数例如 docs/core/generate_core_docs.carp 中的[Macros.carp ControlMacros.carp]五、常见问题与注意事项务必从安装目录运行生成脚本这是原文档明确强调的前提。若从./docs/core内运行脚本中的./docs/core/相对路径将无法指向预期的输出目录。-x与-b的区别-x会编译并执行要求代码含main-b仅构建可执行文件。生成文档这类“运行后即退出”的脚本官方使用-xdocs/Manual.md “Compiler flags”一节。save-docs-ex的两个数组缺一不可第一个必须是模块符号数组第二个必须是文件名字符串数组。传入非模块符号或找不到的模块会得到明确报错见 src/Commands.hs 的错误信息。hidden与deprecated控制文档可见性被标记hidden的绑定不会出现在文档中被标记deprecated的绑定仍会出现但附带弃用标记与说明src/RenderDocs.hs。生成结果验证运行脚本后控制台会输出Generated docs to dirsrc/RenderDocs.hs随后可在输出目录找到每个模块对应的模块名.html与索引页title_index.html直接用浏览器打开即可。六、总结Carp 标准库的官方文档体系是一套完全自动化、可离线自愈的流程在线文档与安装内置的本地副本同源均由docs/core/generate_core_docs.carp这类脚本驱动生成脚本通过Project.config系列配置项docs-directory、docs-logo、docs-prelude、docs-url等定义站点形态通过save-docs-ex选择模块并收录文件级全局符号最终由编译器的RenderDocs模块将源码中的doc元数据渲染为带索引、折叠导航、锚点定位与弃用标记的完整 HTML 站点。理解了这条从源码注释到 HTML 文档的完整链路你既可以在离线环境下随时查阅标准库也能为自己的 Carp 项目一键生成同样规格的 API 文档。赞分享编程语言编译器【免费下载链接】CarpA statically typed lisp, without a GC, for real-time applications.项目地址https://gitcode.com/gh_mirrors/ca/Carp点击查看免费下载相关推荐htmx 中的超媒体 API 与数据 API为什么超媒体 API 可以拥抱变更而不必版本化htmx 中的超媒体 API 与数据 API为什么超媒体 API 可以拥抱变更而不必版本化 本文深入剖析 htmx 项目核心文档之一《Hypermedia A编程语言编译器如何让Mac编程更顺手Notepad--跨平台文本编辑器快速指南如何让Mac编程更顺手Notepad 跨平台文本编辑器快速指南 如果你的主力开发机是 Mac又嫌系统自带 TextEdit 太简陋Notepad 值得一试桌面应用大麦自动抢票工具三步部署Web与移动端双端的完整指南大麦自动抢票工具三步部署Web与移动端双端的完整指南 ticket purchase 是一个基于 Python 的大麦自动抢票工具Web 端用 SeleniGUI 自动化RPA上一篇如何高效使用Figma MCP Server从设计到代码的终极实战指南下一篇RR 安装与调试实战指南从引导条件、镜像转换到 DSM 内核级排障命令全解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考