RUIC 0.4.1 → 0.4.2

data/lib/ruic.rb

@@ -1,4 +1,5 @@
 #encoding:utf-8
+
 class RUIC; end
 module UIC; end
 
@@ -12,9 +13,37 @@ require_relative 'ruic/behaviors'
 require_relative 'ruic/statemachine'
 require_relative 'ruic/presentation'
 
+# The `RUIC` class provides the interface for running scripts using the special DSL,
+# and for running the interactive REPL.
+# See the {file:README.md README} file for description of the DSL.
 class RUIC
 	DEFAULTMETADATA = 'C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml'
 
+	# Execute a script and/or launch the interactive REPL.
+	#
+	# If you both run a `:script` and then enter the `:repl` all local variables created
+	# by the script will be available in the REPL.
+	#
+	#     # Just run a script
+	#     RUIC.run script:'my.ruic'
+	#
+	#     # Load an application and then enter the REPL
+	#     RUIC.run uia:'my.uia', repl:true
+	#
+	#     # Run a script and then drop into the REPL
+	#     RUIC.run script:'my.ruic', repl:true
+	#
+	# The working directory for scripts is set to the directory of the script.
+	#
+	# The working directory for the repl is set to the directory of the first
+	# loaded application (if any);
+	# failing that, the directory of the script (if any);
+	# failing that, the current directory.
+	#
+	# @option opts [String] :script A path to a `.ruic` script to run _(optional)_.
+	# @option opts [String] :uia An `.uia` file to load (before running the script and/or REPL) _(optional)_.
+	# @option opts [Boolean] :repl Pass `true` to enter the command-line REPL after executing the script (if any).
+	# @return [nil]
 	def self.run(opts={})
 		opts = opts
 		ruic = nil
@@ -48,47 +77,75 @@ class RUIC
 		end
 	end
 
+	# Creates a new environment for executing a RUIC script.
+	# @param metadata [String] Path to the `MetaData.xml` file to use.
 	def initialize( metadata=DEFAULTMETADATA )
 		@metadata = metadata
 		@apps = {}
 	end
 
+	# Set the metadata to use; generally called from the RUIC DSL.
+	# @param path [String] Path to the `MetaData.xml` file, either absolute or relative to the working directory.
 	def metadata(path)
 		@metadata = path
 	end
 
+	# Load an application, making it available as `app`, `app2`, etc.
+	# @param path [String] Path to the `*.uia` application file.
+	# @return [UIC::Application] The new application loaded.
 	def uia(path)
-		meta = UIC.Meta @metadata
+		meta = UIC.MetaData @metadata
 		name = @apps.empty? ? :app : :"app#{@apps.length+1}"
-		@apps[name] = UIC.App(meta,path)
+		@apps[name] = UIC.Application(meta,path)
 	end
 
+	# @return [Binding] the shared binding used for evaluating the script and REPL
 	def env
 		@env ||= binding
 	end
 
-	module SelfInspecting
-		def inspect
-			to_s
-		end
-	end
+	# @private used as a one-off
+	module SelfInspecting; def inspect; to_s; end; end
 
+	# Used to resolve bare `app` and `app2` calls to a loaded {UIC::Application Application}.
+	# @return [UIC::Application] the new application loaded.
 	def method_missing(name,*a)
 		@apps[name] || (name=~/^app\d*/ ? "(no #{name} loaded)".extend(SelfInspecting) : super)
 	end
 
+	# Simple assertion mechanism to be used within scripts.
+	#
+	# @example 1) simple call syntax
+	#     # Provides a generic failure message
+	#     assert a==b
+	#     #=> assertion failed (my.ruic line 17)
+	#
+	#     # Provides a custom failure message
+	#     assert a==b, "a should equal b"
+	#     #=> a should equal b : assertion failed (my.ruic line 17)
+	#
+	# @example 2) block with string syntax
+	#     # The code in the string to eval is also the failure message
+	#     assert{ "a==b" }
+	#     #=> a==b : assertion failed (my.ruic line 17)
+	#
+	# @param condition [Boolean] the value to evaluate.
+	# @param msg [String] the nice error message to display.
+	# @yieldreturn [String] the code to evaluate as a condition.
 	def assert(condition=:CONDITIONNOTSUPPLIED,msg=nil,&block)
