2.4. Functional combinators

To simplify the generation of functions that can contain potentially complex logic, a number of primitive functions are provided which can be combined in arbitrary ways. This can facilitate the quick creation of functions that can be used as one-liners.

This was primarily developed for Matching/Filtering of IDA types, but is also exposed to the user if they wish to use it in their endeavors. These can be used for creating one-liner functions that transform an input into various types, constructing a function that will consume or test its input, or really just any number of things.

2.4.1. Examples

To create a closure that will return the type of the second element of a structure:

> f = fcompose( fgetitem(1), fattribute('type') )
>
> st = struc.by('MyStructName')
> print f(st)

To create a closure which will try and call __repr__() whilst falling back to formatting as a string if not possible:

> test = fcondition(fhasattr('__repr__'))
> tf = test(fgetattr('__repr__'), "{!s}".format)
> f = fcompose(tf, fcurry())
> print f(object)

To create a closure which will return a string when defined and an empty string when undefined:

> f = fcompose(fdefault(''), "{!s}".format)
> print f('hi')
> print f(None)

2.4.2. Combinators

fpack(callable, *initial_args, **initial_kwargs))(*packed_args, **packed_kwargs)

Given a callable, return a closure that when called with arguments will pack (box) them before applying them to the callable as its first parameter. Any keyword arguments will be merged together when executing the callable.

Parameters:
  • callable (function) – the function which will be called by the returned closure
  • *initial_args – any default arguments to prefix the parameter that is passed to the callable with
  • **initial_kwargs – any default keyword arguments to pass to the callable
  • *packed_args – any number of arguments which are packed and then concatenated together
  • **packed_kwargs – any extra keyword arguments to apply to the callable
funpack(callable, *initial_args, **initial_kwargs)(*packed_args, **packed_kwargs)

Given a callable, return a closure that when called with arguments will unpack (unbox) them before applying them to the callable as its parameters. Any keyword arguments will be merged together when executing the callable.

Parameters:
  • callable (function) – the function which will be called by the returned closure
  • *initial_args – any default arguments to initially pass to the callable
  • **initial_kwargs – any default keyword arguments to initially pass to the callable
  • *packed_args – any number of arguments which are unpacked and then concatenated together
  • **packed_kwargs – any extra keyword arguments to apply to the callable
fcar(callable, *initial_args, **initial_kwargs))(*args, **kwargs)

Given a callable, return a closure that when called with arguments will only use the first element from args parameter appended to the provided initial_args. Any keyword arguments will be merged together when executing the callable. This is similar to the car function found in programming languages from the LISP family.

Parameters:
  • callable (function) – the function which will be called by the returned closure
  • *initial_args – any default arguments to prefix the parameter that is passed to the callable with
  • **initial_kwargs – any default keyword arguments to pass to the callable
  • *args – any number of arguments from which to use only the first one
  • **kwargs – any extra keyword arguments to apply to the callable
fcdr(callable, *initial_args, **initial_kwargs))(*args, **kwargs)

Given a callable, return a closure that when called with arguments will use all except the first element from args parameter and append it to the end of the provided initial_args. Any keyword arguments will be merged together when executing the callable. This is similar to the cdr function found in programming languages from the LISP family.

Parameters:
  • callable (function) – the function which will be called by the returned closure
  • *initial_args – any default arguments to prefix the parameter that is passed to the callable with
  • **initial_kwargs – any default keyword arguments to pass to the callable
  • *args – any number of arguments from which to use only the first one
  • **kwargs – any extra keyword arguments to apply to the callable
finstance(type)(object)

Given a type, return a closure that will return either :py:const`True` or False based on whether object is an instance of the provided type.

Parameters:
  • type (type) – any kind of python type
  • object – any kind of python object to test
Returns:

whether the object is an instance of the requested type or not
Return type:

bool
fhasitem(item)(object)

Given an item, return a closure that will return true or false based on whether or not object contains it via the “contains” operator.

Aliases: fitemQ

Parameters:
  • item – any kind of python object
  • object – any kind of python object to test membership with
Returns:

whether the object has the requested item or not
Return type:

bool
fgetitem(item, *default)(object)

Given an item, return a closure which fetches item from object. If default is specified, then if the item does not exist in object return it instead.

Aliases: fitem

Parameters:
  • item – any kind of python object to pass as the key to the operator.getitem() function
  • object – any kind of python object to return an item from
  • *default – an item returned by default if the object does not contain the specified item
Returns:

the item that was requested
fsetitem(item)(value)(object)

