Merge pull request #1731 from Quelklef/master
Some documentation additions
This commit is contained in:
commit
a5ed98f5b9
@ -467,25 +467,35 @@ and `&kwonly` must precede `&kwargs`). This is the same order that Python
|
||||
requires.
|
||||
|
||||
&optional
|
||||
Parameter is optional. The parameter can be given as a two item list, where
|
||||
the first element is parameter name and the second is the default value. The
|
||||
parameter can be also given as a single item, in which case the default
|
||||
value is ``None``.
|
||||
All following parameters are optional. They may be given as two-argument lists,
|
||||
where the first element is the parameter name and the second is the default value.
|
||||
The parameter can also be given as a single item, in which case the default value
|
||||
is ``None``.
|
||||
|
||||
The following example defines a function with one required positional argument
|
||||
as well as three optional arguments. The first optional argument defaults to ``None``
|
||||
and the latter two default to ``"("`` and ``")"``, respectively.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
=> (defn total-value [value &optional [value-added-tax 10]]
|
||||
... (+ (/ (* value value-added-tax) 100) value))
|
||||
=> (defn format-pair [left-val &optional right-val [open-text "("] [close-text ")"]]
|
||||
... (+ open-text (str left-val) ", " (str right-val) close-text))
|
||||
|
||||
=> (total-value 100)
|
||||
110.0
|
||||
=> (format-pair 3)
|
||||
'(3, None)'
|
||||
|
||||
=> (total-value 100 1)
|
||||
101.0
|
||||
=> (format-pair "A" "B")
|
||||
'(A, B)'
|
||||
|
||||
=> (format-pair "A" "B" "<" ">")
|
||||
'<A, B>'
|
||||
|
||||
=> (format-pair "A" :open-text "<" :close-text ">")
|
||||
'<A, None>'
|
||||
|
||||
&rest
|
||||
Parameter will contain 0 or more positional arguments. No other positional
|
||||
arguments may be specified after this one.
|
||||
The following parameter will contain a list of 0 or more positional arguments.
|
||||
No other positional parameters may be specified after this one.
|
||||
|
||||
The following code example defines a function that can be given 0 to n
|
||||
numerical parameters. It then sums every odd number and subtracts
|
||||
@ -504,15 +514,14 @@ requires.
|
||||
8
|
||||
=> (zig-zag-sum 1 2 3 4 5 6)
|
||||
-3
|
||||
|
||||
|
||||
&kwonly
|
||||
.. versionadded:: 0.12.0
|
||||
|
||||
Parameters that can only be called as keywords. Mandatory
|
||||
keyword-only arguments are declared with the argument's name;
|
||||
optional keyword-only arguments are declared as a two-element list
|
||||
containing the argument name followed by the default value (as
|
||||
with `&optional` above).
|
||||
All following parmaeters can only be supplied as keywords.
|
||||
Like ``&optional``, the parameter may be marked as optional by
|
||||
declaring it as a two-element list containing the parameter name
|
||||
following by the default value.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
@ -541,7 +550,8 @@ requires.
|
||||
Availability: Python 3.
|
||||
|
||||
&kwargs
|
||||
Parameter will contain 0 or more keyword arguments.
|
||||
Like ``&rest``, but for keyword arugments.
|
||||
The following parameter will contain 0 or more keyword arguments.
|
||||
|
||||
The following code examples defines a function that will print all keyword
|
||||
arguments and their values.
|
||||
@ -560,6 +570,42 @@ requires.
|
||||
parameter-1 1
|
||||
parameter-2 2
|
||||
|
||||
The following example uses all of ``&optional``, ``&rest``, ``&kwonly``, and
|
||||
``&kwargs`` in order to show their interactions with each other. The function
|
||||
renders an HTML tag.
|
||||
It requires an argument ``tag-name``, a string which is the tag name.
|
||||
It has one optional argument, ``delim``, which defaults to ``""`` and is placed
|
||||
between each child.
|
||||
The rest of the arguments, ``children``, are the tag's children or content.
|
||||
A single keyword-only argument, ``empty``, is included and defaults to ``False``.
|
||||
``empty`` changes how the tag is rendered if it has no children. Normally, a
|
||||
tag with no children is rendered like ``<div></div>``. If ``empty`` is ``True``,
|
||||
then it will render like ``<div />``.
|
||||
The rest of the keyword arguments, ``props``, render as HTML attributes.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
=> (defn render-html-tag [tag-name &optional [delim ""] &rest children &kwonly [empty False] &kwargs attrs]
|
||||
... (setv rendered-attrs (.join " " (lfor (, key val) (.items attrs) (+ (unmangle (str key)) "=\"" (str val) "\""))))
|
||||
... (if rendered-attrs ; If we have attributes, prefix them with a space after the tag name
|
||||
... (setv rendered-attrs (+ " " rendered-attrs)))
|
||||
... (setv rendered-children (.join delim children))
|
||||
... (if (and (not children) empty)
|
||||
... (+ "<" tag-name rendered-attrs " />")
|
||||
... (+ "<" tag-name rendered-attrs ">" rendered-children "</" tag-name ">")))
|
||||
|
||||
=> (render-html-tag "div")
|
||||
'<div></div'>
|
||||
|
||||
=> (render-html-tag "img" :empty True)
|
||||
'<img />'
|
||||
|
||||
=> (render-html-tag "img" :id "china" :class "big-image" :empty True)
|
||||
'<img id="china" class="big-image" />'
|
||||
|
||||
=> (render-html-tag "p" " --- " (render-html-tag "span" "" :class "fancy" "I'm fancy!") "I'm to the right of fancy" "I'm alone :(")
|
||||
'<p><span class="fancy">I\'m fancy!</span> --- I\'m to right right of fancy --- I\'m alone :(</p>'
|
||||
|
||||
defn/a
|
||||
------
|
||||
|
||||
@ -1609,6 +1655,9 @@ the given conditional is ``False``. The following shows the expansion of this ma
|
||||
unpack-iterable, unpack-mapping
|
||||
-------------------------------
|
||||
|
||||
(Also known as the splat operator, star operator, argument expansion, argument
|
||||
explosion, argument gathering, and varargs, among others...)
|
||||
|
||||
``unpack-iterable`` and ``unpack-mapping`` allow an iterable or mapping
|
||||
object (respectively) to provide positional or keywords arguments
|
||||
(respectively) to a function.
|
||||
|
Loading…
Reference in New Issue
Block a user