-		if block && condition==:CONDITIONNOTSUPPLIED || condition.is_a?(String)
-			msg = condition.is_a?(String) ? condition : yield
+		if block && condition==:CONDITIONNOTSUPPLIED
+			msg = yield
 			condition = msg.is_a?(String) ? eval(msg,block.binding) : msg
 		end
-		unless condition
+		condition || begin
 			file, line, _ = caller.first.split(':')
-			puts "#{msg && "#{msg} : "}assertion failed (#{file} line #{line})"
+			puts "#{"#{msg} : " unless msg.nil?}assertion failed (#{file} line #{line})"
 			exit 1
 		end
 	end
 
+	# Nicer name for `puts` to be used in the DSL, printing the
+	# 'nice' string equivalent for all supplied arguments.
 	def show(*a); puts *a.map(&:to_s); end
 
 	def inspect
@@ -96,6 +153,18 @@ class RUIC
 	end
 end
 
+# Run a series of commands inside the RUIC DSL.
+#
+# @example
+#   require 'ruic'
+#   RUIC do
+#     uia 'test/MyProject/MyProject.uia'
+#     show app
+#     #=>UIC::Application 'MyProject.uia'>
+#   end
+#
+# If no block is supplied, this is the same as {RUIC.run RUIC.run(opts)}.
+# @option opts [String] :uia Optionally load an application before running the script.
 def RUIC(opts={},&block)
 	if block
 		Dir.chdir(File.dirname($0)) do

data/lib/ruic/application.rb

@@ -1,3 +1,4 @@
+# The `Application` represents the root of your UIC application, corresponding to a `.uia` file.
 class UIC::Application
 	include UIC::FileBacked
 
@@ -5,17 +6,27 @@ class UIC::Application
 		"<UIC::Application '#{File.basename(file)}'#{:' FILENOTFOUND' unless file_found?}>"
 	end
 
+	# @return [UIC::MetaData] the metadata loaded for this application
 	attr_reader :metadata
-	def initialize(metadata,uia_path)
+
+	# @param metadata [UIC::MetaData] the `MetaData` to use for this application.
+	# @param uia_path [String] path to a `.uia` file to load.
+	#        If omitted you will need to later set the `.file = ` for the
+	#        instance and then call {#load_from_file}.
+	def initialize(metadata,uia_path=nil)
 		@metadata = metadata
 		self.file = uia_path
 		@assets = {}
 		load_from_file if file_found?
 	end
 
+	# Loads the application from the file. If you pass the path to your `.uia`
+	# to {#initialize} then this method is called automatically.
+	#
+	# @return [nil]
 	def load_from_file
-		self.doc  = Nokogiri.XML(File.read(file,encoding:'utf-8'))
-		@assets   = @doc.search('assets *').map do |el|
+		self.doc = Nokogiri.XML(File.read(file,encoding:'utf-8'))
+		@assets  = @doc.search('assets *').map do |el|
 			case el.name
 				when 'behavior'     then UIC::Application::Behavior
 				when 'statemachine' then UIC::Application::StateMachine
@@ -23,16 +34,32 @@ class UIC::Application
 				when 'renderplugin' then UIC::Application::RenderPlugin
 			end.new(self,el)
 		end.group_by{ |asset| asset.el.name }
+		nil
 	end
 
+	# @return [Boolean] true if there are any errors with the application.
 	def errors?
 		!errors.empty?
 	end
 
+	# @example
+	#   show app.errors if app.errors?
+	# @return [Array<String>] an array (possibly empty) of all errors in this application (including referenced assets).
 	def errors
 		file_found? ? assets.flat_map(&:errors) : ["File not found: '#{file}'"]
 	end
 
+	# Find an asset by `.uia` identifier or path to the asset.
+	# @example
+	#   main1 = app['#main']
+	#   main2 = app['MyMain.uip']
+	#   main3 = app.main_presentation
+	#   assert main1==main2 && main2==main3
+	# @param asset_id_or_path [String] an idref like `"#status"` or a relative path to the asset like `"VehicleStatus.uip"` or `"scripts/Main.lua"`.
+	# @return [UIC::Application::Behavior]
+	# @return [UIC::Application::StateMachine]
+	# @return [UIC::Application::Presentation]
+	# @return [UIC::Application::RenderPlugin]
 	def [](asset_id_or_path)
 		all = assets
 		if asset_id_or_path.start_with?('#')
