lyrics 0.0.2

data/lib/lyrics/itrans/COPYRIGHT

@@ -0,0 +1,31 @@
+/*
+ * ITRANS software
+ *========================================================================== 
+ * Copyright 1991--2001  Avinash Chopde, All Rights Reserved.
+ *
+ * Permission to use, copy, modify and distribute this software and its
+ * documentation for any purpose is hereby granted without fee, provided that
+ * the above copyright notice appear in all copies and that both that
+ * copyright notice and this permission notice appear in supporting
+ * documentation, and that the name of Avinash Chopde not be used in
+ * advertising or publicity pertaining to distribution of the software
+ * without specific, written prior permission.
+ * Avinash Chopde makes no representations about the suitability of this
+ * software for any purpose.
+ * It is provided "as is" without express or implied warranty.
+ *
+ * AVINASH CHOPDE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,
+ * IN NO EVENT SHALL AVINASH CHOPDE BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+ * OF THIS SOFTWARE.
+ *
+ * Author:  Avinash Chopde
+ *	    e-mail: avinash@acm.org
+ *	    home page: http://www.aczone.com/itrans/
+ *
+ If this package contains any other copyrighted material, the appropriate
+ notice has been included in such units.
+ */

data/lib/lyrics/itrans/itrans.txt

@@ -0,0 +1,8 @@
+#indianifm=udvng.ifm
+
+#indian
+मिलती ह नज़रो स जब नज़र
+होता ह दिल प असर
+हा मिल जाए दिल स अगर दिल
+तो मिलत ह दो हमसफ़र
+#endindian

data/lib/lyrics/itrans/lyric.txt

@@ -0,0 +1,23 @@
+#indianifm=udvng.ifm
+#indian
+%
+##baby baby baby baby baby baby##
+shaa naa naa
+sun baabaa sun baabaa dil kaa kyaa kahanaa
+shaa naa naa \threedots
+
+##reason## hai kuchh gul khilaa naa
+##season## bhii hai aashiqaanaa
+haay aise me.n dil diivaanaa bas me.n kahaa.N
+##take it easy, baby##
+aavaaraa cha.nchal havaa_o.n pe chhaa_ii hai.n madahoshiyaa.N
+aise me.n ko_ii jo kho jaa_e ho jaa_e.n dil kii choriyaa.n
+shaa naa naa \threedots
+
+milatii hai.n nazaro.n se jab nazare.n
+hotaa hai dil pe asar
+haa.n mil jaa_e dil se agar dil
+to milate hai.n do hamasafar
+shaa naa naa \threedots
+%
+#endindian

data/lib/lyrics/itrans/udvng.ifm

