The mutility Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The mutility Reference Manual

This is the mutility Reference Manual, version 0.5, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:48:49 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

#+TITLE: mutility

A collection of various utility functions and macros I use in my libraries.

This is mostly for deduplication of code so I don't have to keep several copies of these functions across different projects. I don't really recommend depending on this library in your own since I may rename, rearrange, or remove things without warning.

All exported symbols are documented via their docstrings, which are of course accessible via Lisp's standard ~documentation~ and ~describe~ functions.

* Sub-systems

- ~mutility/test-helpers~ includes a few functions that are mostly useful for test suites.

* Tests

To run the mutility tests:

#+BEGIN_SRC lisp
(asdf:test-system :mutility)
#+END_SRC

* Future
Ideas, and things that need to be done.

- Come up with a better name for the ~a~ macro.
- Remove/rename ~accumulate~ to prevent clashes with generic-cl's ~accumulate~ function.
- Write functions to parse docstrings (i.e. to extract example code from them so they can be treated as tests).
- Write more tests for the functions.
- Test docstring examples with the docstring-parsing function once it's written.
- Write a test to check for symbol clashes against various other libraries: ~alexandria~, ~serapeum~, ~cl-patterns~, ~thundersnow~, etc.
- Maybe split out stuff into subsystems? i.e. ~sugar~, ~files~, etc.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 mutility

Author

modula t.

Contact

defaultxr at gmail dot com

Home Page

https://github.com/defaultxr/mutility

Source Control

(:git "git@github.com:defaultxr/mutility.git")

Bug Tracker

https://github.com/defaultxr/mutility/issues

License

MIT

Description

modula’s utilities

Version

0.5

Dependencies
Source

mutility.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 mutility.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/mutility-20200610-git/mutility.asd

Systems

