Difference between revisions of "Cycript"

From iPhone Development Wiki
Jump to: navigation, search
m (Additional syntax: a->[c])
m (Bump version number)
 
(18 intermediate revisions by 7 users not shown)
Line 2: Line 2:
 
|developer=saurik
 
|developer=saurik
 
|package=cycript
 
|package=cycript
|version=0.9.233-1
+
|version=0.9.594
 
}}
 
}}
  
[[Cycript]] is a Javascript interpreter which also understands Objective-C syntax. The <tt>cycript</tt> binary is also a [http://en.wikipedia.org/wiki/Read-eval-print_loop REPL] for this language.
+
'''Cycript''' is a JavaScript interpreter which also understands Objective-C syntax. The <tt>cycript</tt> binary is also a [http://en.wikipedia.org/wiki/Read-eval-print_loop REPL] for this language.
  
 
Besides evaluating scripts, Cycript can also hook into a running process (using <tt>cycript -p </tt>''process'') and modify its property.  
 
Besides evaluating scripts, Cycript can also hook into a running process (using <tt>cycript -p </tt>''process'') and modify its property.  
  
Currently Cycript is in beta, so information on this page may change over time.
+
Official documentation can be found on [http://www.cycript.org/manual cycript.org].
 +
 
 +
Presentations about Cycript: [http://www.youtube.com/watch?v=5d1cK0nq4GY saurik explaining how to use Cycript on OS X, targeting the iOS simulator]; [http://www.youtube.com/watch?v=Ox09rWJTuCA Adam Bell explaining how to use Cycript to prototype a tweak] ([https://github.com/b3ll/JailbreakCon2013 example code]).
  
 
== JS/ObjC Object Bridging ==
 
== JS/ObjC Object Bridging ==
Some native Javascript types are bridged to the corresponding Objective-C types for convenient, so you can use
+
 
 +
Some native JavaScript types are bridged to the corresponding Objective-C types for convenient, so you can use
 
<source lang="javascript">[[41,"foo",true,[8,6],{a:12,b:46},36] indexOfObject:"foo"]</source>
 
<source lang="javascript">[[41,"foo",true,[8,6],{a:12,b:46},36] indexOfObject:"foo"]</source>
 
instead of
 
instead of
Line 49: Line 52:
 
<tt>null</tt> in Cycript is equivalent to <tt>nil</tt> in Objective-C. Additionally, <tt>nil</tt>, <tt>YES</tt> and <tt>NO</tt> are also defined in Cycript.
 
<tt>null</tt> in Cycript is equivalent to <tt>nil</tt> in Objective-C. Additionally, <tt>nil</tt>, <tt>YES</tt> and <tt>NO</tt> are also defined in Cycript.
  
== Javascript 1.6+ Features ==
+
== JavaScript 1.6+ Features ==
Cycript supports the following Javascript 1.6+ features extended by Mozilla:
+
 
 +
Cycript supports the following JavaScript 1.6+ features extended by Mozilla:
 
* [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Statements/for_each...in <tt>for each/in</tt>] (JS1.6)
 
* [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Statements/for_each...in <tt>for each/in</tt>] (JS1.6)
 
* [https://developer.mozilla.org/en/New_in_JavaScript_1.7#Array_comprehensions Array comprehensions] (JS1.7)
 
* [https://developer.mozilla.org/en/New_in_JavaScript_1.7#Array_comprehensions Array comprehensions] (JS1.7)
 
<!-- * [https://developer.mozilla.org/en/New_in_JavaScript_1.7#Block_scope_with_let <tt>let</tt> statement] (JS1.7) -->
 
<!-- * [https://developer.mozilla.org/en/New_in_JavaScript_1.7#Block_scope_with_let <tt>let</tt> statement] (JS1.7) -->
 +
* E4X (not available on iPhoneOS).
  
 
== Additional syntax ==
 
== Additional syntax ==
Line 66: Line 71:
 
| Sends ''msg'' to ''obj'' with parameters ''var''. This is the Objective-C's message sending syntax.
 
| Sends ''msg'' to ''obj'' with parameters ''var''. This is the Objective-C's message sending syntax.
 
| <tt>objc_msgSend(</tt>''obj''<tt>, @selector(</tt>''msg''<tt>).value, </tt>''var''<tt> ...)</tt>
 
| <tt>objc_msgSend(</tt>''obj''<tt>, @selector(</tt>''msg''<tt>).value, </tt>''var''<tt> ...)</tt>
 +
|-
 +
| <tt>@import(</tt>''module''<tt>)</tt>
 +
| colspan="2" | Import a .cy file. Similar to JavaScript's ''require()'' function.
 
|-
 
|-
 
| <tt>@selector(</tt>''selname''<tt>)</tt>
 
| <tt>@selector(</tt>''selname''<tt>)</tt>
Line 97: Line 105:
 
| <tt>@"</tt>''str''<tt>"</tt>
 
| <tt>@"</tt>''str''<tt>"</tt>
 
| colspan="2" | Equivalent to <tt>"</tt>''str''<tt>"</tt>.  
 
| colspan="2" | Equivalent to <tt>"</tt>''str''<tt>"</tt>.  
 +
|-
 +
| <tt>[super</tt> ...<tt>]</tt>
 +
| A local variable representing the superclass.
 +
| <tt>objc_msgSend(???,</tt> ... <tt>)</tt>
 +
|-
 +
| <tt>0b</tt>''xxxxxx''
 +
| colspan="2" | Binary literal.
 
|}
 
|}
  
 
== REPL-only additions ==
 
== REPL-only additions ==
 +
 
These are used for debugging.
 
These are used for debugging.
 +
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 114: Line 131:
 
| <tt>?expand</tt>
 
| <tt>?expand</tt>
 
| Toggles whether to display the line break characters, etc. as really a line break or just <tt>\n</tt>.
 
| Toggles whether to display the line break characters, etc. as really a line break or just <tt>\n</tt>.
 +
|-
 +
| <tt>?gc</tt>
 +
| Force a JavaScript garbage collection.
 +
|-
 +
| <tt>?syntax</tt>
 +
| Toggle syntax highlighting.
 
|}
 
|}
  
 
== Additional types ==
 
== Additional types ==
 +
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 136: Line 160:
 
| <tt>Instance</tt>(''address'')
 
| <tt>Instance</tt>(''address'')
 
| Treat the address as an instance of Objective-C object.  
 
| Treat the address as an instance of Objective-C object.  
 +
|-
 +
| <tt>Super</tt>(''self'', ''selector'')
 +
| Returns an object which, when being sent a message, will be forwarded to ''self'''s superclass.
 
|}
 
|}
 
Additionally, the identifiers like <tt>int</tt>, <tt>id</tt>, <tt>char</tt>, <tt>double</tt>, etc. are predefined to the corresponding types (<tt>new Type("i")</tt>, etc). Therefore, to allocator a pointer you may simply use <tt>new int</tt> or even <tt>new int[42]</tt>.
 
Additionally, the identifiers like <tt>int</tt>, <tt>id</tt>, <tt>char</tt>, <tt>double</tt>, etc. are predefined to the corresponding types (<tt>new Type("i")</tt>, etc). Therefore, to allocator a pointer you may simply use <tt>new int</tt> or even <tt>new int[42]</tt>.
  
 
== Additional variables and methods ==
 
== Additional variables and methods ==
 +
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 178: Line 206:
 
| Returns the type encoding for the ''selector'' in ''class''. For example, <tt>@selector(copyWithZone:).type(NSString)</tt> returns <tt>@[email protected]:4^{_NSZone=}8</tt>.
 
| Returns the type encoding for the ''selector'' in ''class''. For example, <tt>@selector(copyWithZone:).type(NSString)</tt> returns <tt>@[email protected]:4^{_NSZone=}8</tt>.
 
|}
 
|}
 +
 +
== Other uses ==
 +
 +
The cycript binary can be used to "compile" Cycript into standard JavaScript 1.5 with the <tt>-c</tt> flag, e.g.
 +
<source lang="bash">
 +
Your-iPhone:~ mobile$ echo "[x*x for each(x in [1,2,3])]" | cycript -c > x.js
 +
Your-iPhone:~ mobile$ cat x.js
 +
(function($cyv,x){$cyv=[];(function($cys){$cys=[1,2,3];for(x in $cys){x=$cys[x];$cyv.push(x*x)}})();return $cyv})()
 +
</source>
 +
 +
== Considerations ==
 +
 +
* Every command typed into the console is run in an autorelease pool so variables "declared" in one command might be deallocated by the time the next command that uses it is run.
  
 
== See also ==
 
== See also ==
 +
 
* [[Cycript Tricks]]
 
* [[Cycript Tricks]]
  
== References ==
+
== External links ==
* Official website: http://www.cycript.org/
+
 
* SVN trunk: http://svn.saurik.com/repos/cycript/trunk/
+
* [http://www.cycript.org/ Official website]
 +
* Source: http://gitweb.saurik.com/cycript.git (git://git.saurik.com/cycript.git)
  
 
{{Navbox ObjCBridges}}
 
{{Navbox ObjCBridges}}

Latest revision as of 22:13, 30 November 2016

Cycript
Cydia Package
Developer saurik
Package ID cycript
Latest Version 0.9.594


Cycript is a JavaScript interpreter which also understands Objective-C syntax. The cycript binary is also a REPL for this language.

Besides evaluating scripts, Cycript can also hook into a running process (using cycript -p process) and modify its property.

Official documentation can be found on cycript.org.

Presentations about Cycript: saurik explaining how to use Cycript on OS X, targeting the iOS simulator; Adam Bell explaining how to use Cycript to prototype a tweak (example code).

JS/ObjC Object Bridging

Some native JavaScript types are bridged to the corresponding Objective-C types for convenient, so you can use

[[41,"foo",true,[8,6],{a:12,b:46},36] indexOfObject:"foo"]

instead of

[[NSArray arrayWithObjects:
  [NSNumber numberWithInt:41],
  "foo",
  [NSNumber numberWithBool:YES],
  [NSArray arrayWithObjects:[NSNumber numberWithInt:8], [NSNumber numberWithInt:6], nil],
  [NSDictionary dictionaryWithObjectsAndKeys:
    [NSNumber numberWithInt:12], "a",
    [NSNumber numberWithInt:46], "b",
  nil],
  [NSNumber numberWithInt:36],
nil] indexOfObject:"foo"]
JS type ObjC type
number NSNumber (CFNumber)
boolean NSNumber (CFBoolean)
string NSString
Array NSArray
object (Associative array) NSDictionary

null in Cycript is equivalent to nil in Objective-C. Additionally, nil, YES and NO are also defined in Cycript.

JavaScript 1.6+ Features

Cycript supports the following JavaScript 1.6+ features extended by Mozilla:

Additional syntax

New Syntax Meaning "Desugared" representation
[obj msg:var] Sends msg to obj with parameters var. This is the Objective-C's message sending syntax. objc_msgSend(obj, @selector(msg).value, var ...)
@import(module) Import a .cy file. Similar to JavaScript's require() function.
@selector(selname) Returns the selector named selname with Objective-C syntax. new Selector("selname");
obj->ivar Obtain the instant variable ivar of an Objective-C object obj. obj.$cyi.ivar
*ptr Dereference the pointer, or list all ivars of an object (so that you can access them using (*obj).ivar). ptr.$cyi
obj->[key] Equivalent to (*obj)[key].
&var Takes the address of a variable. Only instances of ObjC class can have addresses. var.$cya()
@class classname : superclass {}
+
methodname { function body }
-
methodname { function body }
...
@end
Declare an Objective-C class. The classname can be omitted, where an anonymous class will be declared.
@class existingclass
+
methodname { function body }
-
methodname { function body }
...
@end
Insert extra methods to an existing class. The existingclass itself can be an expression e.g. @class ([obj class]) ....
new classname Although not exactly a new syntax, this construction has a new meaning for Objective-C classes. This is similar to [classname alloc], but the resource will be managed by JavaScriptCore's garbage collector. To fully initialize the class, you need to call [new classname initWithFoo:...].
@"str" Equivalent to "str".
[super ...] A local variable representing the superclass. objc_msgSend(???, ... )
0bxxxxxx Binary literal.

REPL-only additions

These are used for debugging.

Line Usage
?debug Toggles debug output.
?bypass Bypass syntax error pretty-printing.
?expand Toggles whether to display the line break characters, etc. as really a line break or just \n.
?gc Force a JavaScript garbage collection.
?syntax Toggle syntax highlighting.

Additional types

Type/Constructor Usage
Selector(selname) Declare a selector.
Functor(function body, type encoding) Associate an Objective-C type encoding to a function, e.g. new Functor(function(x,y){return (x+y).toString(16);}, "*dd"); to declare a (double, double) → char* function.
Pointer(address, type encoding) Treat the input number as a pointer. Like C pointers, the result can be dereferenced using * and subscripted using [i], but pointer arithmetic is not directly supported.
Type(type encoding) Create a type. The resulting value can be new-ed to get a Pointer, e.g. var p = new new Type("d");. To deallocate the pointer, use the free() function.
Instance(address) Treat the address as an instance of Objective-C object.
Super(self, selector) Returns an object which, when being sent a message, will be forwarded to self's superclass.

Additionally, the identifiers like int, id, char, double, etc. are predefined to the corresponding types (new Type("i"), etc). Therefore, to allocator a pointer you may simply use new int or even new int[42].

Additional variables and methods

Variable Meaning
_ Last evaluated value (REPL only).
ObjectiveC.images An associative array, with keys beings the path of loaded libraries, and value is the classes of this library.
ObjectiveC.classes An associative array of classes. The keys are class names and the values are the classes themselves.
ObjectiveC.protocols An associative array of protocols. The keys are protocol names and the values are the protocols themselves.
obj.toJSON() Convert the object to JSON.
obj.toCYON() Convert the object to CYON (Cycript object notation).
obj.value For some objects, returns the address.
class.messages Contains an associative array of messages in the class. The keys are the selector names and the values are implementations (functions).
system.print(string) Print the string to syslog.
system.args Parameters of the executable
selector.type(class) Returns the type encoding for the selector in class. For example, @selector(copyWithZone:).type(NSString) returns @[email protected]:4^{_NSZone=}8.

Other uses

The cycript binary can be used to "compile" Cycript into standard JavaScript 1.5 with the -c flag, e.g.

Your-iPhone:~ mobile$ echo "[x*x for each(x in [1,2,3])]" | cycript -c > x.js
Your-iPhone:~ mobile$ cat x.js
(function($cyv,x){$cyv=[];(function($cys){$cys=[1,2,3];for(x in $cys){x=$cys[x];$cyv.push(x*x)}})();return $cyv})()

Considerations

  • Every command typed into the console is run in an autorelease pool so variables "declared" in one command might be deallocated by the time the next command that uses it is run.

See also

External links