The trivial-renamer Reference Manual

Table of Contents

The trivial-renamer Reference Manual

This is the trivial-renamer Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 18:07:04 2021 GMT+0.

1 Introduction

TRIVIAL-RENAMER

TRIVIAL-RENAMER (RENAME) is a configurable Lisp tool for renaming objects using regular expressions, and maintaining mappings between old and new names. It may be useful as a component in projects such as file managers, MP3 renamers, and FFI generators.

TRIVIAL-RENAMER operates on 'categorized' names. Some examples of categories (which may be arbitrary lisp objects) are: file types/extensions, music album or songs, or FFI types.

Prior to renaming, TRIVIAL-RENAMER requires that you provide it with rules for categories. Each category can have one or more rules; each rule is a pair containing a regex and the substitution string. These are usually bulk-loaded as a list or rules, although you can add them dynamically.

The renaming process consists of rule-based renaming followed by a call to a 'normal' function you provide. If no rules can be found, the 'default' renaming function is called. The result will be checked to assure one-to-one correspondece between old and new names.

Both the format of the rules and the transformation function are configurable; the default is to perform regex text substitution based on rules that contain (regex . newstring).

After renaming, the hashtables built are made available to your application.

Any number of different renamers can be active at the same time.

Dependencies

cl-ppcre

Example

The defaults create a renamer that expects string objects. A simple downcase renaming function is provided to test the functionality.

CL-USER> (ql:quickload :trivial-renamer)
...
CL-USER> (make-instance 'rename:renamer)
#<TRIVIAL-RENAMER:RENAMER {...}>

CL-USER> (rename:please "HELLO WORLD") ;; default is downcasing
"hello world"

CL-USER> (rename:rule 'cat1 '(("e" . "3")))  ;; add a regex substitution rule

(renamer:please "monkey" 'cat1)
"monk3y"

Defaults

The example above shows a number of defaults in use. For instance, both normal and default renaming routines start out as lowercasing the string, unless set. If the renamer itself is not specified, rename:*default-renamer* is used which is useful for testing. If the category is not specified, T is used for category. See the documentation below for more information.

Rationale and use case

The raison d'etre of this library is a cffi binding generator. Translating C identifier names to Lisp required keeping custom name translation rules based on type of C object, its namespace, and even the object's actual name, for total control of renaming.

After renaming, there is still the daunting task of maintaining a relationship between old and new names, uniqueness of mapping, etc.

The required functionality appeared to be well suited for a library.

Keys to initialize the renamer

KEY | DEFAULT | DESCRIPTION --- | ------- | ----------- :TEST | #'equal | equality test for category hashtable. :OVERWRITE | T | if T, overwrite rules if category is introduced more than once. Otherwise, add new rules in front. :VALIDATE | NIL |(lambda (key value r)) optional function to validate a rule. If it returns, rule is valid. :DEFAULT | lowercase | :default (lambda (oldname renamer)...) called if no rule is found, return string. :NORMAL | obj copy | :default (lambda (newname renamer)...) called after rule is processed, return string. :TRANSFORM | * | renaming function; see below

Functions

(rename:rule category &optional renamer)

Parameter | Description --------- | ----------- rule | a list of (regex . newstring) pairs. Each matched regex is substituted with newstring. category | any object that works as a key in the rule hashtable (with :TEST)

(rename:rules list &optional renamer)

Parameter | Description --------- | ----------- list | '(category ((regex . newstring) (regex .newstring)) category ((...)) ...)

(rename:please oldname &optional renamer)

Returns the new name.

Raises errors if the old name is already transformed and new transform mismatches, or if newly generated name is already in use.

(rename:reset &optional renamer)

Clear the renamer data and rules.

Transform function

(lambda name category rules renamer)

It is possible to completely change the behavior of TRIVIAL-RENAMER by installing a different version of this function: the format of the rules, the actual transformations, etc.

The default transform expects each rule to be in the form of (regex . replacement), and repeatedly attempts to perform the replacements on the name.

2 Systems

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

2.1 trivial-renamer

Author

StackSmith <fpgasm@apple2.x10.mx>

License

BSD 3-clause license

Description

rename and manage categorized named objects

Dependency

cl-ppcre

Source

trivial-renamer.asd (file)

Components

• package.lisp (file)
• trivial-renamer.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 trivial-renamer.asd

Location

trivial-renamer.asd

Systems

trivial-renamer (system)

3.1.2 trivial-renamer/package.lisp

Parent

trivial-renamer (system)

Location

package.lisp

Packages

trivial-renamer

3.1.3 trivial-renamer/trivial-renamer.lisp

Dependency

package.lisp (file)

Parent

trivial-renamer (system)

Location

trivial-renamer.lisp

Exported Definitions

• *default-renamer* (special variable)
• clear (function)
• default (method)
• (setf default) (method)
• new->old (method)
• (setf new->old) (method)
• normal (method)
• (setf normal) (method)
• old->new (method)
• (setf old->new) (method)
• please (function)
• renamer (class)
• reset (function)
• rule (function)
• rules (function)

Internal Definitions

• db (method)
• (setf db) (method)
• default-rename-function (function)
• default-transform (function)
• overwrite (method)
• (setf overwrite) (method)
• rename-for-sure (function)
• ruler (class)
• rules-clear (function)
• test (method)
• (setf test) (method)
• transform (method)
• (setf transform) (method)
• validate (method)
• (setf validate) (method)

4 Packages

Packages are listed by definition order.

4.1 trivial-renamer

Source

package.lisp (file)

Nickname

rename

Use List

common-lisp

Exported Definitions

• *default-renamer* (special variable)
• clear (function)
• default (generic function)
• default (method)
• (setf default) (method)
• (setf default) (generic function)
• new->old (generic function)
• new->old (method)
• (setf new->old) (method)
• (setf new->old) (generic function)
• normal (generic function)
• normal (method)
• (setf normal) (method)
• (setf normal) (generic function)
• old->new (generic function)
• old->new (method)
• (setf old->new) (method)
• (setf old->new) (generic function)
• please (function)
• renamer (class)
• reset (function)
• rule (function)
• rules (function)

Internal Definitions

• db (generic function)
• db (method)
• (setf db) (method)
• (setf db) (generic function)
• default-rename-function (function)
• default-transform (function)
• overwrite (generic function)
• overwrite (method)
• (setf overwrite) (method)
• (setf overwrite) (generic function)
• rename-for-sure (function)
• ruler (class)
• rules-clear (function)
• test (generic function)
• test (method)
• (setf test) (method)
• (setf test) (generic function)
• transform (generic function)
• transform (method)
• (setf transform) (method)
• (setf transform) (generic function)
• validate (generic function)
• validate (method)
• (setf validate) (method)
• (setf validate) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *default-renamer*

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

5.1.2 Functions

Function: clear &optional RENAMER

clear the caches, leaving rules intact

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: please OLDNAME &optional CATEGORY RENAMER

rename obj and return new name

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: reset &optional RENAMER

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: rule CATEGORY VAL &optional RULER

add a rule for key appending or replacing

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: rules RULES &optional RULER

Add a bunch of rules

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

5.1.3 Generic functions

Generic Function: default OBJECT

Generic Function: (setf default) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: default (RENAMER renamer)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf default) NEW-VALUE (RENAMER renamer)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: new->old OBJECT

Generic Function: (setf new->old) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: new->old (RENAMER renamer)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf new->old) NEW-VALUE (RENAMER renamer)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: normal OBJECT

