Re: Naming of arguments to built-in functions

On Sun, 13 Dec 2020 at 10:17, Michael Kay <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.
>

I like this. I would suggest using "radians" instead of "angle" for the
maths functions as that better describes what it is, and would help avoid
degrees/radians confusion.

Kind regards,
Reece


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

Received on Sunday, 13 December 2020 11:51:36 UTC