RUIC 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a99bfd85a630d1804e5c38b33296883a2f43342
-  data.tar.gz: f3233b7830899344bcee0c969fdb130e88143b1d
+  metadata.gz: 1c4a0b020e018104674acc04364e26190043161b
+  data.tar.gz: dfea032213116f92cd14c5eccb35286213b28a96
 SHA512:
-  metadata.gz: 474bf2cda9e565b3a050fadb9b266980f3b36075f0a953eabf69106695e623575e980fab75c007e78e47f6de6f5e58f0fad217261008392616b47eeca66207d7
-  data.tar.gz: 5a3066ad987ce4597b0ef47d935c8db28bc477ffb281300406184d1119539f84d6130478e3f7ca6dbb3b025d0603567cea0c208fa89867c75d81031832d1a8a0
+  metadata.gz: 2314350ab17e64a43e6afdf95537287e4ce781f023172634a02e7b285c38c88e1e344df87bbe1bb2feee655a17d1f5b4f0f8fcce0b7caf5e23dbe85b11d2728d
+  data.tar.gz: 1f2e65d2327897075f4c91917aa21d504a3919790d12cdd94a41392584291b1f5d1bd0600ebdf797be4e94afed51d7cbec9890dc74d8a63ad71cdda6240bf94c

data/.yardopts

@@ -1,4 +1,4 @@
---no-private
---markup markdown
-lib/**/*.rb -
+--no-private
+--markup markdown
+lib/**/*.rb -
 README.md LICENSE HISTORY

data/HISTORY

