README.md
ae8a3de8
 
efe46aa4
 MulleScion is a modern template engine for Objective C
ae8a3de8
 =============
 (written in an oldfashioned way)
 
efe46aa4
 Release on [github](//github.com/mulle-nat/MulleScion): [![Build Status](https://travis-ci.org/mulle-nat/MulleScion.svg?branch=release)](https://travis-ci.org/mulle-nat/MulleScion)
e8bf866e
 
68799ba7
 ***
 
efe46aa4
 It's **heavily** (very heavily) inspired by
ae8a3de8
 
1b3d22ed
 [TWIG](//twig.sensiolabs.org/) "The flexible, fast, and secure template
a18b0ba9
 engine for PHP"
ae8a3de8
 
d2f30cd2
 *MulleScion* is fairly flexible, reasonably fast and can be made as
efe46aa4
  secure as you wish.
 
 * **Reasonably
 Fast** :      *MulleScion* can compile templates into a compressed
                archive format. Loading such an archive ought to be lots faster
fec98eee
                than parsing (but because the parse is so fast, maybe isn't).
efe46aa4
                A compiled template is read-only, you can use it many
a18b0ba9
                times to render different output from different input.
ae8a3de8
 
efe46aa4
 * **Secure** :   *MulleScion* has hooks so your application can ensure
a18b0ba9
                that untrusted template code doesn't have access to all of the
                applications data.
ae8a3de8
 
efe46aa4
 * **Flexible** :    There is the possibility of extending KVC and writing your
a18b0ba9
                own "builtin" fuctions. A template can (if allowed) execute
efe46aa4
                arbitrary ObjC code. MulleScion has a powerful define like
                preprocessing capability and macros to expand your template
a18b0ba9
                vocabulary.
efe46aa4
 
15a315b2
 Here is a simple example, where ObjC code is embedded in a template:
efe46aa4
 
7a5390b8
 	<html>
efe46aa4
 	<!-- rendered by {{ [[NSProcessInfo processInfo] processName] }} on
0b507b44
         {{ [NSDate date] }} -->
15a315b2
 	<body>
 	{% for item in [NSTimeZone knownTimeZoneNames] %}
 	    {% if item#.isFirst %}
 	<table>
 	   <tr><th>TimeZone</th></tr>
efe46aa4
 	    {% endif %}
15a315b2
 	   <tr><td>{{ item }}</td></tr>
 	    {% if item#.isLast %}
 	</table>
 	    {% endif %}
 	{% else %}
 	Sorry, no timezone info available.
 	{% endfor %}
 	</body>
 	</html>
60f3619e
 
 
efe46aa4
 Using the MulleScion.framework the creation of a string from your
ae8a3de8
 object using a template file is as easy as:
 
 	NSString  *output;
efe46aa4
 
ae8a3de8
 	output = [MulleScionTemplate descriptionWithTemplateFile:@"test.scion"
     	                                          dataSource:self];
 
d2f30cd2
 This is the general architecture of *MulleScion*
ae8a3de8
 
d2f30cd2
 ![](/dox/MulleScionDataFlow.png "Data Flow Sketch")
 ![](http://www.mulle-kybernetik.com/software/git/MulleScion/raw/master/dox/MulleScionDataFlow.png "Data Flow Sketch")
ae8a3de8
 
efe46aa4
 *MulleScion* is happily used in a commercial project and has gone through
 enough iterations to pronounce it "ready for production".
ae8a3de8
 
65ba6fec
 
bbe95e43
 
9df26d34
 TOOLS
 =============
eccac379
 There is an interactive editor available for OS X called [MulleScionist](http://www.mulle-kybernetik.com/software/git/MulleScionist/),
9df26d34
 which allows you to edit a HTML scion template and preview the results at the
 same time.
ae8a3de8
 
 
 DOCUMENTATION
 =============
 
efe46aa4
 Virtually all the documentation is contained in example **.scion** templates
 in the `dox` folder. For each command or feature there should be a separate
fec98eee
 template file that documents it. **mulle-scion**, the command line utility,
efe46aa4
 contains  a small quickly hacked together webserver that can present the
fec98eee
 documentation using *MulleScion* itself.
 
efe46aa4
 In Xcode just run `Show Documentation in Webserver` and it should setup the
776920e7
 webserver and open your browser to the right address.
ae8a3de8
 
efe46aa4
 MulleScion is very similar to TWIG, so you can glean much of relevance from
 <http://twig.sensiolabs.org>. If you see a feature in TWIG but don't see it in
 the tests file, it's likely not there (but it's probably easily achieved some
fec98eee
 other way (using a `define` or a `macro` or an ObjC category on **NSString**).
ae8a3de8
 
 
 LIMITATIONS
 =============
 Because you can execute arbitrary ObjC methods, and have access to Key Value
9df26d34
 Coding, MulleScion can pretty much do anything. *MulleScion* uses
efe46aa4
 `NSInvocation` for method calls. That means there will be problems with variable
9df26d34
 arguments methods. Be wary of anything using structs and C-Arrays and
d2f30cd2
 C-strings, although *MulleScion* tries to be as helpful as possible.
ae8a3de8
 
9df26d34
 *MulleScion* does not do arithmetic or bitwise logic, quite on purpose.
ae8a3de8
 
9df26d34
 *MulleScion* `&&` and `||` have no operator precedence, use parentheses.
ae8a3de8
 
9df26d34
 *MulleScion* doesn't prevent you from trying stupid things.
ae8a3de8
 
efe46aa4
 The documentation is not very good, actually it is just more or less a
ae8a3de8
 collection of test cases with comments...
 
a18b0ba9
 
 iOS SUPPORT
 =============
9df26d34
 There is iOS Support :)
a18b0ba9
 
 
448f94fd
 SITES
 =============
efe46aa4
 The main development site is Mulle kybernetiK.
448f94fd
 
b8c659f4
 [http://www.mulle-kybernetik.com/software/git/MulleScion/](http://www.mulle-kybernetik.com/software/git/MulleScion/)
448f94fd
 
 releases are pushed to github
 
b8c659f4
 [https://github.com/mulle-nat/MulleScion/](https://github.com/mulle-nat/MulleScion/)
448f94fd
 
 
ae8a3de8
 TODO
 =============
9df26d34
 It might be nice to have delayed evaluation for render results. More tests.
ae8a3de8
 
 
bbe95e43
 INSTALLATION (mulle-scion command line tool only)
 =============
 
 ```
 brew install mulle-kybernetik/software/mulle-scion
 ```
 
 USAGE mulle-scion
 =============
 
 ```
 Usage:
    mulle-scion [options] <input> <datasource> [output] [arguments]
 
 Options:
    -w       : start webserver for /usr/local/share/mulle-scion/dox
    -z       : write compressed archive to outputfile
    -Z       : write compressed keyed archive to outputfile (for IOS)
 
 Input:
    -        : Read template from stdin
    template : a MulleScion template path or URL
 
 Datasource:
    -        : Read data from stdin (only if input is not stdin already)
    args     : use arguments as datasource (see below)
    bundle   : a NSBundle. It's NSPrincipalClass will be used as the datasource
    plist    : a property list path or URL as datasource, see: plist(5)
    none     : empty datasource
 
 Output:
    -        : Write result to stdout
    file     : Write result to file
 
 Arguments:
    key=value: key/value pairs to be used as __ARGV__ contents
               (unless args as datasource was specified)
 
 Examples:
    echo '***{{ VALUE }}***' | mulle-scion - args - VALUE="VfL Bochum 1848"
    echo '***{{ __ARGV__[ 0]}}***' | mulle-scion - none - "VfL Bochum 1848"
 ```
 
 
ae8a3de8
 AUTHOR
 =============
 Coded by Nat!
 2013 Mulle kybernetiK
 
 Mongoose Webserver by
efe46aa4
 Sergey Lyubka
b8c659f4
 
 Hoedown Library by Natacha Porté
 Vicent Martí
 Xavier Mendez, Devin Torres and the Hoedown authors