@@ -44,10 +71,12 @@ class UIC::Application
 		end
 	end
 
+	# @private do not document until working
 	def unused_files
 		referenced_files - directory_files
 	end
 
+	# @private do not document until working
 	def referenced_files
 		# TODO: state machines can reference external scripts
 		# TODO: behaviors can reference external scripts
@@ -55,10 +84,15 @@ class UIC::Application
 		+ presentations.flat_map{ |pres| pres.presentation.referenced_files }
 	end
 
+	# @return [Array] all assets referenced by the application. Ordered by the order they appear in the `.uia`.
 	def assets
 		@assets.values.inject(:+)
 	end
 
+	# @example
+	#   main = app.main
+	#   main = app.main_presentation # more-explicit alternative
+	# @return [UIC::Application::Presentation] the main presentation rendered by the application.
 	def main_presentation
 		initial_id = @doc.at('assets')['initial']
 		presos = presentations
@@ -66,13 +100,18 @@ class UIC::Application
 	end
 	alias_method :main, :main_presentation
 
+	# Change which presentation is rendered for the application.
+	# @param presentation [UIC::Application::Presentation]
+	# @return [UIC::Application::Presentation]
 	def main_presentation=(presentation)
-		# TODO: set to Presentation or PresentationAsset
+		# TODO: set to Presentation or Application::Presentation
 		# TODO: create a unique ID if none exists
 		@doc.at('assets')['initial'] = presentation.id
 	end
 
+	# @return [Hash] a mapping of image paths to arrays of elements/assets that reference that image.
 	def image_usage
+		# TODO: this returns the same asset multiple times, with no indication of which property is using it; should switch to Properties.
 		Hash[
 			(presentations + statemachines)
 				.map(&:image_usage)
@@ -84,31 +123,48 @@ class UIC::Application
 		].tap{ |h| h.extend(UIC::PresentableHash) }
 	end
 
+	# @return [Array<String>] array of all image paths **used** by the application (not just in subfolders).
 	def image_paths
 		image_usage.keys
 	end
 
+	# @return [Array<UIC::Application::Presentation>] all presentations referenced by the application.
 	def presentations
 		@assets['presentation'] ||= []
 	end
 
+	# @return [Array<UIC::Application::Behavior>] all behaviors referenced by the application.
 	def behaviors
 		@assets['behavior'] ||= []
 	end
 
+	# @return [Array<UIC::Application::StateMachine>] all state machines referenced by the application.
 	def statemachines
 		@assets['statemachine'] ||= []
 	end
 
+	# @return [Array<UIC::Application::RenderPlugin>] all render plug-ins referenced by the application.
 	def renderplugins
 		@assets['renderplugin'] ||= []
 	end
 
+	# Save changes to this application and every asset to disk.
 	def save_all!
-		# save!
+		save!
 		presentations.each(&:save!)
-	end
-
+		# TODO: enumerate other assets and save them
+	end
+
+	# Find an element or asset in a presentation by scripting path.
+	# @example
+	#     # Four ways to find the same layer
+	#     layer1 = app.at "main:Scene.Layer"
+	#     layer2 = app/"main:Scene.Layer"
+	#     layer3 = app.main.at "Scene.Layer"
+	#     layer4 = app.main/"Scene.Layer"
+	#
+	#     assert layer1==layer2 && layer2==layer3 && layer3==layer4
+	# @return [UIC::MetaData::Root] The found asset, or `nil` if it cannot be found.
 	def at(path)
 		parts = path.split(':')
 		preso = parts.length==2 ? self["##{parts.first}"] : main_presentation
@@ -116,17 +172,16 @@ class UIC::Application
 		preso.at(parts.last)
 	end
 	alias_method :/, :at
-
-	def xml
-		@doc.to_xml
-	end
 end
 
 class << UIC
-	def Application(metadata,uia_path)
+	# Create a new {UIC::Application}. Shortcut for `UIC::Application.new(...)`
+	# @param metadata [UIC::MetaData] the MetaData to use for this application.
+	# @param uia_path [String] a path to the .uia to load.
+	# @return [UIC::Application]
+	def Application(metadata,uia_path=nil)
 		UIC::Application.new( metadata, uia_path )
 	end