@@ -0,0 +1,206 @@
+Comment * ITRANS IFM file for Unicode Output
+Comment *===================================================================
+Comment * Copyright 2001   Avinash Chopde, All Rights Reserved.
+Comment *
+Comment * Author:  Avinash Chopde <avinash@acm.org> http://www.aczone.com/
+Comment ===================================================================
+% ------------- Instructions for Creating ITRANS IFM files for Unicode 
+% The following page has Unicode ranges for all languages, and
+% includes both Decimal and Hexadecimal values:
+%           http://www.hclrss.demon.co.uk/unicode/devanagari.html
+% For ITRANS tables, visit the online documents at:
+%           http://www.aczone.com/itrans/#onlinedocs
+%
+% The PCC <charcode> ... statements below accept either Decimal or
+% Hexadecimal, so both of these are identical:
+% PCC 2309 0 0 ;
+% is same as:
+% PCC 0x0905 0 0 ;
+% [note: hex numbers must be preceed with "0x", decimal numbers must not
+%  have leading 0's - leading 0's imply that the number is octal]
+% ------------- 
+Comment ===================================================================
+
+itrans: StartINDIAN
+itrans: TEXT_UNICODE sanskrit
+itrans: DEFAULTVOWEL a ;
+
+% These are in Unicode, but not used by ITRANS:
+% 2317 090D DEVANAGARI LETTER CANDRA E 
+% 2318 090E DEVANAGARI LETTER SHORT E 
+% 2321 0911 DEVANAGARI LETTER CANDRA O 
+% 2322 0912 DEVANAGARI LETTER SHORT O 
+% 2356 0934 DEVANAGARI LETTER LLLA  (lda-dot)
+% danda, double danda, nukta, udatta, anudatta, abbreviation sign
+
+itrans: Comment The Vowels - Independent Vowels in Unicode
+
+itrans: CC a 1 ; PCC 2309 0 0 ;
+itrans: CC aa 1 ; PCC 2310 0 0 ;
+itrans: CC i 1 ; PCC 2311 0 0 ;
+itrans: CC ii 1 ; PCC 2312 0 0 ;
+itrans: CC u 1 ; PCC 2313 0 0 ;
+itrans: CC uu 1 ; PCC 2314 0 0 ;
+itrans: CC ri 1 ; PCC 2315 0 0 ;
+itrans: CC rii 1 ; PCC 2400 0 0 ;
+itrans: CC li 1 ; PCC 2316 0 0 ;
+itrans: CC lii 1 ; PCC 2401 0 0 ;
+itrans: CC ay 1 ; PCC 2319 0 0 ; 
+% itrans: CC aay 1 ; % Telugu, etc only ( E ) ?
+itrans: CC aay 1 ; PCC 2319 0 0 ; 
+itrans: CC ai 1 ; PCC 2320 0 0 ;
+itrans: CC o 1 ; PCC 2323 0 0 ;
+% itrans: CC oo 1 ;  % Telugu, etc only ( O ) ?
+itrans: CC oo 1 ; PCC 2323 0 0 ;
+itrans: CC au 1 ; PCC 2324 0 0 ;
+itrans: CC am 2 ; PCC 2309 0 0 ; PCC 2306 0 0 ;
+itrans: CC aha 1 ; PCC 2307 0 0 ; % just visarga
+
+itrans: Comment The Template - use Dependent Vowels as defined in Unicode
+
+itrans: CCADD tmplA ;
+itrans: CC tmplA-half 2 ; PCC implicit 0 0 ; PCC 2381 0 0 ;
+itrans: CC tmplA-conjunct 2 ; PCC implicit 0 0 ; PCC 2381 0 0 ;
+itrans: CC tmplA-a 1 ; PCC implicit 0 0 ;
+itrans: CC tmplA-aa 2 ; PCC implicit 0 0 ; PCC 2366 0 0 ;
+itrans: CC tmplA-i 2 ;  PCC implicit 0 0 ; PCC 2367 0 0 ;
+itrans: CC tmplA-ii 2 ; PCC implicit 0 0 ; PCC 2368 0 0 ;
+itrans: CC tmplA-u 2 ; PCC implicit 0 0 ; PCC 2369 0 0 ;
+itrans: CC tmplA-uu 2 ; PCC implicit 0 0 ; PCC 2370 0 0 ;
+itrans: CC tmplA-ri 2 ; PCC implicit 0 0 ; PCC 2371 0 0 ;
+itrans: CC tmplA-rii 2 ; PCC implicit 0 0 ; PCC 2372 0 0 ;
+itrans: CC tmplA-li 2 ; PCC implicit 0 0 ; PCC 2402 0 0 ;
+itrans: CC tmplA-lii 2 ; PCC implicit 0 0 ; PCC 2403 0 0 ;
+itrans: CC tmplA-ay 2 ; PCC implicit 0 0 ; PCC 2375 0 0 ;
+itrans: CC tmplA-aay 2 ; PCC implicit 0 0 ; PCC 2375 0 0 ;
+itrans: CC tmplA-ai 2 ; PCC implicit 0 0 ; PCC 2376 0 0 ;
+itrans: CC tmplA-o 2 ; PCC implicit 0 0 ; PCC 2379 0 0 ;
+itrans: CC tmplA-oo 2 ; PCC implicit 0 0 ; PCC 2379 0 0 ;
+itrans: CC tmplA-au 2 ; PCC implicit 0 0 ; PCC 2380 0 0 ;
+itrans: CC tmplA-am 2 ; PCC implicit 0 0 ; PCC 2306 0 0 ;
+itrans: CC tmplA-aha 2 ; PCC implicit 0 0 ; PCC 2307 0 0 ;
+
+itrans: Comment The Consonants - in Unicode, all are full consonants
+
+itrans: CCS ka tmplA ;
+itrans: CC ka-implicit 1 ; PCC 2325 0 0 ;
+itrans: CCS kadot ka ;
+itrans: CC kadot-implicit 1 ; PCC 2392 0 0 ;
+itrans: CCS kha tmplA ;
+itrans: CC kha-implicit 1 ; PCC 2326 0 0 ;
+itrans: CCS khadot kha ;
+itrans: CC khadot-implicit 1 ; PCC 2393 0 0 ;
+itrans: CCS ga tmplA ;
+itrans: CC ga-implicit 1 ; PCC 2327 0 0 ;
+itrans: CCS gadot ga ;
+itrans: CC gadot-implicit 1 ; PCC 2394 0 0 ;
+itrans: CCS gha tmplA ;
+itrans: CC gha-implicit 1 ; PCC 2328 0 0 ;
+itrans: CCS nga tmplA ;
+itrans: CC nga-implicit 1 ; PCC 2329 0 0 ;
+itrans: CCS cha tmplA ;
+itrans: CC cha-implicit 1 ; PCC 2330 0 0 ;
+itrans: CCS chha tmplA ;
+itrans: CC chha-implicit 1 ; PCC 2331 0 0 ;
+itrans: CCS ja tmplA ;
+itrans: CC ja-implicit 1 ; PCC 2332 0 0 ;
+itrans: CCS jadot ja ;
+itrans: CC jadot-implicit 1 ; PCC 2395 0 0 ;
+itrans: CCS jha tmplA ;
+itrans: CC jha-implicit 1 ; PCC 2333 0 0 ;
+itrans: CCS jnh tmplA ;
+itrans: CC jnh-implicit 1 ; PCC 2334 0 0 ;
+itrans: CCS tta tmplA ;
+itrans: CC tta-implicit 1 ; PCC 2335 0 0 ;
+itrans: CCS ttha tmplA ;
+itrans: CC ttha-implicit 1 ; PCC 2336 0 0 ;
+itrans: CCS dda tmplA ;
+itrans: CC dda-implicit 1 ; PCC 2337 0 0 ;
+itrans: CCS ddadot tmplA ;
+itrans: CC ddadot-implicit 1 ; PCC 2396 0 0 ;
+itrans: CCS ddha tmplA ;
+itrans: CC ddha-implicit 1 ; PCC 2338 0 0 ;
+itrans: CCS ddhadot ddadot ;
+itrans: CC ddhadot-implicit 1 ; PCC 2397 0 0 ;
+itrans: CCS nna tmplA ;
+itrans: CC nna-implicit 1 ; PCC 2339 0 0 ;
+itrans: CCS ta tmplA ;
+itrans: CC ta-implicit 1 ; PCC 2340 0 0 ;
+itrans: CCS tha tmplA ;
+itrans: CC tha-implicit 1 ; PCC 2341 0 0 ;
+itrans: CCS da tmplA;
+itrans: CC da-implicit 1 ; PCC 2342 0 0 ;
+itrans: CCS dha tmplA ;
+itrans: CC dha-implicit 1 ; PCC 2343 0 0 ;
+itrans: CCS na tmplA ;
+itrans: CC na-implicit 1 ; PCC 2344 0 0 ;
+itrans: CCS nnx tmplA ; % Tamil, etc only? ( ^n )
+itrans: CC nnx-implicit 1 ; PCC 2345 0 0 ; % Devanagari: used as na-dot NNNA
+itrans: CCS pa tmplA ;
+itrans: CC pa-implicit 1 ; PCC 2346 0 0 ;
+itrans: CCS pha tmplA ;
+itrans: CC pha-implicit 1 ; PCC 2347 0 0 ;
+itrans: CCS phadot pha ;
+itrans: CC phadot-implicit 1 ; PCC 2398 0 0 ;
+itrans: CCS ba tmplA ;
+itrans: CC ba-implicit 1 ; PCC 2348 0 0 ;
+itrans: CCS bha tmplA ;
+itrans: CC bha-implicit 1 ; PCC 2349 0 0 ;
+itrans: CCS ma tmplA ;
+itrans: CC ma-implicit 1 ; PCC 2350 0 0 ;
+itrans: CCS ya tmplA ;
+itrans: CC ya-implicit 1 ; PCC 2351 0 0 ;
+itrans: CCS yya tmplA ; % Devanagari: used as ya-dot
+itrans: CC yya-implicit 1 ; PCC 2399 0 0 ;
+itrans: CCS ra tmplA ;
+itrans: CC ra-implicit 1 ; PCC 2352 0 0 ;
+itrans: CCS rra tmplA ; 
+itrans: CC rra-implicit 1 ; PCC 2353 0 0 ;  % RRA ra-dot
+itrans: CCS la tmplA ;
+itrans: CC la-implicit 1 ; PCC 2354 0 0 ;
+itrans: CCS va tmplA ;
+itrans: CC va-implicit 1 ; PCC 2357 0 0 ;
+itrans: CCS sha tmplA ;
+itrans: CC sha-implicit 1 ; PCC 2358 0 0 ;
+itrans: CCS shha tmplA ;
+itrans: CC shha-implicit 1 ; PCC 2359 0 0 ;
+itrans: CCS sa tmplA ;
+itrans: CC sa-implicit 1 ; PCC 2360 0 0 ;
+itrans: CCS ha tmplA ;
+itrans: CC ha-implicit 1 ; PCC 2361 0 0 ;
+itrans: CCS lda tmplA ;
+itrans: CC lda-implicit 1 ; PCC 2355 0 0 ;
+itrans: CCS ksha tmplA ; % ka-shha
+itrans: CC ksha-implicit 3 ; PCC 2325 0 0 ; PCC 2381 0 0 ; PCC 2359 0 0 ;
+itrans: CCS gya tmplA ;  % ja-jnh  Unicode JA-NYA
+itrans: CC gya-implicit 3 ; PCC 2332 0 0 ; PCC 2381 0 0 ; PCC 2334 0 0 ;
+
+itrans: Comment The Specials (Incomplete support in ITRANS)
+
+itrans: CC anusvara-implicit 1 ; PCC 2306 0 0 ;
+itrans: CC chandra-implicit 1 ; PCC 2373 0 0 ; % 2373=CANDRA E, 2374=SHORT E
+itrans: CC chandrabindu-implicit 1 ; PCC 2305 0 0 ;
+itrans: CC aum-implicit 1 ; PCC 2384 0 0 ;
+itrans: CC viraam-implicit 1 ; PCC 2381 0 0 ;
+itrans: CC avagraha-implicit 1 ; PCC 2365 0 0 ;
+% itrans: CC sri-implicit 1 ; PCC 244 0 0 ; % Tamil only?
+
+% rahalf ( ^r or .r ) is a hack that was used in ITRANS, for the
+% half-chandra-ra superscript, it would be very tricky to have it supported
+% here, the best option is to avoid rahalf in the input. Use normal ra instead,
+% i.e, instead of ga.r  use rga in the input.
+itrans: CC rahalf-implicit 2 ; PCC 2352 0 0 ; PCC 2381 0 0 ; % Devanagari only?
+
+itrans: Comment ----------- Digits
+itrans: CC zero 1 ; PCC 2406 0 0 ;
+itrans: CC one 1 ; PCC 2407 0 0 ;
+itrans: CC two 1 ; PCC 2408 0 0 ;
+itrans: CC three 1 ; PCC 2409 0 0 ;
+itrans: CC four 1 ; PCC 2410 0 0 ;
+itrans: CC five 1 ; PCC 2411 0 0 ;
+itrans: CC six 1 ; PCC 2412 0 0 ;
+itrans: CC seven 1 ; PCC 2413 0 0 ;
+itrans: CC eight 1 ; PCC 2414 0 0 ;
+itrans: CC nine 1 ; PCC 2415 0 0 ;
+
+itrans: EndINDIAN

