From 4f68b87962e1f5ce8a7f19a68b2354126d5ab278 Mon Sep 17 00:00:00 2001 From: Jingtao Xu Date: Wed, 27 May 2020 17:18:52 +0800 Subject: [PATCH] add document for ASDF package inferred system. --- literate-lisp.org | 8 ++++---- readme.org | 42 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/literate-lisp.org b/literate-lisp.org index 36bfff3..1911655 100644 --- a/literate-lisp.org +++ b/literate-lisp.org @@ -120,7 +120,7 @@ read them or not should define, and it has three meanings: It means that current code block should ignore by lisp reader. - test \\ It means that current code block should load when feature ~test~ or ~literate-test~ exist. - The feature ~literate-test~ is kept just for a compatiblity for previous releases of ~literate-lisp~. + The feature ~literate-test~ is kept just for a compatibility for previous releases of ~literate-lisp~. - other feature keyword registered in global variable ~*features*~ \\ So you can take advantage of ~*features*~ to load your codes by various purposes. #+BEGIN_SRC lisp @@ -159,7 +159,7 @@ Additionally, we will ignore space characters in the beginning of line, let's fi finally (return i))) #+END_SRC -the reader syntax is simple, ignore all lines until meet a ~#+begin_src lisp~ and header argument ~load~ is true. +The reader syntax is simple by ignoring all lines until meet a ~#+begin_src lisp~ and header argument ~load~ is true. #+BEGIN_SRC lisp (defvar org-lisp-begin-src-id "#+begin_src lisp") (defun sharp-space (stream a b) @@ -254,7 +254,7 @@ We will install the reader syntax globally if the feature ~literate-global~ pres #+literate-global(install-globally) #+END_SRC -Otherwise we will limit the scope of the the new reader syntax in a specified code body, +Otherwise, we will limit the scope of the new reader syntax in a specified code body, by installing it before a code body and uninstalling it after this code body. This will respect global modifications to the readtable in loaded source files. #+BEGIN_SRC lisp @@ -364,7 +364,7 @@ But we have to add our literate syntax in an parent method, here we choose the m (call-next-method))) #+END_SRC -So to use org source files in an package inferred syste, we can write a ASD definition like this: +So to use org source files in a package inferred system, we can write an ASD definition like this: #+BEGIN_SRC lisp :load no (asdf:defsystem literate-libraries :serial t diff --git a/readme.org b/readme.org index 2c9bed7..0a22cab 100644 --- a/readme.org +++ b/readme.org @@ -15,6 +15,9 @@ - [[#a-new-code-block-header-argument-load][a new code block header argument ~load~]] - [[#how-to-debug-org-file-in-lispworks-ide][How to debug org file in LispWorks IDE]] - [[#how-to-write-user-initialization-file-with-literate-programming-style][How to write user initialization file with literate programming style]] + - [[#how-to-include-org-codes-when-using-asdf-package-inferred-system-extension][how to include org codes when using ASDF package-inferred-system extension]] +- [[#create-a-package-for-this-package-inferred-system][Create a package for this package inferred system]] +- [[#implementation][implementation]] - [[#packages-written-by-literate-lisp][packages written by literate-lisp]] - [[#a-demo-literate-application][A demo literate application]] @@ -41,7 +44,7 @@ This library contains the following files: - [[./puzzle.org]] \\ This file contains a puzzle solver to show how to do literate lisp in an org file. - [[./.github/workflows/continuous-integration.yml][continuous-integration.yml]] \\ - The config file used by Web service [[https://github.com/jingtaozf/literate-lisp/actions][github actions]] to test this library. + The config file used by Web service [[https://github.com/jingtaozf/literate-lisp/actions][GitHub actions]] to test this library. - [[./literate-lisp.asd]] \\ The ASDF definition for literate-lisp project. - [[./literate-demo.asd]] \\ @@ -88,6 +91,43 @@ For example, you can put the following codes in file [[http://www.sbcl.org/manua #+END_SRC I find it useful for various Lisp vendors so all initialization codes for them can be in just one file. +** how to include org codes when using ASDF package-inferred-system extension +The [[https://common-lisp.net/project/asdf/asdf.html#The-package_002dinferred_002dsystem-extension][ASDF package-inferred-system extension]] is wonderful, in which each file is its own system, +and dependencies are deduced from the defpackage form or its variant, uiop:define-package. +You can also use literate-lisp to make a package inferred system by writing an ASD definition like this: +#+BEGIN_SRC lisp :load no +(asdf:defsystem literate-libraries + :serial t + :defsystem-depends-on (:literate-lisp) + :default-component-class :org + :class :package-inferred-system) +#+END_SRC +Here *:class :package-inferred-system* enables the package-inferred-system extension, and *:default-component-class :org* means +that ASDF will look for all org files to find out a system and load it. + +For example, you can create an org file in the same directory of above ASD definition file named as *utilities.org* and +contains the following codes +#+begin_example +# -*- encoding:utf-8 Mode: POLY-ORG; -*- --- +* Create a package for this package inferred system +,#+BEGIN_SRC lisp +(defpackage literate-libraries/utilities + (:use :cl) + (:import-from :flexi-streams :octet :make-flexi-stream) + (:import-from :log4cl :log-config) + (:documentation "a utility module.")) +,#+END_SRC +* implementation +... ... +#+end_example +After loading the above ASD definition file, you can load system *literate-libraries/utilities* in your REPL. +#+BEGIN_SRC lisp :load no +(load "/some/path/literate-libraries.asd") +(ql:quickload :literate-libraries/utilities) +#+END_SRC + +Please upgrade to ASDF 3.3.4.5 or later, it is not supported in earlier ASDF versions. + ** packages written by literate-lisp - [[https://github.com/jingtaozf/s-graphviz][s-graphviz]] an S-expression presentation of GraphViz DOT Language ** A demo literate application