2p-parser-core 中文文档教程

Question

2P in Kotlin

一些快速链接：

• GitLab Repository (the one used by developers)
• GitHub Repository (where JVM releases are hosted)
• NPM Repository (where JS releases are hosted)
• Maven Repository (where all releases are hosted)
• Documentation

Intro

tuProlog（以后称为 2P）是一个多范式 用 Java 编写的逻辑编程框架。

2P-Kt 是 2P 的基于 Kotlin 的多平台重启。 它旨在成为符号人工智能（AI）的开放生态系统。 出于这个原因，2P-Kt 由许多递增的相互依赖的模块组成，旨在支持符号化 以可扩展和灵活的方式进行操作和推理。

下图提供了有关模块及其依赖关系的完整概述：

如项目图所示，2P-Kt目前侧重于通过逻辑编程支持知识表示和自动推理， by featuring：

• 逻辑词条表示模块core，

• 逻辑统一表示模块unify，

• 内存索引和逻辑理论存储模块，以及其他类型的逻辑子句集合，即 theory，

• 一个提供逻辑查询的 ISO Prolog 解析的模块，即 solve，有两个实现 （即 solve-classic 和 solve-streams），

• 许多模块（即许多 dsl-* 模块）支持 Prolog-像，领域特定语言（DSL） 旨在桥接逻辑编程与 Kotlin 面向对象 \& 功能环境，

• 两个解析模块：一个针对术语解析，即parser-core，另一个针对理论解析， 即 parser-theory，

• 两个与序列化相关的模块：一个旨在（反）序列化术语和从句，即 serialize-core，以及 其他针对（反）序列化术语理论，即 serialize-theory，

• 一个通过命令行界面使用 Prolog 的模块，即 repl，

• 一个通过命令行界面使用 Prolog 的模块图形用户界面 (GUI)，即 ide。

2P-Kt 的模块化、不拘一格的架构旨在支持和鼓励扩展到 除 Prolog 之外的其他类型的符号 AI 系统——例如 ASP、tabled-Prolog、Problog 等。

此外，2P-Kt 的开发是纯、多平台 科特林项目。 这带来了两个直接的优势：

1. it virtually supports several platforms, there including JVM, JS, Android, and Native (even if, currently, only JVM, JS and Android are supported),
2. it consists of a very minimal and lightweight library, only leveraging on the Kotlin common library, as it cannot commit to any particular platform standard library.

Users

2P-Kt 既可以用作命令行程序，也可以用作 Kotlin、JVM、Android 或 JS 库。

2P-Kt 可执行文件目前可在 发布部分 下载 GitHub 存储库。

适用于 JVM、Android 或 Kotlin 用户的 2P-Kt 模块目前可供导入 在 Maven Central 上，在 it.unibo.tuprolog 下组 ID（不是 与包含旧的基于 Java 的实现的 it.unibo.alice.tuprolog 混淆）。 同样的模块也可以通过 ad-hoc Maven 存储库获得， 由 Bintray 托管。

适用于 JS 用户的 2P-Kt 模块可在 @tuprolog 组织。

End users

Graphical User Interface

如果您的 Prolog 解释器需要 GUI，您可以依赖 2P-Kt IDE，它位于 GitHub 存储库。

2P-Kt 最新版本的页面公开了一些资产 . 在那里，名为：

2p-ide-VERSION-redist.jar

的是包含基于 2P-Kt 的 Prolog 解释器的独立可执行 Jar（VERSION 可能因 实际发布版本）。

下载 2p-ide-VERSION-redist.jar 后，您只需运行以下命令即可启动它：

java -jar 2p-ide-VERSION-redist.jar

但是，如果您已在系统上正确配置 JVM，只需加倍 -点击 前面提到的 JAR 来启动 IDE。 在任何情况下，运行 JAR 应该会出现以下窗口：

在那里，可以根据当前打开的理论文件查询 2P-Kt Prolog 解释器，这当然可以是 通过按 File 然后按 Open... 从用户的文件系统加载。

要发出查询，用户必须将其写在应用程序中心的查询文本字段中。 通过在光标位于查询文本字段上时按 Enter 或单击 > 按钮，用户可以开始新的解决过程，旨在解决问题提供查询。 可以通过反复单击 > 来探索更多解决方案。 还可以通过单击 >> 按钮一次计算所有未探索的解决方案。

要执行新的查询，用户可以：

• write the new query in the query text field, and then press Enter, or
• click on the R (Reset) button, write the new query in the query text field, and then press >.

最后，用户可以利用 IDE 底部的许多选项卡检查求解器的当前状态。 在那里，

