'This file contains useful snippets of code that can speed up the process
'of writing your own scripts.


#####################
# Utility functions #
#####################
'Simple function that wraps the logging method so you have to do less typing
Function Log(Msg)
	SongInfo.Log(Msg)
End Function

'Remove the EOL and LF characters from a string
'Usage: cleanLine = TrimLineFeed(sourceLine)
Function TrimLineFeed(sLine)
	sLine = Replace(sLine,Chr(13),"")
	sLine = Replace(sLine,Chr(10),"")
	TrimLineFeed = sLine
End Function

'Converts time string into milliseconds
'Expected formats:
'	hh:mm:ss
'	h:mm:ss
'	mm:ss
'	m:ss
'	ss
'	s
'	mm:ss.mls
'Usage examples:
' duration = TimeStrToDuration("0:03:56")
' duration = TimeStrToDuration("03:56")
' duration = TimeStrToDuration("3:56")
' duration = TimeStrToDuration("56")
' duration = TimeStrToDuration("03:56.123") NOTE: Milliseconds are simply ignored in this case
Function TimeStrToDuration(timeStr)
 const SepChar = ":"
 Dim P
 Dim Duration
 Dim Params(20)
 Dim ParamCount

	'Firstly lets clean up the string. Make sure there are no spaces or other white space
	'Also add one more SepChar to the end (Just makes our while loop simpler)
	timeStr = Trim(timeStr) & SepChar

	'Split out each value
	ParamCount = 0
	P = InStr(timeStr, SepChar)
	While (P > 0)
		Params(ParamCount) = Mid(timeStr,1,P-1)
		ParamCount = ParamCount + 1
		timeStr = Mid(timeStr,P+1,Len(timeStr))
		P = InStr(timeStr, SepChar)
	Wend

	'Calculate duration
	If ParamCount = 1 Then
	  Duration = int(Params(0))*1000 'seconds only
	ElseIf ParamCount = 2 Then
	  Duration = (((int(Params(0))*60) + (int(Params(1))))*1000) 'minutes and seconds
	ElseIf ParamCount = 3 Then
	  Duration = (((int(Params(0))*60*60) + (int(Params(1))*60) + (int(Params(2))))*1000) 'hours, minutes and seconds
	Else
	  SongInfo.Log("Unexpected time format.")
	  Duration = -1
	End If
	TimeStrToDuration = Duration
End Function

'Add a new parameter value and increase the counter
'NOTE: White space is removed from Data
Function AddParam(Data, ByRef Params, ByRef ParamCount)
  Data = Trim(Data)
  SongInfo.Log("Param" & ParamCount & ": " & Data)
  Params(ParamCount) = Data
  ParamCount = ParamCount + 1
End Function


'Extract data from specific position in the source line
'Usage: data = ExtractRange(sLine, 10, 5, True)
Function ExtractRange(sLine, start, length, doTrim)
 Dim tmp
	tmp = Mid(sLine, start, length)
	If DoTrim Then
		tmp = Trim(tmp)
	End If
	ExtractRange = tmp
End Function

'Extract the data between two string values
'Usage: data = ExtractTagValue(sLine,"<tag>","</tag>") 'sLine is: <xml><tag>data</tag></xml>
'Usage: data = ExtractTagValue(sLine,"artist=","&")    'sLine is: &title=Test&artist=Test&
Function ExtractTagValue(sLine, tagStart, tagClose)
 Dim P1,P2
 Dim Data

	Data = ""

	P1 = InStr(sLine, tagStart) + Len(tagStart)
	If (P1>0) Then
		Data = Mid(sLine, P1, Len(sLine))
		P2 = InStr(Data, tagClose)
		If (P2>0) Then
			Data = Mid(Data, 1, P2-1)
		End If
	End If
	ExtractTagValue = Data
End Function

########################
# HandleLine templates #
########################
'This is a simple handler that expects ALL the data to arrive in a single event.
'This is not ALWAYS the case though! Some Serial and TCP data arrive in 2 or more parts.
'In MOST cases though the data arrives as one event.
Function HandleLine(sLine)
 Dim Params(20)
 Dim ParamCount

	Log("Line-in: " & sLine)
	ExtractParams sLine, Params, ParamCount
	ProcessParams Params, ParamCount
	HandleLine = ""

End Function

'Data events are separated via a known separator character
'In this case the character is ^
'NOTE: We also strip out any potential CR and LF characters, just in case (\n\r)
'This handler could handle data in this form:
'Metallica|Until it sleeps|S|340000^Advertisement|Dial Direct Insurance|A|60000^
Function HandleLine(sLine)
 const  RecordEnd = "^"
 Dim P
 Dim Data
 Dim Params(20)
 Dim ParamCount

	Log("Line-in: " & sLine)
	sLine = TrimLineFeed(sLine) 'Remove NewLine and LineFeed special characters if they exist

	P = InStr(sLine,RecordEnd )
	While (P > 0)
		Data = Mid(sLine,1,P-1)
		sLine = Mid(sLine,P+1,Len(sLine))

		ExtractParams Data, Params, ParamCount
		ProcessParams Params, ParamCount

		P = InStr(sLine, RecordEnd)
	Wend

	'If any portion of the line is left over
	'return it so we can append more data to it
	HandleLine = sLine

	If sLine <> "" Then
		Log("Line-out: " & sLine)
	End If
End Function

