Modul:Citation/utilities

Dokumentation für das Modul Citation/utilities[Ansicht] [Bearbeiten] [Versionsgeschichte] [Aktualisieren]

Dieses Modul wird auf vielen Seiten benutzt, und Änderungen werden projektweit sofort wahrgenommen. Bitte teste Änderungen vorher im /Sandkasten oder in deinem Benutzernamensraum. Die getestete Änderung sollte dann in einem einzigen Edit auf dieser Seite eingefügt werden. Bitte diskutiere Änderungen zuerst auf der Diskussionsseite bevor du sie implementierst.

Dieses Modul ist getestet und für den projektweiten Gebrauch geeignet. Es kann in Vorlagen benutzt und auf Hilfeseiten erläutert werden. Entwicklungen an dem Modul sollten auf Citation/Test und die Anwendung auf der Spielwiese getestet werden, da wiederholte Trial-and-Error-Edits die Resourcen stark belasten können.

Verwendung

Das Modul stellt gemeinsame Funktionen für das Modul:Citation zur Verfügung.

Versionsbezeichnung auf Wikidata: 2024-06-08

Funktionen

function cu.isSet( param )

liefert true, wenn die Zeichenkette param einen nicht-leeren Wert enthält.

function cu.round( num, decimalPlaces )

liefert die auf decimalPlaces Stellen gerundete Zahl num zurück.

function cu.getNumber( s )

konvertiert eine Zeichenkette in eine Zahl unter Berücksichtigung des in Modul:Citation/i18n spezifizierten Dezimalzeichens ci.texts.decimalPoint. Wenn in der Zeichenkette [sic!] enthalten ist, wird 0 zurückgegeben. Damit wird verhindert, dass eine Zahlenangabe als zu groß und fehlerhaft gekennzeichnet wird.

function cu.addErrorMsg( msg )

fügt eine Fehlermeldung in die intern vorgehaltene Fehlertabelle errorMsgs ein.

function cu.getErrorMsgs()

liefert eine Zeichenkette mit allen in der Fehlertabelle errorMsgs enthaltenen Fehlermeldungen – jede aber nur einmal – zurück.

function cu.getFirst( s, delimiter )

liefert das erste Element einer mit dem Trenner delimiter unterteilten Zeichenkette zurück.

function cu.inArray( tab, val )

liefert true zurück, wenn das Element val in der Tabelle tab enthalten ist.

function cu.getKey( t, list )

liefert das key-Element aus der Tabelle list, die Parameternamen in Übersetzung enthält.

function cu.getArgValue( list, param, args )

liefert einen einzelne Wert aus der Parametertabelle args für den Parameter param zurück. Die Tabelle list wir für die Übersetzung der Parameternamen benötigt.

function cu.parameterCleanup( s )

liefert eine bereinigte Zeichenkette zurück, aus der Steuerzeichen, verschiedene Block-Tags (div, p, br) entfernt und XML- bzw. SGML-Zeichenreferenzen ausgetauscht wurden.

function cu.cleanupPageNumbers( pages )

liefert eine Zeichenkette zurück, in der verschiedene Striche durch den Bindestrich ersetzt wurden.

function cu.coinsCleanup( s )

liefert eine Zeichenkette, in der verschiedene Steuerzeichen, span-Tags, Wiki-Syntax (hauptsächlich Links) entfernt wurden.

function cu.finalCleanup( s )

liefert eine Zeichenkette, in der aufeinander folgende Interpunktionszeichen entfernt wurden.

function cu.makeLink( url, text )

liefert einen Link in Wiki-Syntax.

function cu.encodeHandle( handle )

liefert den URI-encodeten Wert des Parameters handle.

function cu.getDate( aDate, aFormat, errorMsg )

liefert eine formatierte Datumsangabe aus aDate mit dem Format aFormat. Bei fehlerhafter Wandlung wird die Fehlermeldung errorMsg in die interne Fehlertabelle geschrieben.