Assign the given value to the specified item of the provided object when called and then return the modified object.

Parameters:
  • item – any kind of python object to pass as the key to the operator.setitem() function
  • value – the value to assign to the python object as used by operator.setitem()
  • object – any kind of python object to assign the item into
Returns:

the object that was modified
fdelitem(*items)(object)

Return a closure that when called with a particular object, will remove the designated items from it prior to returning the modified object.

Parameters:
  • *items – any number of python objects to pass as keys to the operator.delitem() function
  • object – any kind of python object to remove the items from
Returns:

the object that was modified
fhasattr(attribute)(object)

Given an attribute as a string, return a closure that will return True or False based on whether or not object has the specified attribute.

Aliases: fattributeQ

Parameters:
  • attribute (str) – the attribute to check for
  • object – any kind of python object to test
Returns:

whether the object has the requested attribute or not
Return type:

bool
fgetattr(attribute, *default)(object)

Given an attribute, return a closure which fetches the attribute from the object. If default is specified, then if the attribute does not exist in object return it instead.

Aliases: fattribute

Parameters:
  • attribute (str) – an attribute to return from the object
  • object – any kind of python object to return an attribute from
  • *default – an attribute returned by default if the object does not contain with specified attribute
Returns:

the requested attribute
fsetattr(attribute)(value)(object)

Assign the given value to the specified attribute of the provided object when called and return the object.

Aliases: fsetattribute

Parameters:
  • attribute – an attribute on the object to assign.
  • value – the value to assign to the python object as used by builtins.setattr().
  • object – any kind of python object to assign the attribute on.
Returns:

the object that was modified
fconstant(object)

Return a closure that always returns the provided object.

Aliases: fconst, falways

Parameters:object – any kind of python object to return
Returns:a closure that returns the object
fidentity(object)

Given an object, return it. This is the identity function and is typically used to ignore transforming an object.

Parameters:object – any kind of python object to return
Returns:the object
fdefault(default)(object)

Given a default object, return a closure that will return it if object is not defined (false-y).

Parameters:
  • default – the default object to return
  • object – any kind of python object to check
Returns:

the object if it is defined, otherwise the value for default
fcompose(*callables)(object)

Given a number of callables, return a closure that executes them in succession whilst returning the result.

Parameters:
  • *callables – a number of callables that each take one parameter
  • object – any kind of python object to transform
fdiscard(callable, *initial_args, **initial_kwargs)(*args, **kwargs)

Given a callable and any initial_args or initial_kwargs, return a closure that will call it with only those parameters whilst discarding any parameters that were passed to the returned closure.

Parameters:
  • callable (function) – a callable to execute
  • *initial_args – any default arguments to pass as parameters to the callable
  • **initial_kwargs – any default keyword arguments to pass as parameters to the callable
  • *args – any number of arguments that get discarded
  • **kwargs – any kind of keyword arguments that get discarded
fcondition(crit)(true, false)(object)

Given a critiquing function crit, return a closure which takes parameters for true and false. This will return another closure that when passed an object, will check it via the critiquing function (crit) and return true if the function returns a truthy value, or return false if it returns a false-y value.

Parameters:
  • crit (function) – a callable that takes an argument and returns true or false
  • true (object or function) – an object or a function to return (or execute) when value is true
  • false (object or function) – an object or a function to return (or execute) when value is false
  • object – any kind of python object to pass to crit
fmap(*callables)(object)

Given a number of callables, return a closure that executes them synchronously against object returning a tuple composed of the results of each callable.

Parameters:
  • *callables – any number of callables to execute for each desired result returned
  • object – any kind of python object to use
flazy(callable, *initial_args, **initial_kwargs)(*args, **kwargs)

Given a callable, and any initial_args and initial_kwargs, return a closure that caches (memoizes) the result that is returned. The next time this closure is called with the same arguments, the cached version will be returned instead.

Parameters:
  • callable (function) – any callable to execute lazily and memoize its result for
  • *initial_args – any initial arguments to prefix to the callable
  • **initial_kwargs – any initial keyword arguments to apply to the callable
  • *args – any arguments to apply to the callable
  • **kwargs – any keyword arguments to apply to the callable
fpartial(callable, *start_args, **start_kwargs)(*args, **kwargs)

Given a callable, partially apply the arguments specified in both start_args and start_kwargs. This will return a closure that can then be called with any other args or keyword arguments in kwargs.

