rename and manage categorized named objects

trivial-renamer

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



trivial-renamer

Upstream URL

Author

License

trivial-renamer

License:

Authors:

Dependencies:

Dependencies (1)

Dependents (0)