Giters

KDr2 / PLFA-zh

《编程语言基础：Agda 描述》，Programming Language Foundations in Agda 中文版

Home Page:https://agda-zh.github.io/PLFA-zh/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

layout title prev permalink next translators
page
使用说明
/Preface/
/GettingStarted/
/Naturals/
Rongxiao Fu
Oling Cat

Calendar Version Agda agda-stdlib

《编程语言基础：Agda 语言描述》的使用方法与《Programming Language Foundations in Agda》一致。

本书可访问 PLFA-zh 在线阅读。

要参与翻译，请先阅读翻译规范。

用户依赖

你可以在线阅读 PLFA，无需安装任何东西。 然而，如果你想要交互式编写代码或完成习题，那么就需要几样东西：

PLFA 只针对特定的 Agda 和 标准库版本进行了测试，相应版本已在前面的徽章中指明。 Agda 和标准库变化得十分迅速，而这些改变经常搞坏 PLFA，因此使用旧版或新版通常会出现问题。

Agda 和 Agda 标准库有多个版本。如果你使用了包管理器（如 Homebrew 或者 Debian apt），Agda 的版本可能不是最新的。除此之外，Agda 仍然在活跃的开发之中，如果你从 GitHub 上安装了开发版本，开发者的新变更也可能让这里的代码出现问题。 因此，使用上述版本的 Agda 和 Agda 标准库很重要。

macOS 平台：安装 XCode 命令行工具

在 macOS 平台，你需要安装 XCode 命令行工具。 在大多数 macOS 系统版本上，你可以用下面的命令安装它们：

xcode-select --install

安装 Haskell 工具 Stack {name=install-the-haskell-tool-stack}

Agda 使用 Haskell 写的，因此我们需要 Haskell 工具 Stack （简称 Stack）来安装 Agda。 Stack 是管理不同版本的 Haskell 编译器和包的管理程序。

  • UNIX 和 macOS 平台：如果你的包管理程序有 Stack 的包，这是大概是最简单的方法。 比如说 macOS 的 Homebrew 或者 Debian 的 APT 提供了「haskell-stack」包。 不然，你可以按照 Stack 网站上 的指示进行安装。 在一般情况下，Stack 将二进制文件安装至 HOME/.local/bin。 请务必保证这个目录在你的 PATH 之内，你可以将下面的内容加入你的 shell 配置中，例如 HOME/.bash_profile 中：

    export PATH="${HOME}/.local/bin:${PATH}"

    最后，请保证你有最新版的 Stack，运行：

    stack upgrade

  • Windows 平台：Stack 网站上提供 Windows 安装包。

安装 Git {name=install-git}

如果你没有已经安装 Git，请参阅 Git 下载页面。

用 Stack 安装 Agda {name=install-agda-using-stack}

安装 特定 Agda 版本的最简方式是使用 Stack。你可以从 GitHub 上获取需要的版本， 可以通过克隆源码库并切换到合适的分支，也可以直接下载 Zip 包：

git clone https://github.com/agda/agda.git
cd agda
git checkout v2.6.1.3

要安装 Agda，请在其源码目录中运行 Stack：

stack install --stack-yaml stack-8.8.3.yaml

这一步会消耗很长时间和很多内存来完成。

使用已安装的 GHC

Stack 可以为你安装和管理 Glasgow Haskell 编译器（GHC）。 然而，如果你已经安装了 GHC 并且想让 Stack 使用你系统上安装的 GHC 版本，可以传递 --system-ghc 选项并选择对应的 stack-*.yaml 文件。例如，若你安装了 GHC 8.2.2，请运行：

stack install --system-ghc --stack-yaml stack-8.2.2.yaml

检查 Agda 是否被正确地安装

如果你愿意，你可以检查 Agda 是否已正确安装。 创建一个名为 hello.agda 的文件，并输入下面的内容：

data Greeting : Set where
  hello : Greeting

greet : Greeting
greet = hello

从命令行中，切换到 hello.agda 所在的文件夹内，然后运行：

agda -v 2 hello.agda

你会看到如下的消息，而不是错误：

Checking hello (/path/to/hello.agda).
Finished hello.

安装 PLFA 和 Agda 标准库 {name=install-plfa-and-the-agda-standard-library}

你也可以从 GitHub 克隆源码库，或者下载 Zip 包来获取最新版的《编程语言基础：Agda 语言描述》：

git clone --depth 1 --recurse-submodules --shallow-submodules https://github.com/plfa/plfa.github.io plfa
# Remove `--depth 1` and `--shallow-submodules` if you want the complete git history of PLFA and the standard library.