Parameters:
  • callable (function) – any callable to partially apply arguments to
  • *start_args – initial arguments to partially apply to the callable
  • **start_kwargs – initial keyword arguments to partially apply to the callable
  • *args – arguments to continue to apply to the callable
  • **kwargs – any keyword arguments to continue to apply to the callable
fapply(callable, *initial_args, **initial_kwargs)(*args, **kwargs)

Given a callable, return a closure that will apply both the arguments (args) and keyword arguments (kwargs) to it.

Parameters:
  • callable (function) – any callable to apply arguments to
  • *args – the arguments to apply to the callable
  • **kwargs – the keyword arguments to apply to the callable
  • *initial_args – any initial arguments to prefix the args with
  • **initial_kwargs – any initial keyword args to prefix the kwargs with
fcurry(*default_args, **default_kwargs)(callable, *args, **kwargs)

Given default_args and default_kwargs, return a closure that will apply these arguments to its first parameter callable. If args or kwargs is specified, the append these to the default arguments.

Parameters:
  • *default_args – the arguments to apply to the callable
  • **default_kwargs – the keyword arguments to apply to the callable
  • callable (function) – the callable to apply the arguments to
  • *args – any extra arguments to apply to the callable
  • **kwargs – any extra keyword arguments to apply to the callable
frpartial(callable, *reverse_args, **reverse_kwargs)(*args, **kwargs)

Given a callable, the arguments reverse_args, and the keyword arguments reverse_kwargs, return a closure that will apply these to the callable in reverse. If args or kwargs is provided, then apply these to the front of the callable.

Parameters:
  • callable (function) – the callable to apply the arguments to
  • *reverse_args – the arguments to apply to the end of the callable
  • **reverse_kwargs – the keyword arguments to apply to the callable
  • *args – the arguments to apply to the beginning of the callable
  • **kwargs – any extra keyword arguments to apply to the callable
freverse(callable, *reverse_args, **reverse_kwargs)(*extra_args, **extra_kwargs)

Given a callable, the arguments reverse_args, and the keyword arguments reverse_kwargs, return a closure which applies these to the end of the callable. If extra_args or extra_kwargs is provided, then continue to apply these to the callable but in reverse.

Parameters:
  • callable (function) – the callable to apply the arguments to
  • *reverse_args – the arguments to apply to the end of callable
  • **reverse_kwargs – the keyword arguments to apply to callable
  • *extra_args – extra arguments to continue to apply to kwargs
  • **extra_kwargs – any extra keyword arguments to apply to callable
fcatch(callable, *initial_args, **initial_kwargs)(*args, **kwargs)

Given a callable, return a closure that will call it with the arguments initial_args combined with args, and the keyword arguments initial_kwargs combined with kwargs.

This closure will wrap the result of callable so that the second element of the returned tuple will be the result, and the first element will be the exception object if one was raised. If an exception was not raised, then the first element will be the value None, and the second will be the original result.

Parameters:
  • callable (function) – the callable to catch an exception in
  • *initial_args – the initial arguments to apply to the callable
  • **initial_kwargs – the initial keyword arguments to apply to the callable
  • *args – the arguments to apply to the callable
  • **kwargs – the keyword arguments to apply to the callable
fcomplement(callable, *initial_args, **initial_kwargs)(*args, **kwargs)

Given a callable, the arguments initial_args, and the keyword arguments initial_kwargs, return a closure that will invert the result (not) prior to returning it.

Aliases: fnot

Parameters:
  • callable (function) – the callable to invert the result for
  • *initial_args – the initial arguments to apply to the callable
  • **initial_args – the initial keyword arguments to apply to the callable
  • *args – the arguments to apply to the callable
  • **kwargs – the keyword arguments to apply to the callable
first(listable)

Given a listable object, return the first element in its sequence.

Parameters:listable (list or tuple) – any kind of list-like object
Returns:the first element from the iterable
second(iterable)

Given a listable object, return the second element in its sequence.

Parameters:listable (list or tuple) – any kind of list-like object
Returns:the second element from the iterable
third(iterable)

Given a listable object, return the third element in its sequence.

Parameters:listable (list or tuple) – any kind of list-like object
Returns:the third element from the iterable
last(iterable)

Given a listable object, return the last element in its sequence.

Parameters:listable (list or tuple) – any kind of list-like object
Returns:the last element from the iterable
ilist(iterable)

Given an iterable object, return it as a list.

Parameters:iterable – any kind of iterable object
Returns:the items from the iterator
Return type:list
liter(listable)

Given a listable object, return it as an iterable.

Parameters:listable (list or tuple) – any kind of list-like object
Returns:an iterator composed of the items from the list
ituple(iterable)