-	alias_method :App, :Application
 end
 
 __END__

data/lib/ruic/assets.rb

@@ -1,288 +1,290 @@
-#encoding: utf-8
-class UIC::Asset
-	class Root
-		@properties = {}
-		class << self
-			attr_reader :name
-			def properties
-				(ancestors[1].respond_to?(:properties) ? ancestors[1].properties : {}).merge(@properties)
-			end
-
-			def each
-				(@by_name.values - [self]).each{ |klass| yield klass }
-			end
-			include Enumerable
-
-			def inspect
-				"<#{@name}>"
-			end
-		end
-
-		def properties
-			self.class.properties
-		end
-
-		def at(sub_path)
-			presentation.at(sub_path,@el)
-		end
-		alias_method :/, :at
-
-		attr_accessor :presentation, :el
-		def initialize( presentation, element )
-			@presentation = presentation
-			@el = element
-		end
-
-		def type
-			self.class.name
-			# self.class.name.split('::').last
-		end
-
-		def parent
-			presentation.parent_asset(@el)
-		end
-
-		def children
-			presentation.child_assets(@el)
-		end
-
-		def find(criteria={},&block)
-			criteria[:_under] ||= self
-			presentation.find(criteria,&block)
-		end
-
-		# Find the owning component (even if you are a component)
-		def component
-			presentation.owning_component(@el)
-		end
-
-		def component?
-			@el.name == 'Component'
-		end
-
-		def master?
-			presentation.master?(@el)
-		end
-
-		def slide?
-			false
-		end
-
-		def has_slide?(slide_name_or_index)
-			presentation.has_slide?(@el,slide_name_or_index)
-		end
-
-		def slides
-			presentation.slides_for(@el)
-		end
-
-		def on_slide(slide_name_or_index)
-			if has_slide?(slide_name_or_index)
-				UIC::SlideValues.new( self, slide_name_or_index )
-			end
-		end
-
-		def path
-			@path ||= @presentation.path_to(@el)
-		end
-
-		def name
-			properties['name'].get( self, presentation.slide_index(@el) )
-		end
-
-		def name=( new_name )
-			properties['name'].set( self, new_name, presentation.slide_index(@el) )
-		end
-
-		# Get the value(s) of an attribute
-		def [](attribute_name, slide_name_or_index=nil)
-			if property = properties[attribute_name]
-				if slide_name_or_index
-					property.get( self, slide_name_or_index ) if has_slide?(slide_name_or_index)
-				else
-					UIC::ValuesPerSlide.new(@presentation,self,property)
-				end
-			end
-		end
-
-		# Set the value of an attribute, either across all slides, or on a particular slide
-		# el['foo']   = 42
-		# el['foo',0] = 42
-		def []=( attribute_name, slide_name_or_index=nil, new_value )
-			if property = properties[attribute_name] then
-				property.set(self,new_value,slide_name_or_index)
-			end
-		end
-
-		def to_xml
-			@el.to_xml
-		end
-		def inspect
-			"<asset #{@el.name}##{@el['id']}>"
-		end
-
-		def to_s
-			"<#{type} #{path}>"
-		end
-
-		def ==(other)
-			(self.class==other.class) && (el==other.el)
-		end
-		alias_method :eql?, :==
-	end
-
-	attr_reader :by_name
-
-	HIER = {}
-	%w[Asset Slide Scene].each{ |s| HIER[s] = 'Root' }
-	%w[Node Behavior Effect Image Layer MaterialBase PathAnchorPoint RenderPlugin].each{ |s| HIER[s]='Asset' }
-	%w[Alias Camera Component Group Light Model Text Path].each{ |s| HIER[s]='Node' }
-	%w[Material ReferencedMaterial].each{ |s| HIER[s]='MaterialBase' }
-
-	def initialize(xml)
-		@by_name = {'Root'=>Root}
-
-		doc = Nokogiri.XML(xml)
-		hack_in_slide_names!(doc)
-
-		HIER.each do |class_name,parent_class_name|
-			parent_class = @by_name[parent_class_name]
-			el = doc.root.at(class_name)
-			@by_name[class_name] = create_class(el,parent_class,el.name)
-			UIC::Asset.const_set( el.name, @by_name[class_name] ) # give the class instance a name by pointing a constant to it :/
-		end
-
-		# Extend well-known classes with script interfaces after they are created
-		@by_name['State'] = @by_name['Slide']
-		@by_name['Slide'].instance_eval do
-			attr_accessor :index, :name
-			define_method :inspect do
-				"<slide ##{index} of #{@el['component'] || @el.parent['component']}>"
-			end
-			define_method(:slide?){ true }
-		end
-
-		refmat = @by_name['ReferencedMaterial']
-		@by_name['MaterialBase'].instance_eval do
-			define_method :replace_with_referenced_material do
-				type=='ReferencedMaterial' ? self : presentation.replace_asset( self, 'ReferencedMaterial', name:name )
-			end
-		end
-
-		@by_name['Path'].instance_eval do
-			define_method(:anchors){ find _type:'PathAnchorPoint' }
-		end
-
-	end
-
-	# Creates a class from MetaData.xml with accessors for the <Property> listed.
-	# Instances of the class are associated with a presentation and know how to
-	# get/set values in that XML based on value types, slides, defaults.
-	# Also used to create classes from effects, materials, and behavior preambles.
-	def create_class(el,parent_class,name='CustomAsset')
-		Class.new(parent_class) do
-			@name = name
-			@properties = Hash[ el.css("Property").map do |e|
-				type = e['type'] || (e['list'] ? 'String' : 'Float')
-				type = "Float" if type=="float"
-				property = UIC::Property.const_get(type).new(e)
-				[ property.name, UIC::Property.const_get(type).new(e) ]
-			end ]
-		end
-	end
-
-	def new_instance(presentation,el)
-		klass = @by_name[el.name] || create_class(el,@by_name['Asset'],el.name)
-		klass.new(presentation,el)
-	end
-
-	def hack_in_slide_names!(doc)
-		doc.at('Slide') << '<Property name="name" formalName="Name" type="String" default="Slide" hidden="True" />'
-	end
-end
-
-def UIC.Meta(metadata_path)
-	UIC::Asset.new(File.read(metadata_path,encoding:'utf-8'))
-end
-
-class UIC::SlideCollection
-	include Enumerable
-	attr_reader :length
-	def initialize(slides)
-		@length = slides.length-1
-		@slides = slides
-		@lookup = {}
-		slides.each do |s|
-			@lookup[s.index] = s
-			@lookup[s.name]  = s
-		end
-	end
-	def each
-		@slides.each{ |s| yield(s) }
-	end
-	def [](index_or_name)
-		@lookup[ index_or_name ]
-	end
-	def inspect
-		"[ #{@slides.map(&:inspect).join ', '} ]"
-	end
-	def to_ary
-		@slides
-	end
-end
-
-class UIC::ValuesPerSlide
-	def initialize(presentation,asset,property)
-		raise unless presentation.is_a?(UIC::Presentation)
-		raise unless asset.is_a?(UIC::Asset::Root)
-		raise unless property.is_a?(UIC::Property)
-		@preso    = presentation
-		@asset    = asset
-		@el       = asset.el
-		@property = property
-	end
-	def value
-		values.first
-	end
-	def [](slide_name_or_index)
-		@property.get( @asset, slide_name_or_index )
-	end
-	def []=(slide_name_or_index,new_value)
-		@property.set( @asset, new_value, slide_name_or_index )
-	end
-	def linked?
-		@preso.attribute_linked?(@el,@property.name)
-	end
-	def unlink
-		@preso.unlink_attribute( @el, @property.name )
-	end
-	def link
-		@preso.link_attribute( @el, @property.name )
-	end
-	def values
-		@asset.slides.map{ |s| self[s.name] }
-	end
-	def inspect
-		"<Values of '#{@asset.name}.#{@property.name}' across slides>"
-	end
-	alias_method :to_s, :inspect
-end
-
-class UIC::SlideValues
-	def initialize( asset, slide )
-		@asset = asset
-		@slide = slide
-	end
-	def [](attribute_name)
-		@asset[attribute_name,@slide]
-	end
-	def []=( attribute_name, new_value )
-		@asset[attribute_name,@slide] = new_value
-	end
-	def method_missing( name, *args, &blk )
-		asset.send(name,*args,&blk)
-	end
-	def inspect
-		"<#{@asset.inspect} on slide #{@slide.inspect}>"
-	end
+#encoding: utf-8
+class UIC::MetaData
+	class Root
+		@properties = {}
+		class << self
+			attr_reader :name
+			def properties
+				(ancestors[1].respond_to?(:properties) ? ancestors[1].properties : {}).merge(@properties)
+			end
+
+			def each
+				(@by_name.values - [self]).each{ |klass| yield klass }
+			end
+			include Enumerable
+
+			def inspect
+				"<#{@name}>"
+			end
+		end
+
+		def properties
+			self.class.properties
+		end
+
+		def at(sub_path)
+			presentation.at(sub_path,@el)
+		end
+		alias_method :/, :at
+
+		attr_accessor :presentation, :el
+		def initialize( presentation, element )
+			@presentation = presentation
+			@el = element
+		end
+
+		def type
+			self.class.name
+			# self.class.name.split('::').last
+		end
+
+		def parent
+			presentation.parent_asset(self)
+		end
+
+		def children
+			presentation.child_assets(self)
+		end
+
+		def find(criteria={},&block)
+			criteria[:_under] ||= self
+			presentation.find(criteria,&block)
+		end
+
+		# Find the owning component (even if you are a component)
+		def component
+			presentation.owning_component(self)
+		end
+
+		def component?
+			@el.name == 'Component'
+		end
+
+		def master?
+			presentation.master?(self)
+		end
+
+		def slide?
+			false
+		end
+
+		def has_slide?(slide_name_or_index)
+			presentation.has_slide?(self,slide_name_or_index)
+		end
+
+		def slides
+			presentation.slides_for(self)
+		end
+
+		def on_slide(slide_name_or_index)
+			if has_slide?(slide_name_or_index)
+				UIC::SlideValues.new( self, slide_name_or_index )
+			end
+		end
+
+		def path
+			@path ||= @presentation.path_to(self)
+		end
+
+		def name
+			properties['name'].get( self, presentation.slide_index(self) )
+		end
+
+		def name=( new_name )
+			properties['name'].set( self, new_name, presentation.slide_index(self) )
+		end
+
+		# Get the value(s) of an attribute
+		def [](attribute_name, slide_name_or_index=nil)
+			if property = properties[attribute_name]
+				if slide_name_or_index
+					property.get( self, slide_name_or_index ) if has_slide?(slide_name_or_index)
+				else
+					UIC::ValuesPerSlide.new(@presentation,self,property)
+				end
+			end
+		end
+
+		# Set the value of an attribute, either across all slides, or on a particular slide
+		# el['foo']   = 42
+		# el['foo',0] = 42
+		def []=( attribute_name, slide_name_or_index=nil, new_value )
+			if property = properties[attribute_name] then
+				property.set(self,new_value,slide_name_or_index)
+			end
+		end
+
+		def to_xml
+			@el.to_xml
+		end
+		def inspect
+			"<asset #{@el.name}##{@el['id']}>"
+		end
+
+		def to_s
+			"<#{type} #{path}>"
+		end
+
+		def ==(other)
+			(self.class==other.class) && (el==other.el)
+		end
+		alias_method :eql?, :==
+	end
+
+	attr_reader :by_name
+
+	HIER = {}
+	%w[Asset Slide Scene].each{ |s| HIER[s] = 'Root' }
+	%w[Node Behavior Effect Image Layer MaterialBase PathAnchorPoint RenderPlugin].each{ |s| HIER[s]='Asset' }
+	%w[Alias Camera Component Group Light Model Text Path].each{ |s| HIER[s]='Node' }
+	%w[Material ReferencedMaterial].each{ |s| HIER[s]='MaterialBase' }
+
+	def initialize(xml)
+		@by_name = {'Root'=>Root}
+
+		doc = Nokogiri.XML(xml)
+		hack_in_slide_names!(doc)
+
+		HIER.each do |class_name,parent_class_name|
+			parent_class = @by_name[parent_class_name]
+			el = doc.root.at(class_name)
+			@by_name[class_name] = create_class(el,parent_class,el.name)
+		end
+
+		# Extend well-known classes with script interfaces after they are created
+		@by_name['State'] = @by_name['Slide']
+		@by_name['Slide'].instance_eval do
+			attr_accessor :index, :name
+			define_method :inspect do
+				"<slide ##{index} of #{@el['component'] || @el.parent['component']}>"
+			end
+			define_method(:slide?){ true }
+		end
+
+		refmat = @by_name['ReferencedMaterial']
+		@by_name['MaterialBase'].instance_eval do
+			define_method :replace_with_referenced_material do
+				type=='ReferencedMaterial' ? self : presentation.replace_asset( self, 'ReferencedMaterial', name:name )
+			end
+		end
+
+		@by_name['Path'].instance_eval do
+			define_method(:anchors){ find _type:'PathAnchorPoint' }
+		end
+
+	end
+
+	# Creates a class from MetaData.xml with accessors for the <Property> listed.
+	# Instances of the class are associated with a presentation and know how to
+	# get/set values in that XML based on value types, slides, defaults.
+	# Also used to create classes from effects, materials, and behavior preambles.
+	def create_class(el,parent_class,name='CustomAsset')
+		Class.new(parent_class) do
+			@name = name.to_s
+			@properties = Hash[ el.css("Property").map do |e|
+				type = e['type'] || (e['list'] ? 'String' : 'Float')
+				type = "Float" if type=="float"
+				property = UIC::Property.const_get(type).new(e)
+				[ property.name, UIC::Property.const_get(type).new(e) ]
+			end ]
+			def self.inspect
+				@name
+			end
+		end
+	end
+
+	def new_instance(presentation,el)
+		klass = @by_name[el.name] || create_class(el,@by_name['Asset'],el.name)
+		klass.new(presentation,el)
+	end
+
+	def hack_in_slide_names!(doc)
+		doc.at('Slide') << '<Property name="name" formalName="Name" type="String" default="Slide" hidden="True" />'
+	end
+end
+
+def UIC.MetaData(metadata_path)
+	UIC::MetaData.new(File.read(metadata_path,encoding:'utf-8'))
+end
+
+class UIC::SlideCollection
+	include Enumerable
+	attr_reader :length
+	def initialize(slides)
+		@length = slides.length-1
+		@slides = slides
+		@lookup = {}
+		slides.each do |s|
+			@lookup[s.index] = s
+			@lookup[s.name]  = s
+		end
+	end
+	def each
+		@slides.each{ |s| yield(s) }
+	end
+	def [](index_or_name)
+		@lookup[ index_or_name ]
+	end
+	def inspect
+		"[ #{@slides.map(&:inspect).join ', '} ]"
+	end
+	def to_ary
+		@slides
+	end
+end
+
+class UIC::ValuesPerSlide
+	def initialize(presentation,asset,property)
+		raise unless presentation.is_a?(UIC::Presentation)
+		raise unless asset.is_a?(UIC::MetaData::Root)
+		raise unless property.is_a?(UIC::Property)
+		@preso    = presentation
+		@asset    = asset
+		@el       = asset.el
+		@property = property
+	end
+	def value
+		values.first
+	end
+	def [](slide_name_or_index)
+		@property.get( @asset, slide_name_or_index )
+	end
+	def []=(slide_name_or_index,new_value)
+		@property.set( @asset, new_value, slide_name_or_index )
+	end
+	def linked?
+		@preso.attribute_linked?( @asset, @property.name )
+	end
+	def unlink
+		@preso.unlink_attribute( @asset, @property.name )
+	end
+	def link
+		@preso.link_attribute( @asset, @property.name )
+	end
+	def values
+		@asset.slides.map{ |s| self[s.name] }
+	end
+	def inspect
+		"<Values of '#{@asset.name}.#{@property.name}' across slides>"
+	end
+	alias_method :to_s, :inspect
+end
+
+class UIC::SlideValues
+	def initialize( asset, slide )
+		@asset = asset
+		@slide = slide
+	end
+	def [](attribute_name)
+		@asset[attribute_name,@slide]
+	end
+	def []=( attribute_name, new_value )
+		@asset[attribute_name,@slide] = new_value
+	end
+	def method_missing( name, *args, &blk )
+		asset.send(name,*args,&blk)
+	end
+	def inspect
+		"<#{@asset.inspect} on slide #{@slide.inspect}>"
+	end
 end