PLFA 包括了所需要的 Agda 标准库版本，如果你在克隆时使用了 --recurse-submodule 选项，你在 standard-library 文件夹中已经有了 Agda 标准库！

如果你忘记使用了 --recurse-submodules 选项，也没有关系，我们可以修复它！

cd plfa/
git submodule update --init --recursive --depth 1
# Remove `--depth 1` if you want the complete git history of the standard library.

如果你用 Zip 包下载了 PLFA，你可以从 GitHub 上下载所需要的 Agda 标准库版本。 你可以从正确的分支克隆代码仓库，或者下载 Zip 包。

git clone https://github.com/agda/agda-stdlib.git --branch v1.6 --depth 1 agda-stdlib
# Remove `--depth 1` if you want the complete git history of the standard library.

最后，我们需要让 Agda 知道如何找到标准库。 你需要知道标准库安装的目录。 检查 standard-library.agda-lib 文件是否存在，并记录这个文件的路径。 你需要在 AGDA_DIR 创建两个配置文件。在 UNIX 和 macOS 平台，AGDA_DIR 默认为 ~/.agda。在 Windows 平台，AGDA_DIR 一般默认为 %AppData%\agda，而 %AppData% 默认为 C:\Users\USERNAME\AppData\Roaming。

  • 如果 AGDA_DIR 文件夹不存在，创建它。
  • 在 AGDA_DIR 中，创建一个纯文本文件 libraries，内容为 /path/to/standard-library.agda-lib （即上文中记录的路径）。 这个文件让 Agda 知道有一个名为 standard-library 的库可用。
  • 在 AGDA_DIR 中，创建一个纯文本文件 defaults，内容仅为 standard-library 这一行。

关于放置标准库的更多信息可以参阅 Agda 文档中的库管理。

PLFA 也可以设置为一个 Agda 库。 如果你想完成 courses 目录中的习题，或者想导入书中的模块， 那么需要将 PLFA 设置为 Agda 库。完成此设置需要将 plfa.agda-lib 所在的路径作为单独的一行添加到 AGDA_DIR/libraries，并将 plfa 作为单独的一行添加到 AGDA_DIR/defaults。

检查 Agda 标准库是否正确安装

如果你愿意，你可以测试 Agda 标准库是否已正确。创建一个名为 nats.agda 的文件，包括以下内容：

open import Data.Nat

ten : ℕ
ten = 10

（注意 ℕ 是一个 Unicode 字符，而不是普通的大写字母 N。你可以直接从本页复制粘贴它到文件中。）

从命令行中，切换到 nats.agda 所在的文件夹内，然后运行：

agda -v 2 nats.agda

你会看见数行来描述 Agda 在检查你的文件时载入的文件，但是没有错误：

Checking nats (/path/to/nats.agda).
Loading  Agda.Builtin.Equality (…).
…
Loading  Data.Nat (…).
Finished nats.

设置 Agda 的编辑器

Emacs

推荐的 Agda 编辑器是 Emacs。安装 Emacs 可以用下面的方法：

  • UNIX 平台：包管理器中的 Emacs 应该可以使用（只要它的版本比较新），GNU Emacs 下载页面也有最近发布版本的链接。
  • macOS 平台：推荐的 Emacs 是 Aquamacs，但是 GNU Emacs 也可以通过 Homebrew 或者 MacPorts 安装。参阅 GNU Emacs 下载页面中的指示。
  • Windows 平台：参阅 GNU Emacs 下载页面中的指示。

确保你可以用你安装的版本打开、编辑、保存文件。GNU Emacs 网站上的 Emacs 向导描述了如果打开 Emacs 安装中的教程。

Agda 自带了 Emacs 编辑器支持，如果你安装了 Agda，运行下面的命令来配置 Emacs：

agda-mode setup
agda-mode compile

如果你已经是 Emacs 用户，并有自己的设置，你会注意到 setup 命令向你的 .emacs 文件中追加了配置，来配合你已有的设置。

加上 agda-mode。Agda 自带了 agda-mode， 因此如果你已经安装了 Agda，那么之需要运行以下命令就能配置好 agda-mode 了：

检查 agda-mode 是否正确安装

打开之前创建的 nats.agda 文件，使用 C-c C-l 来载入和类型检查这个文件。

在 Emacs 中自动加载 agda-mode

