https://github.com/mmontone/mutils
A collection of Common Lisp modules
https://github.com/mmontone/mutils
common-lisp lisp tools utilities
Last synced: 3 months ago
JSON representation
A collection of Common Lisp modules
- Host: GitHub
- URL: https://github.com/mmontone/mutils
- Owner: mmontone
- Created: 2023-07-20T14:58:59.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-10-24T13:24:14.000Z (7 months ago)
- Last Synced: 2024-10-25T15:49:43.560Z (7 months ago)
- Topics: common-lisp, lisp, tools, utilities
- Language: Common Lisp
- Homepage:
- Size: 202 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.base.md
Awesome Lists containing this project
README
# MUTILS
A collection of Common Lisp utilities provided as modules.
The modules provided are small enough to fit in a single file and Common Lisp package, and an ASDF system definition may not be justified for them.
## Usage
In your ASDF system, `depend-on` `:mutils`, and then use `:require` to pick the modules to load.
Example:
```lisp
(asdf:defsystem :mutils-example
:depends-on (:mutils
(:require :lisp-critic-warnings)
(:require :auto-gensym)))
```
## Modules
Modules are single Lisp files that follow a format similar to [Emacs Packages](https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Packages.html).
They start with a commented section:
* The first line is header with the module name and a short description.
* Then a Copyright and license, followed by some module properties, like author, version, requirements, and more.
* A commentary section with a long description of the module, with usage instructions and examples.
Then a section with the module source code:
* `require` calls are placed at the top.
* The definition of a package and the source code of the module.
* A `provide` call at the end of the file.
The template looks like this:
```
;;; ---
;; Copyright (C) 2023 . All rights reserved.
;; This work is licensed under the terms of the license.
;; For a copy, see >.
;; Author:
;; Version:
;; Requires:
;;; Commentary:
;;
;;; Code:
(require :)
(require :)
(defpackage :
(:use :cl))
(in-package :)
... ...
(provide :)
```
An example module:
```lisp
;;; plump-xpath --- xpath extension for plump.
;; Copyright (C) 2023 Mariano Montone. All rights reserved.
;; This work is licensed under the terms of the MIT license.
;; For a copy, see .
;; Author: Mariano Montone
;; Version: 0.1
;; Requires: plump, xpath
;;; Commentary:
;; xpath extension for plump.
;;; Code:
(require :plump)
(require :xpath)
(defpackage :plump-xpath
(:use :cl))
(in-package :plump-xpath)
...
(provide :plump-xpath)
```
## Contributing
I welcome contributions of new modules. If you are interested in mutils shipping yours, create a pull request or attach your file with the module.
Modules should be general purpose and be compact enough to fit into a single file and package. Although they can also depend on other modules.
The module file should follow the format described in this document.
### Maintenance
Evaluate `(mutils-docs:generate-docs)` after adding a new module.
## Modules api (mutils package)
### describe-module
```lisp
(module-name)
```
Print a description of module.
### describe-modules
```lisp
()
```
Print a description of available mutils modules.
### list-modules
```lisp
(&optional (return :name))
```
List mutils modules.
RETURN can be:
- :name . Just returns the name of the modules, as a keyword. Default.
- :details. Parses the modules and returns its details.
### parse-lisp-module-file
```lisp
(file)
```
Parse a Lisp module file.
Returns the name of the module, its short description,
its properties (author, requirements, keywords, etc.),
its long description/comment with instructions of usage, etc.