Guides

 
 
 

Beginners Guide
 (An applied scripting guide for Ircle)

 

Chapter 3 : Making scripts for Ircle

The following script examples are divided in executable and loadable scripts.
In other words, some only work when you /load them and others have to be executed
with the /<scriptpname> command.
Or by using the Script menu in Ircle.

 

Msg command alias script (executable)

Let me show you how to make your own command alias.
A command alias is an 'alias' for a IRC command to use it with less typing.
Well that is the general purpose.
Let's start with a command alias for a Private Message (MSG).
Normally you have to type the following:
/msg Onno hi there

That is if you want Onno to receive the message "hi there".
Now let's make an alias for msg to let us type the following:

/m Onno hi there

A script that does this looks like this:

on run
   tell application "ircle3.0"
    set theArguments to argstring
    type "/msg " & theArguments
  end tell
end run

Save this as a compiled script with the name "M" so you can execute it with /M.
Put the script in the Ircle script folder and its ready to go.

 

Kick command alias script (executable)

You can use the previous script example to make other command aliases,
for example for the IRC command /kick.

Normally you typed this:

/kick #ircle Paula bye bye

Let's make an alias that makes us able to type this:

/K Paula bye bye

The only thing you have to change in the script above is the following line:

type "/msg " & theArguments

And change it to:

type "/kick " & theChannel & " " & theArguments

You see it uses a new variable called "theChannel" which will contain the channel name.
Therefore we have to add the line:

set theChannel to currentchannel

This way you don't have to type the channelname. It will use the channel name from where
you typed it (the current channel). Then the script will look like this:

on run
  tell application "ircle3.0"
    set theArguments to argstring
    set theChannel to currentchannel
    type "/kick " & theChannel & " " & theArguments
  end tell
end run

Save this as a compiled script with the name "K" and put it in the Ircle scripts folder.
We think you can think of more possibilities here. Try it out, play with the code.

 

Channel bot login script (executable)

If you are one of the people who hate to type the long commands to login into your channel bot
you might take a look at this script example.
Save the script for example as "login" and you can type the following when you are in the channel:
/login

Here is the script :

property myPasswd : "cool"
property theChannel : "#ircle"
property theBot : "x@channels.undernet.org"
   
on run
  tell application "ircle3.0"
    type "/msg " & theBot & " login " & theChannel & " " & myPasswd
  end tell
end run

Ofcourse in this example your password would be "cool", just fill in your own password.

We use here a new object namely "Property".
This makes a variable count throughout the script...so you can use the contents of the variable
in any handler you write.
In other words the scope of "Property" is the whole script.

If you declare variables inside a handler then this variable will have the scope of that handler.
Other handlers may use the same variable name but it won't be the same variable. AppleScript will treat
them as 2 different variables. Using the property object we make the variable global.

(ALG Reference: pages 525-264)

 

NOTE: With the downloadable scripts that come with this guide you will find also an extended login
script wich can handle more then one channel and will automatically send the login the moment
you enter the channel.

 

Random Color script (executable) 

property ctrln : ASCII character 14
property ctrlc : ASCII character 3

on run
  tell application "ircle3.0"
    set args to argstring
    if args is "" then return
    tell me to set thestring to makeColorCharacters(thestring)
    type thestring
  end tell
end run
   
on makeColorCharacters(thestring)
  set resultString to ""
  repeat with itemX from 1 to (count characters of thestring)
    if (character itemX of thestring) is not " " then
      set colorNr to random number from 2 to 13
      set resultString to resultString & (ctrlc & (ASCII character (48 + ¬ 
            colorNr)) & (character itemX of thestring) as string)
    else
      -- no color needed for spaces
      set resultString to resultString & " " as string 
    end if
  end repeat
  return resultString
end makeColorCharacters

 

Here you see we use another tell statement inside the tell statement to Ircle.
We want to let the script talk to itself since Ircle doesn't understand the makeColorCharacters(thestring) command.

