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 staccatissimo-control Show documentation
The newest version!
/**
 *  Copyright (c) 2010-2012, The StaccatoCommons 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();
   * 
   * 
   * 
   * and
   *    * 
   *  MonadicFunction<X, Y> f1 = ...;
   *  f1.apply(x).bind(f2).bind(f3).run();
   * 
   * 
   * 
   * Is equivalent to
   * 
   *    * 
   *  MonadicFunction<X, Y> f1 = ...;
   *  f1.then(f2).then(f3).apply(x).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);
}