data/lib/lyrics/lyrics.rb

@@ -0,0 +1,567 @@
+# Copyright (C) 2006-2008 by Sergio Pistone
+# sergio_pistone@yahoo.com.ar
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the
+# Free Software Foundation, Inc.,
+# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+$LOAD_PATH << File.expand_path(File.dirname(__FILE__))
+
+require "utils/logger"
+require "utils/strings"
+require "utils/http"
+
+$VERBOSE_LOG = false
+
+def debug( message )
+	system( "kdialog", "--msgbox", "<qt>" + message.to_s().gsub( "\n", "<br />" ) + "</qt>" )
+end
+
+class Lyrics
+
+	class Request
+
+		attr_reader :artist, :title, :album, :year, :fetch_data
+		attr_writer :fetch_data
+
+		def initialize( artist, title, album=nil, year=nil )
+			raise "target artist and title values can't be nil" if ! artist || ! title
+			@artist = artist.clone().freeze()
+			@title = title.clone().freeze()
+			@album = album ? album.clone().freeze() : nil
+			@year = year ? year.to_s().strip().to_i() : nil
+			@fetch_data = nil
+		end
+
+		def to_s()
+			ret = " - request artist: #{@artist}\n - request title: #{@title}"
+			ret << "\n - request album: #{@album}" if @album
+			ret << "\n - request year: #{@year}" if @year
+			return ret
+		end
+
+	end
+
+	class Response
+
+		attr_reader :request, :artist, :title, :album, :year, :lyrics, :url, :custom_data #, :suggestions
+		attr_writer :url
+
+		def initialize( request )
+			raise "request can't be nil" if ! request
+			@request = request
+			@artist = nil
+			@title = nil
+			@album = nil
+			@year = nil
+			@lyrics = nil
+			@custom_data = {}
+		end
+
+		def to_s()
+			ret = ""
+			ret << "\n - response artist: #{@artist}" if @artist
+			ret << "\n - response title: #{@title}" if @title
+			ret << "\n - response album: #{@album}" if @album
+			ret << "\n - response year: #{@year}" if @year
+			if @custom_data.size > 0
+				ret << "\n - response custom data:"
+				@custom_data.each { |key, val| ret << "\n    - #{key}: #{val}" }
+			end
+			return ret.size > 0 ? ret.slice( 1..-1 ) : ret
+		end
+
+		def each_modified!()
+			yield "artist", @artist if artist_modified?()
+			yield "title", @title if title_modified?()
+			yield "album", @album if album_modified?()
+			yield "year", @year if year_modified?()
+		end
+
+		def each_modified()
+			each_modified!() { |k, v| yield k, v.clone() }
+		end
+
+		def artist_modified?()
+			return @artist && @artist != request.artist
+		end
+
+		def artist=( artist )
+			@artist = artist ? artist.to_s().strip().freeze() : nil
+		end
+
+		def title_modified?()
+			return @title && @title != request.title
+		end
+
+		def title=( title )
+			@title = title ? title.to_s().strip().freeze() : nil
+		end
+
+		def album_modified?()
+			return @album && @album != request.album
+		end
+
+		def album=( album )
+			@album = album ? album.to_s().strip().freeze() : nil
+		end
+
+		def year_modified?()
+			return @year && @year != request.year
+		end
+
+		def year=( year )
+			if year
+				year = year.to_s().strip().to_i()
+				if year > 1900
+					@year = year
+				else
+					@year = nil
+				end
+			else
+				@year = nil
+			end
+		end
+
+		def lyrics=( lyrics )
+			@lyrics = Strings.decode_htmlentities!( lyrics.to_s() ).strip().freeze()
+			@lyrics = nil if @lyrics.empty?
+		end
+
+		def custom_data=( custom_data )
+			raise "custom_data value must be a hash" if ! custom_data.is_a?( Hash )
+			@custom_data = {}
+			custom_data.each() { |k, v| @custom_data[k] = v.is_a?( String ) ? v.clone().freeze() : v }
+			@custom_data.freeze()
+		end
+
+	end
+
+	class Suggestion
+
+		attr_reader :url, :artist, :title
+
+		def initialize( artist, title, url )
+			@artist = artist.clone().freeze()
+			@title = title.clone().freeze()
+			@url = url.clone.freeze()
+		end
+
+		def to_s()
+			return "art: #{artist} | tit: #{title} | url: #{url}"
+		end
+
+	end
+
+	class FetchPageData
+
+		attr_reader :url, :post_data, :headers_data
+
+		def initialize( url, post_data=nil, headers_data=nil )
+			@url = url.freeze()
+			if post_data && post_data.size > 0
+				@post_data = post_data.clone().freeze()
+				@post_data.each() do |key|
+					@post_data[key] = @post_data[key].clone().freeze() if @post_data[key]
+				end
+			else
+				@post_data = nil
+			end
+			if headers_data && headers_data.size > 0
+				@headers_data = headers_data.clone().freeze()
+				@headers_data.each() do |key|
+					@headers_data[key] = @headers_data[key].clone().freeze() if @headers_data[key]
+				end
+			else
+				@headers_data = nil
+			end
+		end
+
+		def to_s()
+			ret = " - fetch url: #{@url}"
+			if @post_data
+				ret << "\n - fetch post data:"
+				@post_data.each { |key, val| ret << "\n    - #{key}: #{val}" }
+			end
+			if @headers_data
+				ret << "\n - fetch headers data:"
+				@headers_data.each { |key, val| ret << "\n    - #{key}: #{val}" }
+			end
+			return ret
+		end
+
+	end
+
+	attr_reader :cleanup_lyrics
+	attr_writer :cleanup_lyrics
+
+	def initialize( cleanup_lyrics=true, logger=nil )
+		super()
+		@cleanup_lyrics = cleanup_lyrics
+		@logger = logger
+		@tabulation = nil
+		@skip_tabulation = false
+	end
+
+	def log?()
+		return @logger != nil
+	end
+
+	def verbose_log?()
+		return log? && $VERBOSE_LOG
+	end
+
+	def logger=( logger )
+		@logger = logger
+	end
+
+	def log( message, new_lines=1 )
+		@logger.log( message, new_lines ) if @logger
+	end
+
+	def increase_tabulation_level()
+		@logger.increase_tabulation_level() if @logger
+	end
+
+	def decrease_tabulation_level()
+		@logger.decrease_tabulation_level() if @logger
+	end
+
+	def site_host()
+		return self.class.site_host()
+	end
+
+	def site_name()
+		return self.class.site_name()
+	end
+
+	def Lyrics.build_song_add_url( request )
+		return nil
+	end
+
+	def build_song_add_url( request )
+		return self.class.build_song_add_url( request )
+	end
+
+	def Lyrics.known_url?( url )
+		return url.index( "http://#{site_host}" ) == 0
+	end
+
+	def known_url?( url )
+		return self.class.known_url?( url )
+	end
+
+	def notify( message )
+		puts "#{site_name()}: #{message}"
+	end
+
+	# Returns a FetchPageData instance
+	def build_lyrics_fetch_data( request )
+		return FetchPageData.new( nil )
+	end
+
+	# Returns the lyrics page body (or nil if it couldn't be retrieved) and the corresponding url (or nil)
+	def fetch_lyrics_page( fetch_data )
+
+		return nil, nil if ! fetch_data.url
+
+		log( "Fetching lyrics page... ", 0 )
+		if fetch_data.post_data
+			response, url = HTTP.fetch_page_post( fetch_data.url, fetch_data.post_data, fetch_data.headers_data )
+		else
+			response, url = HTTP.fetch_page_get( fetch_data.url, fetch_data.headers_data )
+		end
+
+		if response && response.body()
+			log( "OK" )
+			log( response.body(), 2 ) if verbose_log?
+			return response.body(), url
+		else
+			log( "ERROR" )
+			return nil, url
+		end
+
+	end
+
+	# NOTE: override for example if your using google feeling lucky to verify that
+	# the resulting page is not just some random (trashy) result.
+	# Returns false is page_body does not correspond to the requested lyrics
+	def lyrics_page_valid?( request, page_body, page_url )
+		return true
+	end
+
+	# NOTE: implement in subclasses
+	# Must fill the relevante response properties (lyrics, [artist, title, album, year, custom_data])
+	# def parse_lyrics( response, page_body )
+	# end
+
+	# Returns a Lyrics::Response object
+	def lyrics_direct_search( request )
+
+		fetch_data = build_lyrics_fetch_data( request )
+
+		log(
+			site_name().upcase() + "\n" +
+			"Attempting LYRICS DIRECT SEARCH...\n" +
+			request.to_s() + "\n" +
+			fetch_data.to_s()
+		)
+
+		page_body, page_url = fetch_lyrics_page( fetch_data )
+
+		response = Response.new( request )
+
+		if page_body
+			if lyrics_page_valid?( request, page_body, page_url )
+				log( "Parsing lyrics... ", 0 )
+				response.url = page_url
+				parse_lyrics( response, page_body )
+				log( response.lyrics ? "LYRICS FOUND" : "LYRICS NOT FOUND" )
+				log( response.to_s() )
+				log( " - parsed lyrics:\n[#{lyrics_data.lyrics}" ) if verbose_log?
+				response.lyrics = Strings.cleanup_lyrics( response.lyrics ) if response.lyrics && @cleanup_lyrics
+			else
+				log( "LYRICS PAGE IS INVALID" )
+			end
+		end
+
+		return response
+
+	end
+
+	# Returns a Lyrics::Response object
+	def lyrics_from_url( request, url )
+
+		response = Response.new( request )
+
+		if ! known_url?( url )
+			log( site_name().upcase() + "\nCan't handle received URL: " + url )
+			return response
+		end
+
+		fetch_data = build_lyrics_fetch_data( request )
+		fetch_data = FetchPageData.new( url, fetch_data.post_data, fetch_data.headers_data )
+
+		log(
+			site_name().upcase() + "\n" +
+			"Retrieving LYRICS FROM URL...\n" +
+			request.to_s() + "\n" +
+			fetch_data.to_s()
+		)
+
+		page_body, url = fetch_lyrics_page( fetch_data )
+
+		if page_body
+			log( "Parsing lyrics... ", 0 )
+			response.url = url
+			parse_lyrics( response, page_body )
+			log( response.lyrics ? "LYRICS FOUND" : "LYRICS NOT FOUND" )
+			log( response.to_s() )
+			log( " - parsed lyrics:\n[#{lyrics_data.lyrics}]" ) if verbose_log?
+			response.lyrics = Strings.cleanup_lyrics( response.lyrics ) if response.lyrics && @cleanup_lyrics
+		end
+
+		return response
+
+	end
+
+	# Returns a FetchPageData instance
+	def build_suggestions_fetch_data( request )
+		return FetchPageData.new( nil )
+	end
+
+	# Returns the lyrics page body (nil if it couldn't be retrieved) and the response url
+	def fetch_suggestions_page( fetch_data )
+
+		return nil, nil if ! fetch_data.url
+
+		log( fetch_data.to_s() + "\nFetching suggestions page... ", 0 )
+
+		if fetch_data.post_data
+			response, url = HTTP.fetch_page_post( fetch_data.url, fetch_data.post_data, fetch_data.headers_data )
+		else
+			response, url = HTTP.fetch_page_get( fetch_data.url, fetch_data.headers_data )
+		end
+
+		if response && response.body()
+			log( "OK" )
+			log( response.body(), 2 ) if verbose_log?
+			return response.body(), url
+		else
+			log( "ERROR" )
+			return nil, url
+		end
+
+	end
+
+	# NOTE: override for example if your using google feeling lucky to verify that
+	# the resulting page is not just some random (trashy) result.
+	# Returns false is body does not correspond to the required suggestions page
+	def suggestions_page_valid?( request, page_body, page_url )
+		return true
+	end
+
+	# NOTE: implement in subclasses
+	# Returns an array of Suggestion objects
+	# def parse_suggestions( request, page_body, page_url )
+	# 	return []
+	# end
+
+	# Returns an array of maps { url, artist, title }
+	def suggestions( request )
+
+		log( site_name().upcase() + "\nRetrieving SUGGESTIONS...\n" + request.to_s() )
+
+		fetch_data = build_suggestions_fetch_data( request )
+		suggestions = []
+
+		suggestions_rec( request, fetch_data, suggestions, 0 )
+
+		return suggestions
+
+	end
+
+	def suggestions_rec( request, fetch_data, cumulative_suggestions, recursion_level )
+
+		page_body, page_url = fetch_suggestions_page( fetch_data )
+		return if page_body == nil
+
+		if suggestions_page_valid?( request, page_body, page_url )
+
+			log( "Parsing suggestions...", 0 )
+			suggestions = parse_suggestions( request, page_body, page_url )
+
+			if ! suggestions.is_a?( Array )
+				log( " INVALID RESPONSE FROM PARSE_SUGGESTIONS" )
+				return
+			end
+
+			if suggestions.empty?
+				log( " NO SUGGESTIONS FOUND" )
+				return
+			else
+				log( "" )
+			end
+
+			suggestions.each() do |suggestion|
+				if suggestion.is_a?( FetchPageData )
+					log( " - url: #{suggestion.url}" )
+					increase_tabulation_level()
+					log( "Retrieving SUGGESTIONS LEVEL#{recursion_level+2}..." )
+					suggestions_rec( request, suggestion, cumulative_suggestions, recursion_level + 1 )
+					decrease_tabulation_level()
+				else
+					log( " - #{suggestion.to_s()}" )
+					cumulative_suggestions << suggestion
+				end
+			end
+
+		else
+			log( "SUGGESTIONS PAGE IS INVALID" )
+		end
+
+	end
+	protected :suggestions_rec
+
+
+	def lyrics_from_suggestions( request, suggestions=nil )
+
+		log( site_name().upcase() + "\nSearching LYRICS FROM SUGGESTIONS..." )
+
+		suggestions = suggestions( request ) if suggestions == nil
+
+		normalized_artist, normalized_title = Strings.normalize( request.artist ), Strings.normalize( request.title )
+
+		log( "Scanning suggestions... ", 0 )
+		suggestions.each() do |suggestion|
+			next if ! suggestion.is_a?( Suggestion )
+			if Strings.normalize( suggestion.artist ) == normalized_artist &&
+			   Strings.normalize( suggestion.title ) == normalized_title
+				log( "MATCH FOUND\n" + suggestion.to_s() )
+				# TODO should we use request.album and request.year here?
+				response = lyrics_from_url(
+					Request.new( suggestion.artist, suggestion.title, request.album, request.year ),
+					suggestion.url
+				)
+				return response, suggestions if response.lyrics
+			end
+		end
+
+		log( "NO VALID MATCH FOUND" )
+
+		return Response.new( request ), suggestions
+
+	end
+
+	# Returns a Lyrics::Response object
+	def lyrics_full_search( request )
+
+		# LYRICS DIRECT SEARCH:
+		response = lyrics_direct_search( request )
+		return response if response.lyrics
+
+		# NOT FOUND, SEARCH IN SUGGESTIONS:
+		response, suggs = lyrics_from_suggestions( request, suggestions( request ) )
+		return response
+	end
+
+	# default implementation, overide if there is a more accurate expression for a specific site
+	def Lyrics.build_google_feeling_lucky_url( artist, title=nil )
+		query = Strings.google_search_quote( artist )
+		query << " " << Strings.google_search_quote( title ) if title
+		query << " lyrics"
+		return Strings.build_google_feeling_lucky_url( query, self.site_host() )
+	end
+
+	def build_google_feeling_lucky_url( artist, title=nil )
+		return self.class.build_google_feeling_lucky_url( artist, title )
+	end
+
+	# NOTE: if possible use popular song that are likely to be indexed by google.
+	# We are not testing here how good or complete a site is but if the site plugin
+	# is behaving as expected. We part from the assumption that every plugin should
+	# be able to get lyrics and suggestions for the values returned here.
+	def Lyrics.lyrics_test_data()
+		return [
+			Request.new( "Nirvana", "Smells Like Teen Spirit", "Nevermind" ),
+			Request.new( "Radiohead", "Optimistic", "Kid A" ),
+			Request.new( "Massive Attack", "Protection", "Protection" ),
+			Request.new( "Pearl Jam", "Porch", "Ten" ),
+# 			Request.new( "The Cranberries", "Linger", "Everybody Else Is Doing It, So Why Can't We?" ),
+# 			Request.new( "Radiohead", "Idioteque", "Kid A" ),
+# 			Request.new( "Radiohead", "How To Disappear Completely","stitle"=>"How To Dissapear", "Kid A" ),
+# 			Request.new( "Pearl Jam", "Love Boat Captain", "Riot Act" ),
+# 			Request.new( "Blur", "No Distance Left To Run", "13" ),
+# 			Request.new( "Opeth", "Hope Leaves", "Damnation" ),
+# 			Request.new( "Megadeth", "À tout le monde", "Youthanasia" ),
+# 			Request.new( "Metallica", "Master of Puppets", "Master of Puppets" ),
+# 			Request.new( "Lacuna Coil", "Heaven's a Lie", "Comalies" ),
+# 			Request.new( "Pearl Jam", "Porch", "Ten" ),
+# 			Request.new( "Portishead", "Wandering Star", "Dummy" ),
+		]
+	end
+
+	def lyrics_test_data()
+		return self.class.lyrics_test_data()
+	end
+
+	def Lyrics.suggestions_test_data()
+		return lyrics_test_data()
+	end
+
+	def suggestions_test_data()
+		return self.class.suggestions_test_data()
+	end
+
+end