explore-lisp

explore-lisp

Dafu Chen qchen2015@hotmail.com

Github Repository

参考博客文章:

介绍

explore-lisp是一个Common Lisp工程,用于探索Common Lisp的文档和符号。

安装

前提条件,安装Sbcl和Quicklisp。

请参考:Common Lisp奇先生

  1. 下载源代码到quicklisp的local-projects目录下
    cd ~/quicklisp/local-projects
    git clone https://github.com/qchen-fdii-cardc/explore-lisp
    

利用Quicklisp加载工程。

(ql:quickload :explore-lisp)

如果不希望安装在quicklisp的local-projects目录下,还有两种办法:

  1. 在Quicklisp的local-projects目录下建立一个软链接,指向explore-lisp的源代码目录。
  2. 在clone的目录下运行下面的代码:

; Usage of the project
(require 'uiop)
(require 'asdf)

(push
  (uiop/pathname:merge-pathnames* "./explore-lisp/") asdf:*central-registry*)


(ql:quickload :explore-lisp)

使用

如本项目的文档所示,explore-lisp提供了一些函数,用于探索Common Lisp的文档和符号。

这个文档本身,就是利用这个explore-lisp生成的。

; Usage of the project
(require 'explore-lisp)
(el:export-all-external-symbols 'el :fn "docs.md") 

主要功能函数

函数参考

下面也给出每个函数使用的例子。

首先是dir函数,列出一个包的所有外部符号。

(el:dir 'cl)

这样就能大概知道一个包里面有哪些符号可供使用。其后就能够利用describe函数查看一个符号的详细信息。

(describe 'cl:mapcar)

或者,explore-lisp提供了函数describe-symbols,可以把帮助文档输出为一个字符串。

(el:describe-symbols 'cl)

类似于Matlab的lookfor函数,explore-lisp提供了search-symbols函数,可以搜索包中的符号。

(el:search-symbols 'cl "map")

这个时候只搜索符号名称,如果需要搜索符号的文档,可以使用search-symbols函数的命名参数doc-string

(el:search-symbols 'cl "map" :doc-string t)

最后,explore-lisp提供了export-all-external-symbols函数,可以把一个包的所有外部符号和文档输出到一个文件。

(el:export-all-external-symbols 'cl :fn "cl.md")

export-all-external-symbols-to-stream函数可以把一个包的所有外部符号和文档输出到一个流。

(with-open-file (s "cl.md" :direction :output)
  (el:export-all-external-symbols-to-stream 'cl s))

最近还增加一个函数,lookfor,可以搜索包中的符号,类似于Matlab的lookfor函数。

(el:lookfor "map")

会默认搜索所有安装的包,包含了文档和符号名称,最后打印出名称和一句话文档(如果有的话)。

当然也可以只搜索符号名称。额外提供两个参数,第一个是是否搜索文档的开关,第二个是是否打印的开关。

(el:lookfor "map" nil)

当然,默认返回的第一个参数是找到的符号的数量,第二返回值是所有符号的列表。

(nth-value 1 (el:lookfor "map"))

采用这样(values num lst)的输出形式,在REPL中,运行lookfor函数,就只输出符号的数量,而不会输出符号的列表。

这样,就能配合其他函数,输出需要的信息。

(el:format-descriptions (nth-value 1 (el:lookfor "sequence" nil nil)))

lookfor函数的第三个参数是一个关键字,:all表示搜索所有包,否则只搜索common-lisp包。

在实际的使用中,发现这么做才更加自然。

大概,常用的函数就是这么一些。

增加两个宏,help?,就是describe函数别名,如果(help 'help)或者(help '?),就会输出describe函数的文档。

Logs

MIT