@@ -1,86 +1,110 @@
-## v0.6.0
-
-### Backwards Incompatible Changes
-
-* Changed `FileBacked#resolve_file_path` to `FileBacked#absolute_path`, and added `FileBacked#relative_path`.
-* Removed `.errors?` and `.errors` for application and assets.
-
-### New/Changed Features
-
-* State machines properly report on visual actions.
-  * _Only `<set-attribute>` properly implemented so far._
-* Added much improved `Presentation#referenced_files`, `Application#missing_files`, `Application#unused_files`.
-* Tweaked REPL output.
-  * `nil` results no longer print `#=> nil` in the REPL.
-  * `show` prefixes the result with `#=>`.
-  * Multi-line results are now wrapped, with each line prefixed with `#=>`.
-* Added beginnings of support for effects and renderplugins.
-* Presentations do not cause a runtime error if a custom class (e.g. behavior, effect, custom material) cannot be found.
-
-### Bug Fixes
-* Fix bug that caused some properties to report their type as `nil` or `float` instead of `Float`.
-* Presentations are slightly more capable if they are created without an existing file.
-
-## v0.5.0 - 2014-Nov-26
-
-* Fix bug that prevented loading an application from the command line in another directory.
-* Compatibility: `FileBacked#path_to` is now `FileBacked#resolve_file_path` to prevent conflict with `Presentation#path_to`.
-* Make `inspect` representation of assets more useful.
-* Add convenience methods for collections of assets by type on presentations:
-  `.layers`, `.groups`, `.cameras`, `.lights`, `.components`, `.models`, `.materials`,
-  `.images`, `.behaviors`, `.aliases`, `.paths`, `.anchor_points`, `.texts`
-* Fix bug that prevented behavior instances from having proper `name` or `sourcepath` attribute values.
-* Added `.hierarchy` to presentations and assets for printing the scene graph.
-
-## v0.4.5 - 2014-Nov-19
-
-* Added a large amount of documentation.
-* Minor code refactoring:
-  * Most (internal) Presentation methods that took a scene graph element as the argument now take an asset.
-  * All `FileBacked` assets now have `save!` and `save_as`.
-
-## v0.4.1 - 2014-Nov-16
-
-* Update `MetaData.xml` for tests to newest version.
-* Source paths for images/textures normalize the path (forward slashes and no leading `./`).
-* Added `app.main` as a simpler alias for `app.main_presentation`.
-* Add support for paths and anchor points, including `mypath.anchors` as an array of anchor points.
-* Assets present in MetaData and presentation, but not yet hand-entered into the hierarchy, now work and default to inherit from `Asset`.
-
-## v0.4.0 - 2014-Nov-11
-* Switch attribute filtering again; now all attributes are inline in the `find()` hash, and the four special keys are prefixed with an underscore: `_type`, `_slide`, `_master`, and `_under`.
-
-## v0.3.0 - 2014-Nov-10
-* Switch attribute filtering to use `attr:{ … }` instead of `attributes:{ … }`
-* Attribute matching now requires that a requested attribute be present, or else the asset matching fails.
-  * _For example, `main.find attr:{ diffusecolor:[nil,nil,nil] }` will now only find assets with a `diffusecolor` attribute._
-
-## v0.2.5 - 2014-Nov-10
-* Re-adds blank line after REPL result.
-
-## v0.2.4 - 2014-Nov-10
-* Fix bug with history editing in REPL (prompts no longer have a blank line before)
-* Add temporary hack to make projects using Float2 load correctly
-
-## v0.2.3 - 2014-Nov-7
-* Cleaner mechanism for creating a truly blank binding
-
-## v0.2.2 - 2014-Nov-7
-* REPL shows version number when it starts
-
-## v0.2.1 - 2014-Nov-7
-* REPL mode after script maintains binding of script (all local variables remain available)
-* Customized `.irbrc` files will not cause warnings
-
-## v0.2.0 - 2014-Nov-7
-* Add Presentation#save_as
-* REPL working directory is same as .uia
-
-## v0.1.0 - 2014-Nov-7
-* Add REPL mode for ruic binary
-
-## v0.0.1 - 2014-Nov-7
-* Initial gem release
-* Crawl presentations and modify attributes
-* Batch find assets
-* Save presentation changes back to disk
+## v0.6.1
+
+### New/Changed Features
+
+* Support for the new `PathBuffer` property types (for paths that reference a `.path` on disk).
+* Unsupported/invalid custom property types fall back to String (with a warning).
+
+### Bug Fixes
+* Render plugins are now lightly tested and supported.
+
+
+## v0.6.0
+
+### Backwards Incompatible Changes
+
+* Changed `FileBacked#resolve_file_path` to `FileBacked#absolute_path`, and added `FileBacked#relative_path`.
+* Removed `.errors?` and `.errors` for application and assets.
+
+### New/Changed Features
+
+* State machines properly report on visual actions.
+  * _Only `<set-attribute>` properly implemented so far._
+* Added much improved `Presentation#referenced_files`, `Application#missing_files`, `Application#unused_files`.
+* Tweaked REPL output.
+  * `nil` results no longer print `#=> nil` in the REPL.
+  * `show` prefixes the result with `#=>`.
+  * Multi-line results are now wrapped, with each line prefixed with `#=>`.
+* Added beginnings of support for effects and renderplugins.
+* Presentations do not cause a runtime error if a custom class (e.g. behavior, effect, custom material) cannot be found.
+
+### Bug Fixes
+* Fix bug that caused some properties to report their type as `nil` or `float` instead of `Float`.
+* Presentations are slightly more capable if they are created without an existing file.
+
+
+## v0.5.0 - 2014-Nov-26
+
+* Fix bug that prevented loading an application from the command line in another directory.
+* Compatibility: `FileBacked#path_to` is now `FileBacked#resolve_file_path` to prevent conflict with `Presentation#path_to`.
+* Make `inspect` representation of assets more useful.
+* Add convenience methods for collections of assets by type on presentations:
+  `.layers`, `.groups`, `.cameras`, `.lights`, `.components`, `.models`, `.materials`,
+  `.images`, `.behaviors`, `.aliases`, `.paths`, `.anchor_points`, `.texts`
+* Fix bug that prevented behavior instances from having proper `name` or `sourcepath` attribute values.
+* Added `.hierarchy` to presentations and assets for printing the scene graph.
+
+
+## v0.4.5 - 2014-Nov-19
+
+* Added a large amount of documentation.
+* Minor code refactoring:
+  * Most (internal) Presentation methods that took a scene graph element as the argument now take an asset.
+  * All `FileBacked` assets now have `save!` and `save_as`.
+
+
+## v0.4.1 - 2014-Nov-16
+
+* Update `MetaData.xml` for tests to newest version.
+* Source paths for images/textures normalize the path (forward slashes and no leading `./`).
+* Added `app.main` as a simpler alias for `app.main_presentation`.
+* Add support for paths and anchor points, including `mypath.anchors` as an array of anchor points.
+* Assets present in MetaData and presentation, but not yet hand-entered into the hierarchy, now work and default to inherit from `Asset`.
+
+
+## v0.4.0 - 2014-Nov-11
+* Switch attribute filtering again; now all attributes are inline in the `find()` hash, and the four special keys are prefixed with an underscore: `_type`, `_slide`, `_master`, and `_under`.
+
+
+## v0.3.0 - 2014-Nov-10
+* Switch attribute filtering to use `attr:{ … }` instead of `attributes:{ … }`
+* Attribute matching now requires that a requested attribute be present, or else the asset matching fails.
+  * _For example, `main.find attr:{ diffusecolor:[nil,nil,nil] }` will now only find assets with a `diffusecolor` attribute._
+
+
+## v0.2.5 - 2014-Nov-10
+* Re-adds blank line after REPL result.
+
+
+## v0.2.4 - 2014-Nov-10
+* Fix bug with history editing in REPL (prompts no longer have a blank line before)
+* Add temporary hack to make projects using Float2 load correctly
+
+
+## v0.2.3 - 2014-Nov-7
+* Cleaner mechanism for creating a truly blank binding
+
+
+## v0.2.2 - 2014-Nov-7
+* REPL shows version number when it starts
+
+
+## v0.2.1 - 2014-Nov-7
+* REPL mode after script maintains binding of script (all local variables remain available)
+* Customized `.irbrc` files will not cause warnings
+
+
+## v0.2.0 - 2014-Nov-7
+* Add Presentation#save_as
+* REPL working directory is same as .uia
+
+
+## v0.1.0 - 2014-Nov-7
+* Add REPL mode for ruic binary
+
+
+## v0.0.1 - 2014-Nov-7
+* Initial gem release
+* Crawl presentations and modify attributes
+* Batch find assets
+* Save presentation changes back to disk