function cu.hasExtension( url, ext )

liefert true, wenn die Internetadresse url die Dateierweiterung ext besitzt.

function cu.insertItem( tab, s, formatStr )

fügt die formatierte Zeichenkette s in die Tabelle tab ein, wenn sie nicht leer ist.

function cu.insertItem2( tab, s1, s2, formatStr )

fügt eine formatierte Zeichenkette aus den Teilzeichenketten s1 und s2 in die Tabelle tab ein, wenn sie beide nicht leer sind.

function cu.formatItem( s, formatStr )

liefert die formatierte Zeichenkette s, wenn sie nicht leer ist.

function cu.formatItem2( s1, s2, formatStr )

liefert eine formatierte Zeichenkette aus den Teilzeichenketten s1 und s2, wenn sie beide nicht leer sind.

function cu.templateStyles( frame )

stellt die templatestyles für die Vorlagen bereit, die das Modul Modul:Citation benutzen.

function cu.getNbnCheckDigit( urn )

liefert die Prüfziffer für urn:nbn-Identifikatoren der Länder at, ch, de und fi.

function cu.check_UrnNbn( urn )

prüft, ob die urn über die korrekte Prüfziffer verfügt.

Verwendung in anderen Modulen

Dieses Modul ist notwendig für die Ausführung folgender Module. Bei Anpassungen sollte die Funktionstüchtigkeit der folgenden Module geprüft werden. Benutze dazu auch diese Tracking-Kategorie um Fehler zu finden, die sich dann auf Artikel auswirken:

Citation
Modul benötigt das Modul Citation/utilities – Wartungskategorie, in der nochmals alle Module gelistet sind, die von diesem Modul abhängig sind.

Hinweise

Die obige Dokumentation wurde aus der Seite Modul:Citation/utilities/Doku eingefügt. (bearbeiten | Versionsgeschichte) Die Kategorien für dieses Modul sollten in der Dokumentation eingetragen werden. Die Interwiki-Links sollten auf Wikidata eingepflegt werden.
Liste der Unterseiten

-- documentation
local citationUtilities = {
	suite  = 'Citation',
	sub    = 'utilities', 
	serial = '2024-06-08'
}

-- module variable and administration
local cu = {
	moduleInterface = citationUtilities
}

-- module import
-- require( 'strict' )
local ci = require( 'Module:Citation/i18n' )

-- global variable
local errorMsgs = {}

-- helper functions
function cu.isSet( param )
	return param and param ~= '';
end

-- math function round
function cu.round( num, decimalPlaces )
  local mult = 10^( decimalPlaces or 0 )
  return math.floor( num * mult + 0.5 ) / mult
end

-- converts string to number
function cu.getNumber( s )
	if not cu.isSet( s ) then
		return 0
	end
	if s:find( '[sic!]', 1, true ) then
		return 0
	end
	local kb = s:gsub( ci.texts.decimalPoint, '%.' )
	return tonumber( kb ) or 0
end

-- adds error message to array
function cu.addErrorMsg( msg )
	table.insert( errorMsgs, msg )
end

-- make complete message from message array
function cu.getErrorMsgs()
	-- remove duplicates
	for i = #errorMsgs, 1, -1 do
		for j = 1, #errorMsgs - 1, 1 do
			if errorMsgs[ i ] == errorMsgs[ j ] then
				table.remove( errorMsgs, i )
				break
			end
		end
	end

	local result = table.concat( errorMsgs, ' ' )
	if result ~= '' then
		result = result .. ' '
	end
	return result
end

-- get first item of a delimiter-separated list
function cu.getFirst( s, delimiter )
	local at = s:find( delimiter )
	if at then
		s = mw.text.trim( s:sub( 1, at - 1 ) )
	end
	return s
end

-- check if table contains the value
function cu.inArray( tab, val )
	if type( tab ) == 'string' then
		return tab == val
	end

	for index, value in ipairs( tab ) do
		if value == val then
			return true
		end
	end

	return false
