Wikipedia:Lua/Modul/URIutil/en

Vorlagenprogrammierung	Diskussionen	Lua			Test	Unterseiten
		Modul	Deutsch	English		Modul:	Dokumentation

URIutil – Module with functions for strings in context of resource identifiers. This is not targeting for the subset, which is a locator formed as URL (see URLutil). In fact unique key codes for any kind of documents are covered: DOI, ISBN, ISSN, URN; furthermore some national and other codes like LCCN, GTIN/EAN, DNB, GND, ZDB, assigned by public institutions.

Functions for templates

All functions expect exactly one unnamed parameter (which should be provided to get a meaningful answer). Whitespace ahead and after content is ignored.

The return value is an empty string (“nothing”), if the parameter value does not fulfil the expectations. If there is a result or the query condition is true, at least one visible character will be returned. The result does not begin or end with a space.

coreISSN

7 significant digits of a 8-digit or 13-digit ISSN

formatISBN

Segmentation by hyphens; “X” capitalized.

formatISSN

Segmentation by hyphens; “X” capitalized.

• Optionally: second parameter 8 or 13 for output format; else as got.

isDNBvalid

Is this DNB (also GND, ZDB) identifier formally correct, including check digit?

• GND have at least 9 digits, not former 8 digits SWD and GKD with check digit separated by hyphen.

If a number with up to 7 digits a check digit separated by hyphen is following, a validation by rules before 2012 is tried.

• nothing – if invalid
• number of digits or 2011 – valid

isDOI

Is this a syntactically correct Digital Object Identifier?

• number of organisation – yes
• nothing – if invalid

isEscValid

Are bad percent escapings in attempt?

• nothing – no complaints
• string – objected sequence

isGTINvalid

Is this GTIN (EAN) formally correct, including check digit?

• number of digits
• nothing – if invalid

GTIN are also ISBN-13, ISSN-13 and perhaps one day AV media.

isISBN

Is this a syntactically correct ISBN?

• 10 if 10 digits and hyphens; also terminated by xX
• 13 if 13 digits and hyphens; starting with bookland
• nothing – else

isISBNvalid

Is this a syntactically correct ISBN, including check digit?

• 10 or 13 – yes
• nothing – no

isISSNvalid

Is this ISSN formally correct, including check digit?

• 8 or 13 – yes
• nichts – no

isLCCN

Is this a syntactically correct LCCN?

• string – identified, without separators
• nothing – if invalid

linkDOI

Bracketed external link on DOI resolver

linkISBN

Bracketed external link on Special:Booksources with prefixed keyword ISBN and formatISBN (also when syntactically incorrect)

• Optionally: second parameter 1 permits invalid check digit.
• Optionally: link=0 and nbsp=0

linkISSN

Bracketed external link on data base of periodicals with prefixed keyword ISSN and formatISSN (also when syntactically incorrect)

• Optionally: second parameter 1 permits invalid check digit.
• Optionally: link=0 and nbsp=0

class="plainlinks-print" won’t be issued.

linkURN

Bracketed external link on URN resolver

For the time being not implemented due lack of universal resolver.

mayDOI

isDOI or empty

• Number of organisation – yes
• 0 – empty
• nothing – if invalid

mayISBN

isISBN or empty

• 10 oder 13 – yes
• 0 empty
• nothing – if invalid

mayISSN

isISSNvalid or empty

• 8 oder 13 – yes
• 0 – empty
• nothing – if invalid

mayLCCN

isLCCN or empty

• string – identified, without separators
• 0 – empty
• nothing – if invalid

mayURI

URI in general or empty; no spaces within, isEscValid

• Optionally: second parameter 1 permits ASCII only (no IRI).
• nothing – no complaints
• string – objected sequence

mayURN

Valid URN or empty

• nothing – no complaints
• string – objected sequence

plainISBN

Raw ISBN with digits only (or X); 10 or 13 characters.

Appropriate for Wikipedia:BibRecord.

targetISSN

Bracketed external link on data base of periodicals formatISSN (also when syntactically incorrect)

• Optionally: second parameter 1 permits invalid check digit.

class="plainlinks-print" won’t be issued.

uriDOI

Like linkDOI with prefixed scheme doi:

• Optionally: link=0 – without linking doi: on Digital Object Identifier like doi:

uriURN

Like linkURN with prefixed scheme urn:

Not yet implemented.

failsafe

The Failsafe interface is heading for version management of globally distributed Lua modules. It enables modules equipped with this interface to

• ensure, that a library module required by a template or another module available as local copy does support certain functionality, or complain if not.
• administrate global updating and linking of module codes via Wikidata.

The Failsafe interface is present both at template level and for direct Lua access.

The functions in detail are (not all supported yet completely by every library):

Parameter

