Module:Statement/doc

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search

CodeDiscussionEditHistoryLinksLink count Subpages:DocumentationTestsResultsSandboxLive code All modules

This is the documentation page for Module:Statement

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

[edit]

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

Recording of the word/phrase <q>{{#invoke:Statement|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' ).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

[edit]

General

[edit]

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

[edit]

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

[edit]

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

[edit]

These functions return the main value of the statement.

string

[edit]

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|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

[edit]

Returns a URL value.

Wikitext usage:

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

Module usage:

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

entityId

[edit]

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|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

[edit]

Returns a monolingual text value.

Wikitext usage:

{{#invoke:Statement|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

[edit]

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|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

[edit]

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|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

[edit]

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

[edit]

Returns a string qualifier.

Wikitext usage:

{{#invoke:Statement|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

[edit]

Returns a URL qualifier.

Wikitext usage:

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

Module usage:

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

entityIdQualifier

[edit]

Returns an entity ID qualifier.

Wikitext usage:

{{#invoke:Statement|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

[edit]

Returns a monolingual text qualifier.

Wikitext usage:

{{#invoke:Statement|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

[edit]

Returns a time qualifier.

Wikitext usage:

{{#invoke:Statement|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

[edit]

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

Wikitext usage:

{{#invoke:Statement|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 )