The lyrics Reference Manual

Table of Contents

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

The lyrics Reference Manual

This is the lyrics Reference Manual, version 0.1, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:10:42 2019 GMT+0.


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

1 Introduction

lyrics

Search song lyrics or, the other way around, search songs from lyrics.

Installation

# clone to local-projects for quickload access
git clone https://github.com/mihaiolteanu/lyrics ~/quicklisp/local-projects/lyrics
; Register the new project
(ql:register-local-projects)
# A sqlite3 database is used to store the lyrics
sudo pacman -S sqlite3 

Usage

(ql:quickload :lyrics)

Search the lyrics given an artist and a song name

(lyrics "lake of tears" "the homecoming")
=> "It's the way of a cosmic sailor, in a boat in the night
    But the wolves are not scaring him, he's alright
    Just the day, just the day away, I can feel it sometimes
    ..."

Or, search in the local database for all the songs that contain a given string. The result is a list of artist name, song-name and the verse line that contains the input string.

(search-song "the night")
=> (("coldplay" "Cemeteries of London" "save the night time for your weeping")
    ("coldplay" "Cemeteries of London" "and the night over london lay")
    ("lake of tears" "Forever Autumn" "but the night becomes you")
    ("lake of tears" "The Homecoming" "And the night that showed them all to me?"))

API

lyrics artist song

Memoized lyrics search. Search the lyrics for the given artist and song
name. If the lyrics are not in the db, try and extract them from one of the
supported lyrics websites. If found, save the lyrics in the db and return them. If
not found, return nil.

request-lyrics list-of-artists-and-songs

Start an asynchronous request for lyrics. The argument is a list of
artist-name and song-name lists. This is a batch request for lyrics. The actual
lyrics can be later retrieved from the database since this function only returns
the thread that is started for the request.

search-song lyrics

Return a list of entries, where each entry is a list with the artist name,
the song name and the verse line where the lyrics appears. The artist name and
song can be used to request the full lyrics. There can be multiple entries for
the same artist/song combination.

Details

lyrics uses an sqlite3 database to save all the lyrics that have been searched and found so far. The database file, ~/cl-lyrics.db, is created when the library is first loaded and it is saved in the user home folder.

The following lyrics websites are currently supported and searched for lyrics:

If the song cannot be found on any of the websites, lyrics returns nil. Otherwise lyrics returns the song lyrics and saves them in the database from where they will be fetched on the next call. The lyrics function is memoized.

Authors

Copyright (c) 2019 Mihai Olteanu

Licensed under the GPLv3 license.


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 lyrics

Author

Mihai Olteanu <mihai_olteanu@fastmail.fm>

License

GPLv3

Description

Song lyrics with local database

Version

0.1

Dependencies
Source

lyrics.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 lyrics.asd

Location

lyrics.asd

Systems

lyrics (system)


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

3.1.2 lyrics/package.lisp

Parent

lyrics (system)

Location

package.lisp

Packages

lyrics


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

3.1.3 lyrics/lyrics.lisp

Dependency

package.lisp (file)

Parent

lyrics (system)

Location

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

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


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

5.1.1 Functions

Function: lyrics ARTIST SONG

Memoized lyrics search. Search the lyrics for the given artist and song name. If the lyrics are not in the db, try and extract them from one of the supported lyrics websites. If found, save the lyrics the db and return them. If not found, return nil.

Package

lyrics

Source

lyrics.lisp (file)

Function: search-song LYRICS

Return a list of entries, where each entry is a list with the artist name, the song name and the verse line where the lyrics appears. The artist name and song can be used to request the full lyrics. There can be multiple entries for the same artist/song combination.

Package

lyrics

Source

lyrics.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *db*
Package

lyrics

Source

lyrics.lisp (file)

Special Variable: *raw-websites*
Package

lyrics

Source

lyrics.lisp (file)

Special Variable: *websites*

List of structures, where each structure is a lyrics website

Package

lyrics

Source

lyrics.lisp (file)


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

5.2.2 Functions

Function: case-insensitive-regex REGEX

Transform a ’day’ string into ’[dD][aA][yY]’ for a case insensitive search.

Package

lyrics

Source

lyrics.lisp (file)

Function: copy-website INSTANCE
Package

lyrics

Source

lyrics.lisp (file)

Function: find-lyrics WEBSITE ARTIST SONG

See if this website hosts the lyrics for this artist and song. If yes, then use the css selectors to extract the lyrics. If not, return nil, and move along. Maybe other sites host them.

Package

lyrics

Source

lyrics.lisp (file)

Function: lyrics-from-db ARTIST SONG

Get the lyrics from the db, if they exists. Return nil otherwise.

Package

lyrics

Source

lyrics.lisp (file)

Function: make-website &key (NAME NAME) (URL-TEMPLATE URL-TEMPLATE) (SEPARATOR SEPARATOR) (CSS-SELECTOR CSS-SELECTOR)
Package

lyrics

Source

lyrics.lisp (file)

Function: request-lyrics LIST-OF-ARTISTS-AND-SONGS

Start an asynchronous request for lyrics. The argument is a list of artist-name and song-name lists. This is a batch request for lyrics. The actual lyrics can be later retrieved from the database since this function only returns the thread that is started for the request.

