Misplaced Pages

Module:Coordinates

Article snapshot taken from Wikipedia with creative commons attribution-sharealike license. Give it a read and then ask your questions in the chat. We can research this topic together.

This is an old revision of this page, as edited by MSGJ (talk | contribs) at 10:57, 10 September 2014 (import coordinates from WikiData, per discussion). The present address (URL) is a permanent link to this revision, which may differ significantly from the current revision.

Revision as of 10:57, 10 September 2014 by MSGJ (talk | contribs) (import coordinates from WikiData, per discussion)(diff) ← Previous revision | Latest revision (diff) | Newer revision → (diff) Module documentation[view] [edit] [history] [purge]
WarningThis Lua module is used on approximately 1,370,000 pages, or roughly 2% of all pages.
To avoid major disruption and server load, any changes should be tested in the module's /sandbox or /testcases subpages, or in your own module sandbox. The tested changes can be added to this page in a single edit. Consider discussing changes on the talk page before implementing them.
ProtectedThis module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing.
This module depends on the following other modules:
CSSThis module uses TemplateStyles:

Note: The code which this module's main function (coord) outputs is directly parsed and/or manipulated by Module:Location map and other functions of this module itself (coord2text and coordinsert). If the structure of the output changes (for example, to use the <mapframe> and <maplink> tags), please update the aforementioned scripts as well.

Using the module with coordinsert

When using the {{Coord}} template inside another template, like an infobox, there may be parameters (like type:airport) which should be added automatically. To do so, do something like this: 