Given an iterable object, return it as a tuple.

Parameters:iterable – any kind of iterable object
Returns:the items from the iterator
Return type:tuple
titer(tuple)

Given a tuple, return it as an iterator.

Parameters:tuple (tuple) – any kind of python tuple
Returns:an iterator composed of the items from the tuple
itake(count)(iterable)

Given an integer count, return a closure that will consume that number of elements from the provided iterable and return them as a tuple.

Parameters:
  • count (int or long) – a number of elements to consume
  • iterable – an iterable to consume
Returns:

the items that were selected
Return type:

tuple
iget(index)(iterable)

Given an integer index, return a closure that will consume the required number of elements from the provided iterable in order to return the element at the requested index.

Parameters:
  • count (int or long) – a number of elements to consume
  • iterable – an iterable to consume values from
Returns:

the item at the requested index
islice(iterable, stop)
islice(iterable, start, stop[, step])

Given an iterable, return an iterator which yields the selected values from start to stop. If step is provided, then use its value as the number of values to skip when yielding values. This is similar to using the operator.getitem() function with the slice class for iterators.

Parameters:
  • iterable – an iterable to transform results from
  • start (int or long) – the index to start at
  • stop (int or long) – the index to stop at
  • step (int or long) – the number of values to skip
Returns:

the selected items as an iterator
imap(callable, iterable)

Execute the provided callable against all of the elements in iterable returning an iterator containing the transformed results. This is similar to map() and is the same as the itertools.imap() function from Python 2.x, or the regular map() function from Python 3.x.

Parameters:
  • callable (function) – a callable python object that transforms its argument
  • iterable – an iterable to transform results from
Returns:

the transformed items as an iterator
ifilter(crit, iterable)

Yield each value from iterable that the callable crit returns True for. This is similar to filter() and is the same as the itertools.ifilter() function from Python 2.x, or the regular filter() function from Python 3.x.

Parameters:
  • crit (function) – a callable python object that returns True or False based on its argument
  • iterable – an iterable to critique
Returns:

the filtered items as an iterator
ichain(*iterables)

Given a variable number of iterables, concatenate all of them into a single iterator. This is the same as the itertools.chain(). function.

Parameters:*iterables – any number of iterators
Returns:an iterator composed of all of the provided iterators executed in sequence
izip(*iterables)

Given any number of iterables, return them as an iterator that yields a tuple for each element passed as positional arguments to the function. This is similar to zip(), and is the same as the itertools.izip() function from Python 2.x, or the regular zip() function from Python 3.x.

Parameters:*iterables – any number of iterators
Returns:the items from each iterator zipped together
lslice(iterable, stop)
lslice(iterable, start, stop[, step])

Given an iterable, return a list containing the selected values from start to stop. If step is provided, then use its value as the number of values to skip when returning values. This is similar to the operator.getitem() function being used on lists with the slice class.

Parameters:
  • iterable – an iterable to transform results from
  • start (int or long) – the index to start at
  • stop (int or long) – the index to stop at
  • step (int or long) – the number of values to skip
Returns:

the selected list of items
Return type:

list
lmap(callable, iterable)

Execute the provided callable against all of the elements in iterable returning a list containing the transformed results. This is similar to map() function from Python 2.x, or using the map() function from Python 3.x and iterating through the result as a list.

Parameters:
  • callable (function) – a callable python object that transforms its argument
  • iterable – an iterable to transform results from
Returns:

the transformed list of items
Return type:

list
lfilter(crit, iterable)

Return a list containing each value from iterable that the callable crit returns True for. This is similar to the filter() function from Python 2.x, or using the filter() function from Python 3.x and iterating through the result as a list.

Parameters:
  • crit (function) – a callable python object that returns True or False based on its argument
  • iterable – an iterable to critique
Returns:

the filtered list of items
Return type:

list
lzip(*iterables)

Given any number of iterables, return them as a list composed of tuple objects for each element passed as positional arguments to the function. This is similar to the zip() function from Python 2.x, or the zip() function from Python 3.x and iterating through the reuslt as a list.

Parameters:*iterables – any number of iterators
Returns:the items from each iterator zipped together
Return type:list of tuple
count(iterable)

Given an iterable, return the number of items that it contains.

Note: This is done by consuming values from iterable which will modify its state. If the state of the iterator wishes to be retained, one can either re-create it, or make a copy of it using itertools.tee().

Parameters:iterable – an iterator to count the elements of
Returns:the number of items that were found
Return type:int or long