Package

lyrics

Source

lyrics.lisp (file)

Function: save-lyrics-to-db ARTIST SONG LYRICS

Save the lyrics for future retrieval and return them.

Package

lyrics

Source

lyrics.lisp (file)

Function: setup-db ()

Create a sqlite table in ~/ if one does not already exist.

Package

lyrics

Source

lyrics.lisp (file)

Function: url WEBSITE ARTIST SONG

Create a valid url from the website pattern. First, the artist and song string must be prepared by replacing the spaces with the website separator and then the final url is prepared by replacing the aritst-name and song-name in the template.

Package

lyrics

Source

lyrics.lisp (file)

Function: website-css-selector INSTANCE
Function: (setf website-css-selector) VALUE INSTANCE
Package

lyrics

Source

lyrics.lisp (file)

Function: website-name INSTANCE
Function: (setf website-name) VALUE INSTANCE
Package

lyrics

Source

lyrics.lisp (file)

Function: website-p OBJECT
Package

lyrics

Source

lyrics.lisp (file)

Function: website-separator INSTANCE
Function: (setf website-separator) VALUE INSTANCE
Package

lyrics

Source

lyrics.lisp (file)

Function: website-url-template INSTANCE
Function: (setf website-url-template) VALUE INSTANCE
Package

lyrics

Source

lyrics.lisp (file)


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

5.2.3 Structures

Structure: website ()
Package

lyrics

Source

lyrics.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: name
Readers

website-name (function)

Writers

(setf website-name) (function)

Slot: url-template
Readers

website-url-template (function)

Writers

(setf website-url-template) (function)

Slot: separator
Readers

website-separator (function)

Writers

(setf website-separator) (function)

Slot: css-selector
Readers

website-css-selector (function)

Writers

(setf website-css-selector) (function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, lyrics.asd: The lyrics<dot>asd file
File, Lisp, lyrics/lyrics.lisp: The lyrics/lyrics<dot>lisp file
File, Lisp, lyrics/package.lisp: The lyrics/package<dot>lisp file

L
Lisp File, lyrics.asd: The lyrics<dot>asd file
Lisp File, lyrics/lyrics.lisp: The lyrics/lyrics<dot>lisp file
Lisp File, lyrics/package.lisp: The lyrics/package<dot>lisp file
lyrics.asd: The lyrics<dot>asd file
lyrics/lyrics.lisp: The lyrics/lyrics<dot>lisp file
lyrics/package.lisp: The lyrics/package<dot>lisp file

Jump to:   F   L  

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

A.2 Functions

Jump to:   (  
C   F   L   M   R   S   U   W  
Index Entry  Section

(
(setf website-css-selector): Internal functions
(setf website-name): Internal functions
(setf website-separator): Internal functions
(setf website-url-template): Internal functions

C
case-insensitive-regex: Internal functions
copy-website: Internal functions

F
find-lyrics: Internal functions
Function, (setf website-css-selector): Internal functions
Function, (setf website-name): Internal functions
Function, (setf website-separator): Internal functions
Function, (setf website-url-template): Internal functions
Function, case-insensitive-regex: Internal functions
Function, copy-website: Internal functions
Function, find-lyrics: Internal functions
Function, lyrics: Exported functions
Function, lyrics-from-db: Internal functions
Function, make-website: Internal functions
Function, request-lyrics: Internal functions
Function, save-lyrics-to-db: Internal functions
Function, search-song: Exported functions
Function, setup-db: Internal functions
Function, url: Internal functions
Function, website-css-selector: Internal functions
Function, website-name: Internal functions
Function, website-p: Internal functions
Function, website-separator: Internal functions
Function, website-url-template: Internal functions

L
lyrics: Exported functions
lyrics-from-db: Internal functions

M
make-website: Internal functions

R
request-lyrics: Internal functions

S
save-lyrics-to-db: Internal functions
search-song: Exported functions
setup-db: Internal functions

U
url: Internal functions

W
website-css-selector: Internal functions
website-name: Internal functions
website-p: Internal functions
website-separator: Internal functions
website-url-template: Internal functions

Jump to:   (  
C   F   L   M   R   S   U   W  

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

A.3 Variables

Jump to:   *  
C   N   S   U  
Index Entry  Section

*
*db*: Internal special variables
*raw-websites*: Internal special variables
*websites*: Internal special variables

C
css-selector: Internal structures

N
name: Internal structures

S
separator: Internal structures
Slot, css-selector: Internal structures
Slot, name: Internal structures
Slot, separator: Internal structures
Slot, url-template: Internal structures
Special Variable, *db*: Internal special variables
Special Variable, *raw-websites*: Internal special variables
Special Variable, *websites*: Internal special variables

U
url-template: Internal structures

Jump to:   *  
C   N   S   U  

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

A.4 Data types

Jump to:   L   P   S   W  
Index Entry  Section

L
lyrics: The lyrics system
lyrics: The lyrics package

P
Package, lyrics: The lyrics package

S
Structure, website: Internal structures
System, lyrics: The lyrics system

W
website: Internal structures

Jump to:   L   P   S   W