Naming of arguments to built-in functions

If we allow arguments to be specified by keyword, then we need to think more carefully about what the keywords should be. Attached is a list of the parameter names currently defined; it's a pretty disparate set of naming conventions.

I propose to apply the following conventions:

(a) for the "primary input" of a function, if there is such a thing:

- if it's an atomic value, "value"
- it it's a node, "node"
- if it's an arbitrary sequence, "input"
- if it's a URI to be dereferenced, "href"
- if it's a map, "map"
- if it's an array, "array"
- for angles in math functions, replace Greek theta by "angle"
- for sequences of nodes/atomic values/maps, use "nodes", "values", "maps", etc

(The term "primary" is completely subjective. Generally it indicates that in some subjective sense, the function is returning a property or applying an operation on the "primary input". Intuitively, it means that in an OO language, the function would be a method on this object. In nearly all cases, the primary input is the first argument; the only obvious exception is fn:lang).

(b) for "secondary inputs", describe the role of the parameter, as briefly as possible, always with a single English word. So, for example,
format-number(value, picture), contains(value, substring), matches(value, pattern).

(c) if there are multiple inputs and none is obviously "primary", use a role name for each, for example resolve-uri(relative, base).

(d) where there are two symmetric inputs, e.g. compare(), use "value1" and "value2", or "input1" and "input2" etc.

Michael Kay
Saxonica

Existing list (including some proviosional/draft new functions):

