The cl-slug Reference Manual

Table of Contents

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

The cl-slug Reference Manual

This is the cl-slug Reference Manual, version 0.4.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:33:22 2018 GMT+0.


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

1 Introduction

cl-slug

Quicklisp Build Status Circle CI Coverage Status

Easily create slugs from any string. Supports many languages alphabets. See Supported languages to check for supported languages or to help to add one.

Inspired by Lisp Web Tales.

Usage

* (ql:quickload :cl-slug)
; => (:CL-SLUG)
* (import '(slug:slugify slug:asciify slug:CamelCaseFy))
; => T

The main function is called slugify:

* (slugify "My new cool article, for the blog (V. 2).")
; => "my-new-cool-article-for-the-blog-v-2"
* (slugify "André Miranda")
; => "andre-miranda"

slugify removes any accented character, replacing it with an unaccented equivalent, and any punctuation (a punctuation is a char that returns NIL for alphanumericp) and puts a dash (-) on it's place. You can change that by binding (of setfing) *slug-separator*:

* (let ((*slug-separator* #\_))
    (slugify "Testing the *slug-separator* var..."))
; => "testing_the_slug_separator_var"

slugify also ignores numbers:

* (slugify "one2three4five")
; => "one2three4five"

If you just want to remove accents and punctuation of a given string, use asciify:

* (asciify "Eu André!")
; => "Eu Andre!"

Or if you want a CamelCase, use CamelCaseFy:

* (CamelCaseFy "My new camel case string")
; => "MyNewCamelCaseString"

Available languages are stored in *available-languages*:

* slug:*available-languages*
((:TR . "Türkçe (Turkish)") (:SV . "Svenska (Swedish)") (:FI . "Suomi (Finnish)") 
 (:UK . "українська (Ukrainian)") (:RU . "Ру́сский (Russian)") (:RO . "Română (Romanian)")
 (:RM . "Rumàntsch (Romansh)") (:PT . "Português (Portuguese)") (:PL . "Polski (Polish)")
 (:NO . "Norsk (Norwegian)") (:LT . "Lietuvių (Lithuanian)") (:LV . "Latviešu (Latvian)")
 (:LA . "Lingua Latīna (Latin)") (:IT . "Italiano (Italian)") (:EL . "ελληνικά (Greek)")
 (:FR . "Français (French)") (:EO . "Esperanto") (:ES . "Español (Spanish)") (:EN . "English")
 (:DE . "Deutsch (German)") (:DA . "Dansk (Danish)") (:CS . "Čeština (Czech)")
 (:CURRENCY . "Currency"))

Dependencies

This library depends on CL-PPCRE. The test package uses the prove test library.

Installation

Available on Quicklisp:

(ql:quickload :cl-slug)

Supported languages

The languages that are supported right now are:

Ported from Django():

At the present moment, adding new languages is a fairly manual process:

  1. Identify non-ASCII characters in a given language's alphabet
  2. Establish equivalence between the found characters and ASCII characters
  3. Write them down in the code.

All those things can actually be done for most of the dominant Western languages, but can't be applied for minor regional languages or many other non-Latin languages from the whole world, like Chinese. It's not generic and not scalable.

I couldn't think of a solution so far for this, but if you know a solution (even a partial one) I'd be glad to hear =].

Bugs

If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

Tests

This library is tested under ABCL, SBCL, CCL, CLISP and ECL Common Lisp implementations.

To run all the defined tests, use:

* (asdf:test-system :cl-slug)
; prints lots of (colorful) stuff...
; => T

Tests are ran with Travis CI and Circle CI using cl-travis, CIM, cl-coveralls and Roswell. Check it out!

Author

André Miranda.

License

[LLGPL](https://tldrlegal.com/license/lisp


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

Maintainer

André Miranda

Author

André Miranda

Contact

andremiramor@gmail.com

Home Page

https://github.com/EuAndreh/cl-slug

Source Control

(:git "git@github.com:euandreh/cl-slug.git")

Bug Tracker

https://github.com/EuAndreh/cl-slug/issues

License

LLGPL

Description

Small library to make slugs, mainly for URIs, from english and beyond.

Long Description

# cl-slug
[![Quicklisp](http://quickdocs.org/badge/cl-slug.svg)](http://quickdocs.org/cl-slug/)
[![Build Status](https://travis-ci.org/EuAndreh/cl-slug.svg?branch=master)](https://travis-ci.org/EuAndreh/cl-slug)
[![Circle CI](https://circleci.com/gh/EuAndreh/cl-slug.svg?style=svg)](https://circleci.com/gh/EuAndreh/cl-slug)
[![Coverage Status](https://coveralls.io/repos/EuAndreh/cl-slug/badge.svg?branch=master)](https://coveralls.io/r/EuAndreh/cl-slug?branch=master)

Easily create slugs from any string. Supports many languages alphabets. See [Supported languages](#supported-languages) to check for supported languages or to help to add one.

Inspired by [Lisp Web Tales](http://lispwebtales.ppenev.com/chap05.html#leanpub-auto-rewriting-the-routes).

## Usage
“‘lisp
* (ql:quickload :cl-slug)
; => (:CL-SLUG)
* (import ’(slug:slugify slug:asciify slug:CamelCaseFy))
; => T
“‘

The main function is called ‘slugify‘:

“‘lisp
* (slugify "My new cool article, for the blog (V. 2).")
; => "my-new-cool-article-for-the-blog-v-2"
* (slugify "André Miranda")
; => "andre-miranda"
“‘

‘slugify‘ removes any accented character, replacing it with an unaccented equivalent, and any punctuation (a punctuation is a char that returns ‘NIL‘ for ‘alphanumericp‘) and puts a dash (‘-‘) on it’s place. You can change that by binding (of ‘setf‘ing) ‘*slug-separator*‘:

“‘lisp
* (let ((*slug-separator* #\_))
(slugify "Testing the *slug-separator* var..."))
; => "testing_the_slug_separator_var"
“‘

‘slugify‘ also ignores numbers:

“‘lisp
* (slugify "one2three4five")
; => "one2three4five"
“‘

If you just want to remove accents and punctuation of a given string, use ‘asciify‘:

“‘lisp
* (asciify "Eu André!")
; => "Eu Andre!"
“‘

Or if you want a CamelCase, use ‘CamelCaseFy‘:

“‘lisp
* (CamelCaseFy "My new camel case string")
; => "MyNewCamelCaseString"
“‘

Available languages are stored in ‘*available-languages*‘:
“‘lisp
* slug:*available-languages*
((:TR . "Türkçe (Turkish)") (:SV . "Svenska (Swedish)") (:FI . "Suomi (Finnish)")
(:UK . "українська (Ukrainian)") (:RU . "Ру́сский (Russian)") (:RO . "Română (Romanian)")
(:RM . "Rumàntsch (Romansh)") (:PT . "Português (Portuguese)") (:PL . "Polski (Polish)")
(:NO . "Norsk (Norwegian)") (:LT . "Lietuvių (Lithuanian)") (:LV . "Latviešu (Latvian)")
(:LA . "Lingua Latīna (Latin)") (:IT . "Italiano (Italian)") (:EL . "ελληνικά (Greek)")
(:FR . "Français (French)") (:EO . "Esperanto") (:ES . "Español (Spanish)") (:EN . "English")
(:DE . "Deutsch (German)") (:DA . "Dansk (Danish)") (:CS . "Čeština (Czech)")
(:CURRENCY . "Currency"))
“‘

## Dependencies

This library depends on [CL-PPCRE](http://weitz.de/cl-ppcre). The test package uses the [prove](https://github.com/fukamachi/prove) test library.

## Installation
Available on [Quicklisp](http://quicklisp.org):
“‘
(ql:quickload :cl-slug)
“‘

## Supported languages
The languages that are supported right now are:
- english
- portuguese
- esperanto
- german
- french
- swedish
- finnish
- norwegian
- danish
- italian
- spanish
- romansh

Ported from [Django](https://code.djangoproject.com/browser/django/trunk/django/contrib/admin/media/js/urlify.js)():
- currency
- romanian
- lithuanian
- latvian
- polish
- czesh
- ukranian
- russian
- turkish
- greek
- latin

At the present moment, adding new languages is a fairly manual process:
1. Identify non-ASCII characters in a given language’s alphabet
2. Establish equivalence between the found characters and ASCII characters
3. Write them down in the code.

All those things can actually be done for most of the dominant Western languages, but can’t be applied for minor regional languages or many other non-Latin languages from the whole world, like Chinese. It’s not generic and not scalable.

I couldn’t think of a solution so far for this, but if you know a solution (even a partial one) I’d be glad to hear =].

## Bugs
If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

## Tests
This library is tested under [ABCL](https://common-lisp.net/project/armedbear/), [SBCL](http://www.sbcl.org/), [CCL](http://ccl.clozure.com/), [CLISP](http://www.clisp.org/) and [ECL](https://common-lisp.net/project/ecl/) Common Lisp implementations.

To run all the defined tests, use:
“‘lisp
* (asdf:test-system :cl-slug)
; prints lots of (colorful) stuff...
; => T
“‘

Tests are ran with [Travis CI](https://travis-ci.org/EuAndreh/cl-slug) and [Circle CI](https://circleci.com/gh/EuAndreh/cl-slug) using [cl-travis](https://github.com/luismbo/cl-travis), [CIM](https://github.com/KeenS/CIM), [cl-coveralls](https://github.com/fukamachi/cl-coveralls) and [Roswell](https://github.com/snmsts/roswell). Check it out!

## Author
André Miranda.

## License
[LLGPL](https://tldrlegal.com/license/lisp-lesser-general-public-license#fulltext).

Version

0.4.1

Dependency

cl-ppcre

Source

cl-slug.asd (file)

Components

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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-slug/src

Parent

cl-slug (system)

Location

src/

Component

cl-slug.lisp (file)


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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-slug.asd

Location

cl-slug.asd

Systems

cl-slug (system)


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

4.1.2 cl-slug/src/cl-slug.lisp

Parent

src (module)

Location

src/cl-slug.lisp

Packages

cl-slug

Exported Definitions
Internal Definitions

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

4.2 Other


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

4.2.1 cl-slug/README.md

Parent

cl-slug (system)

Location

README.md


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

5 Packages

Packages are listed by definition order.


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

5.1 cl-slug

Main (and only) package. Package nickname SLUG also available.

Source

cl-slug.lisp (file)

Nickname

slug

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *available-languages*

Alist with (KEY . LANGUAGE-NAMESTRING).

Package

cl-slug

Source

cl-slug.lisp (file)

Special Variable: *slug-separator*

Default separator of slug strings.

Package

cl-slug

Source

cl-slug.lisp (file)


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

6.1.2 Functions

Function: asciify STRING

Removes the accentuation and ponctuation of the given STRING.

Package

cl-slug

Source

cl-slug.lisp (file)

Function: camelcasefy STRING

Makes STRING CamelCase, also removing ponctuation and accentuation.

Package

cl-slug

Source

cl-slug.lisp (file)

Function: slugify STRING

Makes STRING a slug: a downcase string, with no special characters, ponctuation or accentuated letters whatsoever.

Package

cl-slug

Source

cl-slug.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Special variables

Special Variable: %accentuations

Hash table of all {accentuation -> ascii-equivalent} characters.

Package

cl-slug

Source

cl-slug.lisp (file)

Special Variable: %special-chars

Hash table of all {special-char -> ascii-equivalent} strings.

Package

cl-slug

Source

cl-slug.lisp (file)


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

6.2.2 Macros

Macro: add-language NAME KEY-CODE ACCENTUATION-ALIST &optional SPECIAL-CHARS-ALIST
Package

cl-slug

Source

cl-slug.lisp (file)


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

6.2.3 Functions

Function: last-char STRING

Returns the last char of a non-empty string.

Package

cl-slug

Source

cl-slug.lisp (file)

Function: remove-accentuation STRING

Removes accentuation (according to %ACCENTUATIONS) from STRING.

Package

cl-slug

Source

cl-slug.lisp (file)

Function: remove-ponctuation STRING

Removes ponctuation and other special characters from STRING according #’ALPHANUMERICP.

Package

cl-slug

Source

cl-slug.lisp (file)

Function: remove-special-chars STRING

Removes all special characters stored in %SPECIAL-CHARS using #’PPCRE:REPLACE-REGEX-ALL.

Package

cl-slug

Source

cl-slug.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M   O  
Index Entry  Section

C
cl-slug.asd: The cl-slug<dot>asd file
cl-slug/README.md: The cl-slug/readme<dot>md file
cl-slug/src: The cl-slug/src module
cl-slug/src/cl-slug.lisp: The cl-slug/src/cl-slug<dot>lisp file

F
File, Lisp, cl-slug.asd: The cl-slug<dot>asd file
File, Lisp, cl-slug/src/cl-slug.lisp: The cl-slug/src/cl-slug<dot>lisp file
File, other, cl-slug/README.md: The cl-slug/readme<dot>md file

L
Lisp File, cl-slug.asd: The cl-slug<dot>asd file
Lisp File, cl-slug/src/cl-slug.lisp: The cl-slug/src/cl-slug<dot>lisp file

M
Module, cl-slug/src: The cl-slug/src module

O
Other File, cl-slug/README.md: The cl-slug/readme<dot>md file

Jump to:   C   F   L   M   O  

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

A.2 Functions

Jump to:   A   C   F   L   M   R   S  
Index Entry  Section

A
add-language: Internal macros
asciify: Exported functions

C
camelcasefy: Exported functions

F
Function, asciify: Exported functions
Function, camelcasefy: Exported functions
Function, last-char: Internal functions
Function, remove-accentuation: Internal functions
Function, remove-ponctuation: Internal functions
Function, remove-special-chars: Internal functions
Function, slugify: Exported functions

L
last-char: Internal functions

M
Macro, add-language: Internal macros

R
remove-accentuation: Internal functions
remove-ponctuation: Internal functions
remove-special-chars: Internal functions

S
slugify: Exported functions

Jump to:   A   C   F   L   M   R   S  

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

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%accentuations: Internal special variables
%special-chars: Internal special variables

*
*available-languages*: Exported special variables
*slug-separator*: Exported special variables

S
Special Variable, %accentuations: Internal special variables
Special Variable, %special-chars: Internal special variables
Special Variable, *available-languages*: Exported special variables
Special Variable, *slug-separator*: Exported special variables

Jump to:   %   *  
S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-slug: The cl-slug system
cl-slug: The cl-slug package

P
Package, cl-slug: The cl-slug package

S
System, cl-slug: The cl-slug system

Jump to:   C   P   S