# Examples for Model entities
#
# This module introduce flags in all mentities so they can be tagged as example.
# Flagged classes will be treated differently by the documentation tools.
#
# See `MEntity::is_example` and `MEntity::examples`.
module model_examples

import model

# An example from a MEntity flagged with `is example`.
class MExample

	redef init do
		super
		mentity.mexample = self
	end

	# MEntity containing this example
	var mentity: MEntity

	# MEntities this example is for
	#
	# For each entity we provide a weight so examples can be ranked.
	var example_for = new ArrayMap[MEntity, Int]

	redef fun to_s do return mentity.full_name
end

redef class MEntity

	# Is `self` existing for an example purpose?
	#
	# All mentities annotated with `is example` or located inside a mentity that
	# is an example are considered as examples.
	fun is_example: Bool do return mexample != null

	# Return this entity as a MExample
	var mexample: nullable MExample = null

	# Examples found for `self`
	var examples = new Array[MExample]
end

redef class MPackage
	redef fun examples do
		var res = super
		for mgroup in mgroups do
			for example in mgroup.examples do
				if not res.has(example) then res.add example
			end
		end
		return res
	end
end

redef class MGroup
	redef var is_example is lazy do
		var parent = self.parent
		if parent != null and parent.is_example then return true
		return name == "examples"
	end

	redef fun examples do
		var res = super
		for mmodule in mmodules do
			for example in mmodule.examples do
				if not res.has(example) then res.add example
			end
		end
		return res
	end
end

redef class MClass
	redef var is_example is lazy do return intro.is_example

	redef fun examples do
		var res = super
		for mclassdef in mclassdefs do
			for example in mclassdef.examples do
				if not res.has(example) then res.add example
			end
		end
		return res
	end
end

redef class MProperty
	redef var is_example is lazy do return intro.is_example

	redef fun examples do
		var res = super
		for mpropdef in mpropdefs do
			for example in mpropdef.examples do
				if not res.has(example) then res.add example
			end
		end
		return res
	end
end