参考博客文章:
explore-lisp是一个Common Lisp工程,用于探索Common Lisp的文档和符号。
前提条件,安装Sbcl和Quicklisp。
请参考:Common Lisp奇先生。
cd ~/quicklisp/local-projects
git clone https://github.com/qchen-fdii-cardc/explore-lisp
利用Quicklisp加载工程。
(ql:quickload :explore-lisp)
如果不希望安装在quicklisp的local-projects目录下,还有两种办法:
; 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
函数的文档。
help
和?
。lookfor
函数的输入参数,当输入默认参数时,只在common-lisp
包中搜索,设为:all
时,搜索所有包,更新函数文档和README.md, 重新生成文档。lookfor
函数,可以搜索包中的符号,类似于Matlab的lookfor
函数。export-all-external-symbols-to-stream
函数文档,重写README.md
。
MIT