Module:NVR

From blackwiki
Revision as of 02:06, 4 October 2016 by blackwiki>RP88 (fix comment)
Jump to navigation Jump to search


Summary

This module generates links to ships in the Naval Vessel Register (nvr.navy.mil) database. Intended to be used by:

NVR have adopted a file naming convention based on a ship's hull classification symbol with an appended underscore and some number of digits. The extra digits do not seem to follow an identifiable pattern so the former rules-based system used here no longer works.

To get round the 'new' file format, this version of the module adopts a brute-force mechanism by using a local database that maps a ship's hull classification symbol to its associated NVR file name. The database is two large Lua tables maintained at Module:NVR/data.

Using this module from templates

MakeShipLink

This function returns a link to a ship's page at the Naval Vessel Register website.

Usage:

{{#invoke:NVR|MakeShipLink|id=|title=}}
{{#invoke:NVR|MakeShipLink}} — uses the calling template's parameters

Parameters:

1 or id — the ship's case-insensitive hull classification symbol in one of five forms:
  1. SSBN-659 – the preferred format because it matches the format for hull classification symbols generally used for US Navy ships throughout Wikipedia
  2. SSBN 659
  3. SSBN659
  4. SSBN_659
  5. SSBN_659_1635 – the NVR file name format as of September 2017
There are exceptions. There are three ships listed at the NVR website that do not have hull classification symbols. These are: USS Constitution, USS Maine, and USS Texas. For these three ships, use the ship's name for this parameter. The code word OLDIRON, previously used to identify Constitution is no longer supported.
2 or title — A title or label for the link.

Examples:

{{#invoke:NVR|MakeShipLink|DDG_1000}} produces http://www.nvr.navy.mil/SHIPDETAILS/SHIPSDETAIL_DDG_1000.HTML
{{#invoke:NVR|MakeShipLink|constitution}} produces http://www.nvr.navy.mil/SHIPDETAILS/SHIPSDETAIL_CONSTITUTION.HTML
{{#invoke:NVR|MakeShipLink|maine|USS ''Maine''}} produces USS Maine

MakeServiceCraftLink

This function returns a link to a service craft in the Naval Vessel Register.

Usage:

{{#invoke:NVR|MakeServiceCraftLink|id=|title=}}
{{#invoke:NVR|MakeServiceCraftLink}} — uses the calling template's parameters

Parameters: Parameters:

1 or id — the ship's case-insensitive hull classification symbol in one of five forms:
  1. YTB-760 – the preferred format because it matches the format for hull classification symbols generally used for US Navy ships throughout Wikipedia
  2. YTB 760
  3. YTB760
  4. YTB_760
  5. YTB_760_5292 – the NVR file name format as of September 2017
There are exceptions. NVR has separate pages for some single and some multiple sections of some floating drydocks. For these, this module adopts a convention similarly used by NVR where each section is distinguished by a letter designator; that letter must be appended to the hull classification symbol used in this parameter; see the examples
2 or title — A title or label for the link.

Examples:

{{#invoke:NVR|MakeServiceCraftLink|AFDB-7F}} produces http://www.nvr.navy.mil/SHIPDETAILS/SHIPSDETAIL_AFDB7F.HTML
{{#invoke:NVR|MakeServiceCraftLink|ytb-760}} produces Natick

--[[  
 
This module generates links to ships in the Naval Vessel Register (nvr.navy.mil) database.  
It is used by Template:NVR_url and Template:NVR_SC_url
 
Please do not modify this code without applying the changes first at Module:NVR/sandbox and testing 
at Module:NVR/sandbox/testcases and Module talk:NVR/sandbox/testcases.
 
Authors and maintainers:
* User:RP88
 
]]

local p = {}

-- =======================================
-- === Dependencies ======================
-- =======================================

require('Module:No globals')
local rules = require('Module:NVR/rules') -- get rules for transforming NVR links

-- =======================================
-- === Private Functions =================
-- =======================================

--[[
Generate link to NVR database.
]]
local function nvr_link( url_str, title )
	local link = ''

	if (title == '') then
		link = url_str
	else
		link = '[' .. url_str .. ' ' .. title .. ']'
	end
	
    return link
end


--[[
Generate url to NVR database.
]]
local function nvr_url_using_rules( nvrid, rules )
	local url = ''
	
	-- apply transformation rules and determine base URL to use
	local i = 1
	local done = false
	repeat 
		local rule = rules.rules[i]
		i = i + 1
		if rule == nil then
			done = true
		else
			local method = rule.method
			if method == 'literal' then
				-- if nvirid is identical to a literal then set it to a replacement literal
				if ((rule.match == nil) or (nvrid == rule.match)) then
					if rule.replace ~= nil then
						nvrid = rule.replace
					end
					url = rules.urls[rule.url] or ''
					done = true
				end
			elseif method == 'pattern' then
				-- if nvrid meets matching pattern, replace occurrences of pattern in nvrid per rule
				if ((rule.match == nil) or (mw.ustring.find(nvrid, rule.match) ~= nil)) then
					if rule.replace ~= nil then
						if rule.pattern ~= nil then
							nvrid = mw.ustring.gsub(nvrid, rule.pattern, rule.replace);
						else
							nvrid = rule.replace
						end
					end
					url = rules.urls[rule.url] or ''
					done = true
				end
			elseif method == 'all' then
				-- don't alter nvrid at all
				url = rules.urls[rule.url] or ''
				done = true
			else
				-- skip unrecognized rule
			end
		end
	until done
	
	-- replace '****' in url with transformed nvrid
	url = mw.ustring.gsub(url, "%*%*%*%*", nvrid, 1);

    return url
end


-- =======================================
-- === Public Functions ==================
-- =======================================

--[[
MakeShipLink
 
This function returns a link to a ship in the Naval Vessel Register.
 
Usage:
{{#invoke:NVR|MakeShipLink|1=|title=}}
{{#invoke:NVR|MakeShipLink}} - uses the caller's parameters
 
Parameters
    1, id: The 'file name' portion of the url path (typically the ship's hull designation) without the .HTM/.HTML extension. 
    2, title: A title or label for the link.
]]
function p.MakeShipLink( frame )
	-- if no argument provided than check parent template/module args
	local args = frame.args
	if (args[1]==nil) and (args["id"]==nil) then
		args = frame:getParent().args 
	end
	
	local nvrid = args["id"] or args[1]; 
	local title = args["title"] or args[2];

	local output = p._MakeShipLink(nvrid, title)

	return output
end


--[[
MakeServiceCraftLink
 
This function returns a link to a service craft in the Naval Vessel Register.
 
Usage:
{{#invoke:NVR|MakeServiceCraftLink|1=|title=}}
{{#invoke:NVR|MakeServiceCraftLink}} - uses the caller's parameters
 
Parameters
    1, id: The 'file name' portion of the url path (typically the craft's hull designation) without the .HTM/.HTML extension. 
    2, title: A title or label for the link.
]]
function p.MakeServiceCraftLink( frame )
	-- if no argument provided than check parent template/module args
	local args = frame.args
	if (args[1]==nil) and (args["id"]==nil) then
		args = frame:getParent().args 
	end
	
	local nvrid = args["id"] or args[1]; 
	local title = args["title"] or args[2];

	local output = p._MakeServiceCraftLink(nvrid, title)

	return output
end


--[[
This function returns a link to a ship in the Naval Vessel Register. 

Parameters
	nvrid: The 'file name' portion of the url path (typically the ship's hull designation) without the .HTM/.HTML extension, as a string.
	title: Title for link, set to '' for a bare link without a title.
]]
function p._MakeShipLink( nvrid, title )	
	local output = ''
	local url = ''
	
	-- normalize parameters
	nvrid = mw.text.trim(mw.ustring.upper(nvrid or ''))
	title = mw.text.trim(title or '')
	
	-- create url from nvrid
	url = nvr_url_using_rules(nvrid, rules.ShipRules)
	
	-- create link from url
	output = nvr_link(url, title)
		
	return output
end


--[[
This function returns a link to a service craft in the Naval Vessel Register. 

Parameters
	nvrid: The 'file name' portion of the url path (typically the craft's hull designation) without the .HTM/.HTML extension, as a string.
	title: Title for link, set to '' for a bare link without a title.
]]
function p._MakeServiceCraftLink( nvrid, title )	
	local output = ''
	local url = ''
	
	-- normalize parameters
	nvrid = mw.text.trim(mw.ustring.upper(nvrid or ''))
	title = mw.text.trim(title or '')
	
	-- create url from nvrid
	url = nvr_url_using_rules(nvrid, rules.ServiceCraftRules)
	
	-- create link from url
	output = nvr_link(url, title)
		
	return output
end

return p