mutility (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 mutility/package.lisp

Parent

mutility (system)

Location

package.lisp

Packages

mutility


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 mutility/mutility.lisp

Dependency

package.lisp (file)

Parent

mutility (system)

Location

mutility.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 mutility

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: a &rest ARGS

Quickly and conveniently generate lists. Use ! to denote repetition of the previous element, or .. to denote a range.

Inspired by similar functionality in SuperCollider.

Examples:

;; (a 3!3)
;; => (3 3 3)
;;
;; (a -5 (random 3)!5 9 10)
;; => (-5 0 2 2 1 2 9 10)
;;
;; (a 2..9)
;; => (2 3 4 5 6 7 8 9)

See also: ‘repeat-by-!’, ‘expand-ranges’

Package

mutility

Source

mutility.lisp (file)

Macro: define-obsolete-function-alias OLD-FUNCTION-NAME NEW-FUNCTION-NAME

Define an alias for an obsolete function. The alias will warn about the obsolete function when it is used.

Package

mutility

Source

mutility.lisp (file)

Macro: dolist* (ITEM INDEX LIST &optional RESULT) &body BODY

Like the standard ‘dolist’ but includes INDEX as another variable representing the current index into LIST.

Package

mutility

Source

mutility.lisp (file)

Macro: fn &body BODY

Syntax sugar for making ‘lambda’s. BODY is the function body. Underscores in the body can be used to represent the argument to the function.

Package

mutility

Source

mutility.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: concat &rest OBJECTS

Concatenates all OBJECTS together into a string (other than nils, which are skipped).

See also: ‘uiop:strcat’

Package

mutility

Source

mutility.lisp (file)

Function: current-seconds ()

Get the number of seconds that Lisp has been running for.

Package

mutility

Source

mutility.lisp (file)

Function: elt-wrap SEQUENCE N

Get the Nth item in SEQUENCE, wrapping the index if necessary.

Much like ‘elt’, this function can be used on any sequence. However, because this function calls ‘length’ to determine the wrapped index, it may be slow when used on large lists. Consider using ‘nth-wrap’ in those cases instead.

See also: ‘nth-wrap’

Package

mutility

Source

mutility.lisp (file)

Function: exponential-random-range LOW HIGH

Generate a random number between LOW and HIGH, with exponential distribution.

See also: ‘random-range’, ‘gauss’

Package

mutility

Source

mutility.lisp (file)

Function: find-any ITEMS LIST &key TEST

Returns the first item from ITEMS that is found in LIST, or nil if none.

Package

mutility

Source

mutility.lisp (file)

Function: flatten-1 LIST

Like ‘alexandria:flatten’, but only flattens one layer.

Package

mutility

Source

mutility.lisp (file)

Function: friendly-symbol INPUT &optional PACKAGE

Return INPUT as a symbol, with all non-letter, non-number, and non-hypen characters removed.

Package

mutility

Source

mutility.lisp (file)

Function: generate-temporary-file-name &key NAME DIRECTORY EXTENSION ATTEMPT

Generate a string representing a full path to a new temporary file. The file name defaults to a timestamp. Will automatically create DIRECTORY if it doesn’t exist. Will also attempt to generate a new name if a file with that name already exists. ATTEMPT is the attempt number if the filename already exists.

Example:

;; (generate-temporary-file-name :name "foo" :directory "/tmp/lisp/" :extension "wav")
;; => "/tmp/lisp/foo.wav"

;; (generate-temporary-file-name :directory "/tmp/lisp/" :extension :flac)
;; => "/tmp/lisp/2020-04-20-06-09-00.flac"

Package

mutility

Source

mutility.lisp (file)

Function: insert-if FUNCTION LIST ITEM

Destructively insert ITEM into LIST at the position where FUNCTION is true. If the function doesn’t return true, the item is inserted at the end of the list. Similar to ‘nreverse’, the result is returned ;; FIX

Example:

;; (insert-if #’plusp (list -2 -1 1 2) 0)
;; ;; => (-2 -1 0 1 2)

See also: ‘insert-sorted’

Package

mutility

Source

mutility.lisp (file)

Function: insert-sorted LIST NUMBER

Destructively insert NUMBER into LIST in order.

Example:

;; (insert-sorted (list 1 2 3 4) 2.5)
;; ;; => (1 2 2.5 3 4)

See also: ‘insert-if’

Package

mutility

Source

mutility.lisp (file)

Function: length-upto LIST &optional MAX

Get the length of LIST, not counting above MAX.

Package

mutility

Source

mutility.lisp (file)

Function: mapcar-with-index FUNCTION LIST &rest MORE-LISTS

Like ‘mapcar’, but provides the index of the current element as an additional final element to FUNCTION.

Package

mutility

Source

mutility.lisp (file)

Function: my-intern STRING &optional PACKAGE

Converts STRING into a symbol, uppercasing it in the process.

See also: ‘un-intern’

Package

mutility

Source

mutility.lisp (file)

Function: nth-wrap N LIST

Get the Nth item in LIST, wrapping the index if necessary.

Much like ‘nth’, this function can only be used on lists. Use ‘elt-wrap’ to index into any kind of sequence. However, keep in mind that ‘elt-wrap’ may be slower when used on large lists.

See also: ‘elt-wrap’

Package

mutility

Source

mutility.lisp (file)

Function: open-url URL

Open a URL via the OS’s default application.

Package

mutility

Source

mutility.lisp (file)

Function: output &rest ITEMS

Concatenates and prints ITEMS, returning the last one.

See also: ‘concat’

Package

mutility

Source

mutility.lisp (file)

Function: random-coin &optional PROBABILITY

Randomly return true with a probability of PROBABILITY/1.

Package

mutility

Source

mutility.lisp (file)

Function: random-gauss MEAN STANDARD-DEVIATION

Generate a random number from a normal (Gaussian) distribution.

See also: ‘random-range’, ‘exponential-random-range’

Package

mutility

Source

mutility.lisp (file)

Function: random-range LOW &optional HIGH

Return a random number between LOW and HIGH, inclusive. If HIGH is not provided, act the same as (random LOW).

See also: ‘exponential-random-range’, ‘gauss’

Package

mutility

Source

mutility.lisp (file)

Function: replace-all STRING PART REPLACEMENT &key TEST

Returns a new string in which all the occurences of the part is replaced with replacement.

See also: ‘cl-ppcre:regex-replace-all’

Package

mutility

Source

mutility.lisp (file)

Function: restore-hash-table FILENAME &rest MAKE-HASH-TABLE-ARGS

Restore a hash table from a file saved with the ‘save-hash-table’ function.

Package

mutility

Source

mutility.lisp (file)

Function: round-by NUMBER &optional BY

Round NUMBER to the nearest multiple of BY.

Examples:

;; (round-by 1 2) ;; => 0
;; (round-by 1.1 0.5) ;; => 1.0
;; (round-by 6 10) ;; => 10

See also: ‘cl:round’, ‘round-by-direction’

Package

mutility

Source

mutility.lisp (file)

Function: round-by-direction NUMBER &optional BY

Round NUMBER to the nearest multiple of BY. With positive BY, round up; with negative, round down.

Examples:

;; (round-by-direction 0.5 -1) ;; => 0
;; (round-by-direction 0.5 1) ;; => 1

See also: ‘round-by’, ‘cl:round’

Package

mutility

Source

mutility.lisp (file)

Function: save-hash-table HT FILENAME &key OVERWRITE

Save a hash table to a file. See ‘restore-hash-table’ to load the saved table.

Package

mutility

Source

mutility.lisp (file)

Function: split-sequence SEQUENCE DELIMITER

Split SEQUENCE by DELIMITER.

Package

mutility

Source

mutility.lisp (file)

Function: split-string STRING &key MAX-NUM CHAR-BAG INCLUDE-EMPTY

Returns a list of substrings of ’string’ divided by spaces, optionally splitting only to a list of a maximum size.

See also: ‘split-sequence’, ‘str:split’, ‘split-sequence:split-sequence’

Package

mutility

Source

mutility.lisp (file)

Function: string-boolean STRING &optional DEFAULT

Return T or NIL depending on if STRING is a true or false value, or DEFAULT if it is not known.

Package

mutility

Source

mutility.lisp (file)

Function: subseq* SEQUENCE START &optional END

Like subseq, but allows start and end to be negative.

Package

mutility

Source

mutility.lisp (file)

Function: un-intern SYMBOL

Converts a symbol into a string.

See also: ‘my-intern’

Package

mutility

Source

mutility.lisp (file)

Function: wrap NUMBER &optional BOTTOM TOP

Wraps a number between BOTTOM and TOP, similar to ‘cl:mod’.

Examples:

;; (wrap 2 0 1) ;; => 0
;; (wrap 5 0 10) ;; => 5
;; (wrap 15 0 10) ;; => 4

See also: ‘cl:mod’, ‘alexandria:clamp’, ‘within’

Package

mutility

Source

mutility.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Generic functions

Generic Function: keys OBJECT

Get the keys of OBJECT, whether it be a plist, event, etc.

Package

mutility

Source

mutility.lisp (file)

Methods
Method: keys (OBJECT hash-table)
Method: keys (OBJECT cons)
Method: keys (OBJECT null)

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: accumulating &body BODY

Run BODY with the local function ACCUMULATE appending its values to a list, which is then returned. This macro avoids having to reverse the list at the end like with the traditional ‘push’/‘nreverse’ idiom.

See also: ‘uiop:while-collecting’.

Package

mutility

Source

mutility.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: expand-ranges LIST

Expand ranges denoted by a..b in list.

Example:

;; (expand-ranges ’(0..5 -2..2)) ;; => (0 1 2 3 4 5 -2 -1 0 1 2)

Package

mutility

Source

mutility.lisp (file)

Function: prepend-list-to-sublists LIST

Prepend the symbol ’list to LIST and all of its sublists.

Package

mutility

Source

mutility.lisp (file)

Function: random-range.new LOW &optional HIGH

Return a random number between LOW and HIGH, inclusive. If HIGH is not provided, act the same as (random LOW).

Package

mutility

Source

mutility.lisp (file)

Function: repeat ITEM NUM

Get a list containing NUM ITEMs. If ITEM is a function, return a list of NUM of the result of that function.

Package

mutility

Source

mutility.lisp (file)

Function: repeat-by OBJECT REPEATS &optional ADD-LIST

Returns a list of object repeated REPEATS times. If REPEATS is a list of multiple numbers, recursively repeat the generated lists.

When ADD-LIST is true, prepend ’list to each generated list.

Example:

;; (repeat-by 3 3)
;; => (3 3 3)
;;
;; (repeat-by 3 ’(3 2))
;; => ((3 3 3) (3 3 3))

See also: ‘repeat-by-!’, ‘a’

Package

mutility

Source

mutility.lisp (file)

Function: repeat-by-! LIST &optional ADD-LIST

Given LIST, repeat items marked with ! by the number after the !.

When ADD-LIST is true, prepend ’list to each generated list. This is useful if you’re using this function in a macro, such as the ‘a’ macro, which this function does all the heavy lifting for.

Examples:

;; (repeat-by-! ’(1!2))
;; => (1 1)
;;
;; (repeat-by-! ’(1!2!3))
;; => ((1 1) (1 1) (1 1))
;;
;; (repeat-by-! ’(1 (* 2 3)!2))
;; => (1 (* 2 3) (* 2 3))

See also: ‘repeat-by’, ‘a’

Package

mutility

Source

mutility.lisp (file)

Function: split-by-! STRING

Split STRING up by exclamation points.

Package

mutility

Source

mutility.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, mutility.asd: The mutility․asd file
File, Lisp, mutility/mutility.lisp: The mutility/mutility․lisp file
File, Lisp, mutility/package.lisp: The mutility/package․lisp file

L
Lisp File, mutility.asd: The mutility․asd file
Lisp File, mutility/mutility.lisp: The mutility/mutility․lisp file
Lisp File, mutility/package.lisp: The mutility/package․lisp file

M
mutility.asd: The mutility․asd file
mutility/mutility.lisp: The mutility/mutility․lisp file
mutility/package.lisp: The mutility/package․lisp file

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   E   F   G   I   K   L   M   N   O   P   R   S   U   W  
Index Entry  Section

A
a: Exported macros
accumulating: Internal macros

C
concat: Exported functions
current-seconds: Exported functions

D
define-obsolete-function-alias: Exported macros
dolist*: Exported macros

E
elt-wrap: Exported functions
expand-ranges: Internal functions
exponential-random-range: Exported functions

F
find-any: Exported functions
flatten-1: Exported functions
fn: Exported macros
friendly-symbol: Exported functions
Function, concat: Exported functions
Function, current-seconds: Exported functions
Function, elt-wrap: Exported functions
Function, expand-ranges: Internal functions
Function, exponential-random-range: Exported functions
Function, find-any: Exported functions
Function, flatten-1: Exported functions
Function, friendly-symbol: Exported functions
Function, generate-temporary-file-name: Exported functions
Function, insert-if: Exported functions
Function, insert-sorted: Exported functions
Function, length-upto: Exported functions
Function, mapcar-with-index: Exported functions
Function, my-intern: Exported functions
Function, nth-wrap: Exported functions
Function, open-url: Exported functions
Function, output: Exported functions
Function, prepend-list-to-sublists: Internal functions
Function, random-coin: Exported functions
Function, random-gauss: Exported functions
Function, random-range: Exported functions
Function, random-range.new: Internal functions
Function, repeat: Internal functions
Function, repeat-by: Internal functions
Function, repeat-by-!: Internal functions
Function, replace-all: Exported functions
Function, restore-hash-table: Exported functions
Function, round-by: Exported functions
Function, round-by-direction: Exported functions
Function, save-hash-table: Exported functions
Function, split-by-!: Internal functions
Function, split-sequence: Exported functions
Function, split-string: Exported functions
Function, string-boolean: Exported functions
Function, subseq*: Exported functions
Function, un-intern: Exported functions
Function, wrap: Exported functions

G
generate-temporary-file-name: Exported functions
Generic Function, keys: Exported generic functions

I
insert-if: Exported functions
insert-sorted: Exported functions

K
keys: Exported generic functions
keys: Exported generic functions
keys: Exported generic functions
keys: Exported generic functions

L
length-upto: Exported functions

M
Macro, a: Exported macros
Macro, accumulating: Internal macros
Macro, define-obsolete-function-alias: Exported macros
Macro, dolist*: Exported macros
Macro, fn: Exported macros
mapcar-with-index: Exported functions
Method, keys: Exported generic functions
Method, keys: Exported generic functions
Method, keys: Exported generic functions
my-intern: Exported functions

N
nth-wrap: Exported functions

O
open-url: Exported functions
output: Exported functions

P
prepend-list-to-sublists: Internal functions

R
random-coin: Exported functions
random-gauss: Exported functions
random-range: Exported functions
random-range.new: Internal functions
repeat: Internal functions
repeat-by: Internal functions
repeat-by-!: Internal functions
replace-all: Exported functions
restore-hash-table: Exported functions
round-by: Exported functions
round-by-direction: Exported functions

S
save-hash-table: Exported functions
split-by-!: Internal functions
split-sequence: Exported functions
split-string: Exported functions
string-boolean: Exported functions
subseq*: Exported functions

U
un-intern: Exported functions

W
wrap: Exported functions

Jump to:   A   C   D   E   F   G   I   K   L   M   N   O   P   R   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   M   P   S  
Index Entry  Section

M
mutility: The mutility system
mutility: The mutility package

P
Package, mutility: The mutility package

S
System, mutility: The mutility system

Jump to:   M   P   S