RUIC 0.4.1 → 0.4.2

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.el,name,slide) || default
-		end
-	end
-	def set(asset,new_value,slide_name_or_index)
-		asset.presentation.set_attribute(asset.el,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.el )
-			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::Asset::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.el, @asset.el ).sub(/^[^:.]+:/,'')
-					# when :root     then @asset.presentation.path_to( @object.el ).sub(/^[^:.]+:/,'')
-				end
-			end
-			@asset.presentation.set_attribute( @asset.el, @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::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

data/lib/ruic/interfaces.rb

@@ -12,7 +12,12 @@ module UIC::FileBacked
 	def file=( new_path )
 		@file = File.expand_path(new_path)
 		@file_not_found = !File.exist?(new_path)
-		# warn "Could not find file '#{new_path}'" unless file_found?
+	end
+	def to_xml
+		doc.to_xml( indent:1, indent_text:"\t" )
+	end
+	def save!
+		File.open(file,'w:utf-8'){ |f| f << to_xml }
 	end
 end
 
@@ -26,7 +31,7 @@ module UIC::ElementBacked
 			define_method(name){ @el[name] }
 			define_method("#{name}=", &(block || ->(new_value){ @el[name]=new_value.to_s }))
 		end
-	end	
+	end
 end
 
 module UIC::PresentableHash

data/lib/ruic/presentation.rb

@@ -1,11 +1,21 @@
+# A `Presentation` represents a `.uip` presentation, created and edited by UI Composer Studio.
 class UIC::Presentation
 	include UIC::FileBacked
-	def initialize( uip_path )
+
+	# Create a new presentation. If you do not specify the `uip_path` to load from, you must
+	# later set the `.file = `for the presentation, and then call the {#load_from_file} method.
+	# @param uip_path [String] path to the `.uip` to load.
+	def initialize( uip_path=nil )
 		self.file = uip_path
 		load_from_file if file_found?
 	end
 
+	# Load information for the presentation from disk.
+	# If you supply a path to a `.uip` file when creating the presentation
+	# this method is automatically called.
+	# @return [nil]
 	def load_from_file
+		# TODO: this method assumes an application to find the metadata on; the metadata should be part of this class instance instead, shared with the app when present
 		@doc = Nokogiri.XML( File.read( file, encoding:'utf-8' ), &:noblanks )
 		@graph = @doc.at('Graph')
 		@scene = @graph.at('Scene')
@@ -32,6 +42,7 @@ class UIC::Presentation
 					app.metadata.create_class( meta, from, reference.name )
 			end
 			@class_by_ref[ "##{reference['id']}" ] = metaklass
+			nil
 		end
 
 		rebuild_caches_from_document
@@ -42,19 +53,21 @@ class UIC::Presentation
 	end
 
 	def to_xml
-		@doc.to_xml( indent:1, indent_text:"\t" )
-		    .gsub( %r{(<\w+(?: [\w:]+="[^"]*")*)(/?>)}i, '\1 \2' )
-		    .sub('"?>','" ?>')
-	end
-
-	def save!
-		File.open(file,'w:utf-8'){ |f| f << 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)
+	# manipulates the `.doc` of the presentation directly.
+	#
+	# @return [nil]
 	def rebuild_caches_from_document
 		@graph_by_id = {}
 		@scene.traverse{ |x| @graph_by_id[x['id']]=x if x.is_a?(Nokogiri::XML::Element) }
@@ -72,27 +85,38 @@ class UIC::Presentation
 			@addsets_by_graph[graph][name]  = addset
 			@addsets_by_graph[graph][index] = addset
 		end
+		nil
 	end
 
+	# 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.
 	def asset_by_id( id )
 		(@graph_by_id[id] && asset_for_el( @graph_by_id[id] ))
 	end
 
-	# Find the index of the slide where an element is added
-	def slide_index(graph_element)
+	# @param asset [MetaData::Root] 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
-		slide = @logic.at(".//Add[@ref='##{graph_element['id']}']/..")
+		id = asset.el['id']
+		slide = @logic.at(".//Add[@ref='##{id}']/..")
 		(slide ? slide.xpath('count(ancestor::State) + count(preceding-sibling::State[ancestor::State])').to_i : 0) # the Scene is never added
 	end
 
-	def parent_asset( child_graph_el )
+	# @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.
+	def parent_asset( child_asset )
+		child_graph_el = child_asset.el
 		unless child_graph_el==@scene || child_graph_el.parent.nil?
 			asset_for_el( child_graph_el.parent )
 		end
 	end
 
-	def child_assets( parent_graph_el )
-		parent_graph_el.element_children.map{ |child| asset_for_el(child) }
+	# @param parent_asset [MetaData::Root] an asset in the presentation.
+	# @return [Array<MetaData::Root>] 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
 
 	# Get an array of all assets in the scene graph, in document order
@@ -100,8 +124,9 @@ class UIC::Presentation
 		@graph_by_id.map{ |id,graph_element| asset_for_el(graph_element) }
 	end
 
-	# Returns a hash mapping image paths to arrays of the assets referencing them
+	# @return [Hash] a mapping of image paths to arrays of the assets referencing them.
 	def image_usage
+		# TODO: this returns the same asset multiple times, with no indication of which property is using it; should switch to an Asset/Property pair, or some such.
 		asset_types = app.metadata.by_name.values + @class_by_ref.values
 
 		image_properties_by_type = asset_types.flat_map do |type|
@@ -129,16 +154,18 @@ class UIC::Presentation
 		end ].tap{ |h| h.extend(UIC::PresentableHash) }
 	end
 
+	# @return [Array<String>] array of all image paths referenced by this presentation.
 	def image_paths
 		image_usage.keys
 	end
 
+	# Find or create an asset for a scene graph element.
+	# @param el [Nokogiri::XML::Element] the scene graph element.
 	def asset_for_el(el)
 		(@asset_by_el[el] ||= el['class'] ? @class_by_ref[el['class']].new(self,el) : app.metadata.new_instance(self,el))
 	end
+	private :asset_for_el
 
-	attr_reader :addsets_by_graph
-	protected :addsets_by_graph
 
 	def referenced_files
 		(
@@ -148,11 +175,22 @@ class UIC::Presentation
 		).sort_by{ |f| parts = f.split(/[\/\\]/); [parts.length,parts] }
 	end
 
+	# @return [MetaData::Scene] the root scene asset for the presentation.
 	def scene
 		asset_for_el( @scene )
 	end
 
-	def path_to( el, from_el=nil )
+	# Generate the script path for an asset in the 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.
+	# @return [String] the script path to the element.
+	def path_to( asset, from_asset=nil )
+		el = asset.el
+
 		to_parts = if el.ancestors('Graph')
 			[].tap{ |parts|
 				until el==@graph
@@ -161,7 +199,8 @@ class UIC::Presentation
 				end
 			}
 		end
-		if from_el && from_el.ancestors('Graph')
+		if from_asset && from_asset.el.ancestors('Graph')
+			from_el = from_asset.el
 			from_parts = [].tap{ |parts|
 				until from_el==@graph
 					parts.unshift asset_for_el(from_el).name
@@ -177,16 +216,38 @@ class UIC::Presentation
 		to_parts.join('.')
 	end
 
+	# @return [Boolean] true if there any errors with the presentation.
 	def errors?
 		(!errors.empty?)
 	end
 
+	# @return [Array<String>] an array (possibly empty) of all errors in this presentation.
 	def errors
 		(file_found? ? [] : ["File not found: '#{file}'"])
 	end
 
+	# Find an element or asset in this presentation by scripting path.
+	#
+	# * If `root` is supplied, the path is resolved relative to that asset.
+	# * If `root` is not supplied, the path is resolved as a root-level path.
+	#
+	# @example
+	#  preso  = app.main
+	#  scene  = preso.scene
+	#  camera = scene/"Layer.Camera"
+	#
+	#  # Four ways to find the same layer
+	#  layer1 = preso/"Scene.Layer"
+	#  layer2 = preso.at "Scene.Layer"
+	#  layer3 = preso.at "Layer", scene
+	#  layer4 = preso.at "parent", camera
+	#
+	#  assert layer1==layer2 && layer2==layer3 && layer3==layer4
+	#
+	# @return [MetaData::Root] The found asset, or `nil` if it cannot be found.
 	def at(path,root=@graph)
 		name,path = path.split('.',2)
+		root = root.el if root.respond_to?(:el)
 		el = case name
 			when 'parent' then root==@scene ? nil : root.parent
 			when 'Scene'  then @scene
@@ -196,16 +257,48 @@ class UIC::Presentation
 	end
 	alias_method :/, :at
 
-	def get_attribute( graph_element, property_name, slide_name_or_index )
+	# Fetch the value of an asset's attribute on a particular slide. Slide `0` is the Master Slide, slide `1` is the first non-master slide.
+	#
+	# This method is used internally by assets; accessing attributes directly from the asset is generally more appropriate.
+	#
+	# @example
+	#  preso = app.main_presentation
+	#  camera = preso/"Scene.Layer.Camera"
+	#
+	#  assert preso.get_attribute(camera,'position',0) == camera['position',0]
+	#
+	# @param asset [MetaData::Root] 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 )
+		graph_element = asset.el
 		((addsets=@addsets_by_graph[graph_element]) && ( # State (slide) don't have any addsets
-			( addsets[slide_name_or_index] && addsets[slide_name_or_index][property_name] ) || # Try for a Set on the specific slide
-			( addsets[0] && addsets[0][property_name] ) # …else try the master slide
-		) || graph_element[property_name]) # …else try the graph
+			( addsets[slide_name_or_index] && addsets[slide_name_or_index][attr_name] ) || # Try for a Set on the specific slide
+			( addsets[0] && addsets[0][attr_name] ) # …else try the master slide
+		) || graph_element[attr_name]) # …else try the graph
 		# TODO: handle animation (child of addset)
 	end
 
-	def set_attribute( graph_element, property_name, slide_name_or_index, str )
-		if attribute_linked?( graph_element, property_name )
+	# Set the value of an asset's attribute on a particular slide. Slide `0` is the Master Slide, slide `1` is the first non-master slide.
+	#
+	# This method is used internally by assets; accessing attributes directly from the asset is generally more appropriate.
+	#
+	# @example
+	#  preso = app.main_presentation
+	#  camera = preso/"Scene.Layer.Camera"
+	#
+	#  # The long way to set the attribute value
+	#  preso.set_attribute(camera,'endtime',0,1000)
+	#
+	#  # …and the shorter way
+	#  camera['endtime',0] = 1000
+	#
+	# @param asset [MetaData::Root] 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 )
+		graph_element = asset.el
+		if attribute_linked?( asset, property_name )
 			if @addsets_by_graph[graph_element]
 				@addsets_by_graph[graph_element][0][property_name] = str
 			else
@@ -218,7 +311,7 @@ class UIC::Presentation
 				else
 					master = master_slide_for( graph_element )
 					slide_count = master.xpath('count(./State)').to_i
-					0.upto(slide_count).each{ |idx| set_attribute(graph_element,property_name,idx,str) }
+					0.upto(slide_count).each{ |idx| set_attribute(asset,property_name,idx,str) }
 				end
 			else
 				raise "TODO"
@@ -226,24 +319,37 @@ class UIC::Presentation
 		end
 	end
 
-	def owning_component( graph_element )
-		asset_for_el( owning_component_element( graph_element ) )
+	# @return [MetaData::Root] the component (or Scene) asset that owns the supplied asset.
+	# @see MetaData::Root#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
 	def owning_component_element( graph_element )
 		graph_element.at_xpath('(ancestor::Component[1] | ancestor::Scene[1])[last()]')
 	end
+	private :owning_component_element
 
+	# @return [Nokogiri::XML::Element] the "time context" scene graph element that owns the supplied element.
 	def owning_or_self_component_element( graph_element )
 		graph_element.at_xpath('(ancestor-or-self::Component[1] | ancestor-or-self::Scene[1])[last()]')
 	end
+	private :owning_or_self_component_element
 
+	# @return [Nokogiri::XML::Element] the logic-graph element representing the master slide for a scene graph element
 	def master_slide_for( graph_element )
 		comp = owning_or_self_component_element( graph_element )
 		@logic.at("./State[@component='##{comp['id']}']")
 	end
+	private :master_slide_for
 
-	def slides_for( graph_element )
+	# @param asset [MetaData::Root] 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
+	def slides_for( asset )
+		graph_element = asset.el
 		@slides_for[graph_element] ||= begin
 			slides = []
 			master = master_slide_for( graph_element )
@@ -254,31 +360,59 @@ class UIC::Presentation
 		end
 	end
 
-	def has_slide?( graph_element, slide_name_or_index )
+	# @return [Boolean] true if the asset exists on the supplied slide.
+	# @see MetaData::Root#has_slide?
+	def has_slide?( asset, slide_name_or_index )
+		graph_element = asset.el
 		if graph_element == @scene
 			# The scene is never actually added, so we'll treat it just like the first add, which is on the master slide of the scene
-			has_slide?( @addsets_by_graph.first.first, slide_name_or_index )
+			has_slide?( asset_for_el( @addsets_by_graph.first.first ), slide_name_or_index )
 		else
 			@addsets_by_graph[graph_element][slide_name_or_index] || @addsets_by_graph[graph_element][0]
 		end
 	end
 
-	def attribute_linked?(graph_element,attribute_name)
+	# @example
+	#  preso  = app.main
+	#  camera = preso/"Scene.Layer.Camera"
+	#
+	#  # Two ways of determining if an attribute for an asset is linked.
+	#  if preso.attribute_linked?( camera, 'fov' )
+	#  if camera['fov'].linked?
+	#
+	# @return [Boolean] true if this asset's attribute is linked on the master slide.
+	# @see ValuesPerSlide#linked?
+	def attribute_linked?( asset, attribute_name )
+		graph_element = asset.el
 		!(@addsets_by_graph[graph_element] && @addsets_by_graph[graph_element][1] && @addsets_by_graph[graph_element][1].key?(attribute_name))
 	end
 
-	def unlink_attribute(graph_element,attribute_name)
-		if master?(graph_element) && attribute_linked?(graph_element,attribute_name)
-			master_value = get_attribute( graph_element, attribute_name, 0 )
-			slides_for( graph_element ).to_ary[1..-1].each do |slide|
+	# 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 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)
+		graph_element = asset.el
+		if master?(asset) && attribute_linked?(asset,attribute_name)
+			master_value = get_attribute( asset, attribute_name, 0 )
+			slides_for( asset ).to_ary[1..-1].each do |slide|
 				addset = slide.el.at_xpath( ".//*[@ref='##{graph_element['id']}']" ) || slide.el.add_child("<Set ref='##{graph_element['id']}'/>").first
 				addset[attribute_name] = master_value
 			end
 			rebuild_caches_from_document
 			true
+		else
+			false
 		end
 	end
 
+	# Replace an existing asset with a new kind of asset.
+	#
+	# @param existing_asset [MetaData::Root] 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.
 	def replace_asset( existing_asset, new_type, attributes={} )
 		old_el = existing_asset.el
 		new_el = old_el.replace( "<#{new_type}/>" ).first
@@ -291,8 +425,9 @@ class UIC::Presentation
 		end
 	end
 
-	# Is this element added on the master slide?
-	def master?(graph_element)
+	# @return [Boolean] `true` if the asset is added on the master slide.
+	def master?(asset)
+		graph_element = asset.el
 		(graph_element == @scene) || !!(@addsets_by_graph[graph_element] && @addsets_by_graph[graph_element][0])
 	end
 
@@ -305,8 +440,8 @@ class UIC::Presentation
 				next unless options.all? do |att,val|
 					case att
 						when :_type   then el.name == val
-						when :_slide  then has_slide?(el,val)
-						when :_master then master?(el)==val
+						when :_slide  then has_slide?(asset,val)
+						when :_master then master?(asset)==val
 						else
 							if asset.properties[att.to_s]
 								value = asset[att.to_s].value