rb-appscript 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (83) hide show
  1. data/CHANGES +243 -0
  2. data/LICENSE +1 -0
  3. data/README +42 -0
  4. data/TODO +31 -0
  5. data/doc/aem-manual/01_introduction.html +48 -0
  6. data/doc/aem-manual/02_apioverview.html +89 -0
  7. data/doc/aem-manual/03_packingandunpackingdata.html +98 -0
  8. data/doc/aem-manual/04_references.html +401 -0
  9. data/doc/aem-manual/05_targettingapplications.html +133 -0
  10. data/doc/aem-manual/06_buildingandsendingevents.html +175 -0
  11. data/doc/aem-manual/07_findapp.html +54 -0
  12. data/doc/aem-manual/08_examples.html +85 -0
  13. data/doc/aem-manual/09_notes.html +41 -0
  14. data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
  15. data/doc/aem-manual/full.css +21 -0
  16. data/doc/aem-manual/index.html +43 -0
  17. data/doc/appscript-manual/01_introduction.html +82 -0
  18. data/doc/appscript-manual/02_aboutappscripting.html +244 -0
  19. data/doc/appscript-manual/03_quicktutorial.html +154 -0
  20. data/doc/appscript-manual/04_gettinghelp.html +101 -0
  21. data/doc/appscript-manual/05_keywordconversion.html +91 -0
  22. data/doc/appscript-manual/06_classesandenums.html +174 -0
  23. data/doc/appscript-manual/07_applicationobjects.html +181 -0
  24. data/doc/appscript-manual/08_realvsgenericreferences.html +86 -0
  25. data/doc/appscript-manual/09_referenceforms.html +232 -0
  26. data/doc/appscript-manual/10_referenceexamples.html +142 -0
  27. data/doc/appscript-manual/11_applicationcommands.html +204 -0
  28. data/doc/appscript-manual/12_commandexamples.html +129 -0
  29. data/doc/appscript-manual/13_performanceissues.html +115 -0
  30. data/doc/appscript-manual/14_problemapps.html +193 -0
  31. data/doc/appscript-manual/15_notes.html +84 -0
  32. data/doc/appscript-manual/application_architecture.gif +0 -0
  33. data/doc/appscript-manual/application_architecture2.gif +0 -0
  34. data/doc/appscript-manual/finder_to_textedit_event.gif +0 -0
  35. data/doc/appscript-manual/full.css +21 -0
  36. data/doc/appscript-manual/index.html +49 -0
  37. data/doc/appscript-manual/relationships_example.gif +0 -0
  38. data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
  39. data/doc/index.html +30 -0
  40. data/doc/mactypes-manual/index.html +216 -0
  41. data/doc/osax-manual/index.html +169 -0
  42. data/extconf.rb +54 -0
  43. data/misc/adobeunittypes.rb +14 -0
  44. data/misc/dump.rb +72 -0
  45. data/rb-appscript.gemspec +20 -0
  46. data/sample/AB_list_people_with_emails.rb +8 -0
  47. data/sample/Create_daily_iCal_todos.rb +72 -0
  48. data/sample/Hello_world.rb +9 -0
  49. data/sample/List_iTunes_playlist_names.rb +7 -0
  50. data/sample/Make_Mail_message.rb +29 -0
  51. data/sample/Open_file_in_TextEdit.rb +9 -0
  52. data/sample/Organize_Mail_messages.rb +57 -0
  53. data/sample/Print_folder_tree.rb +12 -0
  54. data/sample/Select_all_HTML_files.rb +8 -0
  55. data/sample/Set_iChat_status.rb +20 -0
  56. data/sample/Simple_Finder_GUI_Scripting.rb +14 -0
  57. data/sample/Stagger_Finder_windows.rb +21 -0
  58. data/sample/TextEdit_demo.rb +126 -0
  59. data/sample/iTunes_top40_to_html.rb +64 -0
  60. data/src/lib/_aem/aemreference.rb +1006 -0
  61. data/src/lib/_aem/codecs.rb +617 -0
  62. data/src/lib/_aem/connect.rb +100 -0
  63. data/src/lib/_aem/findapp.rb +83 -0
  64. data/src/lib/_aem/mactypes.rb +228 -0
  65. data/src/lib/_aem/send.rb +257 -0
  66. data/src/lib/_aem/typewrappers.rb +57 -0
  67. data/src/lib/_appscript/defaultterminology.rb +245 -0
  68. data/src/lib/_appscript/referencerenderer.rb +132 -0
  69. data/src/lib/_appscript/reservedkeywords.rb +107 -0
  70. data/src/lib/_appscript/terminology.rb +314 -0
  71. data/src/lib/aem.rb +216 -0
  72. data/src/lib/appscript.rb +830 -0
  73. data/src/lib/kae.rb +1484 -0
  74. data/src/lib/osax.rb +171 -0
  75. data/src/rbae.c +766 -0
  76. data/test/README +1 -0
  77. data/test/test_aemreference.rb +112 -0
  78. data/test/test_appscriptreference.rb +102 -0
  79. data/test/test_codecs.rb +159 -0
  80. data/test/test_findapp.rb +24 -0
  81. data/test/test_mactypes.rb +67 -0
  82. data/test/testall.sh +9 -0
  83. metadata +143 -0
