From e4fd74af1b94dd22e6f8e4f8b3752f17c9391fc6 Mon Sep 17 00:00:00 2001 From: Eli Date: Thu, 17 Jan 2019 08:16:32 -0500 Subject: [PATCH] Clarifying &optional documentation (fixes #1722) --- docs/language/api.rst | 84 +++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 19 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 115460e..4f52418 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -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" "<" ">") + '' + + => (format-pair "A" :open-text "<" :close-text ">") + '' &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 ``
``. If ``empty`` is ``True``, +then it will render like ``
``. +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 ""))) + + => (render-html-tag "div") + '
+ + => (render-html-tag "img" :empty True) + '' + + => (render-html-tag "img" :id "china" :class "big-image" :empty True) + '' + + => (render-html-tag "p" " --- " (render-html-tag "span" "" :class "fancy" "I'm fancy!") "I'm to the right of fancy" "I'm alone :(") + '

I\'m fancy! --- I\'m to right right of fancy --- I\'m alone :(

' + defn/a ------