net.sf.staccatocommons.control.monad.MonadicFunction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of commons-control Show documentation

The newest version!

/*
 Copyright (c) 2011, The Staccato-Commons Team

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; version 3 of the License.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.
 */
package net.sf.staccatocommons.control.monad;

import net.sf.staccatocommons.defs.Applicable;
import net.sf.staccatocommons.defs.Applicative;

/**
 * A {@link MonadicFunction} is an {@link Applicative} from A to Monad<B>.
 * This interface adds to Applicable a function combinator called Kleisli composition
 * 
 * Fortunately, like with most classes within this package, it is not necessary
 * to understand its formal aspects in order to use it.
 * 
 * @author flbulgarelli
 * @since 1.2
 */
@Applicative
public interface MonadicFunction extends Applicable> {

  /**
   * Combines this function with another using the Kleisli composition.
   * 
   * Functions get combined in the following figure:
   * 
   *    * >----this---+----other---->
   * 
   * 
   * This enables to encapsulate a pipeline of monad transformation all
   * together. For example, the following code:
   * 
   *    * 
   *  Monad<X> monad = ...;
   *  monad.bind(f1).bind(f2).bind(f3).run();
   * 
   * 
   * 
   * Is equivalent to
   * 
   *    * 
   *  Monad<X> monad = ...;
   *  monad.bind(f1.then(f2).then(f3)).run();
   * 
   * 
   * 
   * This lets encapsulate a pipeline of common transformations into a single
   * function, so that it can be reused latter.
   * 
   * 
   * @param 
   * @param other
   * @return new {@link MonadicFunction} that combines this one with the given
   *         function into a pipeline
   */
   MonadicFunction then(Applicable> other);
}