Module:Statement/sandbox/doc

This subpage contains documentation, categories, or other content that is not part of the module.
To view the module page itself, see Module:Statement/sandbox.

---

This module is rated as alpha. It is ready for third-party input, and may be used on a few pages to see if problems arise, but should be watched. Suggestions for new features or changes in their input and output mechanisms are welcome.

This module contains functions to deal with a single statement or qualifier in structured data, whether the data comes from Wikidata or Structured Data on Commons. It can be used where you expect a property to only have a single value. If you need to support multiple statements or qualifiers for the same property ID, use a different module (such as Module:Wikidata statements) or write your own.

The module can be used both by other modules and directly from wikitext.

The module only uses best-rank statements: the preferred-rank statements (called “prominent” in Structured Data on Commons) if there are any, otherwise the normal-rank statements. Deprecated-rank statements are never used, even if they’re the only ones.

(This module is unrelated to {{Statement}}, a template to show a representation of a statement encoded in Wikitext.)

Example

Example usage from Wikitext, getting the audio transcription (P9533) of the current file:

Recording of the word/phrase <q>{{#invoke:Statement/sandbox|monolingualText|P9533}}</q>.

Example usage from Lua, doing the same thing (nil signifies the current file as the source of the statement):

local wikitext = require( 'Module:Statement/sandbox' ).monolingualText( nil, 'P9533' )
return 'Recording of the word/phrase <q>' .. wikitext .. '</q>.'

On File:LL-Q188 (deu)-Natschoba-die Freiheit.wav, the result would look like this:

Recording of the word/phrase die Freiheit.

Usage

General

All the functions provided by this module can be called from other modules, or via {{#invoke:}} directly from Wikitext (e.g. in a template).

Wikitext usage

When used from wikitext, the functions take one positional argument, the property ID, and three optional named arguments: |from=entityId as the entity ID to use, |somevalue=some value as the value to return in case of a somevalue statement/qualifier, and |novalue=no value as the value to return in case of a novalue statement/qualifier. The qualifier functions also take a second positional argument, the property ID of the qualifier.

For the entity ID, the alias |entityId=entityId instead of |from=entityId is also supported. If the entity ID is not specified, the entity connected to the current page is used, i.e. the MediaInfo of the current file page, or the Wikidata item linked to the current non-file page.

The returned value is generally wikitext-compatible, but as plain as is possible without losing information.

Module usage

When used from another module, the functions in this module take two arguments:

entity

A full mw.wikibase.entity table (e.g. returned by a mw.wikibase.getEntity() call), or an entity ID as a string, or nil for the entity connected to the current page.

propertyId

The property ID of the statement to look for, as a string.

The qualifier functions take an additional third argument:

qualifierId

The property ID of the qualifier to look for, also as a string.

After this, both kinds of functions take two more optional arguments:

somevalueReturn

The value to return for a somevalue statement/qualifier (known as “unknown value” on Wikidata, or “some value” or “some value without a Wikidata item” in Structured Data on Commons). Defaults to nil.

novalueReturn

The value to return for a novalue statement/qualifier (known as “no value” on Wikidata, or “No value exists for this property” in Structured Data on Commons). Defaults to nil.

They return at least two values:

value

The same value that would be returned to wikitext, i.e. mostly-plain but wikitext-compatible, when the statement/qualifier has a proper value; or one of somevalueReturn/novalueReturn, when the statement has one of these special “values”; or nil if there is no statement/qualifier. See the individual function documentation for details on the value.

hasOther

Whether there were any additional statements (boolean). This module can’t be used to access the data of those statements, but you could use this flag to e.g. add some maintenance category like “Files with more than one something statements”.

The qualifier functions return a third value:

hasOtherQualifiers

Whether there were any additional qualifiers using the same property ID in the statement (boolean). As with hasOther for additional main statements, if this flag is true, this should probably be flagged up as unexpected, or you might want to use a different module if multiple values are genuinely expected.

Some functions return additional values, as documented below. (This does not apply when there is no statement/qualifier, or it does not have a proper value but instead somevalue/novalue.)

Main statement value functions

These functions return the main value of the statement.

string

Returns a string value. Note that the string data value type is used by several data types, including but not limited to string: this function can also be used with properties of some other data types, such as external identifiers. (For URLs you’ll want to use the URL functions instead, though, so the URL doesn’t get wikitext-escaped.)

Wikitext usage:

{{#invoke:Statement/sandbox|string|P760|from=M96915718|somevalue=some value|novalue=no value}}

Module usage:

local wikitext, hasOther, string = statementModule.string( entity, propertyId, somevalueReturn, novalueReturn )

The returned wikitext is the string value, wikitext-escaped (but without any additional wrapping). The third return value, string, is the unescaped plain string value; if you don’t need it, you can leave it out.

url

Returns a URL value.

Wikitext usage:

{{#invoke:Statement/sandbox|url|P973|from=M85023113|somevalue=some value|novalue=no value}}

Module usage:

local url, hasOther = statementModule.url( entity, propertyId, somevalueReturn, novalueReturn )

entityId

Returns an entity ID value. Can be used for properties of all entity types: items, properties, lexemes, senses, forms. (As of March 2022, there is no data type for MediaInfo entities.)

Wikitext usage:

{{#invoke:Statement/sandbox|entityId|P6216|from=M43058895|somevalue=some value|novalue=no value}}

Module usage:

local entityId, hasOther, entityType = statementModule.entityId( entity, propertyId, somevalueReturn, novalueReturn )

The third return value, entityType, is the entity type of the value; if you don’t need it, you can leave it out.

monolingualText

Returns a monolingual text value.

Wikitext usage:

{{#invoke:Statement/sandbox|monolingualText|P1476|from=M96718296|somevalue=some value|novalue=no value}}

Module usage:

local wikitext, hasOther, text, language = statementModule.monolingualText( entity, propertyId, somevalueReturn, novalueReturn )

The returned wikitext is a string with wikitext for a language-tagged span, so that the full information is included. The third and fourth return values provide the plain text (not wikitext-escaped!) and language (as an mw.language instance) of the value.

time

Returns a time value in full. See also the date functions, which return only the “relevant” part of the value, and can be used with the same properties.

Wikitext usage:

{{#invoke:Statement/sandbox|time|P571|from=M38570|somevalue=some value|novalue=no value}}

Module usage:

local timestamp, hasOther, precision, calendar = statementModule.time( entity, propertyId, somevalueReturn, novalueReturn )

The timestamp is in ISO 8601 format. The precision is one of Wikibase’s precision constants (from 0 “billion years” to 11 “days”, or theoretically up to 14 “seconds”), and the calendar is an item ID (typically proleptic Gregorian calendar (Q1985727) or proleptic Julian calendar (Q1985786)). If you don’t need these, you can leave them out.

date

Returns only the part of a time value that is “captured” by its precision, such as the date (without the time part), or only the year.

Wikitext usage:

{{#invoke:Statement/sandbox|date|P571|from=M17811375|somevalue=some value|novalue=no value}}

Module usage:

local date, hasOther, precision, calendar, timestamp = statementModule.date( entity, propertyId, somevalueReturn, novalueReturn )

The date is typically the year, year-month, or year-month-day. The precision and calendar are as in the time functions; the original timestamp (likewise) is appended at the very end.

Qualifier functions

These functions return the first qualifier with the given property ID of the statement. The statement is always the same one that would be returned by the main statement value functions; these functions are for returning the qualifier of that statement, not for selecting a statement based on its qualifiers. (At some point, someone™ should maybe write another module for that, but it isn’t this module.)

Generally speaking, these functions return the same format as their main statement value counterparts, except that (in module usage) the single hasOther flag is replaced by two, hasOtherStatement and hasOtherQualifier.

stringQualifier

Returns a string qualifier.

Wikitext usage:

{{#invoke:Statement/sandbox|stringQualifier|P170|P2093|from=M96915718|somevalue=some value|novalue=no value}}

Module usage:

local wikitext, hasOtherStatement, hasOtherQualifier, string = statementModule.stringQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )

urlQualifier

Returns a URL qualifier.

Wikitext usage:

{{#invoke:Statement/sandbox|urlQualifier|P170|P2699|from=M79977121|somevalue=some value|novalue=no value}}

Module usage:

local url, hasOtherStatement, hasOtherQualifier = urlQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )

entityIdQualifier

Returns an entity ID qualifier.

Wikitext usage:

{{#invoke:Statement/sandbox|entityIdQualifier|P170|P3831|from=M80857538|somevalue=some value|novalue=no value}}

Module usage:

local entityId, hasOtherStatement, hasOtherQualifier, entityType = statementModule.entityIdQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )

monolingualTextQualifier

Returns a monolingual text qualifier.

Wikitext usage:

{{#invoke:Statement/sandbox|monolingualTextQualifier|P180|P1684|from=M107006882|somevalue=some value|novalue=no value}}

Module usage:

local wikitext, hasOtherStatement, hasOtherQualifier, text, language = statementModule.monolingualTextQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )

timeQualifier

Returns a time qualifier.

Wikitext usage:

{{#invoke:Statement/sandbox|timeQualifier|P6731|P580|from=M38570|somevalue=some value|novalue=no value}}

Module usage:

local timestamp, hasOtherStatement, hasOtherQualifier, precision, calendar = statementModule.timeQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )

dateQualifier

Returns a date qualifier. See the non-qualifier functions’ documentation for the distinction between time and date.

Wikitext usage:

{{#invoke:Statement/sandbox|dateQualifier|P180|P585|from=M97052174|somevalue=some value|novalue=no value}}

Module usage:

local date, hasOtherStatement, hasOtherQualifier, precision, calendar, timestamp = statementModule.dateQualifier( entity, propertyId, qualifierId, somevalueReturn, novalueReturn )