Generic Function: (setf normal) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: normal (RENAMER renamer)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf normal) NEW-VALUE (RENAMER renamer)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: old->new OBJECT

Generic Function: (setf old->new) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: old->new (RENAMER renamer)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf old->new) NEW-VALUE (RENAMER renamer)

automatically generated writer method

Source

trivial-renamer.lisp (file)

5.1.4 Classes

Class: renamer ()

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Direct superclasses

ruler (class)

Direct methods

• print-object (method)
• initialize-instance (method)
• new->old (method)
• new->old (method)
• old->new (method)
• old->new (method)
• transform (method)
• transform (method)
• normal (method)
• normal (method)
• default (method)
• default (method)

Direct slots

Slot: default

Initargs

:default

Initform

(function trivial-renamer::default-rename-function)

Readers

default (generic function)

Writers

(setf default) (generic function)

Slot: normal

Initargs

:normal

Initform

(function trivial-renamer::default-rename-function)

Readers

normal (generic function)

Writers

(setf normal) (generic function)

Slot: transform

Initargs

:transform

Initform

(function trivial-renamer::default-transform)

Readers

transform (generic function)

Writers

(setf transform) (generic function)

Slot: old->new

Readers

old->new (generic function)

Writers

(setf old->new) (generic function)

Slot: new->old

Readers

new->old (generic function)

Writers

(setf new->old) (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: default-rename-function STRING RENAMER

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: default-transform OLDNAME CATEGORY RULES RENAMER

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: rename-for-sure OLDNAME CATEGORY RENAMER

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Function: rules-clear RULER

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

5.2.2 Generic functions

Generic Function: db OBJECT

Generic Function: (setf db) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: db (RULER ruler)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf db) NEW-VALUE (RULER ruler)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: overwrite OBJECT

Generic Function: (setf overwrite) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: overwrite (RULER ruler)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf overwrite) NEW-VALUE (RULER ruler)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: test OBJECT

Generic Function: (setf test) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: test (RULER ruler)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf test) NEW-VALUE (RULER ruler)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: transform OBJECT

Generic Function: (setf transform) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: transform (RENAMER renamer)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf transform) NEW-VALUE (RENAMER renamer)

automatically generated writer method

Source

trivial-renamer.lisp (file)

Generic Function: validate OBJECT

Generic Function: (setf validate) NEW-VALUE OBJECT

Package

trivial-renamer

Methods

Method: validate (RULER ruler)

automatically generated reader method

Source

trivial-renamer.lisp (file)

Method: (setf validate) NEW-VALUE (RULER ruler)

automatically generated writer method

Source

trivial-renamer.lisp (file)

5.2.3 Classes

Class: ruler ()

Package

trivial-renamer

Source

trivial-renamer.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

renamer (class)

Direct methods

• initialize-instance (method)
• validate (method)
• validate (method)
• overwrite (method)
• overwrite (method)
• test (method)
• test (method)
• db (method)
• db (method)

Direct slots

Slot: db

Initargs

:db

Readers

db (generic function)

Writers

(setf db) (generic function)

Slot: test

Initargs

:test

Initform

(function equal)

Readers

test (generic function)

Writers

(setf test) (generic function)

Slot: overwrite

Initargs

:overwrite

Initform

t

Readers

overwrite (generic function)

Writers

(setf overwrite) (generic function)

Slot: validate

Initargs

:validate

Initform

(lambda (trivial-renamer::key trivial-renamer::val trivial-renamer::r) (declare (ignore trivial-renamer::key trivial-renamer::val trivial-renamer::r)))

Readers

validate (generic function)

Writers

(setf validate) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types