<?xml version="1.0" encoding="UTF-8"?>
<sigs>
   <f name="node-name" args=""/>
   <f name="node-name" args="arg"/>
   <f name="nilled" args=""/>
   <f name="nilled" args="arg"/>
   <f name="string" args=""/>
   <f name="string" args="arg"/>
   <f name="data" args=""/>
   <f name="data" args="arg"/>
   <f name="base-uri" args=""/>
   <f name="base-uri" args="arg"/>
   <f name="document-uri" args=""/>
   <f name="document-uri" args="arg"/>
   <f name="error" args=""/>
   <f name="error" args="code"/>
   <f name="error" args="code description"/>
   <f name="error" args="code description error-object"/>
   <f name="trace" args="value"/>
   <f name="trace" args="value label"/>
   <f name="numeric-add" args="arg1 arg2"/>
   <f name="numeric-subtract" args="arg1 arg2"/>
   <f name="numeric-multiply" args="arg1 arg2"/>
   <f name="numeric-divide" args="arg1 arg2"/>
   <f name="numeric-integer-divide" args="arg1 arg2"/>
   <f name="numeric-mod" args="arg1 arg2"/>
   <f name="numeric-unary-plus" args="arg"/>
   <f name="numeric-unary-minus" args="arg"/>
   <f name="numeric-equal" args="arg1 arg2"/>
   <f name="numeric-less-than" args="arg1 arg2"/>
   <f name="abs" args="arg"/>
   <f name="ceiling" args="arg"/>
   <f name="floor" args="arg"/>
   <f name="round" args="arg"/>
   <f name="round" args="arg precision"/>
   <f name="round-half-to-even" args="arg"/>
   <f name="round-half-to-even" args="arg precision"/>
   <f name="format-integer" args="value picture"/>
   <f name="format-integer" args="value picture lang"/>
   <f name="format-number" args="value picture"/>
   <f name="format-number" args="value picture decimal-format-name"/>
   <f name="pi" args=""/>
   <f name="exp" args="arg"/>
   <f name="exp10" args="arg"/>
   <f name="log" args="arg"/>
   <f name="log10" args="arg"/>
   <f name="sqrt" args="arg"/>
   <f name="pow" args="x y"/>
   <f name="sin" args="θ"/>
   <f name="cos" args="θ"/>
   <f name="tan" args="θ"/>
   <f name="asin" args="arg"/>
   <f name="acos" args="arg"/>
   <f name="atan" args="arg"/>
   <f name="atan2" args="y x"/>
   <f name="codepoints-to-string" args="arg"/>
   <f name="string-to-codepoints" args="arg"/>
   <f name="compare" args="comparand1 comparand2"/>
   <f name="compare" args="comparand1 comparand2 collation"/>
   <f name="codepoint-equal" args="comparand1 comparand2"/>
   <f name="concat" args="arg1 arg2 ..."/>
   <f name="string-join" args="arg1"/>
   <f name="string-join" args="arg1 arg2"/>
   <f name="substring" args="sourceString start"/>
   <f name="substring" args="sourceString start length"/>
   <f name="string-length" args=""/>
   <f name="string-length" args="arg"/>
   <f name="normalize-space" args=""/>
   <f name="normalize-space" args="arg"/>
   <f name="normalize-unicode" args="arg"/>
   <f name="normalize-unicode" args="arg normalizationForm"/>
   <f name="upper-case" args="arg"/>
   <f name="lower-case" args="arg"/>
   <f name="translate" args="arg mapString transString"/>
   <f name="encode-for-uri" args="uri-part"/>
   <f name="iri-to-uri" args="iri"/>
   <f name="escape-html-uri" args="uri"/>
   <f name="contains" args="arg1 arg2"/>
   <f name="contains" args="arg1 arg2 collation"/>
   <f name="starts-with" args="arg1 arg2"/>
   <f name="starts-with" args="arg1 arg2 collation"/>
   <f name="ends-with" args="arg1 arg2"/>
   <f name="ends-with" args="arg1 arg2 collation"/>
   <f name="substring-before" args="arg1 arg2"/>
   <f name="substring-before" args="arg1 arg2 collation"/>
   <f name="substring-after" args="arg1 arg2"/>
   <f name="substring-after" args="arg1 arg2 collation"/>
   <f name="matches" args="input pattern"/>
   <f name="matches" args="input pattern flags"/>
   <f name="replace" args="input pattern replacement"/>
   <f name="replace" args="input pattern replacement flags"/>
   <f name="tokenize" args="input"/>
   <f name="tokenize" args="input pattern"/>
   <f name="tokenize" args="input pattern flags"/>
   <f name="analyze-string" args="input pattern"/>
   <f name="analyze-string" args="input pattern flags"/>
   <f name="contains-token" args="input token"/>
   <f name="contains-token" args="input token collation"/>
   <f name="resolve-uri" args="relative"/>
   <f name="resolve-uri" args="relative base"/>
   <f name="true" args=""/>
   <f name="false" args=""/>
   <f name="boolean-equal" args="value1 value2"/>
   <f name="boolean-less-than" args="arg1 arg2"/>
   <f name="boolean" args="arg"/>
   <f name="not" args="arg"/>
   <f name="yearMonthDuration-less-than" args="arg1 arg2"/>
   <f name="dayTimeDuration-less-than" args="arg1 arg2"/>
   <f name="duration-equal" args="arg1 arg2"/>
   <f name="years-from-duration" args="arg"/>
   <f name="months-from-duration" args="arg"/>
   <f name="days-from-duration" args="arg"/>
   <f name="hours-from-duration" args="arg"/>
   <f name="minutes-from-duration" args="arg"/>
   <f name="seconds-from-duration" args="arg"/>
   <f name="add-yearMonthDurations" args="arg1 arg2"/>
   <f name="subtract-yearMonthDurations" args="arg1 arg2"/>
   <f name="multiply-yearMonthDuration" args="arg1 arg2"/>
   <f name="divide-yearMonthDuration" args="arg1 arg2"/>
   <f name="divide-yearMonthDuration-by-yearMonthDuration" args="arg1 arg2"/>
   <f name="add-dayTimeDurations" args="arg1 arg2"/>
   <f name="subtract-dayTimeDurations" args="arg1 arg2"/>
   <f name="multiply-dayTimeDuration" args="arg1 arg2"/>
   <f name="divide-dayTimeDuration" args="arg1 arg2"/>
   <f name="divide-dayTimeDuration-by-dayTimeDuration" args="arg1 arg2"/>
   <f name="dateTime" args="arg1 arg2"/>
   <f name="dateTime-equal" args="arg1 arg2"/>
   <f name="dateTime-less-than" args="arg1 arg2"/>
   <f name="date-equal" args="arg1 arg2"/>
   <f name="date-less-than" args="arg1 arg2"/>
   <f name="time-equal" args="arg1 arg2"/>
   <f name="time-less-than" args="arg1 arg2"/>
   <f name="gYearMonth-equal" args="arg1 arg2"/>
   <f name="gYear-equal" args="arg1 arg2"/>
   <f name="gMonthDay-equal" args="arg1 arg2"/>
   <f name="gMonth-equal" args="arg1 arg2"/>
   <f name="gDay-equal" args="arg1 arg2"/>
   <f name="year-from-dateTime" args="arg"/>
   <f name="month-from-dateTime" args="arg"/>
   <f name="day-from-dateTime" args="arg"/>
   <f name="hours-from-dateTime" args="arg"/>
   <f name="minutes-from-dateTime" args="arg"/>
   <f name="seconds-from-dateTime" args="arg"/>
   <f name="timezone-from-dateTime" args="arg"/>
   <f name="year-from-date" args="arg"/>
   <f name="month-from-date" args="arg"/>
   <f name="day-from-date" args="arg"/>
   <f name="timezone-from-date" args="arg"/>
   <f name="hours-from-time" args="arg"/>
   <f name="minutes-from-time" args="arg"/>
   <f name="seconds-from-time" args="arg"/>
   <f name="timezone-from-time" args="arg"/>
   <f name="adjust-dateTime-to-timezone" args="arg"/>
   <f name="adjust-dateTime-to-timezone" args="arg timezone"/>
   <f name="adjust-date-to-timezone" args="arg"/>
   <f name="adjust-date-to-timezone" args="arg timezone"/>
   <f name="adjust-time-to-timezone" args="arg"/>
   <f name="adjust-time-to-timezone" args="arg timezone"/>
   <f name="subtract-dateTimes" args="arg1 arg2"/>
   <f name="subtract-dates" args="arg1 arg2"/>
   <f name="subtract-times" args="arg1 arg2"/>
   <f name="add-yearMonthDuration-to-dateTime" args="arg1 arg2"/>
   <f name="add-dayTimeDuration-to-dateTime" args="arg1 arg2"/>
   <f name="subtract-yearMonthDuration-from-dateTime" args="arg1 arg2"/>
   <f name="subtract-dayTimeDuration-from-dateTime" args="arg1 arg2"/>
   <f name="add-yearMonthDuration-to-date" args="arg1 arg2"/>
   <f name="add-dayTimeDuration-to-date" args="arg1 arg2"/>
   <f name="subtract-yearMonthDuration-from-date" args="arg1 arg2"/>
   <f name="subtract-dayTimeDuration-from-date" args="arg1 arg2"/>
   <f name="add-dayTimeDuration-to-time" args="arg1 arg2"/>
   <f name="subtract-dayTimeDuration-from-time" args="arg1 arg2"/>
   <f name="format-dateTime" args="value picture"/>
   <f name="format-dateTime" args="value picture language calendar place"/>
   <f name="format-date" args="value picture"/>
   <f name="format-date" args="value picture language calendar place"/>
   <f name="format-time" args="value picture"/>
   <f name="format-time" args="value picture language calendar place"/>
   <f name="parse-ietf-date" args="value"/>
   <f name="resolve-QName" args="qname element"/>
   <f name="QName" args="paramURI paramQName"/>
   <f name="QName-equal" args="arg1 arg2"/>
   <f name="prefix-from-QName" args="arg"/>
   <f name="local-name-from-QName" args="arg"/>
   <f name="namespace-uri-from-QName" args="arg"/>
   <f name="namespace-uri-for-prefix" args="prefix element"/>
   <f name="in-scope-namespaces" args="element"/>
   <f name="in-scope-prefixes" args="element"/>
   <f name="hexBinary-equal" args="value1 value2"/>
   <f name="hexBinary-less-than" args="arg1 arg2"/>
   <f name="base64Binary-equal" args="value1 value2"/>
   <f name="base64Binary-less-than" args="arg1 arg2"/>
   <f name="NOTATION-equal" args="arg1 arg2"/>
   <f name="name" args=""/>
   <f name="name" args="arg"/>
   <f name="local-name" args=""/>
   <f name="local-name" args="arg"/>
   <f name="namespace-uri" args=""/>
   <f name="namespace-uri" args="arg"/>
   <f name="number" args=""/>
   <f name="number" args="arg"/>
   <f name="lang" args="testlang"/>
   <f name="lang" args="testlang node"/>
   <f name="path" args=""/>
   <f name="path" args="arg"/>
   <f name="root" args=""/>
   <f name="root" args="arg"/>
   <f name="has-children" args=""/>
   <f name="has-children" args="node"/>
   <f name="innermost" args="nodes"/>
   <f name="outermost" args="nodes"/>
   <f name="index-of" args="seq search"/>
   <f name="index-of" args="seq search collation"/>
   <f name="empty" args="arg"/>
   <f name="exists" args="arg"/>
   <f name="distinct-values" args="arg"/>
   <f name="distinct-values" args="arg collation"/>
   <f name="identity" args="seq"/>
   <f name="insert-before" args="target position inserts"/>
   <f name="remove" args="target position"/>
   <f name="head" args="arg"/>
   <f name="tail" args="arg"/>
   <f name="replicate" args="seq count"/>
   <f name="reverse" args="arg"/>
   <f name="subsequence" args="sourceSeq startingLoc"/>
   <f name="subsequence" args="sourceSeq startingLoc length"/>
   <f name="slice" args="seq positions"/>
   <f name="range" args="seq start"/>
   <f name="range" args="seq start end"/>
   <f name="range" args="seq start end options"/>
   <f name="slice-20201203" args="seq conditions"/>
   <f name="unordered" args="sourceSeq"/>
   <f name="zero-or-one" args="arg"/>
   <f name="one-or-more" args="arg"/>
   <f name="exactly-one" args="arg"/>
   <f name="deep-equal" args="parameter1 parameter2"/>
   <f name="deep-equal" args="parameter1 parameter2 collation"/>
   <f name="differences" args="parameter1 parameter2"/>
   <f name="differences" args="parameter1 parameter2 options"/>
   <f name="differences" args="parameter1 parameter2 options collation"/>
   <f name="count" args="arg"/>
   <f name="avg" args="arg"/>
   <f name="max" args="arg"/>
   <f name="max" args="arg collation"/>
   <f name="min" args="arg"/>
   <f name="min" args="arg collation"/>
   <f name="sum" args="arg"/>
   <f name="sum" args="arg zero"/>
   <f name="id" args="arg"/>
   <f name="id" args="arg node"/>
   <f name="element-with-id" args="arg"/>
   <f name="element-with-id" args="arg node"/>
   <f name="idref" args="arg"/>
   <f name="idref" args="arg node"/>
   <f name="doc" args="uri"/>
   <f name="doc-available" args="uri"/>
   <f name="collection" args=""/>
   <f name="collection" args="arg"/>
   <f name="uri-collection" args=""/>
   <f name="uri-collection" args="arg"/>
   <f name="unparsed-text" args="href"/>
   <f name="unparsed-text" args="href encoding"/>
   <f name="unparsed-text-lines" args="href"/>
   <f name="unparsed-text-lines" args="href encoding"/>
   <f name="unparsed-text-available" args="href"/>
   <f name="unparsed-text-available" args="href encoding"/>
   <f name="environment-variable" args="name"/>
   <f name="available-environment-variables" args=""/>
   <f name="generate-id" args=""/>
   <f name="generate-id" args="arg"/>
   <f name="parse-xml" args="arg"/>
   <f name="parse-xml-fragment" args="arg"/>
   <f name="serialize" args="arg"/>
   <f name="serialize" args="arg params"/>
   <f name="position" args=""/>
   <f name="last" args=""/>
   <f name="current-dateTime" args=""/>
   <f name="current-date" args=""/>
   <f name="current-time" args=""/>
   <f name="implicit-timezone" args=""/>
   <f name="default-collation" args=""/>
   <f name="default-language" args=""/>
   <f name="static-base-uri" args=""/>
   <f name="function-lookup" args="name arity"/>
   <f name="function-name" args="func"/>
   <f name="function-arity" args="func"/>
   <f name="for-each" args="seq action"/>
   <f name="filter" args="seq f"/>
   <f name="fold-left" args="seq zero f"/>
   <f name="fold-right" args="seq zero f"/>
   <f name="for-each-pair" args="seq1 seq2 action"/>
   <f name="sort" args="input"/>
   <f name="sort" args="input collation"/>
   <f name="sort" args="input collation key"/>
   <f name="apply" args="function array"/>
   <f name="same-key" args="k1 k2"/>
   <f name="merge" args="maps"/>
   <f name="merge" args="maps options"/>
   <f name="keys" args="map"/>
   <f name="contains" args="map key"/>
   <f name="get" args="map key"/>
   <f name="find" args="input key"/>
   <f name="put" args="map key value"/>
   <f name="entry" args="key value"/>
   <f name="remove" args="map keys"/>
   <f name="for-each" args="map action"/>
   <f name="filter" args="map predicate"/>
   <f name="replace" args="map key action"/>
   <f name="substitute" args="map action"/>
   <f name="group-by" args="seq key"/>
   <f name="size" args="map"/>
   <f name="collation-key" args="key"/>
   <f name="collation-key" args="key collation"/>
   <f name="json-to-xml" args="json-text"/>
   <f name="json-to-xml" args="json-text options"/>
   <f name="xml-to-json" args="input"/>
   <f name="xml-to-json" args="input options"/>
   <f name="parse-json" args="json-text"/>
   <f name="parse-json" args="json-text options"/>
   <f name="json-doc" args="href"/>
   <f name="json-doc" args="href options"/>
   <f name="json" args="seq"/>
   <f name="json" args="seq options"/>
   <f name="size" args="array"/>
   <f name="get" args="array position"/>
   <f name="put" args="array position member"/>
   <f name="append" args="array appendage"/>
   <f name="join" args="arrays"/>
   <f name="subarray" args="array start"/>
   <f name="subarray" args="array start length"/>
   <f name="slice" args="array positions"/>
   <f name="remove" args="array positions"/>
   <f name="insert-before" args="array position member"/>
   <f name="head" args="array"/>
   <f name="tail" args="array"/>
   <f name="reverse" args="array"/>
   <f name="for-each" args="array action"/>
   <f name="filter" args="array function"/>
   <f name="fold-left" args="array zero function"/>
   <f name="fold-right" args="array zero function"/>
   <f name="for-each-pair" args="array1 array2 function"/>
   <f name="from-sequence" args="seq"/>
   <f name="from-sequence" args="seq function"/>
   <f name="sort" args="array"/>
   <f name="sort" args="array collation"/>
   <f name="sort" args="array collation key"/>
   <f name="flatten" args="input"/>
   <f name="spread" args="input limit"/>
   <f name="spread" args="input limit weight"/>
   <f name="load-xquery-module" args="module-uri"/>
   <f name="load-xquery-module" args="module-uri options"/>
   <f name="transform" args="options"/>
   <f name="random-number-generator" args=""/>
   <f name="random-number-generator" args="seed"/>
   <f name="all" args="seq predicate"/>
   <f name="characters" args="arg"/>
   <f name="highest" args="input"/>
   <f name="highest" args="input collation"/>
   <f name="highest" args="input collation key"/>
   <f name="index-where" args="seq predicate"/>
   <f name="is-NaN" args="arg"/>
   <f name="items-after" args="seq predicate"/>
   <f name="items-before" args="seq predicate"/>
   <f name="items-after" args="seq predicate"/>
   <f name="items-until" args="seq predicate"/>
   <f name="lowest" args="input"/>
   <f name="lowest" args="input collation"/>
   <f name="lowest" args="input collation key"/>
   <f name="replace-with" args="input pattern replacer flags"/>
   <f name="replace-with" args="input pattern replacer"/>
   <f name="some" args="seq predicate"/>
   <f name="stack-trace" args=""/>
   <f name="uniform" args="input"/>
   <f name="uniform" args="input collation"/>
   <f name="unique" args="input"/>
   <f name="unique" args="input collation"/>
</sigs>