Re: Naming of arguments to built-in functions

>> - if it's a URI to be dereferenced, "href"
> 
> "hyper reference"
> 
> I wonder where that name came from originally. $uri (or $url as most people know it) would have been simpler

Blame Tim B-L, I guess. But it seems so ubiquitous that it seems appropriate. I thought it would be good to distinguish URIs that are going to be dereferenced (URLs?) from URIs used purely for naming (collations, namespaces).
> 
>> - for angles in math functions, replace Greek theta by "angle"
> 
> I like θ 
> 
> There generally should be more symbols in use
> 
> (btw has anyone considered adding a "÷" operator as synonym for "div"?)
> 
> 
Yes, I have, and I've proposed it as well. But the fact is, it's 2020 but non-ASCII characters are still a hassle. They still get damaged in transmission by code repositories, text editors, email, you name it, and they also easily get mis-rendered when you display things in a browser.
> 
>> (d) where there are two symmetric inputs, e.g. compare(), use "value1" and "value2", or "input1" and "input2" etc.
> 
> That would be simpler with single letters, like v, w; or a, b; or x,y

Yes, I'm quite sympathetic to x,y.

Michael Kay
Saxonica
> 
> 
> Cheers,
> Benito 
> On 13.12.20 12:20, Christian Grün wrote:
>> Looks good; and I think people will generally be happy to see this
>> unified. What about replacing “input” with a singular/plural term,
>> such as “item/items”?
>> ____________________________________
>> 
>> On Sun, Dec 13, 2020 at 11:17 AM Michael Kay <mike@saxonica.com> <mailto:mike@saxonica.com> wrote:
>>> 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>
>>>