RUIC 0.4.2 → 0.4.3

data/lib/ruic/attributes.rb

@@ -1,165 +1,165 @@
-#encoding: utf-8
-class UIC::Property
-	class << self; attr_accessor :default; end
-	def initialize(el); @el = el; end
-	def name; @name||=@el['name']; end
-	def type; @type||=@el['type']; end
-	def formal; @formal||=@el['formalName'] || @el['name']; end
-	def min; @el['min']; end
-	def max; @el['max']; end
-	def description; @desc||=@el['description']; end
-	def default; @def ||= (@el['default'] || self.class.default); end
-	def get(asset,slide)
-		if asset.slide? || asset.has_slide?(slide)
-			asset.presentation.get_attribute(asset,name,slide) || default
-		end
-	end
-	def set(asset,new_value,slide_name_or_index)
-		asset.presentation.set_attribute(asset,name,slide_name_or_index,new_value)
-	end
-	def inspect
-		"<#{type} '#{name}'>"
-	end
-
-	class String < self
-		self.default = ''
-	end
-	MultiLineString = String
-
-	class Float < self
-		self.default = 0.0
-		def get(asset,slide); super.to_f; end
-	end
-	class Long < self
-		self.default = 0
-		def get(asset,slide); super.to_i; end
-	end
-	class Boolean < self
-		self.default = false
-		def get(asset,slide); super=='True'; end
-		def set(asset,new_value,slide_name_or_index)
-			super( asset, new_value ? 'True' : 'False', slide_name_or_index )
-		end
-	end
-	class Vector < self
-		self.default = '0 0 0'
-		def get(asset,slide)
-			VectorValue.new(asset,self,slide,super)
-		end
-		def set(asset,new_value,slide_name_or_index)
-			new_value = new_value.join(' ') if new_value.is_a?(Array)
-			super( asset, new_value, slide_name_or_index )
-		end
-	end
-	Rotation = Vector
-	Color    = Vector
-	Float2   = Vector
-	class Image < self
-		self.default = nil
-		def get(asset,slide)
-			if idref = super
-				result = asset.presentation.asset_by_id( idref[1..-1] )
-				slide ? result.on_slide( slide ) : result
-			end
-		end
-		def set(asset,new_value,slide)
-			raise "Setting image attributes not yet supported"
-		end
-	end
-	class Texture < String
-		def get(asset,slide)
-			if path=super
-				path.empty? ? nil : path.gsub( '\\', '/' ).sub( /^.\// ,'' )
-			end
-		end
-	end
-
-	class ObjectRef < self
-		self.default = nil
-		def get(asset,slide)
-			ref  = super
-			type = :absolute
-			obj  = nil
-			unless ref=='' || ref.nil?
-				type = ref[0]=='#' ? :absolute : :path
-				ref = type==:absolute ? asset.presentation.asset_by_id( ref[1..-1] ) : asset.presentation.at( ref, asset )
-			end
-			ObjectReference.new(asset,self,slide,ref,type)
-		end
-		def set(asset,new_object,slide)
-			get(asset,slide).object = new_object
-		end
-	end
-
-	class ObjectReference
-		attr_reader :object, :type
-		def initialize(asset,property,slide,object=nil,type=nil)
-			@asset    = asset
-			@name     = property.name
-			@slide    = slide
-			@object   = object
-			@type     = type
-		end
-		def object=(new_object)
-			raise "ObjectRef must be set to an asset (not a #{new_object.class.name})" unless new_object.is_a?(UIC::MetaData::Root)
-			@object = new_object
-			write_value!
-		end
-		def type=(new_type)
-			raise "ObjectRef types must be either :absolute or :path (not #{new_type.inspect})" unless [:absolute,:path].include?(new_type)
-			@type = new_type
-			write_value!
-		end
-		private
-		def write_value!
-			path = case @object
-				when NilClass then ""
-				else case @type
-					when :absolute then "##{@object.el['id']}"
-					when :path     then @asset.presentation.path_to( @object, @asset ).sub(/^[^:.]+:/,'')
-					# when :root     then @asset.presentation.path_to( @object ).sub(/^[^:.]+:/,'')
-				end
-			end
-			@asset.presentation.set_attribute( @asset, @name, @slide, path )
-		end
-	end
-
-	Import     = String #TODO: a real class
-	Mesh       = String #TODO: a real class
-	Renderable = String #TODO: a real class
-	Font       = String #TODO: a real class
-	FontSize   = Long
-
-	StringListOrInt = String #TODO: a real class
-
-	class VectorValue
-		attr_reader :x, :y, :z
-		def initialize(asset,property,slide,str)
-			@asset    = asset
-			@property = property
-			@slide    = slide
-			@x, @y, @z = str.split(/\s+/).map(&:to_f)
-		end
-		def setall
-			@property.set( @asset, to_s, @slide )
-		end
-		def x=(n); @x=n; setall end
-		def y=(n); @y=n; setall end
-		def z=(n); @z=n; setall end
-		alias_method :r, :x
-		alias_method :g, :y
-		alias_method :b, :z
-		alias_method :r=, :x=
-		alias_method :g=, :y=
-		alias_method :b=, :z=
-		def inspect
-			"<#{@asset.path}.#{@property.name}: #{self}>"
-		end
-		def to_s
-			to_a.join(' ')
-		end
-		def to_a
-			[x,y,z]
-		end
-	end
-end
+#encoding: utf-8
+class UIC::Property
+	class << self; attr_accessor :default; end
+	def initialize(el); @el = el; end
+	def name; @name||=@el['name']; end
+	def type; @type||=@el['type']; end
+	def formal; @formal||=@el['formalName'] || @el['name']; end
+	def min; @el['min']; end
+	def max; @el['max']; end
+	def description; @desc||=@el['description']; end
+	def default; @def ||= (@el['default'] || self.class.default); end
+	def get(asset,slide)
+		if asset.slide? || asset.has_slide?(slide)
+			asset.presentation.get_attribute(asset,name,slide) || default
+		end
+	end
+	def set(asset,new_value,slide_name_or_index)
+		asset.presentation.set_attribute(asset,name,slide_name_or_index,new_value)
+	end
+	def inspect
+		"<#{type} '#{name}'>"
+	end
+
+	class String < self
+		self.default = ''
+	end
+	MultiLineString = String
+
+	class Float < self
+		self.default = 0.0
+		def get(asset,slide); super.to_f; end
+	end
+	class Long < self
+		self.default = 0
+		def get(asset,slide); super.to_i; end
+	end
+	class Boolean < self
+		self.default = false
+		def get(asset,slide); super=='True'; end
+		def set(asset,new_value,slide_name_or_index)
+			super( asset, new_value ? 'True' : 'False', slide_name_or_index )
+		end
+	end
+	class Vector < self
+		self.default = '0 0 0'
+		def get(asset,slide)
+			VectorValue.new(asset,self,slide,super)
+		end
+		def set(asset,new_value,slide_name_or_index)
+			new_value = new_value.join(' ') if new_value.is_a?(Array)
+			super( asset, new_value, slide_name_or_index )
+		end
+	end
+	Rotation = Vector
+	Color    = Vector
+	Float2   = Vector
+	class Image < self
+		self.default = nil
+		def get(asset,slide)
+			if idref = super
+				result = asset.presentation.asset_by_id( idref[1..-1] )
+				slide ? result.on_slide( slide ) : result
+			end
+		end
+		def set(asset,new_value,slide)
+			raise "Setting image attributes not yet supported"
+		end
+	end
+	class Texture < String
+		def get(asset,slide)
+			if path=super
+				path.empty? ? nil : path.gsub( '\\', '/' ).sub( /^.\// ,'' )
+			end
+		end
+	end
+
+	class ObjectRef < self
+		self.default = nil
+		def get(asset,slide)
+			ref  = super
+			type = :absolute
+			obj  = nil
+			unless ref=='' || ref.nil?
+				type = ref[0]=='#' ? :absolute : :path
+				ref = type==:absolute ? asset.presentation.asset_by_id( ref[1..-1] ) : asset.presentation.at( ref, asset )
+			end
+			ObjectReference.new(asset,self,slide,ref,type)
+		end
+		def set(asset,new_object,slide)
+			get(asset,slide).object = new_object
+		end
+	end
+
+	class ObjectReference
+		attr_reader :object, :type
+		def initialize(asset,property,slide,object=nil,type=nil)
+			@asset    = asset
+			@name     = property.name
+			@slide    = slide
+			@object   = object
+			@type     = type
+		end
+		def object=(new_object)
+			raise "ObjectRef must be set to an asset (not a #{new_object.class.name})" unless new_object.is_a?(UIC::MetaData::AssetBase)
+			@object = new_object
+			write_value!
+		end
+		def type=(new_type)
+			raise "ObjectRef types must be either :absolute or :path (not #{new_type.inspect})" unless [:absolute,:path].include?(new_type)
+			@type = new_type
+			write_value!
+		end
+		private
+		def write_value!
+			path = case @object
+				when NilClass then ""
+				else case @type
+					when :absolute then "##{@object.el['id']}"
+					when :path     then @asset.presentation.path_to( @object, @asset ).sub(/^[^:.]+:/,'')
+					# when :root     then @asset.presentation.path_to( @object ).sub(/^[^:.]+:/,'')
+				end
+			end
+			@asset.presentation.set_attribute( @asset, @name, @slide, path )
+		end
+	end
+
+	Import     = String #TODO: a real class
+	Mesh       = String #TODO: a real class
+	Renderable = String #TODO: a real class
+	Font       = String #TODO: a real class
+	FontSize   = Long
+
+	StringListOrInt = String #TODO: a real class
+
+	class VectorValue
+		attr_reader :x, :y, :z
+		def initialize(asset,property,slide,str)
+			@asset    = asset
+			@property = property
+			@slide    = slide
+			@x, @y, @z = str.split(/\s+/).map(&:to_f)
+		end
+		def setall
+			@property.set( @asset, to_s, @slide )
+		end
+		def x=(n); @x=n; setall end
+		def y=(n); @y=n; setall end
+		def z=(n); @z=n; setall end
+		alias_method :r, :x
+		alias_method :g, :y
+		alias_method :b, :z
+		alias_method :r=, :x=
+		alias_method :g=, :y=
+		alias_method :b=, :z=
+		def inspect
+			"<#{@asset.path}.#{@property.name}: #{self}>"
+		end
+		def to_s
+			to_a.join(' ')
+		end
+		def to_a
+			[x,y,z]
+		end
+	end
+end

data/lib/ruic/behaviors.rb

@@ -21,6 +21,7 @@ end
 
 class UIC::Application::Behavior < UIC::Behavior
 	include UIC::ElementBacked
+	# @!parse extend UIC::ElementBacked::ClassMethods
 	xmlattribute :id
 	xmlattribute :src
 	def initialize(application,el)

data/lib/ruic/interfaces.rb

@@ -1,35 +1,73 @@
+# Supports classes that represent an XML file on disk (e.g. `.uia` and `.uip`).
 module UIC::FileBacked
-	attr_accessor :doc, :file
+	# @return [Nokogiri::XML::Document] the Nokogiri document representing the instance.
+	attr_accessor :doc
+
+	# @return [String] the absolute path to the underlying file.
+	attr_accessor :file
+
+	# @param relative [String] a file path relative to this file.
+	# @return [String] the full path resolved relative to this file.
 	def path_to( relative )
 		File.expand_path( relative.gsub('\\','/'), File.dirname(file) )
 	end
+
+	# @return [String] the name of the file (without any directories).
 	def filename
 		File.basename(file)
 	end
+
+	# @return [Boolean] `true` if the underlying file exists on disk.
 	def file_found?
-		!@file_not_found
+		@file && File.exist?(@file)
 	end
+
+	# Set the file for the class. Does **not** attempt to load the XML document.
+	# @param new_path [String] the file path for this class.
+	# @return [String]
 	def file=( new_path )
 		@file = File.expand_path(new_path)
-		@file_not_found = !File.exist?(new_path)
 	end
+
+	# @return [String] the XML representation of the document.
 	def to_xml
 		doc.to_xml( indent:1, indent_text:"\t" )
 	end
+
+	# Overwrite the associated file on disk with the {#to_xml} representation of this class.
+	# @return [true]
 	def save!
 		File.open(file,'w:utf-8'){ |f| f << to_xml }
+		true
+	end
+
+	# Save to the supplied file path. Subsequent calls to {#save!} will save to the new file, not the original file name.
+	def save_as(new_file)
+		File.open(new_file,'w:utf-8'){ |f| f << to_xml }
+		self.file = new_file
 	end
 end
 
+# Supports classes that represent an XML element (e.g. `<presentation id="main" src="foo.uip"/>`).
 module UIC::ElementBacked
-	attr_accessor :owner, :el
+
+	# @return [Object] the object in charge of this instance.
+	attr_accessor :owner
+
+	# @return [Nokogiri::XML::Element] the element backing this instance.
+	attr_accessor :el
+
+	# @private
 	def self.included(base)
 		base.extend(ClassMethods)
 	end
+
 	module ClassMethods
-		def xmlattribute(name,&block)
-			define_method(name){ @el[name] }
-			define_method("#{name}=", &(block || ->(new_value){ @el[name]=new_value.to_s }))
+		# @param name [String] the name of an XML attribute to expose.
+		# @param getblock [Proc] a proc to run
+		def xmlattribute(name,getblock=nil,&setblock)
+			define_method(name){ getblock ? getblock[@el[name]] : @el[name] }
+			define_method("#{name}="){ |new_value| @el[name] = (setblock ? setblock[new_value] : new_value).to_s }
 		end
 	end
 end

data/lib/ruic/presentation.rb

@@ -52,16 +52,13 @@ class UIC::Presentation
 		@slides_by_el = {} # indexed by slide state element
 	end
 
+	# @return [String] the xml representation of this presentation. Formatted to match UI Composer Studio's formatting as closely as possible (for minimal diffs after update).
 	def to_xml
 		doc.to_xml( indent:1, indent_text:"\t" )
 		   .gsub( %r{(<\w+(?: [\w:]+="[^"]*")*)(/?>)}i, '\1 \2' )
 		   .sub('"?>','" ?>')
 	end
 
-	def save_as(new_file)
-		File.open(new_file,'w:utf-8'){ |f| f << to_xml }
-	end
-
 	# Update the presentation to be in-sync with the document.
 	# Must be called whenever the in-memory representation of the XML document is changed.
 	# Called automatically by all necessary methods; only necessary if script (dangerously)
@@ -90,12 +87,12 @@ class UIC::Presentation
 
 	# Find an asset in the presentation based on its internal XML identifier.
 	# @param id [String] the id of the asset (not an idref), e.g. `"Material_003"`.
-	# @return [MetaData::Root] the found asset, or `nil` if could not be found.
+	# @return [MetaData::AssetBase] the found asset, or `nil` if could not be found.
 	def asset_by_id( id )
 		(@graph_by_id[id] && asset_for_el( @graph_by_id[id] ))
 	end
 
-	# @param asset [MetaData::Root] an asset in the presentation
+	# @param asset [MetaData::AssetBase] an asset in the presentation
 	# @return [Integer] the index of the first slide where an asset is added (0 for master, non-zero for non-master).
 	def slide_index(asset)
 		# TODO: probably faster to .find the first @addsets_by_graph
@@ -104,8 +101,8 @@ class UIC::Presentation
 		(slide ? slide.xpath('count(ancestor::State) + count(preceding-sibling::State[ancestor::State])').to_i : 0) # the Scene is never added
 	end
 
-	# @param child_asset [MetaData::Root] an asset in the presentation.
-	# @return [MetaData::Root] the scene graph parent of the child asset, or `nil` for the Scene.
+	# @param child_asset [MetaData::AssetBase] an asset in the presentation.
+	# @return [MetaData::AssetBase] the scene graph parent of the child asset, or `nil` for the Scene.
 	def parent_asset( child_asset )
 		child_graph_el = child_asset.el
 		unless child_graph_el==@scene || child_graph_el.parent.nil?
@@ -113,8 +110,8 @@ class UIC::Presentation
 		end
 	end
 
-	# @param parent_asset [MetaData::Root] an asset in the presentation.
-	# @return [Array<MetaData::Root>] array of scene graph children of the specified asset.
+	# @param parent_asset [MetaData::AssetBase] an asset in the presentation.
+	# @return [Array<MetaData::AssetBase>] array of scene graph children of the specified asset.
 	def child_assets( parent_asset )
 		parent_asset.el.element_children.map{ |child| asset_for_el(child) }
 	end
@@ -166,14 +163,13 @@ class UIC::Presentation
 	end
 	private :asset_for_el
 
-
-	def referenced_files
-		(
-			(images + behaviors + effects + meshes + materials ).map(&:file)
-			+ effects.flat_map(&:images)
-			+ fonts
-		).sort_by{ |f| parts = f.split(/[\/\\]/); [parts.length,parts] }
-	end
+	# def referenced_files
+	# 	(
+	# 		(images + behaviors + effects + meshes + materials ).map(&:file)
+	# 		+ effects.flat_map(&:images)
+	# 		+ fonts
+	# 	).sort_by{ |f| parts = f.split(/[\/\\]/); [parts.length,parts] }
+	# end
 
 	# @return [MetaData::Scene] the root scene asset for the presentation.
 	def scene
@@ -185,8 +181,8 @@ class UIC::Presentation
 	# * If `from_asset` is supplied the path will be relative to that asset (e.g. `"parent.parent.Group.Model"`).
 	# * If `from_asset` is omitted the path will be absolute (e.g. `"Scene.Layer.Group.Model"`).
 	#
-	# @param asset [MetaData::Root] the asset to find the path to.
-	# @param from_asset [MetaData::Root] the asset to find the path relative to.
+	# @param asset [MetaData::AssetBase] the asset to find the path to.
+	# @param from_asset [MetaData::AssetBase] the asset to find the path relative to.
 	# @return [String] the script path to the element.
 	def path_to( asset, from_asset=nil )
 		el = asset.el
@@ -244,7 +240,10 @@ class UIC::Presentation
 	#
 	#  assert layer1==layer2 && layer2==layer3 && layer3==layer4
 	#
-	# @return [MetaData::Root] The found asset, or `nil` if it cannot be found.
+	# @return [MetaData::AssetBase] The found asset, or `nil` if it cannot be found.
+	#
+	# @see Application#at
+	# @see MetaData::AssetBase#at
 	def at(path,root=@graph)
 		name,path = path.split('.',2)
 		root = root.el if root.respond_to?(:el)
@@ -267,7 +266,7 @@ class UIC::Presentation
 	#
 	#  assert preso.get_attribute(camera,'position',0) == camera['position',0]
 	#
-	# @param asset [MetaData::Root] the asset to fetch the attribute for.
+	# @param asset [MetaData::AssetBase] the asset to fetch the attribute for.
 	# @param attr_name [String] the name of the attribute to get the value of.
 	# @param slide_name_or_index [String,Integer] the string name or integer index of the slide.
 	def get_attribute( asset, attr_name, slide_name_or_index )
@@ -293,7 +292,7 @@ class UIC::Presentation
 	#  # …and the shorter way
 	#  camera['endtime',0] = 1000
 	#
-	# @param asset [MetaData::Root] the asset to fetch the attribute for.
+	# @param asset [MetaData::AssetBase] the asset to fetch the attribute for.
 	# @param attr_name [String] the name of the attribute to get the value of.
 	# @param slide_name_or_index [String,Integer] the string name or integer index of the slide.
 	def set_attribute( asset, property_name, slide_name_or_index, str )
@@ -319,14 +318,14 @@ class UIC::Presentation
 		end
 	end
 
-	# @return [MetaData::Root] the component (or Scene) asset that owns the supplied asset.
-	# @see MetaData::Root#component
+	# @return [MetaData::AssetBase] the component (or Scene) asset that owns the supplied asset.
+	# @see MetaData::AssetBase#component
 	def owning_component( asset )
 		asset_for_el( owning_component_element( asset.el ) )
 	end
 
-	# @return [MetaData::Root] the component asset that owns the supplied asset.
-	# @see MetaData::Root#component
+	# @return [MetaData::AssetBase] the component asset that owns the supplied asset.
+	# @see MetaData::AssetBase#component
 	def owning_component_element( graph_element )
 		graph_element.at_xpath('(ancestor::Component[1] | ancestor::Scene[1])[last()]')
 	end
@@ -345,9 +344,9 @@ class UIC::Presentation
 	end
 	private :master_slide_for
 
-	# @param asset [MetaData::Root] the asset to get the slides for.
+	# @param asset [MetaData::AssetBase] the asset to get the slides for.
 	# @return [SlideCollection] an array-like collection of all slides that the asset is available on.
-	# @see MetaData::Root#slides
+	# @see MetaData::AssetBase#slides
 	def slides_for( asset )
 		graph_element = asset.el
 		@slides_for[graph_element] ||= begin
@@ -361,7 +360,7 @@ class UIC::Presentation
 	end
 
 	# @return [Boolean] true if the asset exists on the supplied slide.
-	# @see MetaData::Root#has_slide?
+	# @see MetaData::AssetBase#has_slide?
 	def has_slide?( asset, slide_name_or_index )
 		graph_element = asset.el
 		if graph_element == @scene
@@ -389,7 +388,7 @@ class UIC::Presentation
 
 	# Unlinks a master attribute, yielding distinct values on each slide. If the asset is not on the master slide, or the attribute is already unlinked, no change occurs.
 	#
-	# @param asset [MetaData::Root] the master asset to unlink the attribute on.
+	# @param asset [MetaData::AssetBase] the master asset to unlink the attribute on.
 	# @param attribute_name [String] the name of the attribute to unlink.
 	# @return [Boolean] `true` if the attribute was previously linked; `false` otherwise.
 	def unlink_attribute(asset,attribute_name)
@@ -409,10 +408,10 @@ class UIC::Presentation
 
 	# Replace an existing asset with a new kind of asset.
 	#
-	# @param existing_asset [MetaData::Root] the existing asset to replace.
+	# @param existing_asset [MetaData::AssetBase] the existing asset to replace.
 	# @param new_type [String] the name of the asset type, e.g. `"ReferencedMaterial"` or `"Group"`.
 	# @param attributes [Hash] initial attribute values for the new asset.
-	# @return [MetaData::Root] the newly-created asset.
+	# @return [MetaData::AssetBase] the newly-created asset.
 	def replace_asset( existing_asset, new_type, attributes={} )
 		old_el = existing_asset.el
 		new_el = old_el.replace( "<#{new_type}/>" ).first
@@ -431,13 +430,65 @@ class UIC::Presentation
 		(graph_element == @scene) || !!(@addsets_by_graph[graph_element] && @addsets_by_graph[graph_element][0])
 	end
 
-	def find(options={})
+	# Find assets in this presentation matching criteria.
+	#
+	# @example 1) Searching for simple values
+	#  every_asset   = preso.find                          # Every asset in the presentation
+	#  master_assets = preso.find _master:true             # Test for master/nonmaster
+	#  models        = preso.find _type:'Model'            # …or based on type
+	#  slide2_assets = preso.find _slide:2                 # …or presence on a specific slide
+	#  rectangles    = preso.find sourcepath:'#Rectangle'  # …or attribute values
+	#  gamecovers    = preso.find name:'Game Cover'        # …including the name
+	#
+	# @example 2) Combine tests to get more specific
+	#  master_models = preso.find _type:'Model', _master:true
+	#  slide2_rects  = preso.find _type:'Model', _slide:2, sourcepath:'#Rectangle'
+	#  nonmaster_s2  = preso.find _slide:2, _master:false
+	#  red_materials = preso.find _type:'Material', diffuse:[1,0,0]
+	#
+	# @example 3) Matching values more loosely
+	#  pistons       = preso.find name:/^Piston/           # Regex for batch finding
+	#  bottom_row    = preso.find position:[nil,-200,nil]  # nil for wildcards in vectors
+	#
+	# @example 4) Restrict the search to a sub-tree
+	#  group        = preso/"Scene.Layer.Group"
+	#  group_models = preso.find _under:group, _type:'Model'  # All models under the group
+	#  group_models = group.find _type:'Model'                # alternatively start from the asset
+	#
+	# @example 5) Iterate the results as they are found
+	#  preso.find _type:'Model', name:/^Piston/ do |model, index|
+	#     show "Model #{index} is named #{model.name}"
+	#  end
+	#
+	#  # You do not need to receive the index if you do not need its value
+	#  group.find _type:'Model' do |model|
+	#     scale = model['scale'].value
+	#     scale.x = scale.y = scale.z = 1
+	#  end
+	#
+	# @param criteria [Hash] Attribute names and values, along with a few special keys.
+	# @option criteria :_type [String] asset must be of specified type, e.g. `"Model"` or `"Material"` or `"PathAnchorPoint"`.
+	# @option criteria :_slide [Integer,String] slide number or name that the asset must be present on.
+	# @option criteria :_master [Boolean] `true` for only master assets, `false` for only non-master assets.
+	# @option criteria :_under [MetaData::AssetBase] a root asset to require as an ancestor; this asset will never be in the search results.
+	# @option criteria :attribute_name [Numeric] numeric attribute value must be within `0.001` of the supplied value.
+	# @option criteria :attribute_name [String] string attribute value must match the supplied string exactly.
+	# @option criteria :attribute_name [Regexp] supplied regex must match the string attribute value.
+	# @option criteria :attribute_name [Array] each component of the attribute's vector value must be within `0.001` of the supplied value in the array;
+	#                                          if a value in the array is `nil` that component of the vector may have any value.
+	#
+	# @yield [asset,index] Yields each found asset (and its index in the results) to the block (if supplied) as they are found.
+	#
+	# @return [Array<MetaData::AssetBase>] array of all matching assets (may be empty).
+	#
+	# @see MetaData::AssetBase#find
+	def find(criteria={},&block)
 		index = -1
-		start = options.key?(:_under) ? options.delete(:_under).el : @graph
+		start = criteria.key?(:_under) ? criteria.delete(:_under).el : @graph
 		[].tap do |result|
 			start.xpath('./descendant::*').each do |el|
 				asset = asset_for_el(el)
-				next unless options.all? do |att,val|
+				next unless criteria.all? do |att,val|
 					case att
 						when :_type   then el.name == val
 						when :_slide  then has_slide?(asset,val)
@@ -460,6 +511,7 @@ class UIC::Presentation
 		end
 	end
 
+	# @private
 	def inspect
 		"<#{self.class} #{File.basename(file)}>"
 	end
@@ -471,14 +523,25 @@ end
 
 class UIC::Application::Presentation < UIC::Presentation
 	include UIC::ElementBacked
-	xmlattribute :id
-	xmlattribute :src
+	# @!parse extend UIC::ElementBacked::ClassMethods
+
+	# @!attribute [rw] id
+	#   @return [String] the id of the presentation asset
 	xmlattribute :id do |new_id|
 		main_preso = app.main_presentation
 		super(new_id)
 		app.main_presentation=self if main_preso==self
 	end
-	xmlattribute :active
+
+	# @!attribute src
+	#   @return [String] the path to the presentation file
+	xmlattribute :src
+
+	# @!attribute active
+	#   @return [Boolean] is the presentation initially active?
+	xmlattribute :active, ->(val){ val=="True" } do |new_val|
+		new_val ? 'True' : 'False'
+	end
 
 	def initialize(application,el)
 		self.owner = application
@@ -492,6 +555,7 @@ class UIC::Application::Presentation < UIC::Presentation
 	end
 end
 
+# @private no need to document this monkeypatch
 class Nokogiri::XML::Element
 	def index(kind='*') # Find the index of this element amongs its siblings
 		xpath("count(./preceding-sibling::#{kind})").to_i