rb-appscript 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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>