• the Solutions tab is aimed at showing the Prolog interpreter's answers to the user's queries;
• the Stdin tab is aimed at letting the user provide some text the Prolog interpreter's standard input stream;
• the Stdout tab is aimed at showing the Prolog interpreter's standard output stream;
• the Stderr tab is aimed at showing the Prolog interpreter's standard error stream;
• the Warnings tab is aimed at showing any warning possibly generated by the Prolog interpreter while computing;
• the Operators tab is aimed at showing the current content Prolog interpreter's operator table;
• the Flags tab is aimed showing the actual values of all the flags currently defined with the Prolog interpreter;
• the Libraries tab is aimed at letting the user inspect the currently loaded libraries and the predicates, operators, and functions they import;
• the Static (resp. Dynamic) KB tab is aimed at letting the user inspect the current content of the Prolog interpreter's static (resp. dynamic) knowledge base.

在计算出某些查询的解决方案后，这些选项卡中的任何一个都可能会自动更新。 每当某种内容更改wrt时，标签的先前内容，星号都会靠近标签名称，以通知该选项卡中的更新。

Command Line Interface

如果你只需要一个命令行 Prolog 解释器，你可以依赖 2P-Kt REPL，它在 发布部分这 GitHub 存储库。

2P-Kt 最新版本的页面公开了一些资产 . 在那里，名为：

2p-repl-VERSION-redist.jar

的是包含基于 2P-Kt 的 Prolog 解释器的独立可执行 Jar（VERSION 可能因 实际发布版本）。

下载 2p-repl-VERSION-redist.jar 后，您只需运行以下命令即可启动它：

java -jar 2p-repl-VERSION-redist.jar

这应该会启动一个接受 Prolog 查询的交互式读取-评估-打印循环。 正常输出应如下所示：

# 2P-Kt version LAST_VERSION_HERE

?- <write your dot-terminated Prolog query here>.

支持其他选项或执行模式。 可以通过程序帮助探索它们，可以通过运行显示：

java -jar 2p-repl-VERSION-redist.jar --help

这应该显示类似于以下的消息：

Usage: java -jar 2p-repl.jar [OPTIONS] COMMAND [ARGS]...

  Start a Prolog Read-Eval-Print loop

Options:
  -T, --theory TEXT  Path of theory file to be loaded
  -t, --timeout INT  Maximum amount of time for computing a solution (default:
                     1000 ms)
  -h, --help         Show this message and exit

Commands:
  solve  Compute a particular query and then terminate

Gradle users

导入名为 2P_MODULE 的 2P-Kt 模块（版本 2P_VERSION< /code>) 到你基于 Kotlin 的项目中，利用 Gradle， 您只需要在 build.gradle(.kts) 文件中声明相应的依赖项：

// assumes Gradle's Kotlin DSL
dependencies {
    implementation("it.unibo.tuprolog", "2P_MODULE", "2P_VERSION")
}

这样，2P_MODULE的依赖就应该自动导入了。

上面的步骤要求您告诉 Gradle 使用 Maven Central 或我们的 Bintray 存储库（或两者）作为源 用于依赖项查找。 您可以按如下方式进行：

// assumes Gradle's Kotlin DSL
repositories {
    mavenCentral()
    maven("https://dl.bintray.com/pika-lab/tuprolog/")
}

JVM-only projects with Gradle

如果您的项目仅针对 JVM 平台，请记住将 -jvm 后缀添加到 2P_MODULE：

// assumes Gradle's Kotlin DSL
dependencies {
    implementation("it.unibo.tuprolog", "2P_MODULE-jvm", "2P_VERSION")
}

Maven users

导入名为 的 2P-Kt 模块>2P_MODULE（版本 2P_VERSION）到您利用 Maven 的基于 Kotlin 的项目中， 您只需要在 pom.xml 文件中声明相应的依赖项：

<dependency>
    <groupId>it.unibo.tuprolog</groupId>
    <artifactId>2P_MODULE</artifactId>
    <version>2P_VERSION</version>
</dependency>

这样，2P_MODULE的依赖就应该自动导入了。

上面的步骤要求您告诉 Maven 使用 Maven Central 或我们的 Bintray 存储库（或两者）作为源 用于依赖项查找。 您可以按如下方式进行：

<repositories>
    <repository>
        <id>bintray-2p-repo</id>
        <url>https://dl.bintray.com/pika-lab/tuprolog/</url>
    </repository>
</repositories>

JVM-only projects with Maven

如果您的项目仅针对 JVM 平台，请记住将 -jvm 后缀添加到 2P_MODULE：

