Guides

 
 
 

Beginners Guide
(An applied scripting guide for Ircle)

Chapter 2 : A scripting quick start

 

What is AppleScript and how does it work...

AppleScript is an advanced system-level scripting environment. Apple's Open Scripting Architecture (OSA) supports many scriptable applications, development systems, and scripting languages, including Apple's own AppleScript language.

You could say that AppleScript is a combination of a programming language, a macro language and a batch language. In other words you can make standalone applications , control (scriptable) applications and control the Macintosh Finder with it, even on several (Macintosh) computers across a network. All by using a hybrid between a human language and a computer language, which is very simple BUT also very powerful.

The building blocks of scripts are statements. When you write a script, you compose statements that describe the actions you want to perform. AppleScript includes several kinds of statements that allow you to control when and how statements are executed. These include IF statements for conditional execution, REPEAT statements for statements that are repeated, and handler definitions for creating user-defined events.

AppleScript functionality can be expanded by using Scripting Additions or OSAX's (OSA extensions) These additions have to be in the Scripting Additions folder in the Extensions folder of the system folder. AppleScript comes standard with a few scripting additions.

 

AppleScript works by sending messages, called AppleEvents, to applications.
When you write a script, you write one or more groups of instructions called statements.
When you run the script it will send these statements to the AppleScript extension (1), wich interprets the statements and send AppleEvents to the appropriate applications or OSAX's (2). Those Applications or OSAX's will give a result back via an AppleEvent (3), the AppleScript extension will interpret these AppleEvents and send it back to the appropriate script (4).

 

The ScriptEditor 

To compile scripts we have to use a script editor/compiler.
AppleScript comes standard with the Script Editor.

