def equals(value):
    '''
    Returns a function that when called will check the called value with the given value for equality
    '''
    return lambda called_value: value == called_value

def reverse(collection):
    return collection[::-1]


def unpack_args(fn, args):
    '''
    Functionally unpack a collection of arguments.
    Handles case where args is not a collection and will call fn without unpacking..
    '''
    if isinstance(args, Iterable):
        return fn(*args)
    return fn(args)


def compose(*fns):
    '''
    Returns a function composed of the given functions where the first function is the outermost in the composition.

    Example:
    >>> compose(sum, list, set)([1,2,])
    3

    Equivalent to:
    >>> sum(list(set([1,2])))
    3
    '''
    def comp(args, func, *fns):
        if fns:
            return func(comp(args, fns[0], *fns[1:]))
        return func(*args)

    return lambda *args: comp(args, fns[0], *fns[1:])


def partial_front(fn, *args):
    '''
    A partial where the returned function places it's given values in front of the partial values.

    Example:
    >>> join = lambda a,b,c: a+b+c
    >>> partial_first(join, [1,2])([3], [4])
    [3, 4, 1, 2]
    '''
    return lambda *call_args: fn(*(call_args + args))


def partial_as(fn, *args):
    '''
    A partial where the position of the called arguments are specified with {}.

    Note: This is dangerous in the case that a partialized value may be an empty dict unintentionally

    Example:
    >>> join = lambda a,b,c,d: a+b+c+d
    >>> fntools.partial_as(join, [1], {}, [3], {})([3], [4])
    [1, 3, 3, 4]
    '''
    def replace_placeholders(args, call_args):
        if len(filter(equals({}), args)) == len(call_args):
            for i, arg in enumerate(args):
                if arg == {}:
                    args[i] = call_args.pop(0)
            return args
        if not args:
            return call_args
        raise Exception("Number of placeholders does not match number of given arguments")

    return lambda *call_args: fn(*replace_placeholders(list(args), list(call_args)))


def thread_with(value, partial_func, *forms):
    '''
    Thread the given value through the list of forms with partial_func applied.
    '''
    return compose(*map(partial(unpack_args, partial_func), reverse(forms)))(value)


def thread_first(value, *forms):
    '''
    Returns the given value threaded through the given collection of forms as the first argument.

    A form is a function or a tuple containing a function as its first element and a list of arguments.
    The return value of the previously called function will be threaded in as the first argument to the next function.
    Use this to flatten nested function calls.

    Example:
    >>> def add(a, b):
    ...     return a + b
    ...

    >>> add(list((1,2,)), [3])
    [1, 2, 3]

    >>> thread_first((1,2,), list, (add, [3]))
    [1, 2, 3]
    '''
    return thread_with(value, partial_front, *forms)


def thread_last(value, *forms):
    '''
    Returns the given value threaded through the given collection of forms as the last argument.
    Refer to docs above.

    Example:
    >>> thread_last((1,2,), list, (add, [3]))
    [3, 1, 2]
    '''
    return thread_with(value, partial, *forms)


def thread_as(value, *forms):
    '''
    Returns the given value threaded through the given collection of forms in the position of the argument defined by a {}.

    Example:
    >>> join = lambda a,b,c: a+b+c
    ...
    >>> thread_as([2], (join, [1], {}, [3]), set)
    set([1, 2, 3])
    '''
    return thread_with(value, partial_as, *forms)