RUIC 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8266ac3944df4da06963ce797c9f7c4ded165e35
-  data.tar.gz: 56f345f5e38f79cbc2ec24d13c3b591d88332bc3
+  metadata.gz: 8c4e1cec982987968c63ecbbafff9d3e411cde33
+  data.tar.gz: 12b6241b55467219a87ebdbe18b31a7a9c323cf2
 SHA512:
-  metadata.gz: 324c07f70d84f98023a3b2de1606c5e91f158ec2fe13758028dabc71b7eae949253e34a579234bec5444f4aa4f35661ff603a3d88c463c9c75f2c1dc6e2383e5
-  data.tar.gz: 7f3b3bbc26be7a229f2f7dfb180b05a0409b56dd7ff6418cd4e6f4c184b5e55bad8ddc433815b3c9eb2f59013934c67812eeb0be3d2225f64952d0430fba04ba
+  metadata.gz: c16621f5aefc0467c4ebb18df1a76addf920001033127b920a5504b2227bfd88d63abfde631580371cefd6b1551a672117ecb9f5e05c4178ff6652533bb83299
+  data.tar.gz: b50269750f9bbecd3e94f19662c4e1c3897f8e2e00c24aaf01b2a0af29affc6ec6325ac264664fd159f03393d0de8fd42453338c21b10ccdebddf2dcd61491ea

data/README.md

@@ -1,207 +1,252 @@
-# 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._
-
-## Table of Contents
-* [Installing RUIC](#installing-ruic)
-* [Using the RUIC DSL](#using-the-ruic-dsl)
-  * [Creating and Accessing Applications](#creating-and-accessing-applications)
-  * [Working with Presentations](#working-with-presentations)
-  * [Finding Many Assets](#finding-many-assets)
-  * [Working with References](#working-with-references)
-  * [Writing Assertions](#writing-assertions)
-  * [Locating MetaData.xml](#locating-metadataxml)
-* [Known Limitations (aka TODO)](#known-limitations-aka-todo)
-* [History](#history)
-* [License & Contact](#license--contact)
-
-
-
-# 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
-gamecovers    = main.find name:'Game Cover'                    # …or based on name
-slide2_assets = main.find slide:2                              # …or presence on slide
-rectangles    = main.find attributes:{sourcepath:'#Rectangle'} # …or attribute values
-
-# Combine tests to get more specific
-master_models = main.find type:'Model', master:true            
-slide2_rects  = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
-nonmaster_s2  = main.find slide:2, master:false
-red_materials = main.find type:'Material', attributes:{ diffuse:[1,0,0] }
-
-# You can match values more loosely
-pistons       = main.find name:/^Piston/                       # Regex for batch finding
-bottom_row    = main.find attributes:{position:[nil,-200,nil]} # nil for wildcards
-
-# Restrict the search to a sub-tree
-group        = main/"Scene.Layer.Group"
-group_models = group.find type:'Model'                 # Original asset is never included
-group_models = main.find under:group, type:'Model'     # Or use `under` for sub-tree
-
-# 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, `attributes:{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
-```
-
-## Writing Assertions
-
-
-## 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`
-
-
-
-# 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…)
-
-
-# History
-
-## v0.0.1 - 2014-Nov-7
-* Initial gem release
-* Crawl presentations and modify attributes
-* Batch find assets
-* Save presentation changes back to disk
-
-
-
-# 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._
+
+## Table of Contents
+* [Installing RUIC](#installing-ruic)
+* [Using the RUIC DSL](#using-the-ruic-dsl)
+  * [Creating and Accessing Applications](#creating-and-accessing-applications)
+  * [Working with Presentations](#working-with-presentations)
+  * [Finding Many Assets](#finding-many-assets)
+  * [Working with References](#working-with-references)
+  * [Writing Assertions](#writing-assertions)
+  * [Locating MetaData.xml](#locating-metadataxml)
+* [Interactive RUIC](#interactive-ruic)
+* [Known Limitations (aka TODO)](#known-limitations-aka-todo)
+* [History](#history)
+* [License & Contact](#license--contact)
+
+
+
+# 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
+gamecovers    = main.find name:'Game Cover'                    # …or based on name
+slide2_assets = main.find slide:2                              # …or presence on slide
+rectangles    = main.find attributes:{sourcepath:'#Rectangle'} # …or attribute values
+
+# Combine tests to get more specific
+master_models = main.find type:'Model', master:true            
+slide2_rects  = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
+nonmaster_s2  = main.find slide:2, master:false
+red_materials = main.find type:'Material', attributes:{ diffuse:[1,0,0] }
+
+# You can match values more loosely
+pistons       = main.find name:/^Piston/                       # Regex for batch finding
+bottom_row    = main.find attributes:{position:[nil,-200,nil]} # nil for wildcards
+
+# Restrict the search to a sub-tree
+group        = main/"Scene.Layer.Group"
+group_models = group.find type:'Model'                 # Original asset is never included
+group_models = main.find under:group, type:'Model'     # Or use `under` for sub-tree
+
+# 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, `attributes:{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
+```
+
+## Writing Assertions
+
+
+## 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.2.2 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.2.2 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…)
+
+
+# History
+
+## 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
+
+
+
+# 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