#pragma section-numbers off
= filesystem bookmarks =
 * file:///Library/ScriptingAdditions/ (probably)
 * file:///System/Library/ScriptingAdditions/ (.app and .osax bundles)
 * file:///System/Library/Components/AppleScript.component (the core stuff in here)
 * file:///System/Library/Frameworks/Python.framework/Versions/2.3/lib/python2.3/plat-mac/Carbon/AppleEvents.py (constants)

= bookmarks =
 * http://developer.apple.com/technotes/tn/tn1164.html
 * http://developer.apple.com/documentation/mac/IAC/IAC-2.html
 * http://developer.apple.com/documentation/AppleScript/Conceptual/AppleScriptLangGuide/index.html
 * http://maccentral.macworld.com/features/applescriptprimer16/
 * http://www.mactech.com/articles/develop/issue_10/Clark_final.html
 * http://www.mactech.com/articles/mactech/Vol.10/10.01/ExtendApplescript/
 * http://www.mactech.com/articles/mactech/Vol.11/11.07/aeteResources/
 * http://www.mactech.com/articles/develop/issue_12/Berdahl_final.html
 * http://www.mactech.com/articles/develop/issue_21/21simone.html
 * http://www.mactech.com/articles/develop/issue_23/according.html
 * http://soundfarmer.com/moin.cgi/AppleEventsPython
 * http://www.prefab.com/scriptweb/archive/developerarticles.html
 * http://www.scripting.com/samples/
 * http://search.cpan.org/~cnandor/Mac-Glue/Glue.pm
 * http://citeseer.nj.nec.com/555351.html

= snippets from mactech aeteResources =

== suites ==

It’s important to remember that organization of events by suites doesn’t draw any boundary lines in functionality; the Apple Event Manager doesn’t even know about suites. Aside from being a convenience in organizing related events and classes, their only functional significance is that you can import whole suites by name from the ‘aeut’ resource.

You may also want to create a singe suite which puts together pieces of standard suites without completely implementing any of them. In this case, you should give the suite an ID of '****'. If you implement a significant part of a suite, though, you should include it as a separate suite.

The suite ID ‘tpnm’, conventionally called “Type Names,” is magical. If you give a suite this ID, it won’t appear in the Script Editor’s dictionary listing. This is useful for defining classes you want to hide from the user.

If a suite is described in the system’s ‘aeut’ resource and you support it completely, all that you have to do is include this basic information about it; you don’t have to list the events and classes which it supports. However, if you support only some of the events and classes in a suite, or if you support extensions to any of them (extra parameters, elements, or properties), then you must itemize them in the suite. If you include any events or classes in a suite, you’re saying that you support only those events and classes.

== events ==

Parameters do not have to be named, since they can be identified by their position in the event as long as no parameters are left out before them. However, if there is more than one optional parameter, all optional parameters should be named. Also, optional parameters should come after all required parameters, to minimize the chances of confusing /AppleScript or the Apple Event Manager with omitted positional parameters.

== classes ==

A class contains zero or more properties, followed by zero or more elements. The difference between properties and elements has been much discussed in the Apple Event literature, but is worth mentioning here one more time: An element is an item of information which is contained in an object, while a property is something which gives information about an object. Elements can include windows, text, and pictures; properties can include color, font, and size. Some borderline cases are hard to decide; what is most conveniently treated as a property in the usual case may be treated as an object and thus have element-like characteristics. If there can be more than one of something in an object (e.g., the characters in a text object, or pixels in a graphic), it should almost certainly be an element.

== properties ==

The class of a property indicates what type of object the property is, but just what this means is ill-defined. Sometimes it will be one of the object classes defined in AERegistry.h, sometimes it will be a descType (like typeInteger), and sometimes it will be unique to the application. What the class actually means is known only to the application itself. If it is a class name, it indicates what kind of object (using the Apple Event object model) is referred to by the property, without saying anything about the object’s physical representation. For example, cGraphicLine (‘glin’) indicates a graphic line, and cPixel ‘cpxl’ indicates a pixel. How they might be stored is up to the application.

When an object is actually passed around by Apple Events, it becomes a parameter or reply of an event, and then its storage format is specified by the type of the event. When a parameter of an Apple Event is of type typeObjectSpecifier (‘obj ’), then the object specifier contains information about the class of the object; this is the link between parameters, whose structure is known to the Apple Event Manager, and objects, whose structure is known only to the application.

As links go, this is a very tenuous one. In particular, there’s no way to specify what kind of object a parameter of type ‘obj ’ refers to. You can’t make an ‘aete’ resource say that a point or a line is acceptable, but a document or a window isn’t. This is a fact we have to live with, and should make up for in the documentation.