As you can see the script editor window is divided into two parts. The top is the comment part where you can put your name and other copyright info. This will be stored in the script when you compile it.
Below this field you see 4 buttons. The first is record which can be used to record scripts from recordable applications. (I won't go into that in this guide)
The second and third button are stop and run, with these buttons you can run the script you are editing and "stop" to cancel that run.
All the way on the right side you see the syntax button. With this button you can compile your script. (in fact if you run your script from the Script Editor and it wasn't compiled yet it will be compiled first)

To know how we can script certain (scriptable) applications we have to find out what events and properties such applications has.
In other words, what verbs can we use to "talk" to that application.
Every OSAX and scriptable application has a dictionary build in which you can read with the Script Editor.
To read that dictionary we go to the File menu in the menu bar of the Script Editor...and select Open Dictionary...
You will get the following dialog.

 

Lets point it to Ircle and press the open button.
The following window will appear.

 

First you will see only a list on the left side and the right side is blank.
To see the syntax of a certain event or complete class you just click on the list on the left side.
On the right side you will now see the info of those you selected.

In the appendix of this scripting guide you will find the same info (and more).

Okay...when we made our script we have to save it as a compiled script otherwise Ircle can't do anything with it.
So we compile our script as described above and select Save from the File menu in the menu bar.

The following dialog will appear.

 

IMPORTANT!

Save all scripts you want to use with Ircle as Compiled script and use a name that doesn't contain spaces.
Otherwise you may have trouble loading or executing it from Ircle's inputline.

 

Talking to applications

Okay let's start with some scripting...

Since AppleScript doesn't know where to send the AppleEvents you have to tell where your instructions (statements) have to be send to. You do that with the Tell command. You can use this event in a block or in a oneliner.

Example

The oneliner:

tell application "ircle3.0" to type "hello"

Using in a block:

tell application "ircle3.0"
  type "hello"
end Tell

The second way is more convenient if you have more then one statement to send to that application.

(ALG reference: pages 72, 185-190)

 

How to let a script type in the channel

Ircle has a few events to do certain actions. The TYPE event is one of them.
You use this command to type anything in a channel. This can be text, or IRC commands.

Example

This will be send to the frontmost window (default):

tell application "ircle3.0"
  type "/me laughs its head off"
end Tell

This example will tell Ircle to send it to a certain channel:

tell application "ircle3.0"
  type "/me laughs its head off" in channel "#ircle"
end Tell

Ofcourse you have to have that channel open to be able to send that msg to it.

 

Displaying info on your screen

There can be situations you want to be able to display information on your screen, but not in the channel. You can do this with the ECHO event.

Example

This will be send to the frontmost window (default):

tell application "ircle3.0"
  echo "This script is activated!"
end Tell

This example will tell Ircle to send it to the console window:

tell application "ircle3.0"
  echo "This script is activated!" in window "console"
end Tell

 

NOTE: We use the property "window" here since the console is not a channel.

 

Using variables

To make scripts more flexible you can use variables. These are containers where you can store values in. This can be any value.
These variables can have any name you want, as long it is not a reserved word in AppleScript.
Variables can be used in different ways like as Properties, Globals and Local variables.
In this paragraph we will will only explain the local variables.

Example

set theVariable to "hello"

Or...

set theMsg to "hello"

These are two different variables (containers) with both the text "hello".
You can use any name for a variable, but we strongly suggest you use a recognizable name for those variables so your script will be more 'readable' when you want to edit it later.
Variables named 'a' or 'x' doesn't tell you much about their contents, so you better use 'theMsg' or 'itemX' as variable name.
Spaces in the variable names will cause an error, it will be seen as 2 different variables. So 'the msg' can't be used, but 'the_msg' is allowed. Or use upper and lowercase like in the examples above.

Like we said you can store any value in variables. There are classes of values that AppleScript can use (data formats).

String

This can be any ASCII character. (text and numbers)

Number

This can be any number (no text characters)

Boolean

This can only be false or true

List

This is a container that can hold any other class value in a list.

Date

This holds a complete date INCLUDING the time.

 

There are a few others too, but those will not be used in this guide.

 

To add a value to a variable we can use 2 different statements, copy and set.
Copy is used in a different way then set.(the syntax is different, but does the same)
In this guide we will only use set.

Okay, lets use some examples how to use the variables.

set theVariable to "12"

This will put a string containing 12 into the variable

set theVariable to 12

This will put the number 12 in the variable.

As you see the quotes makes the difference.
Anything between the quotes will be used as a string.

set theVariable to "false"

This will put the string containing false into the variable.

set theVariable to false

This will make the variable a boolean with the value false.
False and True are also reserved words and can't be used as variables.

set theVariable to {"12",false}

This will make the variable a list with the values (string) 12 and a (boolean) false.
The curly brackets make the data a list.

set theVariable to {"12",{false,600}}

Like we explained earlier a list can contain any class of data.
Here you see the list contains a string and a list.
The list in the list contains a boolean and a number.

set theVariable to "12" as number

Here we put the string 12 into a variable and tell also that it has to be a number.
Since the data is a nummeric value it can be done.
If the string contains text characters then you get an error.

set theVariable to false as string

Well here is another example where you get an error.
A boolean can't be made a string.

Resume:

Syntax for using variables is...

set <variablename> to <value> [as <class>]

if you we want to make the variable, lets say, a string with the value "hello" we don't have to use the [as string] part.
Since the quotes make the variable already a string. It can't hurt though...but it's double.

set theSecondVariable to theVariable

Here we use the value of a variable to put into another variable.
And we ofcourse we can use here the as <class> for changing the class of the variable.

 

(ALG reference: pages 22-23, 150-156)

 

Making scripts 'smarter'

We can make scripts smarter by letting it decide what to do at certain conditions.
This can be done by using the IF THEN statement.
As with the tell statement you can use this statement in a oneliner and a block.

syntax:

The oneliner...

if <criteria> then <action>

or in a block

if <criteria> then
  <action>
end if

The criteria can only result in 2 things..TRUE or FALSE.
Lets use some examples.

if 24 = 24 then beep

This oneliner will make your computer beep. (beep is an OSAX that comes with
This criteria will return TRUE because 24 equals 24.

With AppleScript we can use also normal verbs for that.

if 24 is 24 then beep

This will do exactly the same.

When we use this function in a block we can also use the else statement.

if theVariable is not 24 then
  beep
else
  set theVariable to 1
end if

Instead of numbers you can also use strings or any other class in the criteria.
With the boolean class you can use the IF THEN even simpler.
(remember...booleans can only contain TRUE or FALSE)

set theVariable to true
if theVariable then
  beep
end if

Variable theVariable is TRUE so this IF THEN statement will beep :)

 

(ALG Reference: pages 190-193)

 

Sending information to your scripts

To make a script know what we just typed in the inputline (in Ircle) we can use the following
techniques.
tell application "ircle3.0"
  set theArguments to argstring
end tell

This will get the whole text you typed as a string.

tell application "ircle3.0"
  set theArguments to argument 1
end tell

This will get only the first argument you typed. (also as a string)

tell application "ircle3.0"
  set theArguments to every argument
end tell

This will get the whole text you typed, but now as a list (!).

NOTE :If you get the info from the inputline you can't retrieve it again. So you must store it in a variable if you want to use it throughout your script.

 

Making a script recognize hostmasks

To make your script recognize hostmasks is probably one of the most powerful functions you would use in your script.
Ircle provides us a Match event for this.

Syntax:

match <string or list> with <String or list with wildcards>

The result you get is always a list.
When there was no match you will get an empty list.

--> {}

Example:

tell application "ircle3.0"
  set theResult to match "Possible" with "Paula"
end tell

--> {}

This will result in a empty list since there wasn't a match.

tell application "ircle3.0"
  set theResult to match "Possible" with "Poss*"
end tell

--> {1}

This will result in a single item list with the value 1 since there was one match.
* and ? are wildcards. * stands for one or more characters, ? stands for one character.

tell application "ircle3.0"
  set theResult to match "Possible" with "P?ssible"
end tell

--> {1}

This will result in a single item list with the value 1 since there was one match.

tell application "ircle3.0"
  set theResult to match "Possible" with {"Onno", "poss*", "Poss?ble"}
end tell

--> {2,3}

This will result in a list with the value 2 and 3 since there were two matches.
Which are on the positions 2 and 3 in the matched list.

tell application "ircle3.0"
  set theResult to match {"Onno", "possible", "PossAway"} with "poss*"
end tell

--> {2,3}

This will result in a list with the value 2 and 3 since there were two matches.
Which are on the positions 2 and 3 in the matched list.

NOTE: You can't match a list with a list. You can only match a list with a string or a string with a list.

 

Using subroutines

In a script you use some functions more then once.
Then it is efficient to make subroutines so you can call them from where you need it.
A sort of "script once, use many" principle.
A subroutine is also called a handler.
If we use the match event as example we get the following script.
on run
  set theItem2 to {"*robert@*.xs4all.nl","*onno@*.macresponse.nl","*paula@*.ircle.com"}
  set theResult to myMatchRoutine("~Robert@ppp1.xs4all.nl", theItem2)
end run
   
on myMatchRoutine(matchitem1, matchItem2)
  tell application "ircle3.0"
    set theResultList to match matchItem1 with matchItem2
  end tell
  return theResultList
end myMatchRoutine

You see we use the RUN handler here...this is a reserved handler name from AppleScript.
This handler is called when a script is executed. You may remove the ON RUN ..END RUN lines.
AppleScript will handle the statements that are not in a subroutine as the RUN handler part.
But for the readability of your script it is better to use these lines.

Now let's take a look at the subroutine myMatchRoutine(matchitem1, matchItem2).

As you see we use a subroutine to get a value. This is called a Function in other script/programming languages (and mathmatics for that matter).
AppleScript handles subroutines and Functions the same.
The value is returned to the place where the subroutine is called by using the RETURN statement. When you don't apply a return statement in a subroutine then the subroutine will return TRUE.
So actually a Subroutine is a Function is disguise.
With using the RETURN statement we control what value the subroutine will return.

Using only RETURN will return the TRUE value.
RETURN can also be used for exiting a subroutine from any part of the subroutine with or without a return value.

When you use RETURN in the RUN part of the script the script will quit because you exited the run handler.

A subroutine can have arguments. Arguments are values passed to the subroutine.
Subroutines can also have no arguments at all.

NOTE : All the variable names used in such subroutine are only valid in that subroutine.
So you can use the same variable name outside that routine without having to worry that the value in that variable will be overwritten.

 

IMPORTANT!

Never use a subroutine name as a variable in your script.
This will change the subroutine to a variable wich causes errors when you try to call the subroutine again.
This change is only at run-level so your scriptsource will not be altered.

 

(ALG Reference: pages 221-240)

 

Ircle handlers

Ircle is capable to load scripts into it's memory.
When you do this Ircle will send info to pre-defined handlers when certain events happen. Like if someone joins a channel the join handler will be called.
These handlers are predefined and therefore reserved for ircle only.
This way you can make your script act on certain events without having the script checking what happens. Ircle does that for you. :)

NOTE: For more info on the Ircle handlers check out the appendix of this scripting guide.

 

< < < Previous chapter

Index

Next chapter > > >


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