data/README.md

@@ -1,220 +1,220 @@
-# What is RUIC?
-RUIC is a Ruby API for reading, analyzing, and manipulating application assets created by NVIDIA's [UI Composer][1]. Among other things, it allows you to:
-
-* See if an application is missing any assets (e.g. images or meshes) and what parts of the application are looking for those.
-* See if there are any files in the application folder that you can delete (e.g. images or materials that are no longer being used).
-* Read and modify the attributes of elements on different slides.
-* Batch change attributes (e.g. change all usage of one font or color to another).
-* Procedurally generate many models with automated placement in your scene.
-
-_Some of the features above are planned, but not yet implemented; see Known Limitations below._
-
-
-# Documentation
-
-In addition to the examples in this file full API documentation is available at:
-http://www.rubydoc.info/gems/RUIC/
-
-
-
-# Installing RUIC
-RUIC can be installed via RubyGems (part of Ruby) via the command:
-
-    gem install ruic   # May need `sudo gem install ruic` depending on your setup
-
-Although RUIC is a pure-Ruby library, it relies on [Nokogiri][2] for all the XML processing and manipulation. Installing RUIC will also automatically install Nokogiri, which may require some compilation.
-
-
-
-# Using the RUIC DSL
-
-RUIC scripts are pure Ruby with a few convenience methods added. You run them via the `ruic` command-line script, e.g.
-
-    ruic myscript.ruic  # or .rb extension, for syntax highlighting while editing
-
-
-## Creating and Accessing Applications
-RUIC scripts must start with `uia` commands to load an application and all its assets.
-After this you can access the application as `app`:
-
-```ruby
-uia '../MyApp.uia'      # Relative to the ruic script file, or absolute
-
-show app.file           #=> /var/projects/UIC/MyApp/main/MyApp.uia
-show app.filename       #=> MyApp.uia
-
-show app.assets.count   #=> 7
-# You can ask for app.behaviors, app.presentations, app.statemachines, and app.renderplugins
-# for arrays of specific asset types
-```
-
-_The `show` command prints the result; it is simply a nicer alias for `puts`._
-
-If you need to load multiple applications in the same script, subsequent `uia` commands will create
-`app2`, `app3`, etc. for you to use.
-
-```ruby
-uia '../MyApp.uia'       # Available as 'app'
-uia '../../v1/MyApp.uia' # Available as 'app2'
-```
-
-
-## Working with Presentations
-
-```ruby
-uia '../MyApp.uia'
-
-main = app.main_presentation   # The presentation displayed as the main presentation (regardless of id)
-sub  = app['#nav']             # You can ask for an asset based on the id in the .uia...
-sub  = app['Navigation.uip']   # or based on the path to the file (relative to the .uia)
-
-
-car = sub/"Scene.Vehicle.Group.Car"      # Find elements in a presentation by presentation path…
-car = app/"nav:Scene.Vehicle.Group.Car"  # …or absolute application path
-
-show car.name #=> Car
-show car.type #=> Model                  # Scene, Layer, Camera, Light, Group, Model, Material,
-                                         # Image, Behavior, Effect, ReferencedMaterial, Text,
-                                         # RenderPlugin, Component, (custom materials)
-
-show car.component?  #=> false           # Ask if an element is a component
-assert car.component==sub.scene          # Ask for the owning component; may be the scene
-```
-
-## Finding Many Assets
-
-```ruby
-uia 'MyApp.uia'
-main = app.main_presentation
-
-every_asset   = main.find                                  # Array of matching assets
-master_assets = main.find _master:true                     # Test for master/nonmaster
-models        = main.find _type:'Model'                    # …or based on type
-slide2_assets = main.find _slide:2                         # …or presence on slide
-rectangles    = main.find sourcepath:'#Rectangle'          # …or attribute values
-gamecovers    = main.find name:'Game Cover'                # …including the name
-
-# Combine tests to get more specific
-master_models = main.find _type:'Model', _master:true
-slide2_rects  = main.find _type:'Model', _slide:2, sourcepath:'#Rectangle'
-nonmaster_s2  = main.find _slide:2, _master:false
-red_materials = main.find _type:'Material', diffuse:[1,0,0]
-
-# You can match values more loosely
-pistons       = main.find name:/^Piston/                   # Regex for batch finding
-bottom_row    = main.find position:[nil,-200,nil]          # nil for wildcards in vectors
-
-# Restrict the search to a sub-tree
-group        = main/"Scene.Layer.Group"
-group_models = group.find _type:'Model'                    # Orig asset is never included
-group_models = main.find _under:group, _type:'Model'       # Or, use `_under` to limit
-
-# Iterate the results as they are found
-main.find _type:'Model', name:/^Piston/ do |model, index|  # Using the index is optional
-	show "Model #{index} is named #{model.name}"
-end
-```
-
-Notes:
-
-* `nil` inside an array is a "wildcard" value, allowing you to test only specific values
-* Numbers (both in vectors/colors/rotations and float/long values) must only be within `0.001` to match.
-  * _For example, `attr:{diffuse:[1,0,0]}` will match a color with `diffuse=".9997 0.0003 0"`_
-* Results of `find` are always in scene-graph order.
-
-
-## Working with References
-
-```ruby
-uia 'MyApp.uia'
-mat1 = app/"main:Scene.Layer.Sphere.Material" # A normal UIC Material
-mat2 = app/"main:Scene.Layer.Cube.Material"   # A normal UIC Material
-p mat2.type                                   #=> "Material"
-ref = mat2.replace_with_referenced_material   # A very specific method :)
-p ref.properties['referencedmaterial'].type   #=> "ObjectRef"
-p ref['referencedmaterial',0].object          #=> nil
-p ref['referencedmaterial',0].type            #=> :absolute
-ref['referencedmaterial',0].object = mat1     #=> Sets an absolute reference
-ref['referencedmaterial',0].type = :path      #=> Use a relative path instead
-
-# Alternatively, you can omit the .object when setting the reference:
-# ref['referencedmaterial',0] = mat1
-
-mat3 = ref['referencedmaterial',1].object     #=> Get the asset pointed to
-assert mat1 == mat3                           #=> They are the same! It worked!
-
-app.save_all!                                 #=> Write presentations in place
-```
-
-
-## Locating MetaData.xml
-RUIC needs access to a UIC `MetaData.xml` file to understand the properties in the various XML files.
-By default RUIC will look in the location specified by `RUIC::DEFAULTMETADATA`, e.g.
-`C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml`
-
-If this file is in another location, you can tell the script where to find it either:
-
-* on the command line: `ruic -m path/to/MetaData.xml myscript.ruic`
-* in your ruic script: `metadata 'path/to/MetaData.xml' # before any 'app' commands`
-
-
-# Interactive RUIC
-In addition to executing a standalone script, RUIC also has a REPL (like IRB) that allows you to
-interactively execute and test changes to your application/presentations before saving.
-There are two ways to enter interactive mode:
-
-* If you invoke the `ruic` binary with a `.uia` file as the argument the interpreter will load
-  the application and enter the REPL:
-
-      $ ruic myapp.uia
-      (RUIC v0.6.0 interactive session; 'quit' or ctrl-d to end)
-
-      uia "test/projects/SimpleScene/SimpleScene.uia"
-      #=> <UIC::Application 'SimpleScene.uia'>
-
-* Alternatively, you can have RUIC execute a script and then enter the interactive REPL
-  by supplying the `-i` command-line switch:
-
-      $ ruic -i test/referencematerials.ruic
-      (RUIC v0.6.0 interactive session; 'quit' or ctrl-d to end)
-
-      app
-      #=> <UIC::Application 'ReferencedMaterials.uia'>
-
-      cubemat
-      #=> <asset Material#Material_002>
-
-  As shown above, all local variables created by the script continue to be available
-  in the interactive session.
-
-
-
-# Known Limitations (aka TODO)
-_In decreasing priority…_
-
-- Report on image assets, their sizes
-- Report used assets (and where they are used)
-- Report unused assets (in a format suitable for automated destruction)
-- Report missing assets (and who was looking for them)
-- Gobs more unit tests
-- Parse .lua headers (in case one references an image)
-- Parse render plugins
-- Read/edit animation tracks
-- Find all colors, and where they are used
-- Visual actions for State Machines
-- Create new presentation assets (e.g. add a new sphere)
-- Modify the scene graph of presentations
-- Create new presentations/applications from code
-- Report on image asset file formats (e.g. find PNGs, find DXT1 vs DXT3 vs DXT Luminance…)
-
-
-
-# License & Contact
-RUIC is copyright ©2014 by Gavin Kistner and is licensed under the [MIT License][3]. See the `LICENSE` file for more details.
-
-For bugs or feature requests please open [issues on GitHub][4]. For other communication you can [email the author directly](mailto:!@phrogz.net?subject=RUIC).
-
-[1]: http://uicomposer.nvidia.com
-[2]: http://nokogiri.org
-[3]: http://opensource.org/licenses/MIT
-[4]: https://github.com/Phrogz/RUIC/issues
+# What is RUIC?
+RUIC is a Ruby API for reading, analyzing, and manipulating application assets created by NVIDIA's [UI Composer][1]. Among other things, it allows you to:
+
+* See if an application is missing any assets (e.g. images or meshes) and what parts of the application are looking for those.
+* See if there are any files in the application folder that you can delete (e.g. images or materials that are no longer being used).
+* Read and modify the attributes of elements on different slides.
+* Batch change attributes (e.g. change all usage of one font or color to another).
+* Procedurally generate many models with automated placement in your scene.
+
+_Some of the features above are planned, but not yet implemented; see Known Limitations below._
+
+
+# Documentation
+
+In addition to the examples in this file full API documentation is available at:
+http://www.rubydoc.info/gems/RUIC/
+
+
+
+# Installing RUIC
+RUIC can be installed via RubyGems (part of Ruby) via the command:
+
+    gem install ruic   # May need `sudo gem install ruic` depending on your setup
+
+Although RUIC is a pure-Ruby library, it relies on [Nokogiri][2] for all the XML processing and manipulation. Installing RUIC will also automatically install Nokogiri, which may require some compilation.
+
+
+
+# Using the RUIC DSL
+
+RUIC scripts are pure Ruby with a few convenience methods added. You run them via the `ruic` command-line script, e.g.
+
+    ruic myscript.ruic  # or .rb extension, for syntax highlighting while editing
+
+
+## Creating and Accessing Applications
+RUIC scripts must start with `uia` commands to load an application and all its assets.
+After this you can access the application as `app`:
+
+```ruby
+uia '../MyApp.uia'      # Relative to the ruic script file, or absolute
+
+show app.file           #=> /var/projects/UIC/MyApp/main/MyApp.uia
+show app.filename       #=> MyApp.uia
+
+show app.assets.count   #=> 7
+# You can ask for app.behaviors, app.presentations, app.statemachines, and app.renderplugins
+# for arrays of specific asset types
+```
+
+_The `show` command prints the result; it is simply a nicer alias for `puts`._
+
+If you need to load multiple applications in the same script, subsequent `uia` commands will create
+`app2`, `app3`, etc. for you to use.
+
+```ruby
+uia '../MyApp.uia'       # Available as 'app'
+uia '../../v1/MyApp.uia' # Available as 'app2'
+```
+
+
+## Working with Presentations
+
+```ruby
+uia '../MyApp.uia'
+
+main = app.main_presentation   # The presentation displayed as the main presentation (regardless of id)
+sub  = app['#nav']             # You can ask for an asset based on the id in the .uia...
+sub  = app['Navigation.uip']   # or based on the path to the file (relative to the .uia)
+
+
+car = sub/"Scene.Vehicle.Group.Car"      # Find elements in a presentation by presentation path…
+car = app/"nav:Scene.Vehicle.Group.Car"  # …or absolute application path
+
+show car.name #=> Car
+show car.type #=> Model                  # Scene, Layer, Camera, Light, Group, Model, Material,
+                                         # Image, Behavior, Effect, ReferencedMaterial, Text,
+                                         # RenderPlugin, Component, (custom materials)
+
+show car.component?  #=> false           # Ask if an element is a component
+assert car.component==sub.scene          # Ask for the owning component; may be the scene
+```
+
+## Finding Many Assets
+
+```ruby
+uia 'MyApp.uia'
+main = app.main_presentation
+
+every_asset   = main.find                                  # Array of matching assets
+master_assets = main.find _master:true                     # Test for master/nonmaster
+models        = main.find _type:'Model'                    # …or based on type
+slide2_assets = main.find _slide:2                         # …or presence on slide
+rectangles    = main.find sourcepath:'#Rectangle'          # …or attribute values
+gamecovers    = main.find name:'Game Cover'                # …including the name
+
+# Combine tests to get more specific
+master_models = main.find _type:'Model', _master:true
+slide2_rects  = main.find _type:'Model', _slide:2, sourcepath:'#Rectangle'
+nonmaster_s2  = main.find _slide:2, _master:false
+red_materials = main.find _type:'Material', diffuse:[1,0,0]
+
+# You can match values more loosely
+pistons       = main.find name:/^Piston/                   # Regex for batch finding
+bottom_row    = main.find position:[nil,-200,nil]          # nil for wildcards in vectors
+
+# Restrict the search to a sub-tree
+group        = main/"Scene.Layer.Group"
+group_models = group.find _type:'Model'                    # Orig asset is never included
+group_models = main.find _under:group, _type:'Model'       # Or, use `_under` to limit
+
+# Iterate the results as they are found
+main.find _type:'Model', name:/^Piston/ do |model, index|  # Using the index is optional
+	show "Model #{index} is named #{model.name}"
+end
+```
+
+Notes:
+
+* `nil` inside an array is a "wildcard" value, allowing you to test only specific values
+* Numbers (both in vectors/colors/rotations and float/long values) must only be within `0.001` to match.
+  * _For example, `attr:{diffuse:[1,0,0]}` will match a color with `diffuse=".9997 0.0003 0"`_
+* Results of `find` are always in scene-graph order.
+
+
+## Working with References
+
+```ruby
+uia 'MyApp.uia'
+mat1 = app/"main:Scene.Layer.Sphere.Material" # A normal UIC Material
+mat2 = app/"main:Scene.Layer.Cube.Material"   # A normal UIC Material
+p mat2.type                                   #=> "Material"
+ref = mat2.replace_with_referenced_material   # A very specific method :)
+p ref.properties['referencedmaterial'].type   #=> "ObjectRef"
+p ref['referencedmaterial',0].object          #=> nil
+p ref['referencedmaterial',0].type            #=> :absolute
+ref['referencedmaterial',0].object = mat1     #=> Sets an absolute reference
+ref['referencedmaterial',0].type = :path      #=> Use a relative path instead
+
+# Alternatively, you can omit the .object when setting the reference:
+# ref['referencedmaterial',0] = mat1
+
+mat3 = ref['referencedmaterial',1].object     #=> Get the asset pointed to
+assert mat1 == mat3                           #=> They are the same! It worked!
+
+app.save_all!                                 #=> Write presentations in place
+```
+
+
+## Locating MetaData.xml
+RUIC needs access to a UIC `MetaData.xml` file to understand the properties in the various XML files.
+By default RUIC will look in the location specified by `RUIC::DEFAULTMETADATA`, e.g.
+`C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml`
+
+If this file is in another location, you can tell the script where to find it either:
+
+* on the command line: `ruic -m path/to/MetaData.xml myscript.ruic`
+* in your ruic script: `metadata 'path/to/MetaData.xml' # before any 'app' commands`
+
+
+# Interactive RUIC
+In addition to executing a standalone script, RUIC also has a REPL (like IRB) that allows you to
+interactively execute and test changes to your application/presentations before saving.
+There are two ways to enter interactive mode:
+
+* If you invoke the `ruic` binary with a `.uia` file as the argument the interpreter will load
+  the application and enter the REPL:
+
+      $ ruic myapp.uia
+      (RUIC v0.6.0 interactive session; 'quit' or ctrl-d to end)
+
+      uia "test/projects/SimpleScene/SimpleScene.uia"
+      #=> <UIC::Application 'SimpleScene.uia'>
+
+* Alternatively, you can have RUIC execute a script and then enter the interactive REPL
+  by supplying the `-i` command-line switch:
+
+      $ ruic -i test/referencematerials.ruic
+      (RUIC v0.6.0 interactive session; 'quit' or ctrl-d to end)
+
+      app
+      #=> <UIC::Application 'ReferencedMaterials.uia'>
+
+      cubemat
+      #=> <asset Material#Material_002>
+
+  As shown above, all local variables created by the script continue to be available
+  in the interactive session.
+
+
+
+# Known Limitations (aka TODO)
+_In decreasing priority…_
+
+- Report on image assets, their sizes
+- Report used assets (and where they are used)
+- Report unused assets (in a format suitable for automated destruction)
+- Report missing assets (and who was looking for them)
+- Gobs more unit tests
+- Parse .lua headers (in case one references an image)
+- Parse render plugins
+- Read/edit animation tracks
+- Find all colors, and where they are used
+- Visual actions for State Machines
+- Create new presentation assets (e.g. add a new sphere)
+- Modify the scene graph of presentations
+- Create new presentations/applications from code
+- Report on image asset file formats (e.g. find PNGs, find DXT1 vs DXT3 vs DXT Luminance…)
+
+
+
+# License & Contact
+RUIC is copyright ©2014 by Gavin Kistner and is licensed under the [MIT License][3]. See the `LICENSE` file for more details.
+
+For bugs or feature requests please open [issues on GitHub][4]. For other communication you can [email the author directly](mailto:!@phrogz.net?subject=RUIC).
+
+[1]: http://uicomposer.nvidia.com
+[2]: http://nokogiri.org
+[3]: http://opensource.org/licenses/MIT
+[4]: https://github.com/Phrogz/RUIC/issues