end

-- convert values t from list if translated
function cu.getKey( t, list )
    local result = ''
    for key, tab in pairs( list ) do
        if cu.inArray( tab, t ) then
            result = key
            break
        end
    end
    return result
end

-- returns a single value from frame argument table
function cu.getArgValue( list, param, args )
	local value = ''
	if list[ param ] then
		for k, v in ipairs( list[ param ] ) do
			if cu.isSet( args[ v ] ) then
				value = args[ v ]
				break
			end
		end
	end
	return value
end

-- string cleanup
function cu.parameterCleanup( s )
	if not cu.isSet( s ) then
		return s -- nil or '' should be kept
	end

	local orig = s
	-- replace control characters
	s = s:gsub( '[\009\010\013]', ' ' ) -- horizontal tab, line feed, carriage return
	s = s:gsub( '[%z%c]', '' ) -- control characters

	-- remove tags
	s = mw.ustring.gsub( s, '</*br[^/>]*/*>', '' ) -- <br> tag
	s = mw.ustring.gsub( s, '</*p[^/>]*/*>', '' ) -- <p> tag
	s = mw.ustring.gsub( s, '</*div[^/>]*/*>', '' ) -- <div> tag

	if orig ~= s then
		cu.addErrorMsg( ci.texts.wrongChars )
	end

	-- replace character references and entities
	s = mw.text.decode( s, true )
	-- replace characters
	s = mw.ustring.gsub( s, '%.%.%.', '…' )
	s = mw.ustring.gsub( s, '%.%.', '‥' )
	return s:gsub( '%s%s+', ' ' ) -- multiple spaces
end

-- remove illegal chars from pages parameters
function cu.cleanupPageNumbers( pages )
	if not cu.isSet( pages ) then
		return ''
	end

	-- replace dashes with hyphens
	return mw.ustring.gsub( '' .. pages, '[–‒—]', '-' );
end

-- string cleanup before COinS creation
function cu.coinsCleanup( s )
	if not cu.isSet( s ) then
		return ''
	end

	-- replace characters
	s = s:gsub( '\226\128\138', ' ' ); -- hair space
	s = mw.ustring.gsub( s, '[\226\128\141\226\128\139\194\173]', '' );
		-- zero-width joiner, zero-width space, soft hyphen

	-- remove characters: soft hyphen, LTR mark, RTL mark
	for i, value in ipairs( { '', '‎', '‏' } ) do
		s = mw.ustring.gsub( s, value, '' )
	end

	-- replace Wiki syntax
	s = s:gsub( "''+", '' ) -- multiple apostrophes
	s = mw.ustring.gsub( s, '</*span[^/>]*/*>', '' ) -- span tags
	s = mw.ustring.gsub( s, '%[%[[^%[%]]*|([^%[%]]*)%]%]', '%1' ) -- MediaWiki links
	s = mw.ustring.gsub( s, '%[%[([^%[%]]*)%]%]', '%1' )
	s = mw.ustring.gsub( s, '%[%a*:?//[^ ]+%s+([^%]]+)%]', '%1' ) -- web links
	s = mw.ustring.gsub( s, '%[mailto:[^ ]+%s+([^%]]+)%]', '%1' )
	s = mw.ustring.gsub( s, '%[%a*:?//([^%]]+)%]', '%1' )
	s = mw.ustring.gsub( s, '%[mailto:([^%]]+)%]', '%1' )

	return s:gsub( '%s%s+', ' ' ) -- multiple spaces
end

-- remove adjoining punctuation marks etc.
function cu.finalCleanup( s )
	s = s:gsub(	'%.+%.', '.' ):gsub( '%s%s+', ' ' ):gsub( '([,;:])(%s%.+)', '.' )
	for _, replacement in ipairs( ci.replacements ) do
		s = mw.ustring.gsub( s, replacement.s, replacement.r )
	end
	s = s:gsub(	'#b#', '.' ) -- restore bibcode
	return s