从版本 2.6.0 开始，Agda 支持 Markdown 风格的文学编程，文件使用 .lagda.md 扩展名。 该扩展名的一个副作用就是大部分编辑器默认会进入 Markdown 编辑模式。 而为了让 agda-mode 在你打开 .agda 或 .lagda.md 文件时自动加载， 请将以下内容放到你的 Emacs 配置文件中：

;; auto-load agda-mode for .agda and .lagda.md
(setq auto-mode-alist
   (append
     '(("\\.agda\\'" . agda2-mode)
       ("\\.lagda.md\\'" . agda2-mode))
     auto-mode-alist))

如果你配置中已有了改变 auto-mode-alist 的设置，将上述内容放置在已有的设置之后，或者将其与已有设置合并（如果你对 Emacs Lisp 足够了解）。 Emacs 的配置文件通常位于 ~/.emacs 或 ~/.emacs.d/init.el，然而 Aquamacs 用户需要将启动设置放到位于 ~/Library/Preferences/Aquamacs Emacs/Preferences 的 Preferences.el 文件中。 对于 Windows 平台，请参阅 GNU Emacs 文档 来寻找配置文件的位置。

可选：在 Emacs 中使用 Mononoki 字体

Agda 中的很多重要符号是用 Unicode 来表示的，因此用来显示和编辑 Agda 的字体需要正确地显示这些符号。最重要的是你使用的字体需要有好的 Unicode 字符支持。我们推荐 Mononoki， 其他的备选字体有 Source Code Pro、 DejaVu Sans Mono 和 FreeMono。

你可以直接从 GitHub 下载并安装 Mononoki。对于大多数系统来说，安装字体只是简单的下载 .otf 或者 .ttf 文件。 如果你的包管理器提供了 Mononoki 的包，那样可能更加简单。 例如，macOS 的 Homebrew 在 cask-fonts cask 中提供了 font-mononiki 包；Debian 的 APT 提供了 fonts-mononoki 包。 将下面的内容加入 Emacs 配置文件，可以把 Mononoki 设置为 Emacs 的默认字体：

