Module:Infobox MOS

Module documentation[view] [edit] [history] [purge]

Note: Do not invoke this module directly; use the corresponding template instead: Template:Infobox MOS.

This module depends on the following other modules: Module: Arguments Module: Infobox Module: Keyboard vis Module: MOS Module: TAMNAMS Module: Template input parse Module: Xenpaper Module: Yesno

This module generates an infobox providing information about a given moment of symmetry (MOS) scale.

---

local p = {}

local getArgs = require("Module:Arguments").getArgs
local ib = require("Module:Infobox")
local kbvis = require("Module:Keyboard vis")
local mos = require("Module:MOS")
local tamnams = require("Module:TAMNAMS")
local tip = require("Module:Template input parse")
local xp = require("Module:Xenpaper")
local yesno = require("Module:Yesno")

-- TODO: bugfix tamnams lookup breaking for mosses with 5 steps or less; interim
-- fix currently implemented shows smaller mosses as descending from itself.

-- Helper function
-- Concatenates the contents of two tables into one
-- This doesn't have a return value; rather, the first table passed has the
-- second table's contents added to it.
function p.concatenate_tables(t1, t2)
	for i=1, #t2 do
		t1[#t1 + 1] = t2[i]
	end
end

-- Helper function
-- Annotates a section header with the equave as superscript text.
function p.annotate_section_header(input_mos, section_header)
	local et_suffix = mos.et_suffix(input_mos)
	return (et_suffix == "edo" 
		and string.format('<div style=\"margin-top: 0.6em;\"><b>%s</b></div>', section_header)
		or  string.format('<div style=\"margin-top: 0.6em;\"><b>%s</b><sup><abbr title=\"In steps of %s\">(%s)</sup></div>', section_header, et_suffix, et_suffix)
	)
end

-- Helper function
-- Create a keyboard visualization, based on the Halberstadt keyboard layout
function p.kb_vis(input_mos)
	local input_mos = input_mos or mos.new(5, 2)
	
	local brightest_mode = mos.brightest_mode(input_mos)
	
	local vis = ""
	if input_mos.nL + input_mos.ns < 40 then
		vis = kbvis.vis_small(brightest_mode)
	end
	
	return {{vis}}
end

-- Helper function
-- Adds categories
function p.categorize(input_mos)
	local input_mos = input_mos or mos.new(5,2)
	
	-- Add to category of abstact mosses
	local categories = "[[Category:Abstract MOS patterns]]"
	
	-- Add notecount category if the notecount is greater than 3
	local notecount = input_mos.nL + input_mos.ns
	if notecount > 3 then
		categories = categories .. string.format("[[Category:%d-tone scales]]", notecount)
	end
	
	-- If the mos is octave-equivalent, add appropriate tamnams-named categories
	-- Otherwise, add to nonoctave category
	if mos.is_octave_equivalent(input_mos) then
		-- Caveats:
		-- - Only octave-equivalent mos names are used as categories.
		-- - Monowood and biwood are excluded (for now).
		-- - Mosses whose notecounts > 10 and periods < 5 are categorized under
		--   the closest tamnams-named ancestor.
		local ancestor_mos = tamnams.find_ancestor(input_mos)
		local tamnams_name = tamnams.lookup_name(ancestor_mos)
		
		if tamnams_name ~= nil then
			categories = categories .. string.format("[[Category:%s]]", tamnams_name)
		end
	else
		categories = categories .. "[[Category:Nonoctave]]"
	end
	
	return categories
end

-- Helper function
-- Creates adjacent links for mos, found by +/-1 large or +/- small steps
function p.adjacent_links(input_mos)
	local input_mos = input_mos or mos.new(1, 1)
	
	local adjacent_mosses = {
		mos.new(input_mos.nL - 1, input_mos.ns - 1, input_mos.equave),		-- UL
		mos.new(input_mos.nL    , input_mos.ns - 1, input_mos.equave),		-- U
		mos.new(input_mos.nL + 1, input_mos.ns - 1, input_mos.equave),		-- UR
		mos.new(input_mos.nL - 1, input_mos.ns    , input_mos.equave),		-- L
		mos.new(input_mos.nL + 1, input_mos.ns    , input_mos.equave),		-- R
		mos.new(input_mos.nL - 1, input_mos.ns + 1, input_mos.equave),		-- DL
		mos.new(input_mos.nL    , input_mos.ns + 1, input_mos.equave),		-- D
		mos.new(input_mos.nL + 1, input_mos.ns + 1, input_mos.equave),		-- DR
	}
	
	local adjacent_links = {
		mos.is_valid(adjacent_mosses[1]) and string.format("[[%s|&#x2196;&nbsp;%s]]", mos.as_long_string(adjacent_mosses[1]), mos.as_string(adjacent_mosses[1]), true) or "",
		mos.is_valid(adjacent_mosses[2]) and string.format("[[%s|&#x2191;&nbsp;%s]]", mos.as_long_string(adjacent_mosses[2]), mos.as_string(adjacent_mosses[2]), true) or "",
		mos.is_valid(adjacent_mosses[3]) and string.format("[[%s|%s&nbsp;&#x2197;]]", mos.as_long_string(adjacent_mosses[3]), mos.as_string(adjacent_mosses[3]), true) or "",
		mos.is_valid(adjacent_mosses[4]) and string.format("[[%s|&#x2190;&nbsp;%s]]", mos.as_long_string(adjacent_mosses[4]), mos.as_string(adjacent_mosses[4]), true) or "",
		mos.is_valid(adjacent_mosses[5]) and string.format("[[%s|%s&nbsp;&#x2192;]]", mos.as_long_string(adjacent_mosses[5]), mos.as_string(adjacent_mosses[5]), true) or "",
		mos.is_valid(adjacent_mosses[6]) and string.format("[[%s|&#x2199;&nbsp;%s]]", mos.as_long_string(adjacent_mosses[6]), mos.as_string(adjacent_mosses[6]), true) or "",
		mos.is_valid(adjacent_mosses[7]) and string.format("[[%s|&#x2193;&nbsp;%s]]", mos.as_long_string(adjacent_mosses[7]), mos.as_string(adjacent_mosses[7]), true) or "",
		mos.is_valid(adjacent_mosses[8]) and string.format("[[%s|%s&nbsp;&#x2198;]]", mos.as_long_string(adjacent_mosses[8]), mos.as_string(adjacent_mosses[8]), true) or ""
	}
	
	return adjacent_links
end

-- TODO: Cleanup and adopt mos functions
-- Helper function
-- Produces section entries for scale sturcture
-- Section is returned as a jagged array and return value must be merged into
-- a larger array.
function p.scale_structure(input_mos)
	local input_mos = input_mos or mos.new(5, 2)
	
	local equave_as_string = mos.equave_as_string(input_mos)
	local equave_in_cents  = mos.equave_to_cents(input_mos)
	
	local number_of_periods = mos.period_count(input_mos)
	local period_as_string = ""
	if number_of_periods == 1 then
		period_as_string = equave_as_string
	else
		period_as_string = mos.reduced_period_to_et_string(input_mos, "")
	end
	local period_in_cents = equave_in_cents / number_of_periods
	
	local step_pattern = string.format("...%d steps...", input_mos.nL+input_mos.ns)
	if input_mos.nL + input_mos.ns <= 40 then
		local brightest_mode = mos.brightest_mode(input_mos)
		step_pattern = string.format("<abbr title=\"Brightest mode\">%s</abbr><br /><abbr title=\"Darkest mode\">%s</abbr>", brightest_mode, string.reverse(brightest_mode))
	end
	
	local section_header = "Scale structure"
	local section_entries = {
		{string.format("<div style=\"margin-top: 0.6em;\"><b>%s</b></div>", section_header)},
		{"[[Step pattern]]", step_pattern},
		{"[[Equave]]", string.format("%s (%.1f{{c}})", equave_as_string, equave_in_cents)},
		{"[[Period]]", string.format("%s (%.1f{{c}})", period_as_string, period_in_cents)}
	}

	return section_entries
end

-- Helper function
-- Produces generator ranges for scale
-- Section is returned as a jagged array and return value must be merged into
-- a larger array.
function p.generator_sizes(input_mos)
	local input_mos = input_mos or mos.new(5, 2,3)
	
	local bright_min_in_steps = mos.bright_gen_to_et_string(input_mos, {1, 1}, "")
	local bright_max_in_steps = mos.bright_gen_to_et_string(input_mos, {1, 0}, "")
	local dark_min_in_steps   = mos.dark_gen_to_et_string  (input_mos, {1, 0}, "")
	local dark_max_in_steps   = mos.dark_gen_to_et_string  (input_mos, {1, 1}, "")
	
	local bright_min_in_cents = mos.bright_gen_to_cents(input_mos, {1, 1})
	local bright_max_in_cents = mos.bright_gen_to_cents(input_mos, {1, 0})
	local dark_min_in_cents = mos.dark_gen_to_cents(input_mos, {1, 0})
	local dark_max_in_cents = mos.dark_gen_to_cents(input_mos, {1, 1})
	
	local section_header = p.annotate_section_header(input_mos, "Generator size")
	local section_entries = {
		{section_header},
		{"[[Bright]]", string.format("%s to %s (%.1f{{c}} to %.1f{{c}})", bright_min_in_steps, bright_max_in_steps, bright_min_in_cents, bright_max_in_cents)},
		{"[[Dark]]"  , string.format("%s to %s (%.1f{{c}} to %.1f{{c}})", dark_min_in_steps, dark_max_in_steps, dark_min_in_cents, dark_max_in_cents)},
	}
	
	return section_entries
end

-- Helper function
-- Produces section entries for tamnams info
-- Conditions for tamnams info inclusion:
-- - Scale is octave-equivalent.
-- - Scales within the "named range" (6-10 notes, or is 1L 1s or 2L 2s) have
--   a tamnams name.
-- - Scales with a notecount greater than 10 and no more than 5 periods have
--   a tamnams-named ancestor.
-- - Scales with a notecount greater than 10 and more than 5 periods don't have
--   a tamnams-named ancestor, but will report what nL ns mos they descend from.
-- Section is returned as a jagged array and return value must be merged into
-- a larger array.
function p.tamnams_information(input_mos)
	local input_mos = input_mos or mos.new(6,6,3)
	
	-- If a mos is octave-equivalent and has 10 or fewer steps, then it has a
	-- tamnams name/prefix/abbrev.
	-- If a mos is octave-equivalent, has more than 10 steps, and is not a root
	-- mos nL ns, then:
	-- - If it has 5 periods or less, then its closest ancestor has a tamnams
	--   name.
	-- - If it has more than 5 periods, then it relates to a root mos nL ns that
	--   has more than 10 steps (ancestor therefore has no tamnams name).
	-- If a mos is not octave-equivalent, then it may have a tamnams name (if
	-- step count is 5 or less; currently unsupported) or not.
	local is_octave_equivalent   = mos.is_octave_equivalent(input_mos)
	local has_tamnams_name       = tamnams.lookup_name(input_mos) ~= nil
	local is_within_named_range  = mos.step_count(input_mos) <= 10
	local is_within_period_count = mos.period_count(input_mos) <= 5
	local is_root_mos = input_mos.nL == input_mos.ns
	
	local section_header = "TAMNAMS information"
	local section_entries = nil
	if is_octave_equivalent and has_tamnams_name then
		section_entries = {
			{string.format("<div style=\"margin-top: 0.6em;\"><b>%s</b></div>", section_header)},
			{"[[TAMNAMS#Mos_pattern_names | Name]]"   , tamnams.lookup_name  (input_mos)},
			{"[[TAMNAMS#Mos_pattern_names | Prefix]]" , tamnams.lookup_prefix(input_mos) .. "-"},
			{"[[TAMNAMS#Mos_pattern_names | Abbrev.]]", tamnams.lookup_abbrev(input_mos)}
		}
	elseif is_octave_equivalent and not has_tamnams_name and not is_root_mos and not is_within_named_range then
		-- Lookup closest named ancestor mos
		local ancestor_mos, ratio_1, ratio_2, generations = tamnams.find_ancestor_info(input_mos)
		
		-- Link to ancestor mos
		local ancestor_link = mos.as_link(ancestor_mos)
		
		-- Lookup step ratio range
		local step_ratio_range = string.format("%s:%s to %s:%s", ratio_1[1], ratio_1[2], ratio_2[1], ratio_2[2])
		local range_name = tamnams.lookup_step_ratio_range(ratio_1, ratio_2)
		local step_ratio_range_entry = range_name == nil and step_ratio_range or string.format("%s (%s)", step_ratio_range, range_name)
		
		local ancestor_name = tamnams.lookup_name(ancestor_mos)
		local ancestor_entry = ancestor_name == nil and ancestor_link or string.format("%s (%s)", ancestor_link, ancestor_name)
		
		section_entries = {
			{string.format("<div style=\"margin-top: 0.6em;\"><b>%s</b></div>", section_header)},
			{"Related to", ancestor_entry},
			{"With tunings", step_ratio_range_entry}
		}
	end
	
	return section_entries
end

-- Helper function
-- Adds a section for scale names
function p.other_names(other_names)
	local other_names = other_names or {"p-chromatic", "hard diatonic"}
	
	local section_header = "Other names"
	
	if #other_names == 0 then
		return nil
	else
		local scale_names = ""
		for i=1, #other_names do
			scale_names = scale_names .. other_names[i]
			if i ~= #other_names then
				scale_names = scale_names .. "<br />"
			end
		end
		
		local section_entries = {
			{string.format("<div style=\"margin-top: 0.6em;\"><b>%s</b></div>", section_header)},
			{"Name(s)", scale_names}
		} 
		return section_entries
	end
end

-- Helper function
-- Produces section for related scales
-- Section is returned as a jagged array and return value must be merged into
-- a larger array.
function p.related_scales(input_mos)
	local input_mos = input_mos or mos.new(5, 2)
	
	-- Produce the mos's relatives
	local parent_mos, sister_mos, soft_child_mos, hard_child_mos, neutral_mos, soft_flought_mos, hard_flought_mos
	parent_mos = mos.parent(input_mos)
	sister_mos = mos.sister(input_mos)
	soft_child_mos, hard_child_mos = mos.children(input_mos)
	neutral_mos = mos.neutralized(input_mos)
	soft_flought_mos, hard_flought_mos = mos.interleaved(input_mos)
	
	-- Produce links to those relatives; parent and sister links have extra
	-- checks to make sure they're valid mosses:
	-- - If the input mos is a root mos (nL ns), then it has no parent
	-- - If the input mos is a root mos, then it's its own sister
	local is_nL_ns = input_mos.nL == input_mos.ns
	local parent_scalesig       = is_nL_ns and "none" or mos.as_link(parent_mos)
	local sister_scalesig       = is_nL_ns and (mos.as_string(input_mos) .. " (self)") or mos.as_link(sister_mos)
	local soft_scalesig         = mos.as_link(soft_child_mos)
	local hard_scalesig         = mos.as_link(hard_child_mos)
	local neutral_scalesig      = mos.as_link(neutral_mos)
	local soft_flought_scalesig = mos.as_link(soft_flought_mos)
	local hard_flought_scalesig = mos.as_link(hard_flought_mos)
	
	local section_header = "Related MOS scales"
	local section_entries = {
		{string.format("<div style=\"margin-top: 0.6em;\"><b>%s</b></div>", section_header)},
		{"[[Operations_on_MOSes#Parent_MOS | Parent]]", parent_scalesig},
		{"[[Operations_on_MOSes#Sister_MOS | Sister]]", sister_scalesig},
		{"[[Operations_on_MOSes#Daughter_MOS | Daughters]]", soft_scalesig .. ", " .. hard_scalesig},
		{"[[Operations_on_MOSes#Neutralization | Neutralized]]", neutral_scalesig},
		{"[[Flought_scale | 2-Flought]]", soft_flought_scalesig .. ", " .. hard_flought_scalesig}
	}
	
	return section_entries
end

-- Helper function
-- Produces simple equal tunings
-- Includes xenpaper links
function p.equal_tunings(input_mos)
	local input_mos = input_mos or mos.new(5, 2)
	
	local bright_gen = mos.bright_gen(input_mos)
	
	local step_ratios = {
		{ 1, 1 },
		{ 4, 3 },
		{ 3, 2 },
		{ 5, 3 },
		{ 2, 1 },
		{ 5, 2 },
		{ 3, 1 },
		{ 4, 1 },
		{ 1, 0 }
	}
	
	local section_header = p.annotate_section_header(input_mos, "Equal tunings")
	local section_entries = {{section_header}}
	
	for i = 1, #step_ratios do
		local step_ratio = step_ratios[i]
		
		local ed_as_string = mos.et_string(input_mos, step_ratio)
		
		local gen_in_steps = mos.bright_gen_to_et_string(input_mos, step_ratio, "")
		local gen_in_cents = mos.bright_gen_to_cents(input_mos, step_ratio)
		
		local step_ratio_name = tamnams.lookup_step_ratio(step_ratio)
		step_ratio_name = step_ratio_name:gsub("^%l", string.upper)
		
		local xenpaper_link = xp.mosstep_pattern_to_xenpaper_link(mos.brightest_mode(input_mos), step_ratios[i], input_mos.equave)
		local caption = string.format("[[%s]] [%s (<span style=\"white-space: nowrap;\">L:s = %d:%d</span>)]", step_ratio_name, xenpaper_link, step_ratio[1], step_ratio[2])
		local text = string.format("[[%s|%s]] (%.1f{{c}})", ed_as_string, gen_in_steps, gen_in_cents)
		
		table.insert(section_entries, { caption, text })
	end

	return section_entries
end

-- New "main" function
function p._infobox_mos(input_mos, other_names_unparsed)
	local input_mos = input_mos or mos.new(4,5,3)
	local other_names_unparsed = other_names_unparsed or ""
	
	local other_names_parsed = tip.parse_entries(other_names_unparsed) or tip.parse_entries(other_names_unparsed, ",")
	
	local sections = {}
	
	-- Keyboard visualization
	local kb_vis = p.kb_vis(input_mos)
	p.concatenate_tables(sections, kb_vis)
	
	-- Scale structure section
	local scale_structure = p.scale_structure(input_mos)
	p.concatenate_tables(sections, scale_structure)
	
	-- Interval range section
	--local step_sizes = p.step_sizes(tuning_parsed)
	--p.concatenate_tables(sections, step_sizes)
	
	-- Generator sizes section
	local gen_sizes = p.generator_sizes(input_mos)
	p.concatenate_tables(sections, gen_sizes)
	
	-- Tamnams info section, if applicable
	local tamnams_info = p.tamnams_information(input_mos)
	if tamnams_info ~= nil then
		p.concatenate_tables(sections, tamnams_info)
	end
	
	-- Other names section, if applicable
	local other_names_section = p.other_names(other_names_parsed)
	if other_names_section ~= nil then
		p.concatenate_tables(sections, other_names_section)
	end
	
	-- Related scales section
	local related_scales = p.related_scales(input_mos)
	p.concatenate_tables(sections, related_scales)
	
	-- Equal tunings section
	local equal_tunings = p.equal_tunings(input_mos)
	p.concatenate_tables(sections, equal_tunings)

	-- Adjacent links
	local adjacent_links = p.adjacent_links(input_mos)
	
	local args = {
		["Adjacent Links"] = adjacent_links,
		["Title"] = mos.as_long_string(input_mos),
		["Rows"] = sections,
	}
	
	return ib._infobox(args)
	--return sections
end

-- Wrapper function
function p.infobox_MOS(frame)
	local args = getArgs(frame)
	
	-- "Scale Signature" is preferred; "Tuning" is supported for legacy purposes
	local unparsed = args["Tuning"] or args["Scale Signature"]
	local input_mos = mos.parse(unparsed)
	local other_names = args["othernames"] or nil
	local debug_mode = yesno(args["debug"], false)
	
	local result = p._infobox_mos(input_mos, other_names)
	if not debug_mode then
		result = result .. p.categorize(input_mos)
	end
	
	return frame:preprocess(result)
end

return p