Value	Result	current
nothing false	local version ID	»2024-08-05«
Minimal version	version ID required at least date in ISO format It will be compared whether the current local implementation matches this version or later. empty, if minimal version not achieved	2001-01-01 → »2024-08-05« 2099-01-01 → »«
wikidata	version ID of global upstream version ID at Wikidata local, if not found there	»2024-08-05«
item	ID of the Wikidata item empty if not defined	Q19644443
~	Corresponding version ID locally and registered at Wikidata empty, if up to date version ID at Wikidata, if not equal	»«
@	Is the current (module) page linked correctly with Wikidata item? empty, if linked to the item which is supposed Iitem ID, if not
The return value is in template programming empty or under Lua false, otherwis a non-empty string as described.

Optional parameters

link=

The functions link* and uri* link the prefixed keyword/scheme to the assumed enzyclopedic article. The parameter value may specify an alternative page name; or link=0 would suppress linking.

nbsp=

The functions link* will use non breaking space between prefixed keyword and code; but nbsp=0 requests ASCII spaces.

Markup of bad codes

The functions link* and uri* assign class="invalid-ISBN" etc. to invalid codes. This might be utilized by users or gadgets for markup, e.g. a red box around the code.

.invalid-ISBN,
.invalid-ISSN {
   border: solid 2px #FF0000;
}

Examples (test page)

A test page illustrates practical use.

Functions for Lua modules (API)

All functions described above can be used by other modules:

local lucky, URIutil = pcall( require, "Modul:URIutil" )
if type( URIutil ) == "table" then
    URIutil = URIutil()
else
    -- failure; URLutil is the error message
    return "<span class=\"error\">" .. URIutil .. "</span>"
end

Subsequently there are available:

• URIutil.coreISSN( attempt )
• URIutil.formatISBN( attempt )
• URIutil.formatISSN( attempt, achieve )
• URIutil.isDNBvalid( attempt )
• URIutil.isDOI( attempt )
• URIutil.isEscValid( attempt )
• URIutil.isGTINvalid( attempt )
• URIutil.isISBN( attempt )
  • Second return value: table with ISBN components; number with error code
• URIutil.isISBNvalid( attempt )
  • Second return value: table with ISBN components; number with error code
• URIutil.isISSNvalid( attempt )
• URIutil.isLCCN( attempt )
• URIutil.linkDOI( attempt )
• URIutil.linkISBN( attempt, allow, abbr, adhere )
• URIutil.linkISSN( attempt, allow, abbr, adhere )
• URIutil.mayDOI( attempt )
• URIutil.mayISBN( attempt )
• URIutil.mayISSN( attempt )
• URIutil.mayLCCN( attempt )
• URIutil.mayURI( attempt, ascii )
• URIutil.mayURN( attempt )
• URIutil.plainISBN( attempt )
• URIutil.targetISSN( attempt, allow, any1, any2, alert )
• URIutil.uriDOI( attempt )
• URIutil.uriHandle( attempt )
• URIutil.uriURN( attempt, alternate )
• URIutil.failsafe( atleast )

  1. atleast
     optional
     nil or required version or "wikidata" or ~ keyword

  returns: string or false

The input parameters are:

• attempt – string with code

Optional:

• achieve – number 8 or 13 for output format; else as got.
• allow – true permit invalid check digit.
• abbr – true or string will link prefixed abbreviation ISBN/ISSN.
• adhere – true use   instead of ASCII space.
• ascii – true permit ASCII only (no IRI).

If succeeding, most functions return a string, the URIutil.is*() a number or string; on failure always false.

Usage

General library; no limitations.

Dependencies

• Modul:URIutil/config – project dependant adaptions
• Modul:URIutil/isbn – definition of ISBN groups
• Modul:URIutil/urn – definition of URN resolvers

Installation on other WMF projects

Follow the steps:

1. Copy main module Module:URIutil into your project.
   • If possible keep the name URIutil.
   • If another name is required due to conflict or naming convention or non-latin script then choose a different one.
2. Register this module at d:Q19644443.
3. Copy the following sub modules, and keep the chosen root name:
   • /isbn
   • /urn
4. Create optionally a /config and populate according to your needs.
5. Ready.
6. Consider translation of doc page.

Local adaption

Create a /config sub module of your root module for mw.loadData() access and return a table with the following components (strings):

issn

URL pattern for ISSN link

If containing $1 current ISSN will replace that placeholder, otherwise appended.

pmid

URL pattern for PMID link

If containing $1 current PMID will replace that placeholder, otherwise appended.

supportISBN

Page target for article on International Standard Book Number

No link if set to "-".

supportISSN

Page target for article on International Standard Serial Number

No link if set to "-".

supportPMID

Page target for article on PubMed

No link if set to "-".

supportURN

Page target for article on Uniform Resource Name

No link if set to "-".