RUIC 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9cedef554fe79e1c76d028914357e410a7199799
-  data.tar.gz: 7462e76fe72621bb0985000630edea4daed2148c
+  metadata.gz: 701fc8ed1b3b80439288e9aff34936285aa24210
+  data.tar.gz: f8373806b048154b3869515c911153721c483dac
 SHA512:
-  metadata.gz: 340ca92ab34bcccce9605db54071ff11ad20294e6f9421a5e260bcfd5215574ece125f277a9f8d896a120d1dbcf8002e7c7521ecd3aa17e7ff40205729f313a3
-  data.tar.gz: 3eb97d8bafb8b1291929b7e34c6417316a472d313b189985057c892642c468395067bdbfa77ce2850c78a8dffbd1596fc3fff66a7d9e6f6ab1b74d0c1012ca9e
+  metadata.gz: 084df33530afad35f3ab412300b0cd79504154e7dc07d565319b09dc395d42a93793528986ae53d7a3e91d8d79cf9130dcdac061d8fce48df749f0ca9dd8cded
+  data.tar.gz: 7619b5c097ed8b05275b2a57f6b1d0c90d90fd79789f621476227f3903ff27336786a6f9e169e3030767c94988cfc44687c08c24637a2ba6740468992bd20598

data/README.md

@@ -1,201 +1,207 @@
-# 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                                      # Returns an array of matching assets
-master_assets = main.find master:true                          # Test for master/non-master
-models        = main.find type:'Model'                         # Test based on type
-slide2_assets = main.find slide:2                              # Test based on slide presence
-rectangles    = main.find attributes:{sourcepath:'#Rectangle'} # Test based on attribute values
-master_models = main.find type:'Model', master:true            # Combine any tests
-slide2_rects  = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
-gamecovers    = main.find name:'Game Cover'
-pistons       = main.find name:/^Piston/                       # Regexes allow easy batch finding
-bottom_row    = main.find attributes:{position:[nil,-200,nil]}
-red_materials = main.find type:'Material', attributes:{diffuse:[1,0,0] }
-
-# Restricting the search to a sub-tree
-group        = main/"Scene.Layer.Group"
-group_models = group.find type:'Model'             # Original asset is never in the results
-group_models = main.find under:group, type:'Model' # Alternative sub-tree limit using `under`
-
-# Iterate the results as they are found
-main.find type:'Model', name:/^Piston/ do |model, index|
-	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 .material files
-- Navigate through scene graph hierarchy (parent, children)
-- Parse .lua files (in case one references an image)
-- Parse render plugins
-- Read/edit animation tracks
-- Find all colors, and where they are used
-- Path to element
-- `element/'relative.path.resolving'`
-- 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
-* _In development, no releases yet._
-
-
-
-# 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)
+* [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

data/bin/ruic

@@ -9,15 +9,17 @@ end
 
 USAGE = <<ENDUSAGE
 Usage:
-   ruic [-h] [-v] [-m /path/to/MetaData.xml] myscript.ruic
+   ruic [-h] [-v] [-i] [-m path/to/MetaData.xml] [-u path/to/my.uia] [myscript.ruic]
 ENDUSAGE
 
 HELP = <<ENDHELP
-   -h, --help       Show this help.
-   -v, --version    Show the version number (#{RUIC::VERSION}).
-   -m, --metadata   The path to use for MetaData.xml
-                    Default: #{RUIC::DEFAULTMETADATA}
-                    Will be overridden by any `metadata` call in your script.
+   -h, --help         Show this help.
+   -v, --version      Show the version number (#{RUIC::VERSION}).
+   -i, --interactive  Enter an interactive REPL after running the script (if any).
+   -m, --metadata     The path to use for MetaData.xml
+                      Default: #{RUIC::DEFAULTMETADATA}
+                      Will be overridden by any `metadata` call in your script.
+   -u, --uia          An application to load.
 ENDHELP
 
 ARGS = {}
@@ -25,9 +27,11 @@ UNFLAGGED_ARGS = [ :script ]
 next_arg = UNFLAGGED_ARGS.first
 ARGV.each do |arg|
 	case arg
-		when '-h','--help'      then ARGS[:help]    = true
-		when '-v','--version'   then ARGS[:version] = true
-		when '-m','--metadata'  then next_arg = :meta
+		when '-h','--help'        then ARGS[:help]        = true
+		when '-v','--version'     then ARGS[:version]     = true
+		when '-i','--interactive' then ARGS[:interactive] = true
+		when '-m','--metadata'    then next_arg = :meta
+		when '-u','--uia'         then next_arg = :uia
 		else
 			if next_arg
 				ARGS[next_arg] = arg
@@ -39,14 +43,18 @@ end
 
 puts "RUIC v#{RUIC::VERSION}" if ARGS[:version]
 
-if ARGS[:help] || !ARGS[:script]
-	puts USAGE unless ARGS[:version]
-	puts HELP if ARGS[:help]
-	exit ARGS[:help] ? 0 : 1
+if ARGS[:help]
+	puts USAGE, HELP
+	exit 0
 end
 
 if ARGS[:meta]
 	RUIC::DEFAULTMETADATA.replace File.expand_path(ARGS[:meta])
 end
 
-RUIC(ARGS[:script])
+if ARGS[:script] && File.extname(ARGS[:script])==".uia"
+	ARGS[:uia] = ARGS[:script]
+	ARGS[:script] = nil
+end
+
+RUIC script:ARGS[:script], uia:ARGS[:uia], repl:ARGS[:interactive] || !ARGS[:script]