;; default to mononoki
(set-face-attribute 'default nil
                    :family "mononoki"
                    :height 120
                    :weight 'normal
                    :width  'normal)

在 Emacs 中使用 agda-mode

要加载文件并对其执行类型检查，请使用 C-c C-l。

Agda 的编辑是通过使用「洞」来交互的，它表示程序中尚未填充的片段。 如果用问号作为表达式，并用 C-c C-l 加载缓冲区，Agda 会将问号替换为一个「洞」。 当光标在洞中时，你可以做以下这些事情：

  • C-c C-c: 分项（询问变量名，case）
  • C-c C-空格：填洞
  • C-c C-r：用构造子精化（refine）
  • C-c C-a：自动填洞（automatic）
  • C-c C-,：目标类型和上下文
  • C-c C-.：目标类型，上下文，以及推断的类型

更多细节请见 emacs-mode 文档。

如果你想在 Agda 代码的侧边而非底栏查看信息，那么可以这样做：

  • 打开 Agda 文件并按 C-c C-l；
  • 按 C-x 1 来仅显示当前 Agda 文件；
  • 按 C-x 3 来垂直分割窗口；
  • 将光标移动到右侧窗口；
  • 按 C-x b 并输入「Agda information」切换到该缓冲区。

现在，Agda 的错误消息将会在代码右侧显示，而非被挤压在底部的狭小空间里。

在 Emacs 中使用 agda-mode 输入 Unicode 字符

当你书写 Agda 代码时，你需要输入标准键盘上没有的字符。Emacs 的「Agda-mode」定义了字符翻译来让这件事更容易：当你输入特定普通字符的序列时，Emacs 会在 Agda 文件中使用对应的特殊字符来替换。

例如，我们可以在之前的 .agda 测试文件中加入一条注释。 比如说，我们想要加入下面的注释：

{- I am excited to type ∀ and → and ≤ and ≡ !! -}

前几个字符都是普通字符，我们可以如往常的方式输入它们……

{- I am excited to type

在最后一个空格之后，我们无法在键盘上找到 ∀ 这个键。这个字符的输入序列是四个字符 \all，所以我们输入这四个字符，当我们完成时，Emacs 会把它们替换成我们想要的……

{- I am excited to type ∀

我们继续输入其他字符。有时字符会在输入时发生变化，因为一个字符的输入序列是另一个字符输入序列的前缀。 在我们输入箭头时会出现这样的情况，它的输入序列是 \->。在输入 \- 之后我们会看到……

{- I am excited to type ∀ and

……因为输入序列 \- 对应了一定长度的短横。当我们输入 > 时，­ 变成了 →！ ≤ 的输入序列是 \<=，≡ 的是 \==。

{- I am excited to type ∀ and → and ≤ and ≡

最后几个字符又回归了普通字符……

{- I am excited to type ∀ and → and ≤ and ≡ !! -}

如果你在 Emacs 中输入 Unicode 时遇到了问题，可以在每章的最后找到当前章节中用到的 Unicode 字符。

带有 agda-mode 的 Emacs 提供了很多有用的命令，其中有两个对处理 Unicode 字符时特别有用。 支持的字符的完整列表可使用 agda-input-show-translations 命令查看：

M-x agda-input-show-translations

agda-mode 支持的所有字符都会列出来。

如果你想知道如何在 agda 文件输入一个特定的 Unicode 字符，请将光标移动到该字符上并输入以下命令：

M-x quail-show-key

你会在迷你缓冲区中看到该字符对应的按键序列。

Spacemacs

Spacemacs 是一个「社区引领的 Emacs 版本」，对 Emacs 和 Vim 的编辑方式都有很好的支持。它自带集成了 agda-mode，所需的只是将它打开。

Visual Studio Code

Visual Studio Code 是一个微软开发的开源代码编辑器。 Visual Studio 市场中有 Agda 插件。

Atom

Atom 是一个 GitHub 开发的开源代码编辑器。 Atom 包管理器中有 Agda 插件。

开发者依赖

PLFA 是以 Pandoc Markdown 格式的文学化 Agda 编写的。 PLFA 可同时在网站上和作为 EPUB 电子书来阅读，二者均可在 UNIX 和 macOS 上构建。 最后，为了帮助开发者避免常见错误，我们提供一系列 Git 钩子脚本。

构建网站和电子书

如果你想在本地构建 PLFA 的网站版，你只需要 Stack！ PLFA 用 Hakyll （一个构造静态网页的 Haskell 库）来构建。 我们配置了一个用于执行常见任务的 Makefile。例如，要构建 PLFA，运行：

make build

如果你想在本地架起 PLFA，并且在源文件修改时重构网页，运行：

make watch

Makefile 除了构造和监视之外，还提供了下列有用的其他功能：

build                      # 构造 PLFA
watch                      # 构造并架起 PLFA，监视文件变更并重新构造
test                       # 测试网页版是否有坏链、不合法的 HTML 等
test-epub                  # 测试 EPUB 电子书版是否符合 EPUB3 标准
clean                      # 清理 PLFA 构造
init                       # 设置 Git 钩子脚本（见下文）
update-contributors        # 从 GitHub 中拉取新贡献者信息至 contributors/
list                       # 列出所有构造功能

完整来说，Makefile 还提供了下列选项，但你可能不会需要用到：

legacy-versions            # 构造老版本的 PLFA
setup-install-bundler      # 安装 Ruby Bundler （‘legacy-versions’ 所需要）
setup-install-htmlproofer  # 安装 HTMLProofer （‘test’ 和 Git 钩子脚本所需要）
setup-check-fix-whitespace # 检查 fix-whitespace 是否已安装 （Git 钩子脚本所需要）
setup-check-epubcheck      # 检查 epubcheck 是否已安装 （EPUB 测试所需要）
setup-check-gem            # 检查 RubyGems 是否已安装
setup-check-npm            # 检查 Node 包管理器是否已安装
setup-check-stack          # 检查 Haskell 工具 Stack 是否已安装

本书的 EPUB 电子书版本会随着网站一起构造，因为网站上包括了电子书版本。

Git 钩子脚本

本源码库包含了几个 Git 钩子：

  1. fix-whitespace 程序用来检查错误的空格。

  2. 可运行的测试套件用来保证一切都能通过类型检查。

你可以运行 make init 来安装这些 Git 钩子。 你可以运行以下命令来安装 fix-whitespace：

stack install fix-whitespace

如果你想让 Stack 使用你系统中安装的 GHC，那么可以传入 --system-ghc 参数并选择对应的 stack-*.yaml 文件，就像在安装 Agda 时那样。

About

《编程语言基础：Agda 描述》，Programming Language Foundations in Agda 中文版

https://agda-zh.github.io/PLFA-zh/

License:Creative Commons Attribution 4.0 International

Languages

Language:HTML 88.2%Language:Agda 7.2%Language:TeX 3.4%Language:CSS 0.5%Language:Haskell 0.3%Language:SCSS 0.2%Language:Makefile 0.1%Language:Shell 0.1%Language:Lua 0.1%Language:Coq 0.0%Language:Ruby 0.0%Language:Emacs Lisp 0.0%