Some properties are magical. There is a special property ID, called kAESpecialClassProperties and represented as ‘c@#!’, which tells you that the property really isn’t a property at all, but a place to store flags which describe the class itself. (The ID undoubtedly immortalizes the language some programmer used on discovering that the lack of class flags made this kludge necessary.)

A property with this class is the way that you create a plural synonym for a class (which is something you should do for all classes that may be used in scripts). Having created the singular class, you create another class which has the same ID, a plural version of the name (e.g., “windows” instead of “window”), no elements, and only one property. This property has ID ‘c@#!’ and class ‘type’, and the property has its Plural flag set.

Another magic ID can be useful for eliminating redundant information. If the first property of a class has the ID ‘c@#^’, this signifies that the class inherits properties from another class. In this case its class is the ID of its base class, and the name of the property must be “<Inherited>”, including the angle brackets. Using this trick can make some ‘aete’ resources significantly smaller, if there are a number of bulky classes which are largely similar.

A property can also belong to more than one class. To do this, you must set the Enumerated flag, and set the class to the ID of an enumeration. The enumerated set specifies the classes to which the property can belong. Alternatively, you can use the Wild Card class (‘****’), which says that a property can be of any class.

If a property can be modified by an event, then the Read/Write flag should be set. If its value is a list (e.g., the styles which are applied to a text item), then the List of Values flag should be set. The Masculine and Feminine flags, once again, don’t apply to English.


= text chunks =

useful builtin suites:
{{{kCoreEventClass
kAECoreSuite
kAETextSuite
kAETableSuite
kAEDBSuite
kAEMiscStandards}}}

If you've got a large 'aete' resource, or large groups of properties used in multiple classes, you can reduce the size and repetitiousness of your 'aete' by defining those sets of properties in an abstract or base class. Then classes that include those property definitions can include an inheritance property, with the ID code 'c@#^' (pInherits), as their first property. The human name for this property should be<Inheritance> (be sure to include the angle brackets as part of the name). The inclusion of this property will indicate to the user that this class inherits some or all of its properties from another class.

= applescript =

knows about metric/english types, stored in different classes than real (subclasses, probably).  smart enough to know you can't convert m^2 to inches!

seems to have a bunch of flags going on during compilation or runtime.. such as "considering case ... end considering"

will names into (arbitrary?) four character codes on demand for records.. but not documented how the conversion happens.. I wonder.  It definitely will use properties it knows about in the namespace first.

python-like references are called possessive and look like "foo's bar's baz", but typically in AS you see "baz of bar of foo"

not case sensitive anywhere by default (even string comparisons)

251 character variable name limit, must start with letter or underscore unless it looks like |myvar| in which case myvar can be completely arbitrary (the /AppleScript in a Nutshell example was |$perlScalar| ... woo)

has reference and copy semantics "set myvar to foo" is python-like assignment.  "copy myvar to foo" copies it.  according to nutshell, copy only matters for list, record, and script types.

seems to have a simple prototype based OO (script objects).  creating a script object creates an instance that you should copy to use.  the properties are totally public rw like in Python.  Doesn't seem to have operator overloading or introspection.  'self' seems to be implicit: "script Foo .. property myFoo:0 .. on foo() .. set myFoo to myFoo + 1 .. end foo .. end script" 

operators are available as both english text and symbols "greater than" or ">", and many have "high ascii" alternatives as well, such as "?" instead of "<="

there are six forms of repeat:
  * repeat with x in list -> for x in list
  * repeat x times -> for _ in range(x)
  * repeat -> while 1
  * repeat while cond -> while cond
  * repeat until cond -> while True: .... if cond: break
  * repeat with x from a to b by c -> for x in range(a, b+1, c)

there is a try statement, but it's only form seems to be "try .. on error errmsg .. end try", so it's probably more like a "goto error:" than anything else.

you can define handlers (functions) "on myFun(arg) .. end myFun" and pass around references to them, but they don't seem to be quite first class.  I couldn't manage to pass a function to another function and call it from there.

according to nutshell, here are the built-in data types:
 * alias
 * boolean
 * class
 * constant (like pi .. I need to find one of these in a terminology!)
 * data
 * date
 * file specification (url or file)
 * integer (from -536870911 to 536870911 .. wtf? thats like 30 bits)
 * international text
 * list
 * number (alias for integer or real?  like basestring?)
 * real
 * record
 * reference
 * RGB color
 * string
 * styled Clipboard Text
 * styled Text
 * text
 * Unicode text
 * (unit of measurement classes) -- area, length, temperature, cubic volume, liquid volume, weight 

There is a special guillemet syntax for doing events and representing data:
 * tell application "myapp" to «event coregetd» name (* the get event in the core suite *)
 * «class cdis» "scratch" (* the disk class, in finder *)
 * «data utxt0075» (* the letter "u" in unicode *)

The date / time stuff is pretty complicated (implementation wise) but seems to be easy to use

= see also =
 * /AppleScript