Module:File

Module documentation[ view · edit · history · purge ]

This documentation is transcluded from Module:File/doc.

Scope

File title and file information. If the code here grows beyond a border line, this should be converted to an interface and the processing code should be outsourced.^{[Please clarify – October 2024]}

Usage

Note that an error is thrown if the title can't be constructed (e.g. a title containing invalid characters is supplied) or metadata isn't available (e.g. due to missing file or extraction error). It is your responsibility to catch them; in Lua through pcall(); from Wikitext as {{#iferror: {{#invoke:File|function|file=File:P%bar]baz.qqq}} | meaningful message}}.

From Wikitext

Examples:

{{#invoke:File|woExtension|file=File:Test.C.JpeG}} → Lua error at line 6: attempt to call global 'File' (a nil value).

{{#invoke:File|extension|file=File:Test.C.JpeG}} → Lua error at line 6: attempt to call global 'File' (a nil value).

{{#invoke:File|csExtension|file=File:Test.C.JpeG}} → Script error: The function "csExtension" does not exist.

{{#invoke:File|mime|file=File:DOESNOTEXIST-0a8de8c83.Png}} → Lua error at line 6: attempt to call global 'File' (a nil value). deprecated (but works even if the file does not exist and has no metadata)

{{#invoke:File|mimeType|file=File:DOESNOTEXIST-0a8de8c83.Png}} → Script error: The function "mimeType" does not exist. preferred (but will not work if the file does not exist to parse its metadata)

{{#invoke:File|fileExists|file=File:Commons-logo.png}} → Script error: The function "fileExists" does not exist.

{{#invoke:File|fileExists|file=File:DOESNOTEXIST-0a8de8c83.png}} → Script error: The function "fileExists" does not exist.

{{#invoke:File|fileExistsRelaxed|file=File:Ba[!#llot-sprite.png}} → Script error: The function "fileExistsRelaxed" does not exist.

{{#invoke:File|width|file=File:Commons-logo.png}} → Script error: The function "width" does not exist.

{{#invoke:File|height|file=File:Commons-logo.png}} → Script error: The function "height" does not exist.

{{#invoke:File|dimensions|file=File:Commons-logo.png}} → Script error: The function "dimensions" does not exist.

{{#invoke:File|size|file=File:Commons-logo.png}} → Script error: The function "size" does not exist.

-- Module for handling Media files (Origin: Wikimedia Commons)

-- Helpers
local h = {}
h.getFile = function(f)
	return File( f.args[1] or f.args["file"] or f.args["title"] or mw.title.getCurrentTitle().text )
end
h.getWikiText = function(title, frame)
	return '<html>' .. (frame or mw.getCurrentFrame()):expandTemplate{ title = title, args = {}}:gsub('<nowiki>.*?</nowiki>', '') .. '</html>'
end

local File = function(title)
	local funcs = {}
	-- =p.File("Foo.bar.svg").extension()
	-- @return "svg"
	funcs.extension = function()
		local parts = mw.text.split( title, '.', true )
		return parts[#parts]
	end
	-- =p.File("Foo.bar.svg").woExtension()
	-- Original author: Bawolff at [[Module:FileName]]
	-- @return "Foo.bar"
	funcs.woExtension = function()
		local parts = mw.text.split( title , '.', true )
		local upTo = #parts - 1
		if upTo == 0 then upTo = 1 end
		return table.concat( parts, '.', 1, upTo )
	end
	-- mapping file extensions to MIME-types
	funcs.extensionMap = {
		PNG  = "image/png",
		GIF  = "image/gif",
		SVG  = "image/svg+xml",
		TIFF = "image/tiff",
		TIF  = "image/tiff",
		JPEG = "image/jpeg",
		JPG  = "image/jpeg"
	}
	-- =p.File("Foo.bar.svg").mime()
	funcs.mime = function()
		local extension = funcs.extension():upper()
		return funcs.extensionMap[extension] or "unknown"
	end
	-- =p.File("Foo.bar.tiff").maxthumb()
	funcs.maxthumb = function()
		local mime = funcs.mime()
		if mime == "image/png" then
			return mw.getCurrentFrame():preprocess( '{{LargePNG/limit}}' )
		elseif mime == "image/tiff" or mime == "image/gif" then
			return mw.getCurrentFrame():preprocess( '{{LargeTIFF/limit}}' )
		else
			return 'unknown @Module:File'
		end
	end
	funcs.dateWorkCreated = function(frame)
		local page, htmlparser = 'File:' .. title, require("Module:HTMLParser")
		local ok, html = pcall( h.getWikiText, page, frame )
		if not ok then return nil end
		-- add a root node
		local root = htmlparser.parse(html)
		local tdElem = root('#fileinfotpl_date')
		-- We queried an ID so there should be only one result
		for td in pairs(tdElem) do
			-- We need the next sibling, which doesn't seem to be directly supported by HTMLParser
			-- ... so ask him for the parent <tr> and find the <time> element in it
			local timeElem = td.parent('time')
			for t in pairs(timeElem) do
				return t.attributes['datetime']
			end
		end
	end
	return funcs
end

-- @exports
local p = {}
p.File = File
p.extension = function(frame)
    return h.getFile(frame).extension():lower()
end
p.extensionUpper = function(frame)
    return h.getFile(frame).extension():upper()
end
p.woExtension = function(frame)
	return h.getFile(frame).woExtension()
end
p.mime = function(frame)
    return h.getFile(frame).mime()
end
p.maxthumb = function(frame)
    return h.getFile(frame).maxthumb()
end
p.dateWorkCreated = function(frame)
    return h.getFile(frame).dateWorkCreated() or ''
end

p.runTests = function()
	local toTest = require('Module:File/tests/all')
	for i, t in ipairs(toTest) do
		local f = File(t.fileName)
		local stringResult = ''
		local ret = true
		local results = {
			extension = (t.extension == f.extension():lower()),
			extensionUpper = (t.extensionUpper == f.extension():upper()),
			woExtension = (t.woExtension == f.woExtension()),
			mime = (t.mime == f.mime()),
			maxthumb = (not (tonumber(f.maxthumb()) == nil) == t.maxthumbIsNumber),
			dateWorkCreated = t.dateWorkCreated == f.dateWorkCreated()
		}
		for k, v in pairs(results) do
			stringResult = stringResult .. k .. ': ' .. (v and 'ok    ' or 'failed') .. ' '
			ret = ret and v
		end
		mw.log(i, ret and 'passed' or 'FAILED', t.typeOfFileName, (not ret) and ('\n >>' .. stringResult .. '\n     >> ' .. t.fileName) or '')
	end
end

return p