<dependency>
    <groupId>it.unibo.tuprolog</groupId>
    <artifactId>2P_MODULE-jvm</artifactId>
    <version>2P_VERSION</version>
</dependency>

NPM users (JavaScript-only projects)

2P-Kt 软件可作为 JavaScript 使用库以及 NPM 上的 @tuprolog 组织。 要将 2P_MODULE 导入到您的 package.json 中，按如下方式声明您的依赖项就足够了：

{
  "dependencies": {
    "@tuprolog/2P_MODULE": "^2P_MODULE_VERSION"
  }
}

请注意 2P_MODULE 的 JS 依赖项应该是自动导入。

Developers

使用 2P-Kt 代码库需要在您的系统上安装和正确配置许多工具：

• JDK 12+ (please ensure the JAVA_HOME environment variable is properly) configured
• Kotlin 1.3.72+
• Gradle 6.4+ (please ensure the GRADLE_HOME environment variable is properly configured)
• Git 2.20+

Develop 2P-Kt with IntelliJ Idea

要参与 2P-Kt 的开发，我们建议 IntelliJ Idea 集成开发环境。 免费的社区 版本就可以了。

Recommended configuration

您将需要用于 IntelliJ Idea 的 Kotlin 插件。 这通常是在 Idea 的第一个安装向导中安装的。 但是，可以通过 IDE 的插件设置对话框轻松地延迟安装此类插件。 要打开此类对话框，请使用 Ctrl+Shift+A，然后搜索“插件”

Importing the project

1. ，使用 < 将此存储库克隆到您喜欢的文件夹中code>git clone 适当

2. 打开IntellJ Idea。 如果项目自动打开，请选择“关闭项目”。 您应该在 IntelliJ IDEA 的欢迎屏幕上，其外观类似于此图像：

3. 选择“导入项目”

4. 导航您的文件系统并找到您所在的文件夹克隆了存储库。 不要选择它。 打开文件夹，您应该会找到一个小写的 2p-in-kotlin 文件夹。 这是正确的项目文件夹，由 git 创建，以防您在没有指定不同文件夹名称的情况下进行克隆。 选择正确的文件夹后，单击确定

5. 选择“从外部模型导入项目”

6. 确保选择“Gradle”作为外部模型工具

7. 单击完成

8. 如果提示覆盖任何.idea 文件，尝试回答No。 有可能IntelliJ拒绝继续，此时再次点击Finish，然后选择Yes

9. 可能会出现“IntelliJ IDEA found a Gradle build script”的对话框，这样case answer Import Gradle Project

10. 等待IDE从Gradle中导入工程。 由于依赖项的数量，该过程可能需要几分钟时间。 如果同步失败，请确保正确配置了 IDE 的 Gradle：

11. 在“设置 -> 构建、执行、部署 -> 构建工具> Gradle'，对于选项'Use Gradle from'，选择'gradle-wrapper.properties file'。 还建议启用自动导入

Developing the project

欢迎对该项目的贡献。 只是一些规则：

• 我们使用 git flow，因此如果您编写新功能，请在单独的 feature/< /code> branch

• 我们建议分叉项目，开发你的东西，然后直接从 Web 界面通过拉取请求回馈

• 。经常提交。 不要通过添加或改变整个世界的单个巨大提交来抛出拉取请求。 将其拆分为多个提交并经常请求合并到主线

• 与 develop 分支保持同步：经常从 develop 拉取（如果构建通过），这样你就不会与主要开发路线偏离太多

• 不要引入低质量或未经测试的代码。 合并请求将在合并前进行审查。

Building the project

在开发的时候，可以依赖IntelliJ来构建项目，一般都会做得很好。 如果你想生成工件，你可以依赖 Gradle。 只需将终端指向项目的根和问题，

./gradlew build

这将触发工件的创建、测试的执行、文档和项目报告的生成。

Versioning

2P 项目利用语义版本控制（SemVer，此后）。

特别是，SemVer 由当前的 Gradle 配置强制执行，该配置具有 DanySK 的 Git 敏感的 SemVer Gradle 插件。 这意味着在这个项目中严格禁止创建标签不是有效 SemVar 字符串的标签。

请注意，2P 项目仍处于初始开发阶段——正如其版本字符串中等于 0 的主要编号所证明的那样。 根据 SemVer 的说法，这意味着任何事情都可能随时发生变化，因为公共 API 不应该被认为是稳定的。

Issue tracking

如果您在使用或开发 2P 时遇到问题，我们鼓励您通过项目 "Issues 提出问题GitLab 上的“部分。