For the first time in this guide we use the REPEAT statement.
This is used to create loops for one or more statements.
There are several types of Repeat statements but in this guide we will only use this form.
In this script we want to repeat the statements to the amount of characters in the string times to be able
to process every character and give it a color. ItemX is filled with the number of times it is repeating.

(ALG Reference: pages 194-204)

Count is a command that is part of AppleScript and can also be part of an application since it belongs in the Core Suite
of a scriptable application. The AppleScript command can count the number of elements of a particular class in a string,
list or record. (records are not handled in this guide)
The application command can count the number of elements of a particular class in an object or objects.
For example you can count the windows that are open in Ircle or the open connections of Ircle.

(ALG Reference: pages 92-96)

 

Character is another class of AppleScript.

(ALG Reference: pages 321-232)

 

ASCII Character is another OSAX we use here that comes standard with AppleScript.
It creates a readable character out of the ASCII number we give it.
For example the ASCII equivalent of "A" is 65.

 

Autogreet script (loadable) 

on join(theConnection, theNick, theUserhost, theChannel)
  tell application "ircle3.0"
    set myNick to nickname of connection theConnection
    if myNick is not theNick then
      type ("Hello " & theNick) in channel theChannel of connection theConnection
    end if
  end tell
end join

 

NOTE: Good to know is that Ircle handlers are called BEFORE ircle handles the event themselves.
In this case you join a channel and the Join handler is called.
To Ircle you are not in the channel yet....so if the script would react on you joining the
channel it would make you talk to a channel you (to ircle) didn't join yet.
Wich will result in an error.
Besides this there is the fact that saying hello to yourself when you join a channel is kind of silly ;)

 

Auto-DCC script for sounds (loadable)

Lets create a script that will automatically DCC a sound to someone who asks for it.
We gonna make a script that will respond to the following line typed by someone in the channel:

!paula nee.wav

This means your nick is this example "paula" and someone wants your sound named "nee.wav".

 

on pubmsg(theConnection, theNick, theSourcehost, theChannel, theString)
  tell application "ircle3.0"
    if theString starts with "!" then
      if first word of theString is (nickname of connection theConnection) then
        tell me to _checkSoundName(theConnection, theNick, theString)
      end if
    end if
  end tell
end pubmsg
   
on _checkSoundName(theConnection, theNick, thestring)
  set oldDelim to AppleScript's text item delimiters
  set AppleScript's text item delimiters to {" "}
  set thestring to text items of thestring
  set AppleScript's text item delimiters to oldDelim
  set theFilename to item 2 of thestring
  tell application "ircle3.0"
    set theSoundFolder to soundfolder as string
    tell application "Finder" to set theSubFolders to name of every folder in folder theSoundFolder
    repeat with itemX from 1 to (count items of theSubFolders) + 1
      if itemX is 1 then
        tell application "Finder" to set isItThere to ¬ 
              exists (file theFilename in folder theSoundFolder)
      else
        tell application "Finder" to set isItThere to ¬ 
              exists (file theFilename in folder (theSoundFolder & (item (itemX - 1) of ¬ 
              theSubFolders) & ":" as string))
      end if
      if isItThere then
        type ("/dcc send " & theNick & " " & theSoundFolder & theFilename) ¬ 
              in connection theConnection
        exit repeat
      else
        type ("/notice " & theNick & " [Auto-DCC] Sorry but I don't know this soundfile.") ¬ 
              in connection theConnection
        exit repeat
      end if
    end repeat
  end tell
end _checkSoundName

 

In the top of this script you see we use AppleScript's built in feature to parse a string
into a list by cutting it up with a delimiter " ".
We keep and restore the old delimiter settings to make sure other routines or even
other scripts running on your machine won't use the wrong delimiter setting.
You may see this as proper scripting.

(ALG Reference: pages 158-160)

 

NOTE: AppleScript has the delimiter default set to " ".
We still set the delimiter in this script because some other script might have change it and didn't put it back to the default setting.
Assuming that the delimiter is still at the default setting would be asking for trouble.
Assumption is the creation of all f....ailures..;)