data/doc/aem-manual/06_buildingandsendingevents.html ADDED
@@ -0,0 +1,175 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>aem | 6. Building and sending events</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>6. Building and sending events</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="05_targettingapplications.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_findapp.html">Next</a>
18
+ </div>
19
+
20
+ <!-- content -->
21
+ <div id="content">
22
+
23
+
24
+
25
+
26
+ <h2>The <code>Application#event</code> method</h2>
27
+
28
+ <p>The <code>Application#event</code> method is used to create new Apple events targetted at the specified application.</p>
29
+
30
+ <pre><code>Application -- the target application
31
+ ...
32
+
33
+ event(event_code, params={}, atts={}, return_id=KAE.KAutoGenerateReturnID,
34
+ codecs=DefaultCodecs) -- construct an Apple event
35
+ event_code : string -- 8-letter code indicating event's class and id,
36
+ e.g. 'coregetd'
37
+ params : hash -- a hash of form {AE_code=&gt;anything,...} containing
38
+ zero or more event parameters
39
+ atts : hash -- a hash of form {AE_code=&gt;anything,...} containing
40
+ zero or more event attributes
41
+ return_id : integer -- reply event's ID
42
+ codecs : Codecs -- codecs object to use when packing/unpacking
43
+ attributes and parameters for this event and its reply
44
+ Result : Event -- a ready-to-send Apple event</code></pre>
45
+
46
+
47
+
48
+
49
+
50
+ <h2>The <code>Event</code> class</h2>
51
+
52
+ <p>The <code>Event</code> class represents an Apple event that has been packed and is ready to send.</p>
53
+
54
+ <pre><code>Event
55
+
56
+ Methods:
57
+
58
+ send(timeout=KAE::KDefaultTimeout, flags=KAE::KAEWaitReply) -- send event
59
+ timeout : integer | KAE::KDefaultTimeout | KAE::KNoTimeOut -- number of
60
+ ticks to wait for application reply before raising timeout error
61
+ flags : integer -- bitwise flags determining how event should be
62
+ handled
63
+ Result : anything -- value returned by application, if any</code></pre>
64
+
65
+
66
+ <p>The <code>send</code> method may be called any number of times.</p>
67
+
68
+
69
+ <h2>Constants</h2>
70
+
71
+ <p>The following constants are defined in the <code>KAE</code> module.</p>
72
+
73
+ <h3>Common parameter keys</h3>
74
+
75
+ <pre><code>KAE::KeyDirectObject
76
+ KAE::KeyAERequestedType</code></pre>
77
+
78
+ <p>(The value for a <code>keyAERequestedType</code> parameter should be an <code>AEType</code> instance.)</p>
79
+
80
+ <p>Other parameter keys are defined by individual applications.</p>
81
+
82
+
83
+ <h3>Attribute keys</h3>
84
+
85
+ <p>Most of the following attributes are already supplied by other means (e.g. keyEventClassAttr, keyEventIDAttr are supplied separately when creating an Apple event; keyTimeoutAttr when sending it) and are only of interest if unpacking AppleEvent descriptors manually. A few may be used when passing an attributes dict to <code>Application#event</code> (<code>EnumConsiderations</code>, <code>EnumConsidsAndIgnores</code>, <code>KeySubjectAttr</code>):</p>
86
+
87
+ KAE::KeyReturnIDAttr
88
+ KAE::KeyEventClassAttr
89
+ KAE::KeyEventIDAttr
90
+ KAE::KeyAddressAttr
91
+ KAE::KeyOptionalKeywordAttr
92
+ KAE::KeyTimeoutAttr
93
+ KAE::KeyInteractLevelAttr
94
+ KAE::KeyEventSourceAttr
95
+ KAE::KeyOriginalAddressAttr
96
+ KAE::KeyAcceptTimeoutAttr
97
+ KAE::EnumConsiderations
98
+ KAE::EnumConsidsAndIgnores
99
+ KAE::KeySubjectAttr</code></pre>
100
+
101
+
102
+ <p>The value of the <code>EnumConsiderations</code> attribute should be a list containing zero or more <code>AEEnum</code> instances with the following codes:</p>
103
+
104
+ <pre><code>KAE::KAECase
105
+ KAE::KAEDiacritic
106
+ KAE::KAEWhiteSpace
107
+ KAE::KAEHyphens
108
+ KAE::KAEExpansion
109
+ KAE::KAEPunctuation
110
+ KAE::KASConsiderReplies
111
+ KAE::KASNumericStrings</code></pre>
112
+
113
+ <p>See the <a href="http://developer.apple.com/documentation/Carbon/Reference/Apple_Event_Manager/index.html">Apple Event Manager</a> API reference for more info. Note that the <code>EnumConsiderations</code> attribute is deprecated in favour of the <code>EnumConsidsAndIgnores</code> attribute.</p>
114
+
115
+
116
+ <p>The value of the <code>EnumConsidsAndIgnores</code> attribute should be an integer composed from the sum of zero or more of the following bit masks:</p>
117
+
118
+ <pre><code>KAE::KAECaseConsiderMask
119
+
120
+
121
+
122
+ <h3>Send flag constants</h3>
123
+
124
+ <p>The value of the <code>send</code> method's <code>flags</code> argument should be an integer composed from the sum of zero or more of the following bit masks:</p>
125
+
126
+ <pre><code>KAE::KAENoReply
127
+ KAE::KAEQueueReply
128
+ KAE::KAEWaitReply
129
+
130
+ KAE::KAEDontReconnect
131
+
132
+ KAE::KAEWantReceipt
133
+
134
+ KAE::KAENeverInteract
135
+ KAE::KAECanInteract
136
+ KAE::KAEAlwaysInteract
137
+
138
+ KAE::KAECanSwitchLayer</code></pre>
139
+
140
+ <p>See the <a href="http://developer.apple.com/documentation/Carbon/Reference/Apple_Event_Manager/apple_event_manager_ref/chapter_1.4_section_6.html">Apple Event Manager</a> API reference for details.</p>
141
+
142
+
143
+ <h3>Other constants</h3>
144
+
145
+ <pre><code>KAE::KAutoGenerateReturnID</code></pre>
146
+
147
+
148
+ <h2>The <code>CommandError</code> class</h2>
149
+
150
+ <p>The <code>CommandError</code> class is raised by <code>Event#send</code> and represents an error raised by the target application or Apple Event Manager when sending an event.</p>
151
+
152
+ <pre><code>CommandError(MacOS.Error)
153
+
154
+ Methods:
155
+
156
+ number
157
+ Result: integer -- error number
158
+
159
+ message
160
+ Result: string | nil -- error message, if any</code></pre>
161
+
162
+ <!-- TO DO: MacOSError notes -->
163
+
164
+
165
+ </div>
166
+
167
+ <!-- bottom navigation -->
168
+ <div class="navbar">
169
+ <a href="05_targettingapplications.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_findapp.html">Next</a>
170
+ </div>
171
+
172
+ <!--footer-->
173
+ <p class="footer">&copy; 2006 HAS</p>
174
+ </body>
175
+ </html>
data/doc/aem-manual/07_findapp.html ADDED
@@ -0,0 +1,54 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>aem | 7. Locating applications</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>7. Locating applications</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="06_buildingandsendingevents.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_examples.html">Next</a>
18
+ </div>
19
+
20
+ <!-- content -->
21
+ <div id="content">
22
+
23
+
24
+
25
+
26
+ <h2>The <code>FindApp</code> module</h2>
27
+
28
+ <p>The findapp module is used to obtain the full path to an application given it file name, bundle ID, or creator code. It exports the following functions:</p>
29
+
30
+ <pre><code>by_name(name) -- Find the application with the given name.
31
+ name : string -- application's name, e.g. 'Finder.app'. The '.app' suffix
32
+ is optional. Absolute paths are also accepted.
33
+ Result : string -- full path to application
34
+
35
+ by_id(id) -- Find the application with the given bundle id.
36
+ id : string -- bundle id, e.g. 'com.apple.textedit'
37
+ Result : string -- full path to application
38
+
39
+ by_creator(creator) -- Find the application with the given creator type.
40
+ creator : string -- four-char code, e.g. 'ttxt'
41
+ Result : string -- full path to application</code></pre>
42
+
43
+
44
+ </div>
45
+
46
+ <!-- bottom navigation -->
47
+ <div class="navbar">
48
+ <a href="06_buildingandsendingevents.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_examples.html">Next</a>
49
+ </div>
50
+
51
+ <!--footer-->
52
+ <p class="footer">&copy; 2006 HAS</p>
53
+ </body>
54
+ </html>
data/doc/aem-manual/08_examples.html ADDED
@@ -0,0 +1,85 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>aem | 8. Examples</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>8. Examples</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_notes.html">Next</a>
18
+ </div>
19
+
20
+ <!-- content -->
21
+ <div id="content">
22
+
23
+
24
+ <h2>Identifying Applications</h2>
25
+
26
+ <pre><code># application "Macintosh HD:Applications:TextEdit.app"
27
+ textedit = AEM::Application.by_path('/Applications/TextEdit.app')
28
+
29
+ # application "TextEdit"
30
+ textedit = AEM::Application.by_path(FindApp.by_name('TextEdit'))
31
+
32
+ # application "TextEdit" of machine "eppc://my-mac.local"
33
+ textedit = AEM::Application.by_url('eppc://my-mac.local/TextEdit')</code></pre>
34
+
35
+
36
+ <h2>Building References</h2>
37
+
38
+ <pre><code># name (of application)
39
+ AEM.app.property('pnam')
40
+
41
+ # text of every document
42
+ AEM.app.elements('docu').property('ctxt')
43
+
44
+ # end of every paragraph of text of document 1
45
+ AEM.app.elements('docu').by_index(1).property('ctxt').elements('cpar').end
46
+
47
+ #�paragraphs 2 thru last of first document
48
+ AEM.app.elements('docu').first.elements('cpar').by_range(
49
+ AEM.con.elements('cpar').by_index(2),
50
+ AEM.con.elements('cpar').last)
51
+
52
+ # paragraphs of document 1 where it != "\n"
53
+ AEM.app.elements('docu').by_index(1).elements('cpar').by_filter(AEM.its.ne("\n"))</code></pre>
54
+
55
+
56
+ <h2>Sending Events</h2>
57
+
58
+ <pre><code># quit TextEdit
59
+ textedit.event('corequit').send
60
+
61
+ # name of TextEdit
62
+ p textedit.event('coregetd', {'----' =&gt; AEM.app.property('pnam')}).send
63
+
64
+ # count documents of TextEdit
65
+ p textedit.event('corecnte', {'----' =&gt; AEM.app.elements('docu')}).send
66
+
67
+ # make new document at end of documents of TextEdit
68
+ textedit.event('corecrel', {
69
+ 'kocl' =&gt; AEM::AEType.new('docu'),
70
+ 'insh' =&gt; AEM.app.elements('docu').end
71
+ }).send</code></pre>
72
+
73
+
74
+
75
+ </div>
76
+
77
+ <!-- bottom navigation -->
78
+ <div class="navbar">
79
+ <a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_notes.html">Next</a>
80
+ </div>
81
+
82
+ <!--footer-->
83
+ <p class="footer">&copy; 2006 HAS</p>
84
+ </body>
85
+ </html>
data/doc/aem-manual/09_notes.html ADDED
@@ -0,0 +1,41 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>aem | 9. Notes</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>9. Notes</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="08_examples.html">Previous</a> | <a href="index.html">Up</a>
18
+ </div>
19
+
20
+ <!-- content -->
21
+ <div id="content">
22
+
23
+
24
+ <h2>Copyright</h2>
25
+
26
+ <p>(C) 2006 HAS -- hhas -at- users - sourceforge - net (<a href="http://rb-appscript.rubyforge.org">http://rb-appscript.rubyforge.org</a>)</p>
27
+
28
+ <p>Released under the MIT License.</p>
29
+
30
+
31
+ </div>
32
+
33
+ <!-- bottom navigation -->
34
+ <div class="navbar">
35
+ <a href="08_examples.html">Previous</a> | <a href="index.html">Up</a>
36
+ </div>
37
+
38
+ <!--footer-->
39
+ <p class="footer">&copy; 2006 HAS</p>
40
+ </body>
41
+ </html>
data/doc/aem-manual/full.css ADDED
@@ -0,0 +1,21 @@
1
+ body {font-family: sans-serif; line-height:140%; color:#000; background-color:#fff; margin: 0 10%;}
2
+
3
+ #content {margin:2em 0 2.25em;}
4
+ dt {font-weight:bold;}
5
+
6
+ .comment {color:#666; background-color:transparent;}
7
+
8
+ hr {height: 1px; background-color: #114; border: 0px solid #114;}
9
+
10
+
11
+ table {line-height:130%; width:100%; color:#000; background-color:#e8e8ff; border:dotted black 1px; margin:1.2em 0em 2.4em; padding: 0 0 1em;}
12
+
13
+ th, td {padding: 0.4em 1.6em; margin: 0; border-width: 0;}
14
+
15
+ th {text-align:left; font-size:0.95em; color:#225; background-color:#ccd;}
16
+
17
+ thead {background-color:#ccd;}
18
+
19
+
20
+ h1+.navbar {margin-top:0;
21
+ }
data/doc/aem-manual/index.html ADDED
@@ -0,0 +1,43 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>appscript | Contents</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>Contents</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="01_introduction.html">Next</a>
18
+
19
+ </div>
20
+
21
+ <!-- content -->
22
+ <div id="content"><ol>
23
+ <li><a href="01_introduction.html">Introduction</a></li>
24
+ <li><a href="02_apioverview.html">API overview</a></li>
25
+ <li><a href="03_packingandunpackingdata.html">Packing and unpacking data</a></li>
26
+ <li><a href="04_references.html">References</a></li>
27
+ <li><a href="05_targettingapplications.html">Targetting applications</a></li>
28
+ <li><a href="06_buildingandsendingevents.html">Building and sending events</a></li>
29
+ <li><a href="07_findapp.html">Locating applications</a></li>
30
+ <li><a href="08_examples.html">Examples</a></li>
31
+ <li><a href="09_notes.html">Notes</a></li>
32
+ </ol></div>
33
+
34
+ <!-- bottom navigation -->
35
+ <div class="navbar">
36
+ <a href="01_introduction.html">Next</a>
37
+
38
+ </div>
39
+
40
+ <!--footer-->
41
+ <p class="footer">&copy; 2004 HAS</p>
42
+ </body>
43
+ </html>
data/doc/appscript-manual/01_introduction.html ADDED
@@ -0,0 +1,82 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
+ <head>
4
+
5
+ <title>appscript | 1. Introduction</title>
6
+
7
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
+ <style type="text/css" media="all"><!--@import url(full.css);--></style>
9
+
10
+ </head>
11
+ <body>
12
+
13
+ <h1>1. Introduction</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_aboutappscripting.html">Next</a>
18
+
19
+ </div>
20
+
21
+ <!-- content -->
22
+ <div id="content">
23
+ <h2>What is appscript?</h2>
24
+
25
+ <p>Ruby appscript (rb-appscript) is a high-level, user-friendly Apple event bridge that allows you to control scriptable Mac OS X applications using ordinary Ruby scripts. Appscript makes Ruby a serious alternative to Apple's own AppleScript language for automating your Mac.</p>
26
+
27
+ <p>For example, to get the value of the first paragraph of the topmost document in TextEdit:</p>
28
+
29
+ <pre><code>AS.app('TextEdit').documents[1].paragraphs[1].get</code></pre>
30
+
31
+ <p>This is equivalent to the AppleScript statement:</p>
32
+
33
+ <pre><code>tell application "TextEdit"
34
+ get paragraph 1 of document 1
35
+ end tell</code></pre>
36
+
37
+ <p>Appscript builds upon lower-level Ruby modules (ae, aem) to provide:</p>
38
+
39
+ <ol>
40
+ <li>a high-level <em>RPC mechanism</em> for sending commands to applications via Apple events</li>
41
+ <li>a mechanism for converting data between common Ruby and Apple event types</li>
42
+ <li>a simple <em>embedded query language</em> for identifying one or more objects in an application's object model</li>
43
+ <li>a mechanism for representing these object model "references" in human-readable form based on application-defined terminology</li>
44
+ <li>a clean, <em>object oriented-like </em> syntax for ease of use.</li>
45
+ </ol>
46
+
47
+
48
+
49
+ <h2>"Hello World!"</h2>
50
+
51
+ <p>The following script uses appscript to create a new "Hello World!" document in TextEdit:</p>
52
+
53
+ <pre><code>#!/usr/bin/env ruby
54
+
55
+ require "appscript"
56
+
57
+ AS.app('TextEdit').documents.end.make(
58
+ :new => :document,
59
+ :with_properties => {:text => "Hello World!\n"}
60
+ )</code></pre>
61
+
62
+
63
+
64
+ <h2>Notes</h2>
65
+
66
+ <p>Ruby appscript (rb-appscript) is a port of the robust, mature Python appscript (py-appscript) bridge. There are a few minor syntax and API changes to accomodate the differences between the two languages, and rb-appscript lacks the built-in help system provided by py-appscript (external help tools will be provided at a later date), but apart from that they are very similar.</p>
67
+
68
+ <p>Please note that rb-appscript, like py-appscript, takes a few liberties with traditional Ruby syntax and semantics in order to support the behaviours and features provided by the Apple Event Manager API. These differences are noted in later chapters.</p>
69
+
70
+
71
+ </div>
72
+
73
+ <!-- bottom navigation -->
74
+ <div class="navbar">
75
+ <a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_aboutappscripting.html">Next</a>
76
+
77
+ </div>
78
+
79
+ <!--footer-->
80
+ <p class="footer">&copy; 2006 HAS</p>
81
+ </body>
82
+ </html>