Module:WikidataIB

From Encyclopedia of Buddhism
Jump to: navigation, search

This module is designed specifically to implement a mechanism which moves control of whether Wikidata values are used in an infobox from the template coder at the infobox design level to the editor at the article level. It should only be used inside an infobox.

One of the sandboxes at Module:WikidataIB/sandbox, Module:WikidataIB/sandbox1 or Module:WikidataIB/sandbox2 should be used for testing anything other than trivial amendments.

Test cases for the main module can be found at Module talk:WikidataIB/testing.

Test cases for the sandboxes are at Module talk:WikidataIB/sandbox/testing and Module talk:WikidataIB/sandbox1/testing.

Overview

The module provides these calls specifically for use in infoboxes at present:

  1. getValue
    getSourcedValue - obsoleted; use getValue instead.
  2. getPreferredValue
  3. getNormalValue
  4. getCoords
  5. getQualifierValue

The obsolete call getSourcedValue is now removed as it is redundant to getValue which can do the same job using the |onlysourced=true parameter.

There are also these utility calls:

  1. getLink
  2. getLabel
  3. getAT
  4. formatDate
  5. checkBlacklist
  6. emptyor

Generalised calls:

{{#invoke:WikidataIB |getValue |<PropertyID> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no> |noicon=<yes/no> |df=<dmy/mdy/y> |bc=<BC/BCE> |<local parameter>}}
{{#invoke:WikidataIB |getPreferredValue |<PropertyID> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no> |noicon=<yes/no> |df=<dmy/mdy/y> |bc=<BC/BCE> |<local parameter>}}
{{#invoke:WikidataIB |getSourcedValue |<PropertyID> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |<local parameter>}}
{{#invoke:WikidataIB |getCoords |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |<local parameter>}}
{{#invoke:WikidataIB |getQualifierValue |<PropertyID> |pval=<ID of target value for the property> |qual=<qualifier ID for that target value> |name=<fieldname> |suppressfields=<list of fields which will never display> |fetchwikidata=<list of fields to fetch values from Wikidata> |onlysourced=<yes/no>}}

Function details

Function getValue

  • getValue can also take a named parameter |qid= which is the Wikidata ID for the article. This will not normally be used but is available for testing, although it makes the call expensive.
  • The property to be returned is passed in the first unnamed property.
  • The name of the field that this function is called from is passed in the named parameter |name=, which is first checked against a blacklist of fields that are never to be displayed, (i.e. the call must return nil in all circumstances). If the field is not on the blacklist, it is then checked against a whitelist. If the name of the field matches, the call will return any locally supplied value if it is supplied as the second unnamed parameter, or the Wikidata value otherwise.
  • The name is compulsory when the blacklist or whitelist is used, so the module returns nil if it is not supplied.
  • The blacklist is passed in the named parameter |suppressfields=
  • The whitelist is passed in the named parameter |fetchwikidata=

The getValue function will accept a boolean parameter onlysourced which will suppress return of Wikidata values that are unsourced or only sourced to Wikipedia. The absence of the parameter, an empty parameter (|onlysourced=) and the empty string ("") all default to true (i.e. only referenced values are returned). The values no, false and 0 are treated as false (i.e. all values are returned); any other value is true (although |onlysourced=yes is recommended for readability).

The getValue function will accept a boolean parameter noicon which will suppress the trailing "edit at Wikidata" icon for when the returned value is to be further processed by the infobox (e.g. a url). The absence of the parameter or an empty parameter (|noicon=) default to false (i.e. the icon is added). The empty string ("") and the values no, false and 0 are treated as false; any other value is true (although |noicon=true is recommended for readability).

In order to handle the requirement for dates in mdy, dmy or just year formats, getValue accepts a named parameter |df= that may take the values "dmy", "mdy", or "y" - default is "dmy".

As an article may require either of suffixes BC and BCE, getValue accepts a named parameter |bc= that may take the values "BC", or "BCE" - default is "BCE". Some test cases are shown at Module talk:WikidataIB/testing #Calls to getValue for dates.

Specific value-type handlers

The module has specific handlers for the following data types:

  1. Items that correspond to an article in some Wikipedia, called "wikibase-items". These will be linked to the corresponding (and disambiguated) article on English Wikipedia where possible.
  2. Items that represent dates.
  3. Items that represent Commons media, urls, external ids, or other sorts of plain text.

Items that represent other types of data are returned using the mwdiawiki library call formatPropertyValues().

The third class of data types may be used with the parameters:

  • |prefix=, |postfix=, |linkprefix=, |linkpostfix=

If you don't supply |linkprefix=, then just |prefix= and |postfix= are used. For example, when getting the [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P717)] in [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q532127)]:

  • {{#invoke:WikidataIB/sandbox|getValue|P717|fetchwikidata=ALL|onlysourced=no |prefix="before " |postfix=" after" |qid=Q532127}}Script error: No such module "WikidataIB/sandbox".

Use double-quotes to enclose the parameter value if it has leading or trailing spaces (otherwise they are stripped out). If you supply |linkprefix=, then all four parameters are used and a link is made for each value like this:

  • [[ linkprefix WikidataValue1 linkpostfix | prefix WikidataValue1 postfix]], [[ linkprefix WikidataValue2 linkpostfix | prefix WikidataValue2 postfix]], etc.

That allows multiple links to be made to different sections of a list article, such as List of observatory codes. For example, when getting the [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P717)] in [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q532127)] we can make the links:

  • {{#invoke:WikidataIB/sandbox|getValue|P717|fetchwikidata=ALL|onlysourced=no |prefix= |postfix= |linkprefix="List of observatory codes#" |linkpostfix= |qid=Q532127}}Script error: No such module "WikidataIB/sandbox".

Formatting multiple returned values

  • |sorted=<yes|no> is a boolean passed to enable sorting of the values returned. No parameter, or an empty string, or "false", or "no", or "0" disables sorting. It's only a very dumb alphabetical sort and sorts linked values as "[[ ..."
  • |sep=<separator characters> allows the separator between multiple returned values to be defined. The default is ", " (comma plus normal space). If the separator has leading or trailing spaces, enclose it in double quotes (e.g. |sep=" - "). Any double quotes are stripped from the separator. The pipe character (|) must be escaped as {{!}}. For reasons of accessibility (see MOS:PLIST), do not use |sep=<br> for vertical unbulleted lists; use |list=ubl instead.
  • |list=<hlist|ubl> allows multiple returned values to be displayed as a horizontal list (|list=hlist), or a vertical unbulleted list (|list=ubl). These override the separator and do not display the 'pen icon' linked to "Edit at Wikidata"

Function getPreferredValue

The getPreferredValue function works exactly like getValue, taking the same parameters, but if any values for a property have the preferred rank set, it will only return those values.

Function getNormalValue

The getNormalValue function complements getPreferredValue, taking the same parameters, but if any values for a property have the normal rank set, it will only return those values.

If a property has a mixture of preferred and normal ranks set, these functions will separate them.

Comparison example

Fetching the name(s) of the [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P170)] from [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q29016906)]:

  • {{#invoke:WikidataIB |getValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}Lua error at line 248: attempt to index field 'wikibase' (a nil value).
  • {{#invoke:WikidataIB |getPreferredValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}Lua error at line 248: attempt to index field 'wikibase' (a nil value).
  • {{#invoke:WikidataIB |getNormalValue |P170 |fetchwikidata=ALL |qid=Q29016906 |onlysourced=no}}Lua error at line 248: attempt to index field 'wikibase' (a nil value).

Function getCoords

  • getCoords can also take a named parameter |qid= which is the Wikidata ID for the article. This will not normally be used but is available for testing, although it makes the call expensive.
  • The coordinates from Wikidata are parsed and passed to Template:Coord which returns the display as if it were called manually.
  • The name of the field that this function is called from is passed in the named parameter |name=, which is first checked against a blacklist of fields that are never to be displayed, (i.e. the call must return nil in all circumstances). If the field is not on the blacklist, it is then checked against a whitelist. If the name of the field matches, the call will return any locally supplied value if it is supplied as the unnamed parameter, or the Wikidata value otherwise.
  • The name is compulsory when the blacklist or whitelist is used, so the module returns nil if it is not supplied.
  • The blacklist is passed in the named parameter |suppressfields=
  • The whitelist is passed in the named parameter |fetchwikidata=

Function getQualifierValue

The getQualifierValue is for use when we want to fetch the value of a qualifier. We need to know the property and the value of the property that it qualifies. The parameters are:

  • The property ID passed in the unnamed parameter (or |1=)
  • The target value for that property in |pval=
  • The qualifier ID for that target value in |qual=
  • The name of the field where its called from to implement whitelisting and blacklisting of the property in
  • The list of fields to be fetched ("whitelist") in |fetchwikidata= - accepts |fetchwikidata=ALL to fetch all fields
  • Optional list of fields not to be displayed ("blacklist") in |suppressfields=
  • Optional boolean to specify whether only sourced values of the property are returned (defaults to "no") in |onlysourced=
  • Optional item ID for arbitrary access (expensive call!) in |qid=

Example of getQualifierValue

In [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q1513315)] there is a property [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P793)], which has a value [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q385378)]. That has two qualifiers, [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P580)] and [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P582)]. To get the start date:

  • {{#invoke:WikidataIB |getQualifierValue |P793 |pval=Q385378 |qual=P580 |name=xyz |fetchwikidata=ALL }}

In South Pole Telescope it returns:

  • Lua error at line 248: attempt to index field 'wikibase' (a nil value).

Function getLink

getLink returns the label for a Qid wiki-linked to the local article (if the article exists). If label doesn't exist, it returns the Qid wiki-linked to the local article (if the article exists).

Wikidata: [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q29016906)] and [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q3621491)]
  • {{#invoke:WikidataIB |getLink |Q29016906}}Lua error at line 718: attempt to index field 'wikibase' (a nil value).
  • {{#invoke:WikidataIB |getLink |Q3621491}}Lua error at line 718: attempt to index field 'wikibase' (a nil value).

Function getLabel

getLabel returns the label for a Qid. If label doesn't exist, it returns the Qid. Note that this is the label given to the Wikidata entry in the same language as the current Wikipedia, if the label exists.

Wikidata: [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q29016906)] and [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q3621491)]
  • {{#invoke:WikidataIB |getLabel |Q29016906}}Lua error at line 180: attempt to index field 'wikibase' (a nil value).
  • {{#invoke:WikidataIB |getLabel |Q3621491}}Lua error at line 180: attempt to index field 'wikibase' (a nil value).

Function getAT

getAT returns the article title for a Qid. If the article title doesn't exist, it returns nothing. Note that this is the title of the article in the current Wikipedia, if the interlanguage link exists in the Wikidata entry.

Wikidata: [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q29016906)] and [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q3621491)]
  • {{#invoke:WikidataIB |getAT |Q29016906}}Lua error at line 746: attempt to index field 'wikibase' (a nil value).
  • {{#invoke:WikidataIB |getAT |Q3621491}}Lua error at line 746: attempt to index field 'wikibase' (a nil value).

Function formatDate

formatDate accepts a datetime of the usual format from mw.wikibase.entity:formatPropertyValues, like "1 August 30 BCE" as parameter 1 and formats it according to the df (date format) and bc parameters.

  • {{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BCE |df=dmy}} → 1 August 30 BCE
  • {{#invoke:WikidataIB |formatDate | 1 August 30 BCE |bc=BC |df=mdy}} → August 1, 30 BC
  • df = "dmy" / "mdy" / "y" - default is "dmy"
  • bc = "BC" / "BCE" - default is "BCE"

Coding into an infobox

Typically, the getValue call will be invoked in an infobox definition, using appropriate template parameters. One simple implementation is given as an example in Template:Infobox book/Wikidata/Sandbox. As an illustration, the 'author' field in the infobox is coded like this:

| label2  = Author{{#if:{{{authors|}}}|s}}
|  data2  = {{#invoke:WikidataIB |getValue |P50 |name=author |fetchwikidata={{{fetchwikidata|}}} |suppressfields={{{suppressfields|}}} |{{{authors|{{{author|}}}}}} }}

The property to be fetched is the first unnamed parameter. In this case it is [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (P50)].

The name of the field is passed in |name= and that name is checked against the blacklist and the whitelist. To always suppress the author field in a particular article, an editor will set |suppressfields=author in the infobox. The author field will then never be displayed.

If the field is not blacklisted, then the infobox can be set to display a locally supplied value for author simply by setting |author=George Orwell, for example, in the infobox. It also accepts |authors=. If the name of the field is on the whitelist, e.g. |fetchwikidata=author; genre; pub_date; pages; dewey; congress, and the local value is not supplied, then the infobox will display the value retrieved from Wikidata. Any separators can be used, except | and {}.

As a shorthand, |fetchwikidata=ALL will fetch all of the fields that are not blacklisted, as long as no local value is already provided in the article for a given field.

Since Wikidata labels are normally lower case, the sentence case function from Module:String2 can be used to capitalise the first letter of the returned text, e.g.

  • {{#invoke:String2 | sentence | {{#invoke:WikidataIB |getValue |P136 |name=genre |fetchwikidata=ALL |onlysourced=false}} }} in [Lua error in Module:Wikibase at line 27: attempt to index field 'wikibase' (a nil value). Lua error in Module:Wikibase at line 40: attempt to index field 'wikibase' (a nil value). (Q1396889)] produces:
  • Script error: No such module "String2".

Example of calls in an infobox

Basic use of getValue:

  • {{#invoke:WikidataIB |getValue |P000 |name=fieldname |qid={{{qid|}}} |fetchwikidata={{{fetchwikidata|}}} |onlysourced={{{onlysourced|}}} |{{{localparameter|}}} }}

Full collection of parameters:

  • {{#invoke:WikidataIB |getValue |P000 |name=fieldname |qid={{{qid|}}} |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |onlysourced={{{onlysourced|}}} |noicon={{{noicon|}}} |wdl={{{wikidatalink|}}} |df={{dateformat|}} |bc={{{bc|}}} |prefix= |postfix= |linkprefix= |linkpostfix= |sorted={{{sorted|}}} |sep={{{separator|}}} |list={{listtype|}}} |{{{localparameter|}}} }}

Any of the parameters can, of course, be be fixed for a given field in an infobox, rather than taking the parameter supplied to the infobox, which will affect all fields. For example, one field may set |list=hlist where a series of short words is expected; whereas another field could use |list=ubl where an unbulleted vertical list of several words on each line is required.

Coodinates

The getCoords call will display the output of Template:Coord when supplied with the coordinates returned from Wikidata. It can be coded like this:

|label20 = Coordinates
| data20 = {{#invoke:WikidataIB |getCoords |name=coordinates |suppressfields={{{suppressfields|}}} |fetchwikidata={{{fetchwikidata|}}} |{{{coordinates|}}} }}

An example is Template:Infobox biosphere reserve

{{Infobox biosphere reserve
| fetchwikidata = ALL
}}

Displays coordinates in the usual positions when used in an article where Wikidata has coordinates.

Upgrading existing infoboxes

Since the parameter |fetchwikidata= is needed for any Wikidata functionality, an existing infobox may be replaced by an infobox incorporating these calls without any change whatsoever to any article. Each article using the new infobox can later be enabled by supplying |fetchwikidata=ALL, or a list of required fields for that article. At that point, the onus is on the editor enabling the functionality to check that no unwanted fields are now being displayed. If so, they can be added to a blacklist for the article by setting |suppressfields= to the list of unwanted fields.

Verifiability

Where it will always be essential for a particular field to only contain values that are referenced, use getValue, making sure that |onlysourced= is not set to 'false', '0' or 'no'. By default it will exclude values that are unsourced or only sourced to a Wikipedia, thus making the job of checking easier at the article level. If unsourced data is acceptable (!), set |onlysourced=no. As it is beyond my wit to produce an automated mechanism that knows whether an existing source is reliable or not in a given context, that job must still be performed at the article level by an editor familiar with the subject. It should always be done when first enabling Wikidata for that article.

Example of use: Infobox book

This section is taken from Template:Infobox book/Wikidata/Sandbox/doc.

No Wikidata

{{Infobox book/Wikidata/Sandbox
| suppressfields =
| fetchwikidata  =
| name           = Animal Farm
| title_orig     = Animal Farm: A Fairy Story
| image          = Animal Farm - 1st edition.jpg
| image_size     = 200px
| caption        = First edition cover
| author         = [[George Orwell]]
| country        = United Kingdom
| language       = English
| genre          = Political satire
}}

Works as a non-aware infobox: only locally supplied parameters are displayed.

{{Infobox book/Wikidata/Sandbox
| name           = Animal Farm
| title_orig     = Animal Farm: A Fairy Story
| image          = Animal Farm - 1st edition.jpg
| image_size     = 200px
| caption        = First edition cover
| author         = [[George Orwell]]
| country        = United Kingdom
| language       = English
| genre          = Political satire
}}

The blacklist and whitelist can be omitted if unused

All Wikidata

{{Infobox book/Wikidata/Sandbox
| fetchwikidata  = author; genre; pub_date; pages; dewey; congress
}}

Fetches the author, publication date, number of pages, Dewey index, and Library of Congress catalogue number values from Wikidata.

{{Infobox book/Wikidata/Sandbox
| fetchwikidata  = ALL
}}

As shorthand, the |fetchwikidata= parameter can be set to ALL to fetch all available fields. Any field can be suppressed by naming it in |suppressfields=, or overridden by supplying a local value.

Never display genre

{{Infobox book/Wikidata/Sandbox
| suppressfields = genre
| fetchwikidata  = author; genre; pub_date; pages; dewey; congress
}}

The genre field will always be suppressed, even if a local value is supplied.

{{Infobox book/Wikidata/Sandbox
| suppressfields = genre
| fetchwikidata  = author; genre; pub_date; pages; dewey; congress
| genre          = Political satire
}}

Local override

{{Infobox book/Wikidata/Sandbox
| fetchwikidata  = author; genre; pub_date; pages; dewey; congress
| genre          = Political satire
}}

The genre field is set to display "Political satire", no matter what is stored in Wikidata.

{{Infobox book/Wikidata/Sandbox
| fetchwikidata  = ALL
| genre          = Novel
}}

The genre field is set to display "Novel", no matter what is stored in Wikidata.

Don't fetch genre

{{Infobox book/Wikidata/Sandbox
| suppressfields = 
| fetchwikidata  = author; pub_date; pages; dewey; congress
}}

The genre field will not be fetched from Wikidata. Only the author, publication date, number of pages, Dewey index, and Library of Congress catalogue number are imported. A local value for genre will display.

See also


-- Module to implement use of a blacklist and whitelist for infobox fields
-- can take a named parameter |qid which is the Wikidata ID for the article. This will not normally be used
-- Fields in blacklist are never to be displayed, i.e. module must return nil in all circumstances
-- Fields in whitelist return local value if it exists or the Wikidata value otherwise
-- The name of the field that this function is called from is passed in named parameter |name
-- The name is compulsory when blacklist or whitelist is used, so the module returns nil if it is not supplied
-- blacklist is passed in named parameter |suppressfields
-- whitelist is passed in named parameter |fetchwikidata

local p = {}

local i18n =
{
	["errors"] =
	{
		["property-not-found"] = "Property not found.",
		["entity-not-found"] = "Wikidata entity not found.",
		["unknown-claim-type"] = "Unknown claim type.",
		["unknown-entity-type"] = "Unknown entity type.",
		["qualifier-not-found"] = "Qualifier not found.",
		["site-not-found"] = "Wikimedia project not found.",
		["unknown-datetime-format"] = "Unknown datetime format.",
		["local-article-not-found"] = "Article is available on Wikidata, but not on Wikipedia"
	},
	["months"] =
	{
		"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
	},
	["century"] = "century",
	["BC"] = "BC",
	["BCE"] = "BCE",
	["ordinal"] =
	{
		[1] = "st",
		[2] = "nd",
		[3] = "rd",
		["default"] = "th"
	},
	["filespace"] = "File",
	["editonwikidata"] = "Edit this on Wikidata",
	["latestdatequalifier"] = function (date) return "before " .. date end,
	-- some languages, e.g. Bosnian use a period as a suffix after each number in a date
	["datenumbersuffix"] = "",
	["abbr"] =
	{
		["Q828224"]  = "km",
		["Q11573"]   = "m",
		["Q174728"]  = "cm",
		["Q174789"]  = "mm",
		["Q712226"]  = "sq km",
		["Q11570"]   = "kg",
		["Q41803"]   = "g",
		["Q3241121"] = "mg",
		["Q2332346"] = "ml",
	},
}

require("Module:i18n").loadI18n("Module:WikidataIB/i18n", i18n)


-------------------------------------------------------------------------------
-- Private functions
-------------------------------------------------------------------------------
--
-------------------------------------------------------------------------------
-- makeOrdinal needs to be internationalised along with the above:
-- takes cardinal numer as a numeric and returns the ordinal as a string
-- we need three exceptions in English for 1st, 2nd, 3rd, 21st, .. 31st, etc.
local function makeOrdinal (cardinal)
	local ordsuffix = i18n.ordinal.default
	if cardinal % 10 == 1 then
		ordsuffix = i18n.ordinal[1]
	elseif cardinal % 10 == 2 then
		ordsuffix = i18n.ordinal[2]
	elseif cardinal % 10 == 3 then
		ordsuffix = i18n.ordinal[3]
	end
	-- In English, 1, 21, 31, etc. use 'st', but 11, 111, etc. use 'th'
	-- similarly for 12 and 13, etc.
	if (cardinal % 100 == 11) or (cardinal % 100 == 12) or (cardinal % 100 == 13) then
		ordsuffix = i18n.ordinal.default
	end
	return tostring(cardinal) .. ordsuffix
end


-------------------------------------------------------------------------------
-- roundto takes a positive number (x)
-- and returns it rounded to (sf) significant figures
local function roundto(x, sf)
	if x == 0 then return 0 end
	x = math.abs(x)
	if sf < 1 then sf = 1 end
	local e = math.floor(math.log10(x)) - sf + 1
	local m = math.floor(x / 10^e + 0.5)
	x = m * 10^e
	-- if it's integral, cast to an integer:
	if  x == math.floor(x) then x = math.floor(x) end
	return x
end


-------------------------------------------------------------------------------
-- formatDate takes a datetime of the usual format from mw.wikibase.entity:formatPropertyValues
-- like "1 August 30 BCE" as parameter 1 and formats it according to the df (date format) and bc parameters
-- df = ["dmy" / "mdy" / "y"] default will be "dmy"
-- bc = ["BC" / "BCE"] default will be "BCE"
-- first the local version
local format_Date = function(datetime, dateformat, bc)
	local datetime = datetime or "1 August 30 BCE" -- in case of nil value
	-- chop off multiple vales and/or any hours, mins, etc.
	-- keep anything before punctuation - we just want a single date:
	local dateval = string.match( datetime, "[%w ]+")

	local dateformat = string.lower(dateformat or "dmy") -- default to dmy

	local bc = string.upper(bc or "") -- can't use nil for bc
	-- we only want to accept two possibilities: BC or default to BCE
	if bc == "BC" then
		bc = "&nbsp;" .. i18n["BC"] -- prepend a non-breaking space.
	else
		bc = "&nbsp;" .. i18n["BCE"]
	end

	local postchrist = true -- start by assuming no BCE
	local dateparts = {}
	for word in string.gmatch(dateval, "%w+") do
		if word == "BCE" or word == "BC" then -- **internationalise later**
			postchrist = false
		else
			-- we'll keep the parts that are not 'BCE' in a table
			dateparts[#dateparts + 1] = word
		end
	end
	if postchrist then bc = "" end -- set AD dates to no suffix **internationalise later**

	local sep = "&nbsp;" -- separator is nbsp
	local fdate = table.concat(dateparts, "&nbsp;") -- formatted date defaults to same order as input

	-- if we have day month year, check dateformat
	if #dateparts == 3 then
		if dateformat == "y" then
			fdate = dateparts[3]
		elseif dateformat == "mdy" then
			fdate = dateparts[2] .. sep .. dateparts[1] .. "," .. sep .. dateparts[3]
		end
	elseif #dateparts == 2 and dateformat == "y" then
		fdate = dateparts[2]
	end

	return fdate .. bc
end


-------------------------------------------------------------------------------
-- parseParam takes a (string) parameter, e.g. from the list of frame arguments,
-- and makes "false", "no", and "0" into the (boolean) false
-- it makes the empty string and nil into the (boolean) value passed as default
-- allowing the parameter to be true or false by default.
local parseParam = function(param, default)
	if param and param ~= "" then
		param = param:lower()
		if (param == "false") or (param == "no") or (param == "0") then
			return false
		else
			return true
		end
	else
		return default
	end
end


-------------------------------------------------------------------------------
-- The label in a Wikidata item is subject to vulnerabilities
-- that an attacker might try to exploit.
-- It needs to be 'sanitised' by removing any wikitext before use.
-- If it doesn't exist, just return the id for the item
local labelOrId = function (id)
	local label = mw.wikibase.label(id)
	if label then
		return mw.text.nowiki(label)
	else
		return id
	end
end


-------------------------------------------------------------------------------
-- sourced takes a table representing a statement that may or may not have references
-- it counts how many references are sourced to something not contianing the word "wikipedia"
-- the reference string "ref" is available for debugging
-- it returns a boolean = true if there are any sourced references.
local sourced = function(claim)
	local refs = 0
	if claim.references then
		for kr, vr in pairs(claim.references) do
			local ref = mw.wikibase.renderSnaks(vr.snaks)
			if not ref:find("Wikipedia") then refs = refs + 1 end
		end
	end
	return refs > 0
end


-- parseInput processes the Q-id , the blacklist and the whitelist
-- if an input parameter is supplied, it returns that and ends the call.
-- it returns a boolean indicating whether or not the call should continue
-- and an object containing all of the Wikidata for the Qid supplied or the current page
local parseInput = function(frame, input_parm, property_id)
	-- There may be a local parameter supplied, if it's blank, set it to nil
	local input_parm = mw.text.trim(input_parm or "")
	if input_parm == "" then input_parm = nil end

	-- can take a named parameter |qid which is the Wikidata ID for the article.
	-- This will not normally be used because it's an expensive call.
	local args = frame.args
	local qid = args.qid
	if qid == "" then qid = nil end

	-- The blacklist is passed in named parameter |suppressfields
	local blacklist = args.suppressfields or args.spf

	-- The whitelist is passed in named parameter |fetchwikidata
	local whitelist = args.fetchwikidata or args.fwd

	-- The name of the field that this function is called from is passed in named parameter |name
	local fieldname = args.name
	if blacklist then
		-- The name is compulsory when blacklist is used, so return nil if it is not supplied
		if not fieldname or fieldname == "" then return false, nil, nil end
		-- If this field is on the blacklist, then return nil
		if blacklist:find(fieldname) then return false, nil, nil end
	end

	-- If we got this far then we're not on the blacklist
	-- The blacklist overrides any locally supplied parameter as well
	-- If a non-blank input parameter was supplied return it
	if input_parm then return false, input_parm, nil end

	-- Otherwise see if this field is on the whitelist:
	if not (whitelist and (whitelist == 'ALL' or whitelist:find(fieldname))) then
		-- not on the whitelist so just return what should be a nil input parameter
		return false, input_parm, nil
	end

	-- See what's on Wikidata:
	local entity = mw.wikibase.getEntityObject(qid)
	if entity and entity.claims then
		local props = entity.claims[property_id]
		if props and props[1] then
			return true, entity, props
		end
	end
	-- no property on Wikidata
	return false, input_parm, nil
end


local function _getvalue(frame, entity, props, filter, propertyID)
	-- onlysourced is a boolean passed to return only values sourced to other than Wikipedia
	-- if nothing or an empty string is passed set it true
	-- if "false" or "no" or "0" is passed set it false
	local args = frame.args
	local onlysrc = parseParam(args.onlysourced or args.osd, true)

	-- noicon is a boolean passed to suppress the trailing "edit at Wikidata" icon
	-- for use when the value is processed further by the infobox
	-- if nothing or an empty string is passed set it false
	-- if "false" or "no" or "0" is passed set it false
	local noic = parseParam(args.noicon, false)

	-- wdlinks is a boolean passed to enable links to Wikidata when no article exists
	-- if nothing or an empty string is passed set it false
	-- if "false" or "no" or "0" is passed set it false
	local wdl = parseParam(args.wdlinks or args.wdl, false)

	-- sorted is a boolean passed to enable sorting of the values returned
	-- if nothing or an empty string is passed set it false
	-- if "false" or "no" or "0" is passed set it false
	local sorted = parseParam(args.sorted, false)

	-- sep is a string that is used to separate multiple returned values
	-- if nothing or an empty string is passed set it to the default
	-- any double-quotes " are stripped out, so that spaces may be passed
	-- e.g. |sep=" - "
	local sepdefault = ", " -- **internationalise later**
	local separator = args.sep or ""
	separator = string.gsub(separator, '"', '')
	if #separator == 0 then
		separator = sepdefault
	end

	-- list is the name of a template that a list of multiple values is passed through
	-- examples include "hlist" and "ubl"
	local list = args.list or ""

	-- prefix is a string that may be nil, empty (""), or a string of characters
	-- this is prefixed to each value
	-- useful when when multiple values are returned
	-- any double-quotes " are stripped out, so that spaces may be passed
	local prefix = args.prefix or ""
	prefix = string.gsub(prefix, '"', '')

	-- postfix is a string that may be nil, empty (""), or a string of characters
	-- this is postfixed to each value
	-- useful when when multiple values are returned
	-- any double-quotes " are stripped out, so that spaces may be passed
	local postfix = args.postfix or ""
	postfix = string.gsub(postfix, '"', '')

	-- linkprefix is a string that may be nil, empty (""), or a string of characters
	-- this creates a link and is then prefixed to each value
	-- useful when when multiple values are returned and indirect links are needed
	-- any double-quotes " are stripped out, so that spaces may be passed
	local lprefix = args.linkprefix or ""
	lprefix = string.gsub(lprefix, '"', '')

	-- linkpostfix is a string that may be nil, empty (""), or a string of characters
	-- this is postfixed to each value when linking is enabled with lprefix
	-- useful when when multiple values are returned
	-- any double-quotes " are stripped out, so that spaces may be passed
	local lpostfix = args.linkpostfix or ""
	lpostfix = string.gsub(lpostfix, '"', '')

	-- maxvals is a string that may be nil, empty (""), or a number
	-- this determines how many items may be returned when multiple values are available
	-- setting it = 1 is useful where the returned string is used within another call, e.g. image
	local maxvals = tonumber(args.maxvals) or 0

	-- unitabbr is a boolean passed to enable unit abbreviations for common units
	-- if nothing or an empty string is passed set it false
	-- if "false" or "no" or "0" is passed set it false
	local uabbr = parseParam(args.unitabbr, false)

	-- So now we have something to return: deal with:
	-- (1) ["datatype"] = "wikibase-item";
	-- (2) ["datatype"] = "time";
	-- (3) ["datatype"] = "commonsMedia",
	--     ["datatype"] = "external-id",
	--     ["datatype"] = "string",
	--     ["datatype"] = "url"
	-- (4) ["datatype"] = "globe-coordinate", or anything else

	local lang = mw.language.getContentLanguage().code
	local thisQid = entity.id
	-- table 'out' is going to to store the return value(s):
	local out = {}
	local icon = " [[" .. i18n["filespace"] .. ":Blue pencil.svg |frameless |text-top |10px |alt=" .. i18n["editonwikidata"] .. "|link=https://www.wikidata.org/wiki/" .. thisQid .. "?uselang=" .. lang .. "#" .. propertyID .. "|" .. i18n["editonwikidata"] .. "]]"
	local datatype = props[1].mainsnak.datatype
	for k, v in pairs(props) do
		local datavalue = v.mainsnak.datavalue
		datavalue = datavalue and datavalue.value
		if (not filter(v)) or (onlysrc and not sourced(v)) then
			-- do nothing; either isn't preferred when prefered values are requested, or isn't sourced when onlysourced=true
		elseif v.mainsnak.snaktype == "somevalue" then -- check for value is unknown
			out[#out + 1] = "Unknown"
		elseif v.mainsnak.snaktype == "novalue" then -- check for value is none
			-- out[#out + 1] = "No value" -- don't return a value for this
		-- data type is a wikibase item:
		elseif datatype == "wikibase-item" then
			-- it's wiki-linked value, so output as link if possible
			local qnumber = "Q" .. datavalue["numeric-id"]
			local sitelink = mw.wikibase.sitelink(qnumber)
			local label = labelOrId(qnumber)
			if sitelink then
				out[#out + 1] = "[[" .. lprefix .. sitelink .. lpostfix .. "|" .. label .. "]]"
			else
				-- no sitelink, so check first for a redirect with that label
				local artitle = mw.title.new(label, 0)
				if artitle.id > 0 then
					if artitle.isRedirect then
						-- no sitelink, but there's a redirect with the same title as the label
						-- let's link to that
						out[#out + 1] = "[[".. lprefix .. label .. lpostfix .. "|" .. label .. "]]"
					else
						-- no sitelink and not a redirect but an article exists with the same title as the label
						-- that's probably a dab page, so output the plain label
						out[#out + 1] = label
					end
				else
					-- no article or redirect with the same title as the label
					if wdl then
						-- show that there's a Wikidata entry available
						out[#out + 1] = "[[:d:Q" .. datavalue["numeric-id"] .. "|" .. label .. "]]&nbsp;<span title='" .. i18n["errors"]["local-article-not-found"] .. "'>[[File:Wikidata-logo.svg|16px|alt=|link=]]</span>"
					else
						-- no wikidata links required, so just give the plain label
						out[#out + 1] = label
					end
				end
			end
			-- If the property has a qualifier of latest date, add that in all cases:
			if v.qualifiers then
				local quals = v.qualifiers["P1326"] -- latest date qualifier
				if quals then
					out[#out] = out[#out] .. " (" .. i18n.latestdatequalifier(mw.wikibase.renderSnaks(quals)) .. ")"
				end
			end
		-- data type is time:
		elseif datatype == "time" then
			-- it's a date value, so output according to formatting preferences
			local timestamp = datavalue.time
			-- A year can be stored like this: "+1872-00-00T00:00:00Z",
			-- which is processed here as if it were the day before "+1872-01-01T00:00:00Z",
			-- and that's the last day of 1871, so the year is wrong.
			-- So fix the month 0, day 0 timestamp to become 1 January instead:
			timestamp = timestamp:gsub("%-00%-00T", "-01-01T")
			local dateprecision = datavalue.precision
			local fpvdate = tonumber(timestamp:sub(2, 5))
			local fdate
			if dateprecision >= 9 then -- 9 is year precision
				local dateformat = "y"
				if dateprecision >= 10 then -- prepend month
					fpvdate = i18n.months[tonumber(timestamp:sub(7, 8))] .. " " .. fpvdate
					dateformat = args.df
					if dateprecision >= 11 then -- prepend day
							fpvdate = tonumber(timestamp:sub(10, 11)) .. " " .. fpvdate
					end
					if timestamp:sub(1, 1) == "-" then
						fpvdate = fpvdate .. " BCE"
					end
				end
				fdate = format_Date(fpvdate, dateformat, args.bc)
			elseif dateprecision == 7 then -- century
				local century = math.floor((fpvdate - 1) / 100) + 1
				fdate = makeOrdinal(century) .. "&nbsp;" .. i18n["century"]
				if timestamp:sub(1, 1) == "-" then -- date is BC
					local bc = string.upper(args.bc or "") -- can't use nil for bc
					-- we only want to accept two possibilities: BC or default to BCE
					if bc == "BC" then
						fdate = fdate .. "&nbsp;" .. i18n["BC"] -- use non-breaking space.
					else
						fdate = fdate .. "&nbsp;" .. i18n["BCE"]
					end
				end
			else
				-- date precisions 0 to 6 (billion years to millenium) TODO:
				--
			end
			out[#out+1] = fdate
		-- data types which are strings:
		elseif datatype == "commonsMedia" or datatype == "external-id" or datatype == "string" or datatype == "url" then
			-- commonsMedia or external-id or string or url
			-- all have mainsnak.datavalue.value as string
			if lprefix ~= "" then
				out[#out+1] = "[[" .. lprefix .. datavalue .. lpostfix .. "|" .. prefix .. datavalue .. postfix .. "]]"
			else
				out[#out+1] = prefix .. datavalue .. postfix
			end -- check for link requested
		-- data types which are quantities:
		elseif datatype == "quantity" then
			-- quantities have mainsnak.datavalue.value.amount and mainsnak.datavalue.value.unit
			-- the unit is of the form http://www.wikidata.org/entity/Q829073
			-- convert amount to a number
			local amount = tonumber(datavalue.amount) or "Not a number"
			-- check if upper and/or lower bounds are given and significant
			local upb = tonumber(datavalue.upperBound)
			local lowb = tonumber(datavalue.lowerBound)
			if upb and lowb then
				-- differences rounded to 2 sig fig:
				local posdif = roundto(upb - amount, 2)
				local negdif = roundto(amount - lowb, 2)
				if posdif ~= negdif then
					-- non-symmetrical
					amount = amount .. " +" .. posdif .. " -" .. negdif
				elseif posdif ~= 0 then
					-- symmetrical and significant
					amount = amount .. " ±" .. posdif
				end
				-- otherwise range is zero, so leave it off: amount = amount
			end
			-- extract the qid in the form 'Qnnn' from the value.unit url and then fetch the label from that
			local unit = ""
			local unitqid = string.match( datavalue.unit, "(Q%d+)" )
			if unitqid then
				if uabbr and i18n.abbr[unitqid] then
					-- it's on the list of common abbreviations, so use that
					unit = "&nbsp;" .. i18n.abbr[unitqid]
				else
					-- otherwise use the label (i.e. unit name) if it exists
					local uname = mw.wikibase.label( unitqid )
					if uname then unit = " " .. uname end
				end
			end
			out[#out+1] = amount .. unit
		else
			-- some other data type
			-- e.g. globe-coordinate where mainsnak.datavalue.value is a table
			-- either write a specific handler
			-- or we can use formatPropertyValues() as a temporary measure. This won't work with multiple valid values.
			out[#out+1] = entity:formatPropertyValues(propertyID).value
			break
		end -- of datatype/unknown value/sourced check
		if maxvals > 0 and #out >= maxvals then break end
	end -- of for each value loop

	-- if there's anything to return, then return a list
	-- comma-separated by default, but may be specified by the sep parameter
	-- optionally specify a hlist or ubl
	if #out > 0 then
		if sorted then table.sort(out) end
		-- if there's a pen icon add it the end of the last value
		if not noic then
			out[#out] = out[#out] .. icon
		end
		if list == "" then
			return table.concat(out, separator)
		else
			return frame:expandTemplate{title = list, args = out}
		end
	else
		return nil -- no items had valid reference
	end
end



-------------------------------------------------------------------------------
-- Public functions
-------------------------------------------------------------------------------
--
-- getValue is used to get a value, or a comma separated list of them if multiple values exist
--

p.getValue = function(frame)
	local propertyID = mw.text.trim(frame.args[1] or "")

	local success, errorOrEntity, props = parseInput(frame, frame.args[2], propertyID)
	if not success then
		return errorOrEntity
	end
	local function filter(claim)
		return true
	end
	return _getvalue(frame, errorOrEntity, props, filter, propertyID)
end


-------------------------------------------------------------------------------
-- getPreferredValue is used to get a value, or a comma separated list of them if multiple values exist
-- If preferred ranks are set, it will return those values, otherwise values with normal ranks
--
p.getPreferredValue = function(frame)
	local propertyID = mw.text.trim(frame.args[1] or "")

	local success, errorOrEntity, props = parseInput(frame, frame.args[2], propertyID)
	if not success then
		return errorOrEntity
	end
	local prefflag = false
	for k, v in pairs(props) do
		if v.rank == "preferred" then
			prefflag = true
			break
		end
	end
	local function filter(claim)
		return claim.rank == "preferred" or prefflag == false
	end
	return _getvalue(frame, errorOrEntity, props, filter, propertyID)
end


-------------------------------------------------------------------------------
-- getNormalValue is used to get a value, or a comma separated list of them if multiple values exist
-- If normal ranks are set, it will return those values, otherwise all values
--
p.getNormalValue = function(frame)
	local propertyID = mw.text.trim(frame.args[1] or "")

	local success, errorOrEntity, props = parseInput(frame, frame.args[2], propertyID)
	if not success then
		return errorOrEntity
	end
	local normflag = false
	for k, v in pairs(props) do
		if v.rank == "normal" then
			normflag = true
			break
		end
	end
	local function filter(claim)
		return claim.rank == "normal" or normflag == false
	end
	return _getvalue(frame, errorOrEntity, props, filter, propertyID)
end

-------------------------------------------------------------------------------
-- getCoords is used to get coordinates for display in an infobox
-- whitelist and blacklist are implemented
-- optional 'display' parameter is allowed, defaults to "inline, title"
--
p.getCoords = function(frame)
	local propertyID = "P625"

	-- if there is a 'display' parameter supplied, use it
	-- otherwise default to "inline, title"
	local disp = frame.args.display
	if not disp or disp == "" then
		disp = "inline, title"
	end

	local success, errorOrEntity = parseInput(frame, frame.args[1], propertyID)
	if not success then
		return errorOrEntity
	else
		local entity = errorOrEntity
		local lat_long = {}
		local coords = entity:formatPropertyValues(propertyID).value
		-- the latitude and longitude are returned like this: nn°nn&#39;nn.n&#34;
		-- using html entities with hex values really screws up parsing the numbers - thanks devs
		local lat = mw.ustring.match(coords, "^[^,]*")  -- everything from the start to before the comma
		local long = mw.ustring.match(coords, "[^ ]*$") -- everything from after the space to the end
		lat = lat:gsub("&#%d%d;", ":")                  -- clean out the html entities
		long = long:gsub("&#%d%d;", ":")                -- clean out the html entities
		-- read the latitude numbers into a table
		for num in mw.ustring.gmatch(lat, "%d+%.?%d*") do
			lat_long[#lat_long + 1] = num
		end
		-- add the N/S
		lat_long[#lat_long + 1] = lat:sub(-1)
		-- read the longitude numbers into a table
		for num in mw.ustring.gmatch(long, "%d+%.?%d*") do
			lat_long[#lat_long + 1] = num
		end
		-- add E/W for long
		lat_long[#lat_long + 1] = long:sub(-1)
		-- add named parameter for display
		lat_long["display"] = disp
		-- invoke template Coord with the values stored in the table
		return frame:expandTemplate{title = 'coord', args = lat_long}
	end
end


-------------------------------------------------------------------------------
-- getQualifierValue is used to get a formatted value of a qualifier
--
-- The call needs:	a property (the unnamed parameter or 1=)
-- 					a target value for that property (pval=)
--					a qualifier for that target value (qual=)
-- The usual whitelisting and blacklisting of the property is implemented
-- The boolean onlysourced= parameter can be set to return nothing
-- when the property is unsourced (or only sourced to Wikipedia)
--
p.getQualifierValue = function(frame)
	local args = frame.args
	local propertyID = mw.text.trim(args[1] or "")

	-- The PropertyID of the target value of the property
	-- whose qualifier is to be returned is passed in named parameter |pval=
	local propvalue = args.pval

	-- The PropertyID of the qualifier
	-- whose value is to be returned is passed in named parameter |qual=
	local qualifierID = args.qual

	-- onlysourced is a boolean passed to return qualifiers
	-- only when property values are sourced to something other than Wikipedia
	-- if nothing or an empty string is passed set it false
	-- if "false" or "no" or 0 is passed set it false
	local onlysrc = parseParam(args.onlysourced, false)


	local success, errorOrEntity, props = parseInput(frame, args[2], propertyID)
	if not success then
		return errorOrEntity
	else
		local entity = errorOrEntity
		-- Scan through the values of the property
		-- we want something like property is P793, significant event (in propertyID)
		-- whose value is something like Q385378, construction (in propvalue)
		-- then we can return the value(s) of a qualifier such as P580, start time (in qualifierID)
		for k1, v1 in pairs(props) do
			if v1.mainsnak.snaktype == "value" and v1.mainsnak.datavalue.type == "wikibase-entityid" then
				-- It's a wiki-linked value, so check if it's the target (in propvalue)
				-- and if it has qualifiers
				if v1.mainsnak.datavalue.value.id == propvalue and v1.qualifiers then
					if (onlysrc == true) and not sourced(v1) then
						return
					end
					-- if we've got this far, we have a (sourced) claim with qualifiers
					-- which matches the target, so find the value(s) of the qualifier we want
					local quals = v1.qualifiers[qualifierID]
					local out = {}
					if quals then
						if quals[1].datatype == "wikibase-item" then
							for k2, v2 in pairs(quals) do
								local valueID = v2.datavalue.value.id
								local sitelink = mw.wikibase.sitelink(valueID)
								local label = labelOrId(valueID)
								if sitelink then
									out[#out + 1] = "[[" .. sitelink .. "|" .. label .. "]]"
								else
									out[#out + 1] = "[[:d:" .. valueID .. "|" .. label .. "]]&nbsp;<span title='" .. i18n["errors"]["local-article-not-found"] .. "'>[[File:Wikidata-logo.svg|16px|alt=|link=]]</span>"
								end
							end
							return table.concat(out, ", ")
						else
							return mw.wikibase.renderSnaks(quals)
						end
					end
				end
			end -- of loop through values of propertyID
		end
	end
	return nil
end


-------------------------------------------------------------------------------
-- getLink returns the label for a Qid wiki-linked to the local article (if the article exists)
-- if label doesn't exist, it returns the Qid wiki-linked to the local article (if the article exists)
--
p.getLink = function(frame)
	local itemID = mw.text.trim(frame.args[1] or "")
	if itemID == "" then return end
	local sitelink = mw.wikibase.sitelink(itemID)
	local label = labelOrId(itemID)
	if sitelink then
		return "[[" .. sitelink .. "|" .. label .. "]]"
	else
		return label
	end
end


-------------------------------------------------------------------------------
-- getLabel returns the label for a Qid
-- if label doesn't exist, it returns the Qid
--
p.getLabel = function(frame)
	local itemID = mw.text.trim(frame.args[1] or frame.args.qid or "")
	if itemID == "" then return end
	return labelOrId(itemID)
end


-------------------------------------------------------------------------------
-- getAT returns the article title for a Qid
-- or nothing if it doesn't exist
--
p.getAT = function(frame)
	local itemID = mw.text.trim(frame.args[1] or frame.args.qid or "")
	if itemID == "" then return end
	return mw.wikibase.sitelink(itemID)
end


-------------------------------------------------------------------------------
-- getDescription returns the article description for a Qid
-- Qid defaults to the current article if omitted
-- Any local parameter supplied (other than "Wikidata") becomes the return value
-- Nothing is returned if the description doesn't exist or 'none' is passed locally
--
p.getDescription = function(frame)
	local desc = mw.text.trim(frame.args[1] or "")
	local itemID = mw.text.trim(frame.args.qid or "")
	if itemID == "" then itemID = nil end
	if desc:lower() == 'wikidata' then
		return mw.wikibase.description(itemID)
	elseif desc:lower() == 'none' then
		return nil
	else
		return desc
	end
end


-------------------------------------------------------------------------------
-- formatDate is a wrapper to export the private function format_Date
--
p.formatDate = function(frame)
	return format_Date(frame.args[1], frame.args.df, frame.args.bc)
end


-------------------------------------------------------------------------------
-- checkBlacklist allows a test to check whether a named field is suppressed
-- {{#if:{{#invoke:WikidataIB |checkBlacklist |name=Joe |suppressfields=Dave; Joe; Fred}} | not blacklisted | blacklisted}}
-- displays "blacklisted"
-- {{#if:{{#invoke:WikidataIB |checkBlacklist |name=Jim |suppressfields=Dave; Joe; Fred}} | not blacklisted | blacklisted}}
-- displays "not blacklisted"
--
p.checkBlacklist = function(frame)
	local blacklist = frame.args.suppressfields
	local fieldname = frame.args.name
	if blacklist and fieldname then
		if blacklist:find(fieldname) then return nil end
		return true
	end
end


-------------------------------------------------------------------------------
-- emptyor returns nil if its first unnamed argument is just punctuation, whitespace or html tags
-- otherwise it returns the argument unchanged (including leading/trailing space)
-- unless the argument may contain "=" when it must be called explicitly:
-- |1=arg
-- (when leading/trailing spaces are trimmed)
p.emptyor = function(frame)
	local s = frame.args[1]
	if not s or s == "" then return nil end
	local sx = s:gsub("%s", ""):gsub("<[^>]*>", ""):gsub("%p", "")
	if sx == "" then
		return nil
	else
		return s
	end
end

return p