Module:Annotated link

local getShortDescription = require( 'Module:GetShortDescription' ).main
local getArgs = require( 'Module:Arguments' ).getArgs
local mLang = require( 'Module:Lang' )

local function pipedLink( name, display ) return '[[:' .. name ..  '|' .. display .. ']]' end

local function isEmpty( value ) return value == nil or value == '' end

local function notEmpty( value ) return not isEmpty( value ) end

-- Unescape functionality grabbed from https://stackoverflow.com/a/14899740/1832568
local function unescape( str )
	str = string.gsub( str, '&#(%d+);', string.char )
	str = string.gsub( str, '&#x(%d+);', function( d ) return string.char( tonumber( d, 16 ) ) end )
	return str
end

local function alarmingMessage( message )
	return '<span style="color:#d33">[[Module:AnnotatedLink]] ' .. message .. '.</span>'
		.. '[[Category:Pages displaying alarming messages about Module:AnnotatedLink]]'
end

local function langify( args )
	local lang = args.lang
	local text = args.text
	if isEmpty( lang ) or lang == 'en' then return text end
	return mLang._lang {
		lang,
		text,
		italic = args.italic,
		nocat = args.nocat,
		size = args.size,
		cat = args.cat,
		rtl = args.rtl
	}
end

-- Short descriptions on en Wikipedia should be formatted with an uppercase first letter, but
-- the typical application of this module will require the first character to be lowercase.
-- By default; this module will ensure all the short descriptions retrieved by Module:GetShortDescription are
-- transformed to start with a lowercase first letter, but this may be overridden if required.
local function handleFirstLetterCase( short_description, case )
	if isEmpty( case ) then case = 'lower' end
	return mw.ustring.gsub( short_description, '^([^%d])', function( first_char )
		if case == 'upper' then return mw.ustring.upper( first_char ) end
		return mw.ustring.lower( first_char ) end
	)
end

local function annotatedLink( args )
	local name = args.name
	if isEmpty( name ) then return alarmingMessage( 'requires a page name (including namespace)' ) end
	
	-- In order to handle an attempt to annotate a template link,
	-- already formatted with the likes of {{tl|<template name>}};
	-- unescape name to make sense of braces in lua patern matching.
	name = unescape( name )
	
	if mw.ustring.match( name, '^{%b{}}$' ) then
		-- The possibility to extract useful data exists here: e.g. {{tl*|Template}}.
		return alarmingMessage( 'requires only a page name (including namespace) without markup. ' ..
			'If an attempt is being made to annotate a link to a template, provide only the template name with namespace e.g. "Template:Example"'
		)
	end
	
	-- If a literal link was provided as name; extract the content and apply it to name and display as appropriate.
	local wikilink = mw.ustring.match( name, '^%[%[%s*(.-)%s*%]%]$' )
	if wikilink then
		local link_name, link_display = unpack( mw.text.split( wikilink, '%s*|%s*' ) )
		if link_name then name = link_name end
		if link_display and not args.display then args.display = link_display end
	end
	
	local result
	
	-- Get the short description from Module:GetShortDescription.
	local short_description = getShortDescription( {
		args = {
			objectify_alarm = true,
			lang_italic = args.desc_lang_italic,
			lang_nocat = args.desc_lang_nocat,
			lang_size = args.desc_lang_size,
			lang_cat = args.desc_lang_cat,
			lang_rtl = args.desc_lang_rtl,
			lang_no = args.desc_lang_no,
			fallback = args.fallback,
			prefer = args.prefer,
			only = args.only,
			name = name
		}
	} )
	
	-- If the short_description is an { alarm = message }; return it.
	if type( short_description ) == 'table' then return short_description.alarm end
	
	local is_template = name:match( '^Template:(.+)$' )
	local template_link = args.template_link
	if is_template and template_link ~= 'no' then
		result = '{{' .. pipedLink( name, is_template ) .. '}}'
		if template_link == 'code' then
			result = '<code>' .. result .. '</code>'
		end
	else
		local display = args.display
		if isEmpty( display ) then display = name end
		
		result = langify( {
			lang = args.link_lang,
			text = pipedLink( name, display ),
			italic = args.link_lang_italic,
			nocat = args.link_lang_nocat,
			size = args.link_lang_size,
			cat = args.link_lang_cat,
			rtl = args.link_lang_rtl
		} )
		
		if notEmpty( args.quote ) then result = '"' .. result .. '"' end
		
		local abbr = args.abbr
		if notEmpty( abbr ) then
			result = result .. ' (<abbr'
			local abbr_title = args.abbr_title
			if notEmpty( abbr_title ) then result = result .. ' title="' .. abbr_title .. '"' end
			result = result .. '>' .. abbr .. '</abbr>)'
		end
	end
	
	if isEmpty( result ) then return alarmingMessage( 'could not create a link for "' .. name .. '"' ) end
	
	local aka = args.aka
	if notEmpty( aka ) then
		result = result .. ', also known as ' .. langify( {
			lang = args.aka_lang,
			text = aka,
			italic = args.aka_lang_italic,
			nocat = args.aka_lang_nocat,
			size = args.aka_lang_size,
			cat = args.aka_lang_cat,
			rtl = args.aka_lang_rtl
		} )
	end
	
	local wedge = args.wedge
	if notEmpty( wedge ) then
		result = result .. ', ' .. langify( {
			lang = args.wedge_lang,
			text = wedge,
			italic = args.wedge_lang_italic,
			nocat = args.wedge_lang_nocat,
			size = args.wedge_lang_size,
			cat = args.wedge_lang_cat,
			rtl = args.wedge_lang_rtl
		} )
	end

	if isEmpty( short_description ) then return result end
	
	short_description = handleFirstLetterCase( short_description, args.desc_first_letter_case )
	
	local dash = args.dash
	if isEmpty( dash ) then dash = '&nbsp;–' end
	
	return result .. dash .. ' ' .. short_description
end

local p = {}

function p.main( frame )
	local args = getArgs( frame )
	if isEmpty( args ) then return alarmingMessage( 'could not getArgs' ) end
	return annotatedLink( args )
end

return p
Module:Annotated link

Usage

name

display

quote

abbr

template_link

aka

wedge

dash

desc_first_letter_case

prefix_parentheses

space_cat

Module:GetShortDescription parameters

only

prefer

fallback

Foreign language text

link_lang

aka_lang

wedge_lang