'Data events are separated with CR and/or LF characters
'This handler can handle cases where both or either of these characters are present
Function HandleLine(sLine)
 Dim P
 Dim Data
 Dim Params(20)
 Dim ParamCount
 Dim RecordEnd1
 Dim RecordEnd2

	RecordEnd1 = Chr(13)
	RecordEnd2 = Chr(10)
	P = InStr(sLine, RecordEnd1)
	If P <= 0 Then
		P = InStr(sLine, RecordEnd2)
	End If

	While (P > 0)
		Data = Mid(sLine,1,P-1)
		Data = TrimLineFeed(Data) 'Remove NewLine and LineFeed special characters if they STILL exist
		sLine = Mid(sLine,P+1,Len(sLine))

		If Data <> "" Then
			ExtractParams Data, Params, ParamCount
			ProcessParams Params, ParamCount
		End If

		P = InStr(sLine, RecordEnd1)
		If P <= 0 Then
			P = InStr(sLine, RecordEnd2)
		End If
	Wend

	'If any portion of the line is left over
	'return it so we can append more data to it
	HandleLine = sLine

	If sLine <> "" Then
		Log("Line-out: " & sLine)
	End If
End Function

###########################
# ExtractParams templates #
###########################
'Split line into Params using a known "splitter" character that seperates the data
' Usage:
' 	Dim Params(20)
' 	Dim ParamCount
' 	ExtractParams sLine, Params, ParamCount
' NOTE: sLine above is for example "artist|title|S|03:35"
Function ExtractParams(sLine, ByRef Params, ByRef ParamCount)
const  FieldSplitter = "|"
Dim  P
Dim Data

	ParamCount = 0

	P = InStr(sLine,FieldSplitter)
	While (P > 0)
		Data = Trim(Mid(sLine,1,P-1))
		sLine = Mid(sLine,P+1,Len(sLine))

		AddParam Data, Params, ParamCount

		P = InStr(sLine, FieldSplitter)
	Wend

	If sLine <> "" Then
		AddParam sLine, Params, ParamCount
   	End If
End Function

'Split line into Params if the expected format is a Key=Value format
'Example input format:
'CurrentEvent:CutID=E6072a Type=2MS ArtistName=Basement Jaxx SongTitle=Where's Your Head At Duration=00:04:41.757
Function ExtractParams(sLine, ByRef Params, ByRef ParamCount)

	'Add a dummy string to the end so we can use it for an ending match
    sLine = Trim(sLine) & " Dummy="

	'Check if the event is valid
    If Mid(sLine,1,12) <> "CurrentEvent" Then
      Log("Not current event. Aborting processing.")
      Exit Function
    End If

    ParamCount = 0

	'#0# Cut ID
	Data = Trim(ExtractTagValue(sLine,"CutID=","Type="))
	AddParam Data, Params, ParamCount

	'#1# Type
	Data = Trim(ExtractTagValue(sLine,"Type=","ArtistName="))
	AddParam Data, Params, ParamCount

	'#2# Artist
	Data = Trim(ExtractTagValue(sLine,"ArtistName=","SongTitle="))
	AddParam Data, Params, ParamCount

	'#3# Title
	Data = Trim(ExtractTagValue(sLine,"SongTitle=","Duration="))
	AddParam Data, Params, ParamCount

	'#4# Duration
	Data = Trim(ExtractTagValue(sLine,"Duration=","Dummy="))
	AddParam Data, Params, ParamCount
End Function

'Extract line into Params from XML string
'Example input:
'<audio><title>Wherever You Will Go</title><artist>Calling</artist><type>SONG</type></audio>
Function ExtractParams(sLine, ByRef Params, ByRef ParamCount)
 Dim Data

	ParamCount = 0

	'#0# Song title
	Data = ExtractTagValue(sLine, "<title>","</title>")
	AddParam Data, Params, ParamCount

	'#1# Artist name
	Data = ExtractTagValue(sLine, "<artist>","</artist>")
	AddParam Data, Params, ParamCount

	'#2# Category
	Data = ExtractTagValue(sLine, "<type>", "</type>")
	AddParam Data, Params, ParamCount

End Function

'Extract line into Params if the data is at fixed locations within the string
'Example input strings:
'         10        20        30        40        50        60        70        80        90
'123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
'1024    Tiny Dancer                        Elton John                         Playing 06:13.90 Song
' 871    FIRST NORTH BANK/FINANCIAL 10                                         Playing 00:10.65 Spot
'944     Never Gonna Be Alone               Nickelback                         Cued    03:38.91 Song
Function ExtractParams(sLine, ByRef Params, ByRef ParamCount)
Dim tmp
	'Code
	tmp = ExtractRange(sLine, 1, 4, True)
	AddParam tmp, Params, ParamCount

	'Title
	tmp = ExtractRange(sLine, 9, 35, True)
	AddParam tmp, Params, ParamCount

	'Artist
	tmp = ExtractRange(sLine, 44, 35, True)
	AddParam tmp, Params, ParamCount

	'Action
	tmp = ExtractRange(sLine, 79, 7, True)
	AddParam tmp, Params, ParamCount

	'Duration
	tmp = ExtractRange(sLine, 87, 8, True)
	AddParam tmp, Params, ParamCount

	'Songtype
	tmp = ExtractRange(sLine, 96, 4, True)
	AddParam tmp, Params, ParamCount
End Function