{{#if:{{{coordinates|}}}|{{#invoke:Coordinates|coordinsert|{{{coordinates|}}}|parameter1:value1|parameter2:value2|parameter3:value3…}}|

Do not add more vertical bars | than necessary.

Using the module with coord2text to extract latitude or longitude

Developers maintaining legacy code may need to extract latitude or longitude to use a parameters in other code, or a mathematical expression. The module's "coord2text" function can be used to extract data from the {{Coord}} template. To extract the latitude from a Coord template, use:

{{#invoke:coordinates|coord2text|{{Coord|57|18|22|N|4|27|32|E}}|lat}} → Script error: The function "coord2text" does not exist.

To extract the longitude, use:

{{#invoke:coordinates|coord2text|{{Coord|57|18|22|N|4|27|32|E}}|long}} → Script error: The function "coord2text" does not exist.

Modules using this module directly

Tracking categories

The above documentation is transcluded from Module:Coordinates/doc. (edit | history)
Editors can experiment in this module's sandbox (edit | diff) and testcases (edit | run) pages.
Subpages of this module. 

--[[
This module is intended to replace the functionality of {{Coord}} and related
templates.  It provides several methods, including

{{#Invoke:Coordinates | coord }} : General function formatting and displaying
coordinate values.

{{#Invoke:Coordinates | dec2dms }} : Simple function for converting decimal
degree values to DMS format.

{{#Invoke:Coordinates | dms2dec }} : Simple function for converting DMS format
to decimal degree format.

{{#Invoke:Coordinates | link }} : Export the link used to reach the tools

]]

local math_mod = require( "Module:Math" );
local globalFrame = nil
local coordinates = {};

local current_page = mw.title.getCurrentTitle()
local page_name = mw.uri.encode( current_page.prefixedText, 'WIKI' );
local coord_link = '//tools.wmflabs.org/geohack/geohack.php?pagename=' .. page_name .. '&params='

--]
local function displaytitle (s, notes)
	local l = "]: " .. s
	local co = '<span id="coordinates">' .. l .. notes .. '</span>';
	return '<span style="font-size: small;">' .. co .. '</span>';
end

--]
local function displayinline (s, notes)
	return s .. notes	
end

--]
local function dmsTest (first, second)
	local concatenated = first:upper() .. second:upper();
	
	if concatenated == "NE" or concatenated == "NW" or concatenated == "SE" or concatenated == "SW" or
		concatenated == "EN" or concatenated == "WN" or concatenated == "ES" or concatenated == "WS" then
		return true;
	end
	return false;
end

--]
local function optionalArg(arg, suplement)
	if arg ~= nil and arg ~= "" then
		return arg .. suplement
	end
	return ""
end

--[[
Formats any error messages generated for display
]]
local function errorPrinter(errors)
	local result = ""
	for i,v in ipairs(errors) do
		local errorHTML = '<strong class="error">Coordinates: ' .. v .. '</strong>'
		result = result .. errorHTML .. "<br />"
	end
	return result
end

--[[
Determine the required CSS class to display coordinates

Usually geo-nondefault is hidden by CSS, unless a user has overridden this for himself
default is the mode as specificied by the user when calling the {{coord}} template
mode is the display mode (dec or dms) that we will need to determine the css class for 
]]
local function displayDefault(default, mode)
	if default == "" then
		default = "dec"
	end
	
	if default == mode then
		return "geo-default"
	else
		return "geo-nondefault"
	end
end

--[[
specPrinter

Output formatter.  Takes the structure generated by either parseDec
or parseDMS and formats it for inclusion on Misplaced Pages.
]]
local function specPrinter(args, coordinateSpec)
	local uriComponents = coordinateSpec
	if uriComponents == "" then
		-- RETURN error, should never be empty or nil
		return "ERROR param was empty"
	end
	if args ~= "" and args ~= nil then
		uriComponents = uriComponents .. "&title=" .. mw.uri.encode(coordinateSpec)
	end
	
	local geodmshtml = '<span class="geo-dms" title="Maps, aerial photos, and other data for this location">'
			 .. '<span class="latitude">' .. coordinateSpec .. '</span> '
			 .. '<span class="longitude">' ..coordinateSpec .. '</span>'
			 .. '</span>'

	local lat = tonumber( coordinateSpec ) or 0
	local geodeclat
	if lat < 0 then
		-- FIXME this breaks the pre-existing precision
		geodeclat = coordinateSpec:sub(2) .. "°S"
	else
		geodeclat = (coordinateSpec or 0) .. "°N"
	end

	local long = tonumber( coordinateSpec ) or 0
	local geodeclong
	if long < 0 then
		-- FIXME does not handle unicode minus
		geodeclong = coordinateSpec:sub(2) .. "°W"
	else
		geodeclong = (coordinateSpec or 0) .. "°E"
	end
	
	local geodechtml = '<span class="geo-dec" title="Maps, aerial photos, and other data for this location">'
			 .. geodeclat .. ' '
			 .. geodeclong
			 .. '</span>'

	local geonumhtml = '<span class="geo">'
			 .. coordinateSpec .. '; '
			 .. coordinateSpec
			 .. '</span>'

	local inner = '<span class="' .. displayDefault(coordinateSpec, "dms" ) .. '">' .. geodmshtml .. '</span>'
				.. '<span class="geo-multi-punct">&#xfeff; / &#xfeff;</span>'
				.. '<span class="' .. displayDefault(coordinateSpec, "dec" ) .. '">';

	if args == "" or args == nil then
		inner = inner .. geodechtml 
				.. '<span style="display:none">&#xfeff; / ' .. geonumhtml .. '</span></span>'
	else
		inner = inner .. '<span class="vcard">' .. geodechtml 
				.. '<span style="display:none">&#xfeff; / ' .. geonumhtml .. '</span>'
				.. '<span style="display:none">&#xfeff; (<span class="fn org">'
				.. args .. '</span>)</span></span></span>'
	end

	return '<span class="plainlinks nourlexpansion">' .. 
		'' .. '</span>'
end

--]
local function convert_dec2dms_d(coordinate)
	local d = math_mod._round( coordinate, 0 ) .. "°"
	return d .. ""
end

--]
local function convert_dec2dms_dm(coordinate)	
	coordinate = math_mod._round( coordinate * 60, 0 );
	local m = coordinate % 60;
	coordinate = math.floor( (coordinate - m) / 60 );
	local d = coordinate % 360 .."°"
	
	return d .. string.format( "%02d′", m )
end

--]
local function convert_dec2dms_dms(coordinate)
	coordinate = math_mod._round( coordinate * 60 * 60, 0 );
	local s = coordinate % 60
	coordinate = math.floor( (coordinate - s) / 60 );
	local m = coordinate % 60
	coordinate = math.floor( (coordinate - m) / 60 );
	local d = coordinate % 360 .."°"

	return d .. string.format( "%02d′", m ) .. string.format( "%02d″", s )
end

--[[ 
Helper function, convert decimal latitude or longitude to 
degrees, minutes, and seconds format based on the specified precision.  
]]
local function convert_dec2dms(coordinate, firstPostfix, secondPostfix, precision)
	local coord = tonumber(coordinate)
	local postfix
	if coord >= 0 then
		postfix = firstPostfix
	else
		postfix = secondPostfix
	end

	precision = precision:lower();
	if precision == "dms" then
		return convert_dec2dms_dms( math.abs( coord ) ) .. postfix;
	elseif precision == "dm" then
		return convert_dec2dms_dm( math.abs( coord ) ) .. postfix;
	elseif precision == "d" then
		return convert_dec2dms_d( math.abs( coord ) ) .. postfix;
	end
end

--[[
Convert DMS format into a N or E decimal coordinate
]]
local function convert_dms2dec(direction, degrees_str, minutes_str, seconds_str)
	local degrees = tonumber(degrees_str)
	local minutes = tonumber(minutes_str) or 0
	local seconds = tonumber(seconds_str) or 0
	
	local factor = 1
	direction = direction:gsub('^ *(.-) *$', '%1');
	if direction == "S" or direction == "W" then
		factor = -1
	end
	
	local precision = 0
	if seconds_str ~= nil and seconds_str ~= '' then
		precision = 5 + math.max( math_mod._precision(seconds_str), 0 );
	elseif minutes_str ~= nil and minutes_str ~= '' then
		precision = 3 + math.max( math_mod._precision(minutes_str), 0 );
	else
		precision = math.max( math_mod._precision(degrees_str), 0 );
	end
	
	local decimal = factor * (degrees+(minutes+seconds/60)/60) 
	return string.format( "%." .. precision .. "f", decimal ) -- not tonumber since this whole thing is string based.
end

--[[ 
Checks input values to for out of range errors.
]]
local function validate( lat_d, lat_m, lat_s, long_d, long_m, long_s, source, strong )
	local errors = {};
	lat_d = tonumber( lat_d ) or 0;
	lat_m = tonumber( lat_m ) or 0;
	lat_s = tonumber( lat_s ) or 0;
	long_d = tonumber( long_d ) or 0;
	long_m = tonumber( long_m ) or 0;
	long_s = tonumber( long_s ) or 0;

	if strong then
		if lat_d < 0 then
			table.insert(errors, {source, "latitude degrees < 0 with hemisphere flag"})
		end
		if long_d < 0 then
			table.insert(errors, {source, "longitude degrees < 0 with hemisphere flag"})
		end
		--[[ 
		#coordinates is inconsistent about whether this is an error.  If globe: is
		specified, it won't error on this condition, but otherwise it will.
		
		For not simply disable this check.
		
		if long_d > 180 then
			table.insert(errors, {source, "longitude degrees > 180 with hemisphere flag"})
		end
		]]
	end	
		
	if lat_d > 90 then
		table.insert(errors, {source, "latitude degrees > 90"})
	end
	if lat_d < -90 then
		table.insert(errors, {source, "latitude degrees < -90"})
	end
	if lat_m >= 60 then
		table.insert(errors, {source, "latitude minutes >= 60"})
	end
	if lat_m < 0 then
		table.insert(errors, {source, "latitude minutes < 0"})
	end
	if lat_s >= 60 then
		table.insert(errors, {source, "latitude seconds >= 60"})
	end
	if lat_s < 0 then
		table.insert(errors, {source, "latitude seconds < 0"})
	end
	if long_d >= 360 then
		table.insert(errors, {source, "longitude degrees >= 360"})
	end
	if long_d <= -360 then
		table.insert(errors, {source, "longitude degrees <= -360"})
	end
	if long_m >= 60 then
		table.insert(errors, {source, "longitude minutes >= 60"})
	end
	if long_m < 0 then
		table.insert(errors, {source, "longitude minutes < 0"})
	end
	if long_s >= 60 then
		table.insert(errors, {source, "longitude seconds >= 60"})
	end
	if long_s < 0 then
		table.insert(errors, {source, "longitude seconds < 0"})
	end
	
	return errors;
end

--[[
parseDec

Transforms decimal format latitude and longitude into the a
structure to be used in displaying coordinates
]]
local function parseDec( lat, long, format )
	local coordinateSpec = {}
	local errors = {}
	
	if long == "" or long == nil then
		return nil, {{"parseDec", "Missing longitude"}}
	elseif not tonumber(long) then
		return nil, {{"parseDec", "Longitude could not be parsed as a number: " .. long}}
	end
	
	errors = validate( lat, nil, nil, long, nil, nil, 'parseDec', false );	
	coordinateSpec  = lat;
	coordinateSpec = long;

	local mode = coordinates.determineMode( lat, long );
	coordinateSpec  = convert_dec2dms( lat, "N", "S", mode)  -- {{coord/dec2dms|{{{1}}}|N|S|{{coord/prec dec|{{{1}}}|{{{2}}}}}}}
	coordinateSpec = convert_dec2dms( long, "E", "W", mode)  -- {{coord/dec2dms|{{{2}}}|E|W|{{coord/prec dec|{{{1}}}|{{{2}}}}}}}	
	
	if format ~= "" then
		coordinateSpec.default = format
	else
		coordinateSpec.default = "dec"
	end

	return coordinateSpec, errors
end

--[[
parseDMS

Transforms degrees, minutes, seconds format latitude and longitude 
into the a structure to be used in displaying coordinates
]]
local function parseDMS( lat_d, lat_m, lat_s, lat_f, long_d, long_m, long_s, long_f, format )
	local coordinateSpec = {}
	local errors = {}
	
	lat_f = lat_f:upper();
	long_f = long_f:upper();
	
	-- Check if specified backward
	if lat_f == 'E' or lat_f == 'W' then
		local t_d, t_m, t_s, t_f;
		t_d = lat_d;
		t_m = lat_m;
		t_s = lat_s;
		t_f = lat_f;
		lat_d = long_d;
		lat_m = long_m;
		lat_s = long_s;
		lat_f = long_f;
		long_d = t_d;
		long_m = t_m;
		long_s = t_s;
		long_f = t_f;
	end	
	
	errors = validate( lat_d, lat_m, lat_s, long_d, long_m, long_s, 'parseDMS', true );
	if long_d == nil or long_d == "" then
		return nil, {{"parseDMS", "Missing longitude" }}
	elseif not tonumber(long_d) then
		return nil, {{"parseDMS", "Longitude could not be parsed as a number:" .. long_d }}
	end
	
	if lat_m == nil and lat_s == nil and long_m == nil and long_s == nil and #errors == 0 then 
		if math_mod._precision( lat_d ) > 0 or math_mod._precision( long_d ) > 0 then
			if lat_f:upper() == 'S' then 
				lat_d = '-' .. lat_d;
			end
			if long_f:upper() == 'W' then 
				long_d = '-' .. long_d;
			end	 
			
			return parseDec( lat_d, long_d, format );
		end		
	end   
	
	coordinateSpec  = lat_d.."°"..optionalArg(lat_m,"′") .. optionalArg(lat_s,"″") .. lat_f
	coordinateSpec = long_d.."°"..optionalArg(long_m,"′") .. optionalArg(long_s,"″") .. long_f
	coordinateSpec  = convert_dms2dec(lat_f, lat_d, lat_m, lat_s) -- {{coord/dms2dec|{{{4}}}|{{{1}}}|0{{{2}}}|0{{{3}}}}}
	coordinateSpec = convert_dms2dec(long_f, long_d, long_m, long_s) -- {{coord/dms2dec|{{{8}}}|{{{5}}}|0{{{6}}}|0{{{7}}}}}

	if format ~= "" then
		coordinateSpec.default = format
	else
		coordinateSpec.default = "dms"
	end   

	return coordinateSpec, errors
end

--[[ 
Check the input arguments for coord to determine the kind of data being provided
and then make the necessary processing.
]]
local function formatTest(args)
	local result, errors;
	local primary = false;
	
	if args == "" then
		-- no lat logic
		return errorPrinter( {{"formatTest", "Missing latitude"}} )
	elseif not tonumber(args) then
		-- bad lat logic
		return errorPrinter( {{"formatTest", "Unable to parse latitude as a number:" .. args}} )
	elseif args == "" and args == "" and args == "" then
		-- dec logic
		result, errors = parseDec( args, args, args )
		if result == nil then
			return errorPrinter( errors );
		end			  
		result.param	= table.concat( {args, "_N_", args, "_E_", args } );
	elseif dmsTest(args, args) then
		-- dms logic
		result, errors = parseDMS( args, args, args, args, 
			args, args, args, args, args )
		if args ~= '' then
			table.insert( errors, { 'formatTest', 'Extra unexpected parameters' } );
		end
		if result == nil then
			return errorPrinter( errors );
		end
		result.param = table.concat( { args, args, args, args, args,
			args, args, args, args } , '_' );
	elseif dmsTest(args, args) then
		-- dm logic
		result, errors = parseDMS( args, args, nil, args, 
			args, args, nil, args, args )
		if args ~= '' then
			table.insert( errors, { 'formatTest', 'Extra unexpected parameters' } );
		end
		if result == nil then
			return errorPrinter( errors );
		end
		result.param = table.concat( { args, args, args, args, args,
			args, args } , '_' );
	elseif dmsTest(args, args) then
		-- d logic
		result, errors = parseDMS( args, nil, nil, args, 
			args, nil, nil, args, args )
		if args ~= '' then
			table.insert( errors, { 'formatTest', 'Extra unexpected parameters' } );
		end	
		if result == nil then
			return errorPrinter( errors );
		end
		result.param = table.concat( { args, args, args, args, args } , '_' );
	else
		-- Error
		return errorPrinter( {{"formatTest", "Unknown argument format"}} )
	end
	result.name	 = args
	
	local extra_param = {'dim', 'globe', 'scale', 'region', 'source', 'type'}
	for _, v in ipairs( extra_param ) do
		if (args or '') ~= '' then 
			table.insert( errors, {'formatTest', 'Parameter: "' .. v .. '=" should be "' .. v .. ':"' } );
		end
	end
	
	if #errors == 0 then
		return specPrinter( args, result )	
	else
		return specPrinter( args, result ) .. " " .. errorPrinter(errors) .. ']'; 
	end	
end

--[[
link

Simple function to export the coordinates link for other uses.

Usage:
	{{ Invoke:Coordinates | link }}
	
]]
function coordinates.link(frame)
	return coord_link;
end

--[[
dec2dms

Wrapper to allow templates to call dec2dms directly.

Usage:
	{{ Invoke:Coordinates | dec2dms | decimal_coordinate | positive_suffix | 
		negative_suffix | precision }}
	
decimal_coordinate is converted to DMS format.  If positive, the positive_suffix
is appended (typical N or E), if negative, the negative suffix is appended.  The
specified precision is one of 'D', 'DM', or 'DMS' to specify the level of detail
to use.
]]
function coordinates.dec2dms(frame)
	globalFrame = frame
	local coordinate = frame.args
	local firstPostfix = frame.args
	local secondPostfix = frame.args
	local precision = frame.args

	return convert_dec2dms(coordinate, firstPostfix, secondPostfix, precision)
end

--[[
Helper function to determine whether to use D, DM, or DMS
format depending on the precision of the decimal input.
]]
function coordinates.determineMode( value1, value2 )
	local precision = math.max( math_mod._precision( value1 ), math_mod._precision( value2 ) );
	if precision <= 0 then
		return 'd'
	elseif precision <= 2 then
		return 'dm';
	else
		return 'dms';
	end
end		

--[[
dms2dec

Wrapper to allow templates to call dms2dec directly.

Usage:
	{{ Invoke:Coordinates | dms2dec | direction_flag | degrees | 
		minutes | seconds }}
	
Converts DMS values specified as degrees, minutes, seconds too decimal format.
direction_flag is one of N, S, E, W, and determines whether the output is 
positive (i.e. N and E) or negative (i.e. S and W).
]]
function coordinates.dms2dec(frame)
	globalFrame = frame
	local direction = frame.args
	local degrees = frame.args
	local minutes = frame.args
	local seconds = frame.args

	return convert_dms2dec(direction, degrees, minutes, seconds)
end

--[[
coord

Main entry point for Lua function to replace {{coord}}

Usage:
	{{ Invoke:Coordinates | coord }}
	{{ Invoke:Coordinates | coord | lat | long }}
	{{ Invoke:Coordinates | coord | lat | lat_flag | long | long_flag }}
	...
	
	Refer to {{coord}} documentation page for many additional parameters and 
	configuration options.
	
Note: This function provides the visual display elements of {{coord}}.  In
order to load coordinates into the database, the {{#coordinates:}} parser 
function must also be called, this is done automatically in the Lua
version of {{coord}}.
]]
function coordinates.coord(frame)
	globalFrame = frame
	local args = frame.args
	local pFrame = frame:getParent();
	if args == nil then
		args = pFrame.args;
		if pFrame.args ~= nil then
			for k,v in pairs( frame.args ) do
				args = v;
			end
		elseif pFrame.args == nil and mw.wikibase.getEntityObject() ~= nil then
			local entity = mw.wikibase.entity.create( mw.wikibase.getEntityObject() )
			if entity and entity.claims and entity.claims.P625 and 
			entity.claims.P625.mainsnak.snaktype == "value" then
				args = entity.claims.P625.mainsnak.datavalue.value.latitude
				args = entity.claims.P625.mainsnak.datavalue.value.longitude
			end
		end
	end
	
	for i=1,10 do 
		if args == nil then 
			args = ""
		else
			args = string.match(args, '^%s*(.-)%s*$' );  --remove whitespace
		end		
	end
	args = args or '';
	
	local contents = formatTest(args)
	local Notes = args.notes or ""
	local Display = string.lower(args.display or "inline")
	if Display == '' then
		Display = 'inline';
	end
	
	local text = ''
	if string.find( Display, 'inline' ) ~= nil
		or Display == 'i'
		or Display == 'it'
		or Display == 'ti'
	then
		-- Coordinates are displayed inline.
		text = displayinline(contents, Notes)
	end
	if string.find( Display, 'title' ) ~= nil
		or Display == 't' 
		or Display == 'it'
		or Display == 'ti'
	then
		-- Coordinates are displayed in the title.
		text = text .. displaytitle(contents, Notes)
		-- Add a Wikidata category for mainspace pages.
		if mw.wikibase and current_page.namespace == 0 then
			local wikidata_cat
			local entity = mw.wikibase.getEntity()
			if entity and entity.claims and entity.claims.p625 then
				local snaktype = entity.claims.p625.mainsnak.snaktype
				if snaktype == 'value' then
					wikidata_cat = ']' -- coordinates exist both here and on Wikidata, and can be compared
				elseif snaktype == 'somevalue' then
					wikidata_cat = ']'
				elseif snaktype == 'novalue' then
					wikidata_cat = ']'
				end
			else
				wikidata_cat = ']' -- we have to either import the coordinates to Wikidata or remove them here
			end
			if wikidata_cat then
				text = text .. wikidata_cat
			end
		end
	end

	return text
end

return coordinates
Categories: