futils.args — io.randomseed/futils 1.2.3

futils library, function arguments handling.

argc clj macro

(argc f)

Determines the number of arguments that the given function takes and returns a map containing these keys:

:arities – a sorted sequence of argument counts for all arities, :engine – :clj (if metadata were used to determine arities – DEPRECATED); :jvm (if Java reflection methods were used to determine arities), :macro – a flag informing whether the given object is a macro, :variadic – a flag informing whether the widest arity is variadic.

Variadic parameter is counted as one of the possible arguments. Macro implicite arguments (&env and &form) are not counted.

Macro flag (:macro) is only present when macro was detected.

If the given argument cannot be used to obtain a Var bound to a functon or a function object then it returns nil.

argc-clj clj

(argc-clj varobj)

Uses the given Var's :arglists metadata value to determine the number of arguments taken by a function that the Var is bound to. See (doc futils.args/argc) for more specific documentation.

argc-jvm clj

(argc-jvm f)

Uses JVM reflection calls to determine number of arguments the given function takes. Returns a map. See (doc futils.args/argc) for more specific documentation.

args-relax clj deprecated

DEPRECATED: Use 'relax*' instead.

relax clj macro

(relax f & {:as options})

Returns a variadic function object that calls the given function f, adjusting the number of passed arguments to the nearest matching arity. It cuts argument list or pads it with nil values if necessary.

The arities will be obtained using JVM reflection calls to anonymous class representing a function object.

To determine the number of arguments the nearest arity is picked up by matching a number of passed arguments to number of arguments for each arity. If there is no exact match then the next arity capable of taking all arguments is selected.

If the expected number of arguments is lower than the number of arguments actually passed to a wrapper call then the exceeding ones will be ignored.

If the detected number of arguments that the original function expects is higher than the number of arguments really passed then nil values (or other padding values) will be passed as extra arguments.

When a variadic function is detected and its variadic arity is the closest to a number of arguments passed then all of them will be used during a function call (no argument will be ignored).

The relax takes optional named arguments:

:pad-fn – a function that generates values for padding, :pad-val – a value to use for padding instead of nil, :verbose – a switch (defaults to false) that if set to true causes wrapper to return a map containing additional information.

See (doc futils.args/relax*) for more information about :pad-fn and :verbose options.

relax* clj

(relax* f
        &
        {:keys [arities pad-fn variadic verbose pad-val]
         :as uber-args
         :or {verbose false variadic false}})

Returns a variadic function object that calls the given function, adjusting the number of passed arguments to nearest matching arity. It cuts argument list or pads it with nil values if necessary.

It takes 1 positional, obligatory argument, which should be a function (f) and two named, keyword arguments:

:arities – a sorted sequence of argument counts for all arities, :variadic – a flag informing whether the widest arity is variadic.

It also makes use of optional named arguments:

:pad-fn – a function that generates values for padding, :pad-val – a value to use for padding instead of nil, :verbose – a switch (defaults to false) that if set to true, causes wrapper to return a map containing additional information.

To determine the number of arguments the nearest arity is picked up by matching a number of passed arguments to each number from a sequence (passed as :arities keyword argument). If there is no exact match then the next arity capable of handling all arguments is chosen.

If the expected number of arguments is lower than a number of arguments actually passed to a wrapper call, the exceeding ones will be ignored.

If the declared number of arguments that the original function expects is higher than the number of arguments really passed then nil values (or other padding values) will be placed as extra arguments.

When a variadic function is detected and its variadic arity is the closest to the number of passed arguments then all of them will be used.

If the :verbose flag is set the result will be a map containing the following:

:argc-received – a number of arguments received by the wrapper, :argc-sent – a number of arguments passed to a function, :argc-cutted – a number of arguments ignored, :argc-padded – a number of arguments padded with nil values, :args-received – arguments received by the wrapper, :args-sent – arguments passed to a function, :arities – a sorted sequence of argument counts for all arities, :arity-matched – an arity (as a number of arguments) that matched, :engine – a method used to check arities (:clj or :jvm), :result – a result of calling the original function, :variadic – a flag telling that the widest arity is variadic, :variadic-used – a flag telling that a variadic arity was used, :verbose – a verbosity flag (always true in this case).

If a padding function is given (with :pad-fn) it should take keyword arguments. Each call will receive the following:

:argc-received – a number of arguments received by the wrapper, :arity-matched – an arity (as a number of arguments) that matched, :iteration – a number of current iteration (starting from 1), :iterations – a total number of iterations, :previous – a value of previously calculated argument (the result of a previous call or a value of the last positional argument when padding function is called for the first time).

Values associated with :iteration and :previous keys will change during each call, rest of them will remain constant. See (doc futils.utils/frepeat) for more info.

If there is no last argument processed at a time when f is called for the first time (because no arguments were passed), the :previous key is not added to a passed map. That allows to use a default value in a binding map of f or to make easy checks if there would be some previous value (nil is too ambiguous).