website/index.html

   1 <html><head><title>Cycript</title>
   2 </head><body>
   3
   4 <h1>Cycript: Objective-JavaScript</h1>
   5
   6 <h3>What is Cycript?</h3>
   7
   8 <p>A programming language designed to blend the barrier between Objective-C and JavaScript. This project has similar goals to JSCocoa, but a very different set of starting technologies and a different guiding philosophy. In particular, Cycript has started life with a full-blown JavaScript parser/serializer, allowing it to have interesting hybrid syntax without constraints (such as those imposed on JSCocoa by JSLint).</p>
   9
  10 <h3>Is it done?</h3>
  11
  12 <p>Well, it works ;P. It is still "in flux": core language features are changing every few hours. However, it has already changed the workflow of the "elite" iPhone developers that write most of the extensions you see in Cydia: having a language that changes doesn't matter when you are mostly using it at the immediate console. I'm hoping, however, that I manage tolock it into something that feels "correct" in the very near future.</p>
  13
  14 <h3>How do you pronounce "Cycript"?</h3>
  15
  16 <p>I pronounce it "sscript" (with a geminate, aka long, 's'). I doubt anyone else will pronounce it like this, but I have my hopes.</p>
  17
  18 <h3>Where do I get it?</h3>
  19
  20 <p>Right now you can find releases of it at: <a href="http://www.cycript.org/debs/">http://www.cycript.org/debs/</a>. This package depends on MobileSubstrate and libffi (both of which are in Cydia).</p>
  21
  22 <h3>So, how do I use it?!</h3>
  23
  24 <p>Although you can write full applications in Cycript, the fastest way to get playing with it is via the immediate console: just type "cycript".<p>
  25
  26 <xmp>iPhone:~$ cycript
  27 cy# </xmp>
  28
  29 <p>Code typed at this prompt will be executed as it is able to be parsed: the immediate console is trying to eagerly parse lines of code as they come in (and thereby is not subject to automatic-semicolon insertion, for those JavaScript experts). Parse errors will be noted to the output in a hopefully useful fashion.</p>
  30
  31 <xmp>cy# function a() {
  32 cy>    a + q r
  33   | .........^
  34   | syntax error, unexpected Identifier, expecting ; or "\n"
  35 cy# </xmp>
  36
  37 <p>It should be noted that it is possible that you will manage to break my JavaScript serializer. In these cases, parse errors may be thrown by the underlying JavaScript engine rather than Cycript. To debug these issues you can use the special console command ?debug.</p>
  38
  39 <xmp>cy# ?debug
  40 debug == true
  41 cy# var a = ((0 + (1)) * (2 * 3)) + m['a']('\'')
  42 var a=(0+1)*(2*3)+m.a("'");
  43 ...</xmp>
  44
  45 <p>In addition to standard JavaScript, you an also access anything in the Objective-C runtime. Attempts have been made, sparingly, to bridge syntax when possible between the two environments. In particular, you may notice interesting properties of arrays, dictonaries, strings, and numbers. Care has been taken to minimize the damage to the object model.</p>
  46
  47 <xmp>cy# var a = [NSMutableArray arrayWithCapacity:4]
  48 cy# a instanceof Array
  49 true
  50 cy# [a class]
  51 "NSCFArray"
  52 cy# [a addObject:"hello"]; a
  53 ["hello"]
  54 cy# a[1] = 4; a.push(10); a
  55 ["hello",4,10]
  56 cy# a.splice(1, 1, 6, 7); a
  57 ["hello",6,7,10]
  58 cy# b = [1, 2]; [b replaceObjectAtIndex:0 withObject:5]; b
  59 [5,2]</xmp>
  60
  61 <p>Memory management is mostly automatic, but instead of using the usual -[alloc] message you will need to use JavaScript's "new" operator, which returns a special "uninitialized" handle that can be used to send a single message (probably a form of init) before it "expires" and reverts to nil.</p>
  62
  63 <xmp>cy# var a = new NSMutableDictionary
  64 cy# a
  65 "*** -[NSCFDictionary count]: method sent to an uninitialized mutable dictionary object"
  66 cy# var b = [a init]; b
  67 {}
  68 cy# a
  69 nil
  70 cy# var q = [new NSString init]; q
  71 ""</xmp>
  72
  73 <p>One note in particular is made about selectors. Not only do they act as in Objective-C, including being typed using @selector notation, but they also have Function.prototype in their prototype-chain, allowing you to use them in interesting functional ways ala JavaScript. You can also generate one from a string using new Selector().</p>
  74
  75 <xmp>cy# var sel = @selector(initWithFrame:)
  76 cy# sel
  77 @selector(initWithFrame:)
  78 cy# sel.call(new UIView, [UIHardware fullScreenApplicationContentRect])
  79 "<UIView: 0x22dae0; frame = (0 20; 320 460); layer = <CALayer: 0x209990>>"
  80 cy# new Selector("initWithFrame:")
  81 @selector(initWithFrame:)</xmp>
  82
  83 <p>As one would expect from JavaScript, objects have a property called constructor that references their class. You can also add methods along the prototype chain to instances. Eventually, all objects go through Instance, where you can put functions that should be available for all Objective-C classes.</p>
  84
  85 <xmp>cy# Instance.prototype.getMethod = function (sel) { return class_getInstanceMethod(this, sel); }
  86 {}
  87 cy# NSObject.getMethod(@selector(init))
  88 0x801354
  89 cy# NSObject.prototype.getMethod = function (sel) { return "ark"; }
  90 {}
  91 cy# NSObject.getMethod(@selector(init))
  92 "ark"</xmp>
  93
  94 <p>Given that sending messages is actually a different namespace than function resolution, it is important to separate out the analog of a "prototype" in the world of Objective-C from that in JavaScript. Therefore, a field called "messages" (may change) is also added to Class objects. These messages can even be traded around and reassigned, with the results fully mapping back to the Objective-C runtime.</p>
  95
  96 <xmp>cy# var view = [new UIView init]
  97 cy# view.constructor
  98 "UIView"
  99 cy# view.constructor.messages['description']
 100 0x309d84f5
 101 cy# [view description]
 102 "<UIView: 0x229bc0; frame = (0 0; 0 0); layer = <CALayer: 0x229d60>>"
 103 cy# view.constructor.messages['description'] = function () { return "not!"; }
 104 {}
 105 cy# [view description]
 106 "not!"</xmp>
 107
 108 <p>Structures are also supported (although unions are currently on the todo list and bitfields are still DOA): they are bridged back/forth as much as possible. You can specify them using either array syntax or in the form of dictionaries.</p>
 109
 110 <xmp>cy# var rect = [UIHardware fullScreenApplicationContentRect]
 111 cy# rect
 112 {origin:{x:0,y:20},size:{width:320,height:460}}
 113 cy# rect.origin = [2, 3]
 114 [2,3]
 115 cy# rect.size = {width: 0, height: 1}
 116 {width:0,height:1}
 117 cy# rect
 118 {origin:{x:2,y:3},size:{width:0,height:1}}</xmp>
 119
 120 <p>Access, allocation, and casting of pointers is possible through the usage of the Pointer and Type classes. Pointers can be indirected using the * and -> operators, as in C.</p>
 121
 122 <xmp>cy# var count = new new Type("I")
 123 cy# var methods = class_copyMethodList(UIApplication, count)
 124 cy# *count
 125 305
 126 cy# *new Pointer(count, "d")
 127 7.304555902977629e-304
 128 cy# free(count)
 129 cy# methods
 130 0x843800
 131 cy# methods[304]
 132 0x825248
 133 cy# method_getName(methods[304])
 134 @selector(init)</xmp>
 135
 136 <p>Objective-C @properties (some of which are auto-detected, as Apple doesn't always compile them into the resulting binaries) can be accessed using . notation. Currently, auto-detected @properties are usable, but aren't enumerable. This namespace is strictly separated from that of instance variables, which you can access by indirecting the object using * or ->.</p>
 137
 138 <xmp>cy# var view = [new UIView init]
 139 cy# ps = []; for (var p in view) ps.push(p); ps
 140 ["skipsSubviewEnumeration","gestureRecognizers","gesturesEnabled","capturesDescendantTouches","deliversTouchesForGesturesToSuperview","userInteractionEnabled","layer","tag"]
 141 cy# vs = []; for (var v in *view) vs.push(v); vs
 142 ["isa","_layer","_tapInfo","_gestureInfo","_gestureRecognizers","_charge","_tag","_viewFlags"]
 143 cy# view.layer
 144 "<CALayer: 0x228f60>"
 145 cy# view->_layer
 146 "<CALayer: 0x228f60>"
 147 cy# (*view)._layer
 148 "<CALayer: 0x228f60>"</xmp>
 149
 150 <p>Fully-fledged Objective-C classes can also be declared using @class, which blurs the line between Objective-C's @interface and @implementation. Right now, declaring instance variables are not supported, but will be in a future version: for now you must provide an empty variable block.</p>
 151
 152 <xmp>cy# @class TestClass : NSObject {
 153 cy> }
 154 cy> - description {
 155 cy>     return "test";
 156 cy> }
 157 cy> @end
 158 cy# [new TestClass init]
 159 "test"</xmp>
 160
 161 <p>The @class syntax can also be used to extend existing classes in a manner similar to categories. Note that type signatures, however, are not yet supported, so you end up heavily restricted in what you can add via this mechanism. In this case, one can also use a parenthesized expression as the class name.</p>
 162
 163 <xmp>cy# @class NSObject
 164 cy> - description { return "replaced"; }
 165 cy> @end
 166 cy# var o = [new NSObject init]
 167 cy# o
 168 "replaced"
 169 cy# @class ([o class]) - description { return "again"; } @end
 170 cy# o
 171 "again"</xmp>
 172
 173 <p>Cycript is also capable of accessing normal C functions and variables. Knowledge of the type signatures of various functions are provided in the bridge definition file, which is currently a plist stored at /usr/lib/libcycript.plist.</p>
 174
 175 <xmp>cy# malloc
 176 0x31d48389
 177 cy# var p = malloc(4)
 178 cy# p
 179 0x22e0a0
 180 cy# free(p)
 181 cy# </xmp>
 182
 183 <p>Cycript attempts to do its best to serialize information to the console about objects. In particular, CoreFoundaton objects bridged to Objective-C are detected and printed using CFCopyDescription.</p>
 184
 185 <xmp>cy# UIGetScreenImage()
 186 "<CGImage 0x22f540>"
 187 cy# ABAddressBookCreate()
 188 "<ABCAddressBook 0x229cf0 [0x38208484]>"</xmp>
 189
 190 <h3>How do I write an application with it?</h3>
 191
 192 <p>This isn't quite "ready for primetime", but you can download the example HelloCycript.app from <a href="http://www.cycript.org/examples/">http://www.cycript.org/examples/</a> and put it in /Applicatons.</p>
 193
 194 <h3>What else can it do?</h3>
 195
 196 <p>Probably the awesomest thing you can do with Cycript is to hook into an existing process using the -p argument to the console interpreter. As an example, let's hook our way into SpringBoard and start spelunking.</p>
 197
 198 <xmp>iPhone:~$ ps ax | grep Spring
 199 18110   ??  Us     0:03.03 /System/Library/CoreServices/SpringBoard.app/SpringBoard
 200 18115 s006  S+     0:00.02 grep --color=auto --exclude=.svn Spring
 201 iPhone:~$ cycript -p 18110
 202 cy# UIApp
 203 "<SpringBoard: 0x266f00>"
 204 cy# UIApp->_uiController.window
 205 "<SBAppWindow: 0x27ac10; baseClass = UIWindow; frame = (0 0; 320 480); layer = <CALayer: 0x27aba0>>"
 206 cy# UIApp->_uiController.window.subviews
 207 ["<UIView: 0x4a6efa0; frame = (0 0; 320 480); autoresize = W+H; layer = <CALayer: 0x4a62d70>>","<SBAppContextHostView: 0x49a68f0; frame = (0 0; 320 480); clipsToBounds = YES; hidden = YES; layer = <CALayer: 0x2b4d10>> enabled: yes, context array: (\n)","<SBAppContextHostView: 0x4b5ccf0; frame = (0 0; 320 480); clipsToBounds = YES; hidden = YES; layer = <CALayer: 0x4b7f180>> enabled: yes, context array: (\n)"]
 208 cy# UIApp->_uiController.window.subviews[0].subviews
 209 ["<UIImageView: 0x4b3cea0; frame = (0 0; 320 480); opaque = NO; userInteractionEnabled = NO; layer = <CALayer: 0x4a75550>>","<UIView: 0x4b4ba80; frame = (0 0; 320 480); autoresize = W+H; layer = <CALayer: 0x4b4bbf0>>"]
 210 cy# UIApp->_uiController.window.subviews[0].subviews[0].image.size
 211 {width:320,height:480}
 212 cy# UIApp->_uiController.window.subviews[0].subviews[1].subviews
 213 ["<SBIconContentView: 0x4b4bc20; frame = (0 40; 320 349); autoresize = H; layer = <CALayer: 0x4a613c0>>","<UIView: 0x4a25250; frame = (0 389; 320 91); layer = <CALayer: 0x4a38630>>"]
 214 cy# UIApp->_uiController.window.subviews[0].subviews[1].subviews[0].subviews
 215 ["<SBIconListPageControl: 0x27aab0; baseClass = UIPageControl; frame = (0 330; 320 19); autoresize = TM; layer = <CALayer: 0x4b3c370>>","<SBIconScrollView: 0x4a62360; baseClass = UIScrollView; frame = (0 0; 320 330); autoresize = H; layer = <CALayer: 0x4a624e0>>"]
 216 cy# var pages = UIApp->_uiController.window.subviews[0].subviews[1].subviews[0].subviews[0]
 217 cy# pages.currentPage
 218 1
 219 cy# pages.numberOfPages
 220 15</xmp>
 221
 222 </body></html>