The trivial-renamer Reference Manual

Table of Contents

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

The trivial-renamer Reference Manual

This is the trivial-renamer Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:41:19 2018 GMT+0.


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

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.


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 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

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 trivial-renamer.asd

Location

trivial-renamer.asd

Systems

trivial-renamer (system)


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

3.1.2 trivial-renamer/package.lisp

Parent

trivial-renamer (system)

Location

package.lisp

Packages

trivial-renamer


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

3.1.3 trivial-renamer/trivial-renamer.lisp

Dependency

package.lisp (file)

Parent

trivial-renamer (system)

Location

trivial-renamer.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 trivial-renamer

Source

package.lisp (file)

Nickname

rename

Use List

common-lisp

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 Special variables

Special Variable: *default-renamer*
Package

trivial-renamer

Source

trivial-renamer.lisp (file)


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

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)


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

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)


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

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)


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

5.2 Internal definitions


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

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)


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

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)


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

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-renamer.asd: The trivial-renamer<dot>asd file
File, Lisp, trivial-renamer/package.lisp: The trivial-renamer/package<dot>lisp file
File, Lisp, trivial-renamer/trivial-renamer.lisp: The trivial-renamer/trivial-renamer<dot>lisp file

L
Lisp File, trivial-renamer.asd: The trivial-renamer<dot>asd file
Lisp File, trivial-renamer/package.lisp: The trivial-renamer/package<dot>lisp file
Lisp File, trivial-renamer/trivial-renamer.lisp: The trivial-renamer/trivial-renamer<dot>lisp file

T
trivial-renamer.asd: The trivial-renamer<dot>asd file
trivial-renamer/package.lisp: The trivial-renamer/package<dot>lisp file
trivial-renamer/trivial-renamer.lisp: The trivial-renamer/trivial-renamer<dot>lisp file

Jump to:   F   L   T  

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

A.2 Functions

Jump to:   (  
C   D   F   G   M   N   O   P   R   T   V  
Index Entry  Section

(
(setf db): Internal generic functions
(setf db): Internal generic functions
(setf default): Exported generic functions
(setf default): Exported generic functions
(setf new->old): Exported generic functions
(setf new->old): Exported generic functions
(setf normal): Exported generic functions
(setf normal): Exported generic functions
(setf old->new): Exported generic functions
(setf old->new): Exported generic functions
(setf overwrite): Internal generic functions
(setf overwrite): Internal generic functions
(setf test): Internal generic functions
(setf test): Internal generic functions
(setf transform): Internal generic functions
(setf transform): Internal generic functions
(setf validate): Internal generic functions
(setf validate): Internal generic functions

C
clear: Exported functions

D
db: Internal generic functions
db: Internal generic functions
default: Exported generic functions
default: Exported generic functions
default-rename-function: Internal functions
default-transform: Internal functions

F
Function, clear: Exported functions
Function, default-rename-function: Internal functions
Function, default-transform: Internal functions
Function, please: Exported functions
Function, rename-for-sure: Internal functions
Function, reset: Exported functions
Function, rule: Exported functions
Function, rules: Exported functions
Function, rules-clear: Internal functions

G
Generic Function, (setf db): Internal generic functions
Generic Function, (setf default): Exported generic functions
Generic Function, (setf new->old): Exported generic functions
Generic Function, (setf normal): Exported generic functions
Generic Function, (setf old->new): Exported generic functions
Generic Function, (setf overwrite): Internal generic functions
Generic Function, (setf test): Internal generic functions
Generic Function, (setf transform): Internal generic functions
Generic Function, (setf validate): Internal generic functions
Generic Function, db: Internal generic functions
Generic Function, default: Exported generic functions
Generic Function, new->old: Exported generic functions
Generic Function, normal: Exported generic functions
Generic Function, old->new: Exported generic functions
Generic Function, overwrite: Internal generic functions
Generic Function, test: Internal generic functions
Generic Function, transform: Internal generic functions
Generic Function, validate: Internal generic functions

M
Method, (setf db): Internal generic functions
Method, (setf default): Exported generic functions
Method, (setf new->old): Exported generic functions
Method, (setf normal): Exported generic functions
Method, (setf old->new): Exported generic functions
Method, (setf overwrite): Internal generic functions
Method, (setf test): Internal generic functions
Method, (setf transform): Internal generic functions
Method, (setf validate): Internal generic functions
Method, db: Internal generic functions
Method, default: Exported generic functions
Method, new->old: Exported generic functions
Method, normal: Exported generic functions
Method, old->new: Exported generic functions
Method, overwrite: Internal generic functions
Method, test: Internal generic functions
Method, transform: Internal generic functions
Method, validate: Internal generic functions

N
new->old: Exported generic functions
new->old: Exported generic functions
normal: Exported generic functions
normal: Exported generic functions

O
old->new: Exported generic functions
old->new: Exported generic functions
overwrite: Internal generic functions
overwrite: Internal generic functions

P
please: Exported functions

R
rename-for-sure: Internal functions
reset: Exported functions
rule: Exported functions
rules: Exported functions
rules-clear: Internal functions

T
test: Internal generic functions
test: Internal generic functions
transform: Internal generic functions
transform: Internal generic functions

V
validate: Internal generic functions
validate: Internal generic functions

Jump to:   (  
C   D   F   G   M   N   O   P   R   T   V  

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

A.3 Variables

Jump to:   *  
D   N   O   S   T   V  
Index Entry  Section

*
*default-renamer*: Exported special variables

D
db: Internal classes
default: Exported classes

N
new->old: Exported classes
normal: Exported classes

O
old->new: Exported classes
overwrite: Internal classes

S
Slot, db: Internal classes
Slot, default: Exported classes
Slot, new->old: Exported classes
Slot, normal: Exported classes
Slot, old->new: Exported classes
Slot, overwrite: Internal classes
Slot, test: Internal classes
Slot, transform: Exported classes
Slot, validate: Internal classes
Special Variable, *default-renamer*: Exported special variables

T
test: Internal classes
transform: Exported classes

V
validate: Internal classes

Jump to:   *  
D   N   O   S   T   V  

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

A.4 Data types

Jump to:   C   P   R   S   T  
Index Entry  Section

C
Class, renamer: Exported classes
Class, ruler: Internal classes

P
Package, trivial-renamer: The trivial-renamer package

R
renamer: Exported classes
ruler: Internal classes

S
System, trivial-renamer: The trivial-renamer system

T
trivial-renamer: The trivial-renamer system
trivial-renamer: The trivial-renamer package

Jump to:   C   P   R   S   T