This is the lib-helper Reference Manual, version 1.10.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 05:05:55 2024 GMT+0.
lib-helper/lib-helper.asdlib-helper/package.lisplib-helper/generics/convert.lisplib-helper/types/system.lisplib-helper/types/methods.lisplib-helper/types/origin-package.lisplib-helper/types/lib-hierarchy.lisplib-helper/types/lib-symbol.lisplib-helper/types/converters.lisplib-helper/known-libs.lisplib-helper/utils.lisplib-helper/packages-common.lisplib-helper/system-helpers.lisplib-helper/std-lib/std-defs.lisplib-helper/std-lib/packages-std.lisplib-helper/libs/lib-defs.lisplib-helper/libs/user-lib-defs.lisplib-helper/libs/packages-lib.lispThe main system appears first, followed by any subsystem dependency.
lib-helperReorganise existing symbols in standard and third party libs to common hierarchical packages.
Albus M Piroglu <mattapiroglu@gmail.com>
Albus M Piroglu <mattapiroglu@gmail.com>
MIT
# LIB-HELPER
## Motive
If you have looked at your screen bewildered, trying to remember a
function or an object name in Common-Lisp standard library, then this package
may help you. There are more than 970 of those functions and objects (i.e. symbols) and
I don’t think everybody can browse through them easily when they are listed
in CL package altogether.
In addition, there are thousands of third party libraries. How can one use
a number of them together without constantly checking their source code, help and
readme files all the time? There are different ways to organise knowledge and reach
it and categorising them is one of them, if not the most efficient.
Some other languages may be seen as having the advantage of organising their
standard library hierarchically, or at least with one level of grouping.
Having such a central group of packages to organise others (packages) might give us an
easy way to come up with a collection of de-facto standard library composed of
popular libraries.
In addition, this system gives you packages corresponding to classes and their related symbols and specialised methods under that package. This is similar to what you get with member & encapsulation based OOP-style code completion in other languages.
## Description
This is an organisation of popular functionalities in a central, easy-to-browse
set of packages. This library by itself doesn’t add any utility function to common-lisp,
instead it just reorganises the work of others in an easier to reach structure.
The taxonomy selection is mainly based on groups from clhs sections, cl-cookbook and some other common programming languages’ standard libraries.
Some symbols may be exported from multiple packages, when I think that
there’s strong overlap and that one might look for the same symbol in
different packages.
The goal of this library is to create a hierarchy of packages with the sole purpose of organising existing packages and symbols independently, thus without imposing anything on them. That’s why in summary all it does is import symbols from others and re-export them from suitable places in the hierarchy.
For this purpose, lib-helper creates its package hierarchy with names under LIB.* (note that these packages include CL standard symbols too).
Since CL itself puts all its standard library in a flat list, it can also benefit from such grouping. That’s why I kept a pure CL hierarchy of packages under the names STD.*
## Installation
### Quicklisp
(ql:quickload "lib-helper")
### ASDF
First, git clone this repo to your computer
> git clone https://github.com/albuspiroglu/cl-lib-helper.git
Then make asdf find the new system. One way is to create/edit a conf file in ~/.config/common-lisp/source-registry.conf.d/some.conf and add this line:
(:directory "path-to-cl-lib-helper-download/")
And on your REPL:
“‘
(asdf:clear-source-registry)
(asdf:load-system "lib-helper")
“‘
## Usage
A screen recording of example usage: https://youtu.be/NygQTvbkMjY
A typical usage might be with slime/sly loaded (or using your IDE’s completion drop-down), start typing "(lib." on repl and hit tab to get a list of packages starting with name lib., then shortlist and find what you’re looking for.
Or type "(lib:" and see the list of items in that group in a dropdown.
Libraries are arranged in a hierarchy. Child level packages are created as symbols starting with a dot in the parent level. This way, after choosing the completion for a child level, one can change the dot to a colon to check the lower level’s symbols, and keep going down the hierarchy until they reach a target. The way it works is:
Assume some symbols at a level is at:
lib.lvl1.lvl2:<symbols>
Then a dropdown at lib.lvl1: would give:
lib.lvl1:
.lvl2
*any other symbol in lvl1*
choosing lib.lvl1:.lvl2, then editing the line to get lib.lvl1.lvl2: will give the list of \*symbols\* that we’re looking for.
e.g. try to get to lib.str.comp:*
After finding what you were looking for, you can either use the symbol from the package you found, or use it directly from its original package. The primary purpose of this library is to let you find things, not to alter your coding convention (although using the package names of this library might improve readability - although this claim is not tested yet).
Speaking of finding, check the (lib:find-syms) function description below, it is quite powerful.
#### Classes as packages
With 2021-08-12 commit, we now have this interesting feature. If a package has a class defined in it, then there will be a corresponding package with that class name, and all the methods specialised to that class + slot accessors will be symbols under that package. This way, you can see all relevant methods in one place, instead of trying to guess or using clos functions to find the specialisations. A class symbol pointing to the sub package will be starting with double-dots ".." instead of single as is the case for sub packages.
e.g.
(lib.cont.lil.interface:
tab completion above will list lots of classes defined in interface package, all starting with .., so:
(lib.cont.lil.interface:..
will filter only the classes under interface. Then, choose the class \<any>, for example:
(lib.cont.lil.interface..<any>:
and you’ll see symbols specialised for that class.
Try to find your more favorite system / class as example.
#### Lazy system loading
Third party systems are not listed as system dependencies in .asd file, but instead dynamically loaded as requested. For example, alexandria is not a dependency, but their symbols are in the lib-defs.lisp, and they are interned with symbol names ending with a ~.
When you want to use, e.g. alexandria:cswitch, you should first find and call:
“‘
(lib.lang.flow:cswitch~)
“‘
Which will load the corresponding system, alexandria, then intern all the symbols of alexandria to their target packages in the hierarchy. Then you can call the previous command (or any other from the same system) without ~ at the end.
Btw, system loading is done by asdf, thus you should already have the corresponding system downloaded and asdf-reachable.
#### Name non-shadowing
If a symbol is exported from multiple systems/packages, then they are added to the symbols package list (in lib-defs.lisp) and for each package a symbol.N is created (except the first one is the symbol name).
### Utilities
#### (lib:apropos-lib sub-str), (std:apropos-lib sub-str)
Look for symbols containing sub-str in the lib hierarchy and
print the matching branches.
#### (lib:find-syms phrase), (std:find-syms phrase)
Given a number of words in the phrase (first word for the symbol, others for
description and package path, find the closest matches within the lib hierarchy.
phrase can be either one string with multiple words, or a list of expressions (cl-ppcre re expressions).
Match will be listed for:
(first phrase) contained in symbol name AND
(every (rest phrase)) contained in path or symbol description.
e.g.
(lib:find-syms "interface lil")
will list more results then:
(lib:find-syms "interface lil pure")
The way we extract the description of any symbol is:
"symbol-path-in-hierarchy : any description in any symbol namespace"
This means lib-helper will search for function description, variable description, class or struct or macro description all the same, and concat them to the description. This gives us a powerful way to do search (or I call it a better apropos). For example to find any symbol with the word "structure" in its descriptions:
(lib:find-syms ’(".*" "structure"))
or
(lib:find-syms ".* structure")
#### (lib:packages), (std:packages)
See the list of packages, printed with some grouping.
#### (lib:get-package-names), (std:get-package-names)
Get the list of package names under lib. or std.
#### (lib:delete-this-system), (std:delete-this-system)
Deletes all the LIB.* and STD.* packages and does an asdf:clear-system :lib-helper.
If you change lib-defs.lisp or std-defs.lisp and want to update your current lisp image, just do a:
(lib:delete-this-system)
(asdf:load-system :lib-helper)
## Implementations tested
Working for: sbcl2.1 / sbcl2.2, clisp 2.49, lispworks 7.1, abcl 1.8
## Extending / Hacking
### Disabling/removing a system from lib hierarchy
Edit known-libs.lisp, and find the let form that populates the \*system-table\*. If any of the system isn’t loaded on your lisp-image, change the t to a nil for that system. This will create symbols~ for that system in the hierarchy, but won’t try finding the corresponding system. If you don’t want any of the system symbols in the hierarchy, then comment-out / remove that system’s line there.
### Adding your local packages / libraries
If you want to add you own or favorite system in the hierarchy, you can use the helper function to generate the form you need. An example usage is in test/dev-help.lisp, where we call generate-system-symbols for two system and write the output to a file:
“‘
(with-open-file (f "temp-defs.lisp~" :direction :output :if-exists :supersede)
(generate-system-symbols "cl-ppcre" "LIB.STR"
’(("CL-PPCRE" "ppcre"))
f)))
“‘
Then you’ve got two options:
1. If you want to keep the changes for your own use, put the additions to user-lib-defs.lisp. This file is for local user extensions.
2. If you want to share the changes with a pull request, append the output to lib-defs.lisp, to variable \*lib-package-tree\*
## Contributing
The complete hierarchy is contained in a tree in either lib-defs.lisp (std + 3rd party) or std-defs.lisp (ansi symbols only). If you want to change / add libs, modifying these lists will be enough.
## TODO
- [ ] CLHS categorisation: Using the full symbol index page (1), for each symbol, find the sections that mention this symbol in sections pages (2), and form the library packages corresponding to the sections.
- Add(ing) well known asdf libraries to the lib.* categories (~~asdf-uiop~~, ~~alexandria~~, ~~ppcre~~, ~~iterate~~, containers, ~~closer-mop~~, bordeaux-threads, ~~lil~~, lparallel, osicat, cl-opengl, etc.).
- [ ] Add cl-containers. Since I already created some container branches, I should merge cl-containers into them. But then to reduce confusion, I can add ".clc" to the end of each category to separate the cl-containers bits. This way someone looking for hash-tables can use lib.cont.hash:, or lib.cont.hash.clc: .
- [ ]
#### [2021-08-01]
While working on cl-containers, I started realising a problem in design. This library is trying to categorise libraries into hierarchical packages, sometimes using library author’s package structure, sometimes using domain-categorised sections. Both ideas would be expected to converge but the difficulty of different authors standardising such a category is an unsolved problem. I think I’ll come up with some guidelines.
Here, the list of criteria while managing the hierarchy is roughly:
1. Keep the tree balanced, with number of subbranches around 3-5
2. Keep the number of symbols low, possibly < 30? Or instead minimise number of non-coherent symbols, where coherent symbols are syntactically similar (such as car, caar, cdr, cadr; or select-item, select-node, select-somethingelse).
3. DONE: ~~Generic methods can be cloned to different branches where each branch represents a class that implements those methods. This is helpful to organise object oriented design. We will end up having packages that correspond to classes with methods and members.~~
4. Mostly DONE: I can get symbols of a system with some hierarchy that contains class and struct separation and their methods: ** make this automatic - working on (generate-system-symbols) now.
- [ ] import module as / using namespace new_name !!!
I just realised that I can add these functions (I feel like there are already good alternatives, starting with uiop/defpackage import-reexport facility) to easily use a library branch within a package. But the improvement here is, we’ll import-reexport a whole tree of packages to a new base branch. So we can do this:
(in-package my-dev-package)
(import-package-as "LIB.CONT.SEQ.ACCESS" "SEQ")
(seq:extremum ’(1 2 3 4) #’<)
(import-package "LIB.CONT.LIL.PURE") ; to import immediate syms and packages
(queue:\<fifo-queue> ...)
(collection:conj ...)
## Improvement ideas
If you have ideas, I’ll be more than
happy to collaborate as time allows. One thing worth pursuing might be
hierarchical packages (as is seen in some implementations).
## History
### [2022-10-08]
* Some fixes to load cleanly with sbcl. Also the library is now on quicklisp.
* Facility to add user’s local definitions. Add them to user-lib-defs.lisp. Details in Hacking / Extending section above, in addition
to code comments in the same file.
### [2021-12-21]
Major code restructuring. Looking at the lib-helper.asd should make it possible to understand the complete project, or at least help with it. Classes improved & separated, with additional contextual separations.
Also tests are added.
### [2021-08-12]
Classes as packages.
### [2021-08-09]
For some packages, I had included only the symbols of a package if they originated from that package. Now the decision is to include all external symbols of a package instead. e.g. uiop:define-package’s :use-reexport, or a package manually exporting its imported symbols.
### [2021-08-07]
Added find-symbols and apropos-lib. This is becoming quite useful!
### [2021-08-01]
Add cl-containers. This library proves to be quite difficult to categorise, although it is organised quite well itself.
### [2021-06-27]
Turn the base code into a package.
## References
1. http://www.lispworks.com/documentation/lw50/CLHS/Front/X_AllSym.htm
2. http://www.lispworks.com/documentation/lw50/CLHS/Front/Contents.htm
# License
Copyright (c) [2021] [Albus M Piroglu]
Licensed under the MIT License.
1.10.1
cl-ppcre (system).
closer-mop (system).
alexandria (system).
iterate (system).
cl-containers (system).
package.lisp (file).
generics (module).
types (module).
known-libs.lisp (file).
utils.lisp (file).
packages-common.lisp (file).
system-helpers.lisp (file).
std-lib (module).
libs (module).
Modules are listed depth-first from the system components tree.
lib-helper/genericsGenerics are where the defgeneric forms for multiple types reside. Then the
specialisations, i.e. defmethods are defined for each related type, under types module.
package.lisp (file).
lib-helper (system).
convert.lisp (file).
lib-helper/typesClasses, structs, deftypes and their methods.
generics (module).
lib-helper (system).
system.lisp (file).
methods.lisp (file).
origin-package.lisp (file).
lib-hierarchy.lisp (file).
lib-symbol.lisp (file).
converters.lisp (file).
lib-helper/std-libpackages-common.lisp (file).
lib-helper (system).
std-defs.lisp (file).
packages-std.lisp (file).
lib-helper/libspackages-common.lisp (file).
lib-helper (system).
lib-defs.lisp (file).
user-lib-defs.lisp (file).
packages-lib.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
lib-helper/lib-helper.asdlib-helper/package.lisplib-helper/generics/convert.lisplib-helper/types/system.lisplib-helper/types/methods.lisplib-helper/types/origin-package.lisplib-helper/types/lib-hierarchy.lisplib-helper/types/lib-symbol.lisplib-helper/types/converters.lisplib-helper/known-libs.lisplib-helper/utils.lisplib-helper/packages-common.lisplib-helper/system-helpers.lisplib-helper/std-lib/std-defs.lisplib-helper/std-lib/packages-std.lisplib-helper/libs/lib-defs.lisplib-helper/libs/user-lib-defs.lisplib-helper/libs/packages-lib.lisplib-helper/lib-helper.asdlib-helper (system).
prepare-libs (function).
prepare-std-libs (function).
lib-helper/generics/convert.lispGeneric function for conversion between types
lib-helper/types/system.lispDefines load behaviour for systems.
types (module).
initialize-instance (method).
print-object (method).
activate-system (function).
asdf-system-loaded (function).
make-system (generic function).
maybe-load (function).
maybe-load-system-at-startup (function).
should-load-at-startup (function).
system (class).
system-import-symbols-at-startup (reader method).
(setf system-import-symbols-at-startup) (writer method).
system-loaded (method).
system-loaded (reader method).
(setf system-loaded) (writer method).
system-name (method).
system-name (reader method).
(setf system-name) (writer method).
with-system (macro).
lib-helper/types/methods.lispFind generic functions and their methods for organising classes.
types (module).
print-object (method).
print-object (method).
<gf-tree> (special variable).
<method-detail> (special variable).
<symbol> (special variable).
all-elements-are-method-details (function).
gf (reader method).
(setf gf) (writer method).
gf-tree (class).
gmethods (reader method).
(setf gmethods) (writer method).
list-of-method-details (type).
method-detail (class).
method-detailp (function).
method-obj (reader method).
(setf method-obj) (writer method).
specializers (reader method).
(setf specializers) (writer method).
lib-helper/types/origin-package.lispThe package where a symbol originated from
system.lisp (file).
types (module).
print-object (method).
containing-system (reader method).
(setf containing-system) (writer method).
make-origin-package (function).
origin-package (class).
origin-packagep (function).
pkg-name (reader method).
(setf pkg-name) (writer method).
lib-helper/types/lib-hierarchy.lispTypes and functions pertaining the lib-hierarchy
types (module).
print-object (method).
print-object (method).
setup-packages (function).
<lib-hierarchy-branch> (special variable).
<lib-hierarchy> (special variable).
<list> (special variable).
add-sub-packages (function).
branches (reader method).
(setf branches) (writer method).
define-sub-package-syms (function).
get-name (reader method).
(setf get-name) (writer method).
get-parent-name (function).
get-sub-packages (function).
lib-hierarchy (class).
lib-hierarchy-branch (class).
lib-symbols (reader method).
(setf lib-symbols) (writer method).
parent (reader method).
(setf parent) (writer method).
path (reader method).
(setf path) (writer method).
path-desc (reader method).
(setf path-desc) (writer method).
lib-helper/types/lib-symbol.lispA symbol that can exist in multiple source packages, mapped
to multiple symbols under one lib-hierarchy-branch
types (module).
print-object (method).
+doc-sys+ (special variable).
<lib-symbol> (special variable).
all-elements-are-lib-symbols (function).
all-elements-are-origin-packages (function).
all-elements-are-symbols (function).
find-lib-aux (function).
full-desc (reader method).
(setf full-desc) (writer method).
get-sym-desc (function).
get-target-sym-name (function).
import-and-get-symbols (function).
intern-later (function).
intern-now (function).
lazy-intern (function).
lib-symbol (class).
lib-symbolp (function).
list-of-lib-symbols (type).
list-of-origin-packages (type).
list-of-symbols (type).
match-with-symbol (function).
origin-packages (reader method).
(setf origin-packages) (writer method).
parent (reader method).
(setf parent) (writer method).
rename-import-syms (function).
set-full-desc (function).
sym-name (reader method).
(setf sym-name) (writer method).
syms (reader method).
(setf syms) (writer method).
lib-helper/types/converters.lispConverter methods definitions.
lib-hierarchy.lisp (file).
types (module).
lib-helper/known-libs.lispA collection of know systems and their load-at-startup status.
package.lisp (file).
lib-helper (system).
*hierarchies* (special variable).
*system-table* (special variable).
add-to-package-lists (function).
*lib-package-test* (special variable).
lib-helper/utils.lisppackage.lisp (file).
lib-helper (system).
mkstr (function).
lib-helper/packages-common.lispShared functionality between packages-*.lisp below
package.lisp (file).
utils.lisp (file).
lib-helper (system).
apropos-lib (function).
delete-system-aux (function).
find-syms (function).
get-package-names-aux (function).
packages-aux (function).
symbol-count (function).
delete-hierarchy (function).
delete-packages (function).
lib-helper/system-helpers.lispHelper functions to generate hierarchies for systems
package.lisp (file).
utils.lisp (file).
lib-helper (system).
generate-system-symbols (function).
*skipped-classes-in-check* (special variable).
filter-external-syms (function).
format-package-tree-syms (function).
get-class-methods (function).
get-class-methods-unique-names (function).
get-generic-functions (function).
get-package-external-symbols (function).
get-struct-externals (function).
get-symbol-node (function).
lib-helper/std-lib/std-defs.lispstd-lib (module).
*std-package-tree* (special variable).
lib-helper/std-lib/packages-std.lispstd-defs.lisp (file).
std-lib (module).
std.
apropos-lib (function).
delete-this-hierarchy (function).
delete-this-system (function).
find-syms (function).
get-package-names (function).
packages (function).
symbol-count (function).
lib-helper/libs/lib-defs.lisplibs (module).
*lib-package-tree* (special variable).
lib-helper/libs/user-lib-defs.lisplib-defs.lisp (file).
libs (module).
*user-package-tree* (special variable).
lib-helper/libs/packages-lib.lispuser-lib-defs.lisp (file).
libs (module).
lib.
apropos-lib (function).
delete-this-hierarchy (function).
delete-this-system (function).
find-syms (function).
get-package-names (function).
packages (function).
symbol-count (function).
Packages are listed by definition order.
libcommon-lisp.
apropos-lib (function).
delete-this-hierarchy (function).
delete-this-system (function).
find-syms (function).
get-package-names (function).
packages (function).
symbol-count (function).
lib~common-lisp.
*hierarchies* (special variable).
*lib-package-tree* (special variable).
*std-package-tree* (special variable).
*system-table* (special variable).
add-to-package-lists (function).
apropos-lib (function).
delete-system-aux (function).
find-syms (function).
generate-system-symbols (function).
get-package-names-aux (function).
packages-aux (function).
setup-packages (function).
symbol-count (function).
*lib-package-test* (special variable).
*skipped-classes-in-check* (special variable).
*user-package-tree* (special variable).
+doc-sys+ (special variable).
<gf-tree> (special variable).
<lib-hierarchy-branch> (special variable).
<lib-hierarchy> (special variable).
<lib-symbol> (special variable).
<list> (special variable).
<method-detail> (special variable).
<symbol> (special variable).
activate-system (function).
add-sub-packages (function).
all-elements-are-lib-symbols (function).
all-elements-are-method-details (function).
all-elements-are-origin-packages (function).
all-elements-are-symbols (function).
asdf-system-loaded (function).
branches (generic reader).
(setf branches) (generic writer).
containing-system (generic reader).
(setf containing-system) (generic writer).
convert (generic function).
define-sub-package-syms (function).
delete-hierarchy (function).
delete-packages (function).
filter-external-syms (function).
find-lib-aux (function).
format-package-tree-syms (function).
full-desc (generic reader).
(setf full-desc) (generic writer).
get-class-methods (function).
get-class-methods-unique-names (function).
get-generic-functions (function).
get-name (generic reader).
(setf get-name) (generic writer).
get-package-external-symbols (function).
get-parent-name (function).
get-struct-externals (function).
get-sub-packages (function).
get-sym-desc (function).
get-symbol-node (function).
get-target-sym-name (function).
gf (generic reader).
(setf gf) (generic writer).
gf-tree (class).
gmethods (generic reader).
(setf gmethods) (generic writer).
import-and-get-symbols (function).
intern-later (function).
intern-now (function).
lazy-intern (function).
lib-hierarchy (class).
lib-hierarchy-branch (class).
lib-symbol (class).
lib-symbolp (function).
lib-symbols (generic reader).
(setf lib-symbols) (generic writer).
list-of-lib-symbols (type).
list-of-method-details (type).
list-of-origin-packages (type).
list-of-symbols (type).
make-origin-package (function).
make-system (generic function).
match-with-symbol (function).
maybe-load (function).
maybe-load-system-at-startup (function).
method-detail (class).
method-detailp (function).
method-obj (generic reader).
(setf method-obj) (generic writer).
mkstr (function).
origin-package (class).
origin-packagep (function).
origin-packages (generic reader).
(setf origin-packages) (generic writer).
parent (generic reader).
(setf parent) (generic writer).
path (generic reader).
(setf path) (generic writer).
path-desc (generic reader).
(setf path-desc) (generic writer).
pkg-name (generic reader).
(setf pkg-name) (generic writer).
rename-import-syms (function).
set-full-desc (function).
should-load-at-startup (function).
specializers (generic reader).
(setf specializers) (generic writer).
sym-name (generic reader).
(setf sym-name) (generic writer).
syms (generic reader).
(setf syms) (generic writer).
system (class).
system-import-symbols-at-startup (generic reader).
(setf system-import-symbols-at-startup) (generic writer).
system-loaded (generic function).
(setf system-loaded) (generic writer).
system-name (generic function).
(setf system-name) (generic writer).
with-system (macro).
stdcommon-lisp.
apropos-lib (function).
delete-this-hierarchy (function).
delete-this-system (function).
find-syms (function).
get-package-names (function).
packages (function).
symbol-count (function).
lib-helper-asdasdf/interface.
common-lisp.
prepare-libs (function).
prepare-std-libs (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Names of each package in the hierarchy and their symbols.
Each package is a list, with:
first item: package name
second item: package description
third : a list of:
(symbol-name-to-export (original-package-name system-name) (opn2 sysname2) ..)
lib~.
Names of each package in the hierarchy and their symbols.
Each package is a list, with:
first item: package name
second item: package description
third : a list of:
(symbol-name-to-export
original-package-name)
lib~.
A hash table of {key:string val:system},
with meanings:
key: system-name,
val: system object
lib~.
Add the hierarchy to the *hierarchies*
lib~.
Look for symbols containing sub-str in the lib hierarchy and
print the matching branches.
print-results: if t (default), print the results instead of returning a list.
lib~.
Delete all packages and symbols defined by hierarchy lib:
lib.
Delete all packages and symbols defined by hierarchy std:
std.
Delete all packages defined by system lib-helper, and remove it from asdf buffer.
lib.
Delete all packages defined by system lib-helper, and remove it from asdf buffer.
std.
Find closest matches within std or lib hierarchy.
INPUTS:
phrase:
a number of words as one string (first word for the symbol, others for
description and package path)
OR
re-patterns as a list of strings in the phrase,
print-results: if t (default), print the results instead of returning a list.
OUTPUT: nil or list of results
Note: re-patterns use cl-ppcre.
EXAMPLES:
(find-syms "prin")
find symbols with prin in symbol name
(find-syms "prin io")
Different to previous example, this will do a further filtering by finding symbols that have prin in symbol name, and io in either the package-path name or its documentation.
(find-syms ’("prin" ".*\bio\b.*"))
Further limiting to previous, filter ones with only complete word io. But one might prefer a shorter and almost equally effective:
(find-syms "prin std.io")
if they are trying to limit with path name.
lib.
Find closest matches within std or lib hierarchy.
INPUTS:
phrase:
a number of words as one string (first word for the symbol, others for
description and package path)
OR
re-patterns as a list of strings in the phrase,
print-results: if t (default), print the results instead of returning a list.
OUTPUT: nil or list of results
Note: re-patterns use cl-ppcre.
EXAMPLES:
(find-syms "prin")
find symbols with prin in symbol name
(find-syms "prin io")
Different to previous example, this will do a further filtering by finding symbols that have prin in symbol name, and io in either the package-path name or its documentation.
(find-syms ’("prin" ".*\bio\b.*"))
Further limiting to previous, filter ones with only complete word io. But one might prefer a shorter and almost equally effective:
(find-syms "prin std.io")
if they are trying to limit with path name.
lib~.
Find closest matches within std or lib hierarchy.
INPUTS:
phrase:
a number of words as one string (first word for the symbol, others for
description and package path)
OR
re-patterns as a list of strings in the phrase,
print-results: if t (default), print the results instead of returning a list.
OUTPUT: nil or list of results
Note: re-patterns use cl-ppcre.
EXAMPLES:
(find-syms "prin")
find symbols with prin in symbol name
(find-syms "prin io")
Different to previous example, this will do a further filtering by finding symbols that have prin in symbol name, and io in either the package-path name or its documentation.
(find-syms ’("prin" ".*\bio\b.*"))
Further limiting to previous, filter ones with only complete word io. But one might prefer a shorter and almost equally effective:
(find-syms "prin std.io")
if they are trying to limit with path name.
std.
function maturity: 1
Generate a package tree corresponding to the system. Then the result can be
manually pasted into the lib-defs.lisp
Also creates sections for classes and their implemented methods.
sys-name: string, name of the asdf system
prefix : the package-tree section prefix for packages of the system to be imported from.
e.g. for containers package to be under lib.cont pass "LIB.CONT".
packages: list of packages to import from and to ("package-from" "package-to".
A system may define many packages, but the
the user should manually choose a subset that the symbols will be imported
from, and pass them here.
example calls:
(with-open-file (f "temp-defs.lisp~" :direction :output :if-exists :supersede)
(generate-system-symbols "lil" "LIB.CONT"
’(("LIL/CORE/ALL" "LIL.CORE")
("LIL/INTERFACE/ALL" "LIL.INTERFACE"))
f))
(with-open-file (f "temp-defs.lisp~" :direction :output :if-exists :supersede)
(generate-system-symbols "cl-ppcre" "LIB.STR"
’(("CL-PPCRE" "ppcre"))
f))
an example return output:
("LIB.CONT.LIL/PURE/HASH-TABLE" "Package: LIL/PURE/HASH-TABLE"
(("<HASH-TABLE>" ("lil" "LIL/PURE/HASH-TABLE"))
("HASHMAP-INTERFACE" ("lil" "LIL/PURE/HASH-TABLE"))
("BUCKETMAP-INTERFACE" ("lil" "LIL/PURE/HASH-TABLE"))
...
))
("LIB.CONT.LIL.INTERFACE.ORDER" "Package: LIL/INTERFACE/ORDER"
(("<ORDER>" ("lil" "LIL/INTERFACE/ORDER"))
("<ORDER-FROM-LESSP>" ("lil" "LIL/INTERFACE/ORDER"))
("<LESSP>" ("lil" "LIL/INTERFACE/ORDER"))
...
))
lib~.
Return a list of package names in the package-tree.
lib~.
Print package names in first hierachical categorization.
lib~.
Creates and defines packages in package-tree.
lib~.
Return the count of unique symbols within the tree.
lib~.
lib-hierarchy-branch) stream) ¶origin-package) stream) ¶lib-symbol) stream) ¶lib-hierarchy) stream) ¶method-detail) stream) ¶Dev helper for testing internal functions.
lib~.
Names of each package in the hierarchy and their symbols.
Each package is a list, with:
first item: package name
second item: package description
third : a list of:
(symbol-name-to-export (original-package-name system-name) (opn2 sysname2) ..)
lib~.
Doc system functions and corresponding types for documentation lookup in multiple namespaces of a symbol.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
An empty object to be passed to generic functions as an interface. Idea partially from lil library.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
An empty object to be passed to generic functions as an interface.
lib~.
asdf:load the system and for every symbol of it
import-export them in the tree.
This function is not called during lib-helper load, but is attached to the library branches for on-demand use.
lib~.
Find package names that are sub-packages of h-branch, and make them
symbols of .package-name, i.e. a dot prepended, and intern in the parent package.
e.g.
a package path1.path2 can have symbols interned for it such as:
path1.path2:.path2.1
path1.path2:.path2.2
path1.path2:.path2.3
lib~.
Define all symbols of the existing target branch package p, including the listed symbols & symbols for each .sub-package
INPUTS:
p: lib-hierarchy-branch
OUTPUTS: nil
lib~.
Search in package-tree for symbols meeting search-closure predicate.
print-results: if t, print results, don’t return, otherwise return a list of results.
lib~.
Return all methods in the current lisp image which act on class type or its parent types, i.e. have parameters of type class or any of class’ parents.
lib~.
Return all generic functions defined in the current lisp image as list of gf-tree.
lib~.
Return the symbols that are exported from the package, i.e. external.
lib~.
Given lib.lvl1.lvl2 shaped package name, return lib.lvl1; or lib.lvl1.lvl2..class1, return lib.lvl1.lvl2
lib~.
Given a struct name, check for each struct name and return the package-external ones as a list.
lib~.
pkg-name: string
Returns a list of paths that are sub packages of pkg-name.
lib~.
Given a symbol, return its corresponding description. If there are descriptions in more than one namespace (function, variable, class, etc.), combine the results.
lib~.
Name of the symbol to create depends on how many systems / packages are
exporting the symbol. If more than one, than the first one is the sym-name,
and subsequent ones are appended a dot + number starting from 1. If the system
is not loaded, then a tilde will be appended to the name.
index: 0 based, which index system is the symbol imported from in a symbol list
of (sym-name (sys0 pkg0) (sys1 pkg1) ..)
e.g. from a list of: ("CAR" (NIL "CL") ("my-system" "MY-PACKAGE"))
we want the symbol for my-system, thus call
(get-target-sym-name "CAR" 1 :loaded nil)
to get "CAR.1~"
lib~.
For one target symbol, return a list of symbols which are either from a system-package, or a list of sym-nameN{~}* where ~ is optional. See Lazy interning in the top comment of *lib-package-tree* for details.
lib~.
Create a symbol with a ~ at the end, bound to a function to do:
load the associated system (via asdf - not quicklisp, so everything is offline),
create the expected symbol without the ~ this time, pointing to the actual object of concern and
delete the symbol with the ~ at the end.
lib~.
Either shadowing-import or create a symbol and link to sym.
lib~.
See Lazy interning in the
top comment of *lib-package-tree* for details.
Intern a symbol, and return that symbol name (package relative).
lib~.
Return true if first expression in phrase-regexes matches the symbol name AND all the rest in phrase-regexes match the symbol’s full-description (which includes hierarchy path along with all symbol-namespace descriptions, i.e. function description + variable description + class + method-combination etc.).
lib~.
asdf load the system if necessary. orig-pkg: is of type origin-package
lib~.
For the symbols in branch that belong to orig-pkg,
unintern the symbols corresponding to that package, which will be named
as a-symbol{.N}~, and shadowing-import every the a-symbol name from from-pkg
to to-pkg in branch.
orig-pkg: is of type origin-package
branch: a lib-hierarchy-branch
from-pkg: a common-lisp package designator
lib~.
Return t if sys-name should be loaded. This depends on load-at-startup and (already) loaded values.
lib~.
lib~.
lib-hierarchy)) ¶automatically generated reader method
lib~.
lib-hierarchy)) ¶automatically generated writer method
lib~.
origin-package)) ¶origin-package)) ¶The system that contains this package
Convert obj from type origin to type destination.
lib~.
gf-tree) (origin symbol) g &key &allow-other-keys) ¶Conversion: symbol -> gf-tree
lib-symbol) (origin list) obj &key parent &allow-other-keys) ¶Conversion: list -> lib-symbol
lib-hierarchy-branch) (origin list) obj &key parent &allow-other-keys) ¶Conversion: list -> lib-hierarchy-branch
lib-hierarchy) (origin list) obj &key &allow-other-keys) ¶Conversion: list -> lib-hierarchy
lib~.
lib-symbol)) ¶lib-symbol)) ¶Hierarchy path + all namespace descriptions of the symbol combined.
lib~.
lib-hierarchy)) ¶automatically generated reader method
name.
lib~.
lib-hierarchy)) ¶automatically generated writer method
name.
lib~.
lib-hierarchy-branch)) ¶automatically generated reader method
lib~.
lib-hierarchy-branch)) ¶automatically generated writer method
import-symbols-at-startup:
(t: if system already loaded in the lisp image and
you want to import/export its symbols,
nil: if you don’t want to import the system’s symbols yet, regardless of whether system is loaded. Each exported symbol of the system will have a function with same name + ~ and when called will asdf:load-system the system and make all symbols of the system available.
lib~.
string) &key import-symbols-at-startup) ¶Given a system name and a keyword for import-symbols-at-startup, make an instance of system.
list) &key) ¶Given a list of (system-name import-symbols-at-startup), make an instance of system.
lib~.
method-detail)) ¶method-detail)) ¶The method object.
lib~.
lib-symbol)) ¶automatically generated reader method
lib~.
lib-symbol)) ¶automatically generated writer method
lib~.
lib-symbol)) ¶automatically generated reader method
lib-hierarchy-branch)) ¶A link to the package-tree of this branch (this will be either std-tree or lib-tree).
lib~.
lib-symbol)) ¶automatically generated writer method
lib-hierarchy-branch)) ¶A link to the package-tree of this branch (this will be either std-tree or lib-tree).
lib~.
lib-hierarchy-branch)) ¶lib-hierarchy-branch)) ¶Path name for the branch. This corresponds to a package, or
rather a package is created that corresponds to every branch.
path.
lib~.
lib-hierarchy-branch)) ¶lib-hierarchy-branch)) ¶Description of the path or package.
lib~.
origin-package)) ¶automatically generated reader method
lib~.
origin-package)) ¶automatically generated writer method
lib~.
method-detail)) ¶method-detail)) ¶Method lambda list.
lib~.
lib-symbol)) ¶lib-symbol)) ¶The symbol name of the source symbol
lib~.
lib-symbol)) ¶lib-symbol)) ¶The actual symbols, corresponding to sym-name, one for each
origin-packages.
First one is named the same as sym-name, subsequent ones appended
an increasing number, from 1. If lazy-interned, then appended ~ or
{.n}~
syms.
A tree for a generic function including its methods and their lambda lists.
A library hierarchy (a.k.a. package-tree) is defined with this type. It is essentially a list.
A branch of a lib-hierarchy / package tree.
A branch is e.g.:
("LIB.CONT.LIST.CREATE" "List creation"
(("CIRCULAR-LIST" ("alexandria" "ALEXANDRIA")) ; symbols list start here
("CONS" (NIL "CL"))
("COPY-LIST" (NIL "CL"))
...
lib~.
Path name for the branch. This corresponds to a package, or
rather a package is created that corresponds to every branch.
string
:path
path.
A link to the package-tree of this branch (this will be either std-tree or lib-tree).
lib~::lib-hierarchy
:parent
Description of the path or package.
string
:path-desc
lib~::list-of-lib-symbols
:lib-symbols
When there are multiple sys-pkg, multiple symbols will be created in the branch, first one with the symbol’s name, subsequent ones having a {.N}~, N in (1,2..). Also there’s a lazy interning process. If a system is not loaded, then its symbols will not be imported, but rather a symbol of the same name + ~ appended, and tied to a closure that’ll load the system then import all symbols from the system to their branches.
lib~.
The symbol name of the source symbol
string
:sym-name
lib~::list-of-origin-packages
:origin-packages
lib~::lib-hierarchy-branch
:parent
Hierarchy path + all namespace descriptions of the symbol combined.
string
:full-desc
Details of a method.
Defines where a package comes from. Used by new symbols interned in the hierarchy so that we can point to the actual place.
Objects of this class defines an asdf system and how it will be regarded during and after lib-helper load.
| Jump to: | (
A B C D F G I L M O P R S W |
|---|
| Jump to: | (
A B C D F G I L M O P R S W |
|---|
| Jump to: | *
+
<
B F G I L M N O P S |
|---|
| Jump to: | *
+
<
B F G I L M N O P S |
|---|
| Jump to: | C F G K L M O P S T U |
|---|
| Jump to: | C F G K L M O P S T U |
|---|