The property "soundfolder" we used in this script is a property of Ircle.
This property contains the path to the soundsfolder you have set in the Ircle preferences.
In the Reference Guide on this site you can find more of these properties.

In this script we scripted the Finder.. The Finder is just another scriptable application which also comes with a full set of OSAX's. And in MacOS 8.5 and up you can almost script anything in the Finder.
In this guide we won't go into this aspect of scripting....maybe in a next guide.

 

Simple FServer script (loadable) 

property fserveCommands : {}
   
on pubmsg(theConnection, theNick, theSourcehost, theChannel, theString)
  tell application "ircle3.0"
    if (match theString with fserveCommands) is not {} then
      type "/fserve " & theNick in connection theConnection
    end if
  end tell
  return false
end pubmsg

 

We use a reserved handler from Ircle here.

(The reserved handlers are all listed and explained in the Reference Guide on this site)

 

Auto-away with message log script (loadable) 

property msgLog : {}
property lastActivity : 0
property autoAwayIdleTime : (5 * 60)
   
   
on input(theConnection, theChannel, theString)
  set lastActivity to current date
end input
   
   
on privmsg(theConnection, theNick, theUserhost, theTarget, theString)
  tell application "ircle3.0"
    set myAwayStatus to away of connection theConnection
    if myAwayStatus then
      set msgLog to msgLog & "[" & (time string of (current date)) & ¬ 
            "/" & theNick & "] " & theString
      type ("/notice " & theNick & " Your msg has been logged.") ¬ 
            in connection theConnection
    end if
  end tell
end privmsg
   
   
on showMsgLog()
  tell application "ircle3.0"
    repeat with itemX from 1 to (count items of msgLog)
      echo (item itemX of msgLog)
    end repeat
  end tell
end showMsgLog
   
   
on delMsgLog()
  set msgLog to {}
  tell application "ircle3.0" to echo "Message log is deleted..."
end delMsgLog
   
   
on idle
  tell application "ircle3.0"
    set myAwayStatus to away of connection theConnection
    if myAwayStatus is false then
      if lastActivity is greater than or equal to ((current date) - autoAwayIdleTime) then
        set theMsg to "Automatic set away after " & ¬ 
            (autoAwayIdleTime/60) & " minutes - msgs will be logged"
        type "/broadcast " & theMsg
        type "/away " & theMsg
      end if
    end if
  end tell
  return 15
end idle

 

Since this is a script that we load into Ircle we can trigger the handlers we just made (showmsglog and delmsglog)
from the inputline of Ircle. We just use /showmsglog and the handler is triggered.
So if you want you can put all your executable scripts in one loadable script and make handlers for each executable
script. :)

Current date is another OSAX we use which comes standard with AppleScript.
This OSAX returns the system date and time as a Date class.
With the statement "time string" we get the time in a string with the format HH:MM:SS.
You can read more in the dictionary of this OSAX.

(ALG Reference: pages 43-47)

 

At the end of this script you find a very interesting handler named "idle".
This handler is a reserved name from AppleScript (just like the "run" handler).
This handler is called by AppleScript every x seconds when the there are no incoming events.
The time it takes to make AppleScript trigger this handler is set in the Return statement at the end of
the handler. These values are the seconds it will take to trigger this handler again, so in this case 15 seconds.
If you leave the return statement out it will trigger the idle handler every second. 

IMPORTANT:
Never change the return value of the idle handler to 0 (zero). I think you can imagine what happends then.

 

(ALG Reference: page 248)

 

(Smart) bankick command alias script (executable)

Let's turn the difficulty up a notch (or two).
You might hate the amount of info you always have to type when you want to ban someone from your channel.

We're gonna make a ban kick script that only needs the nickname of the target and it will produce a 'good' ban mask.
Save the following script as "BK" and the following syntax can be used from the inputline of Ircle:

/bk <nickname> <kickmessage>

The script looks like this:

on run
  tell application "ircle3.0"
    set args to every argument
    if args is {} then return
    set theNick to item 1 of args as string
    set kickMsg to ""
    if (count items of args) > 1 then
      repeat with itemX from 2 to (count items of args)
        set kickMsg to kickMsg & (item itemX of args) & " " as string
      end repeat
    end if
   
    set theConnection to currentconnection
    set theChannel to currentchannel
   
    -- check if the nickname exists in this channel
                if (exists user theNick of channel theChannel of ¬ 
           connection theConnection) is false then
      beep
      return
    end if
   
    set thehostname to hostname of (user theNick of ¬
		channel theChannel of connection theConnection)
    set theUserName to username of (user theNick of ¬ 
          channel theChannel of connection theConnection)
   
    set oldDelim to AppleScript's text item delimiters
    set AppleScript's text item delimiters to {"."}
    set checkIP to text items of thehostname
    set AppleScript's text item delimiters to oldDelim
   
    -- process the hostname
                repeat with itemX from 1 to (count items of checkIP)
      try
        set testIp to item itemX of checkIP as number
      on error
        tell me to set hostmask to _MakeDomainMask(checkIP) as string
        exit repeat
      end try
      tell me to set hostmask to _MakeIpMask(checkIP) as string
    end repeat
   
    -- process the username of the nick
                if the first character of theUserName is "~" then
      set theUserName to (characters 2 thru (count items of theUserName) of theUserName)
    end if
   
    -- put the banmask together
                set theBanmask to "*" & theUserName & "@" & hostmask as string
    set banString to "/mode " & theChannel & " +b " & theBanmask as string
   
    -- okay..lets start bankicking
                type banString in connection theConnection
    type ("/kick " & theChannel & " " & theNick & " " & ¬ 
        kickMsg) in connection theConnection
  end tell
end run
   
   
on _MakeIpMask(thehostname)
  set ipMaskString to ""
  repeat with itemX from 1 to ((count items of thehostname) - 1)
    set ipMaskString to ipMaskString & (item itemX of thehostname) & ¬ 
     "." as string
  end repeat
  set ipMaskString to ipMaskString & "*"
  return ipMaskString
end _MakeIpMask
   
   
on _MakeDomainMask(thehostname)
  set DomainMaskString to "*"
  repeat with itemX from 2 to (count items of thehostname)
    set DomainMaskString to DomainMaskString & "." & ¬ 
      (item itemX of thehostname) as string
  end repeat
  return DomainMaskString
end _MakeDomainMask

 

In this script we use commentlines to make the script readable.
Ofcourse to much commentlines will make the script UNreadable again.
Commentlines are the lines that start with "--".
AppleScript will ignore those lines when it compiles the script.

(ALG Reference: pages 26-27)

 

In this script we use for the first time in this guide the TRY statement. This statement enables us to
catch any errors and act accordingly upon them without getting an error message on the screen.
When an error occures in this TRY statement then it will jump to the ON ERROR part of this statement.
In this script example we use this to enable us to see if the hostname is an IP or a domain name.
IP's are numeric and domain names can contain numbers and text.
To try to make the string a number we check if the value contains text or not.
If it does then this will result in an error since you can't make text into a number.

(ALG Reference: pages 204-209)

 

We use a range reference form in this script which is build into AppleScript.

Syntax is: 

<class> <start index> thru <stop Index> of <value>

As we look what we have used in this script it looks like this: 

characters 2 thru (count items of theUserName) of theUserName

The result is a range of the variable theUserName.
In this case the whole string without character 1.

 

NOTE: Instead of Thru you can also use Through.

 

(ALG Reference: page 136) 

As you may have noticed we use an underscore for handlers that are not commands for the users.
This is just a way to make it less likely that a user types /<whatever command> and triggers one of the scripts
handlers.
It's just a way of preventing this. Other scripters might have a different way of preventing this.

 

- END OF THE BEGINNERS GUIDE -
 

< < < Previous Chapter

Index

Scripting Guide's

 


Nothing of this guide may be published in any form without written consent of the author
© 2000-2005 Scripters Guild - Email : webmaster.