end

function cu.makeLink( url, text )
	return mw.ustring.format( '[%s %s]', url, text )
end

function cu.getDate( aDate, aFormat, errorMsg )
	local function formatDate( aDate, aFormat )
		return mw.getContentLanguage():formatDate( aFormat, aDate, true )
	end

	if aFormat == 'R' then
		return aDate
	end

	if aDate ~='' then
		local success, t = pcall( formatDate, aDate, aFormat )
		if success then
			return t
		else
			cu.addErrorMsg( errorMsg )
			return ''
		end
	else
		return ''
	end
end

-- check if url contains the file extension ext
function cu.hasExtension( url, ext )
	ext = '%.' .. ext
	url = url:uupper()
	return url:match( ext .. '$' ) or url:match( ext .. '[%?#]' ) or
		url:match( ext .. '&#035' ); -- &#035 is #
end

function cu.getExtension( url )
	if not cu.isSet( url ) then
		return false
	end
	for i, value in ipairs( { 'PDF', 'DOC', 'DOCX', 'RTF', 'ODT', 'PPT', 'PPTX',
		'XLS', 'XLSX' } ) do
		if cu.hasExtension( url, value ) then
			return value
		end
	end
	return false
end

function cu.insertItem( tab, s, formatStr )
	if cu.isSet( s ) then
		if formatStr then
			table.insert( tab,
				mw.ustring.format( formatStr, s )
			)
		else
			table.insert( tab, s )
		end
	end
end

function cu.insertItem2( tab, s1, s2, formatStr )
	if cu.isSet( s1 ) and cu.isSet( s2 ) then
		if formatStr then
			table.insert( tab,
				mw.ustring.format( formatStr, s1, s2 )
			)
		else
			table.insert( tab, s1 )
			table.insert( tab, s2 )
		end
	end
end

function cu.formatItem( s, formatStr )
	if cu.isSet( s ) then
		if formatStr then
			return mw.ustring.format( formatStr, s )
		else
			return s
		end
	else
		return ''
	end
end

function cu.formatItem2( s1, s2, formatStr )
	if cu.isSet( s1 ) and cu.isSet( s2 ) then
		if formatStr then
			 return mw.ustring.format( formatStr, s1, s2 )
		else
			return s1 .. ' ' .. s2
		end
	else
		return ''
	end
end

function cu.templateStyles( frame )
	return frame:extensionTag( 'templatestyles', '', { src = ci.styleSrc } );
end

-- Check digit estimation for countries at, ch, de, and fi
-- See: https://github.com/bohnelang/URN-Pruefziffer
-- Description of the algorithm: http://www.pruefziffernberechnung.de/U/URN.shtml
function cu.getNbnCheckDigit( urn )
	-- two-digits codes for ascii characters starting from &#45; == '-'
	local code='3947450102030405060708094117############1814191516212223242542262713282931123233113435363738########43'
	local sum = 0
	local pos = 1
	local digit1, digit2, x
	urn = urn:upper():sub( 1, -2 ) -- remove last character
	for i = 1, urn:len() do
		x = 2 * ( urn:byte( i ) - 45 ); -- &#45; == '-' 
		digit1 = tonumber( code:sub( x + 1, x + 1 ) );
		digit2 = tonumber( code:sub( x + 2, x + 2 ) );
		if digit1 == 0 then
			sum = sum + digit2 * pos
			pos = pos + 1
		else
			sum = sum + digit1 * pos + digit2 * ( pos + 1 )
			pos = pos + 2
		end
	end
	return tostring( math.floor( sum / digit2 ) % 10 );
end

function cu.check_UrnNbn( urn )
	urn = urn:gsub( '/fragment/.+$', '' ) -- remove fragment
	return urn:sub( -1 ) == cu.getNbnCheckDigit( urn )
end

return cu