<commit_before><?php
/**
 * Created by PhpStorm.
 * User: rgladson
 * Date: 1/6/2016
 * Time: 11:03 AM
 */

namespace PHPixme;

/**
 * Class Attempt
 * Attempt is equivalent to a Try ... Catch block in a object oriented form,
 * providing a consistency to the flow of data through functions which are
 * not applied on errors unless transformed. It also provides transformations
 * to options, and share some of it's methods, such as get, and getOrElse.
 * Note: Some of these methods will throw Exceptions if their contract
 * with a callback function is not met. They will not catch these kinds of errors.
 * @package PHPixme
 */
abstract class Attempt implements
  CollectionInterface
  , UnaryApplicativeInterface
  , \Countable
{
  use AssertTypeTrait, ClosedTrait;
  const shortName = 0;

  /**
   * @param callable $value
   * @return Failure|Success
   */
  public static function of($value)
  {
    return Attempt($value);
  }

  /**
   * @return boolean
   */
  abstract public function isFailure();

  /**
   * @return boolean
   */
  abstract public function isSuccess();

  /**
   * @return mixed - Get the value contained on success
   * @throws mixed - throws the value on failure
   */
  abstract public function get();

  /**
   * @param $default
   * @return mixed
   */
  public function getOrElse($default)
  {
    return $this->isSuccess() ? $this->get() : $default;
  }

  /**
   * @param callable $hof (): Attempt
   * @return Attempt
   * @throws \Exception on function not returning a Attempt subtype
   */
  public function orElse(callable $hof)
  {
    if ($this->isSuccess()) {
      return $this;
    }
    try {
      $result = $hof();
    } catch (\Exception $e) {
      return Failure($e);
    }
    return Attempt::assertType($result);
  }


  /**
   * Changes a Failure to a success.
   * If called on a Success, it will return a failure with an unsupported action exception
   * @return Attempt
   */
  abstract public function failed();

  /**
   * Map $hof across the success value
   * @param callable $hof ($value, $key, Success $container): static
   * @return Attempt - Success($hof($value)) or the same Failure as before
   */
  abstract public function map(callable $hof);

  /**
   * Tries to recover the error value as a success using $rescueException.
   * Has no affect on Success
   * @param callable $rescueException ($value, $container): mixed ! \Exception
   * @return Attempt - If return, type Success, If Thrown, type Failure
   */
  abstract public function recover(callable $rescueException);

  /**
   * Recovers using a $hof which returns either a Success or Failure.
   * @param callable $hof ($value, $container) : Attempt
   * @return Attempt
   * @throws \Exception When $rescueException does not return an Attempt type
   */
  abstract public function recoverWith(callable $hof);


  /**
   * Returns an array with the value at the { @see static::shortName ::shortName } offset
   * @return array
   */
  public function toArray()
  {
    try {
      return [$this::shortName => $this->get()];
    } catch (\Exception $e) {
      return [$this::shortName => $e];
    }<commit_msg>documenting non-inherited from interface filter function in Attempt, which both already implement. (cherry picked from commit 0db9e44)<commit_after><?php
/**
 * Created by PhpStorm.
 * User: rgladson
 * Date: 1/6/2016
 * Time: 11:03 AM
 */

namespace PHPixme;

/**
 * Class Attempt
 * Attempt is equivalent to a Try ... Catch block in a object oriented form,
 * providing a consistency to the flow of data through functions which are
 * not applied on errors unless transformed. It also provides transformations
 * to options, and share some of it's methods, such as get, and getOrElse.
 * Note: Some of these methods will throw Exceptions if their contract
 * with a callback function is not met. They will not catch these kinds of errors.
 * @package PHPixme
 */
abstract class Attempt implements
  CollectionInterface
  , UnaryApplicativeInterface
  , \Countable
{
  use AssertTypeTrait, ClosedTrait;
  const shortName = 0;

  /**
   * @param callable $value
   * @return Failure|Success
   */
  public static function of($value)
  {
    return Attempt($value);
  }

  /**
   * @return boolean
   */
  abstract public function isFailure();

  /**
   * @return boolean
   */
  abstract public function isSuccess();

  /**
   * @return mixed - Get the value contained on success
   * @throws mixed - throws the value on failure
   */
  abstract public function get();

  /**
   * @param $default
   * @return mixed
   */
  public function getOrElse($default)
  {
    return $this->isSuccess() ? $this->get() : $default;
  }

  /**
   * @param callable $hof (): Attempt
   * @return Attempt
   * @throws \Exception on function not returning a Attempt subtype
   */
  public function orElse(callable $hof)
  {
    if ($this->isSuccess()) {
      return $this;
    }
    try {
      $result = $hof();
    } catch (\Exception $e) {
      return Failure($e);
    }
    return Attempt::assertType($result);
  }


  /**
   * Changes a Failure to a success.
   * If called on a Success, it will return a failure with an unsupported action exception
   * @return Attempt
   */
  abstract public function failed();

  /**
   * Map $hof across the success value
   * @param callable $hof ($value, $key, Success $container): static
   * @return Attempt - Success($hof($value)) or the same Failure as before
   */
  abstract public function map(callable $hof);

  /**
   * Tries to recover the error value as a success using $rescueException.
   * Has no affect on Success
   * @param callable $rescueException ($value, $container): mixed ! \Exception
   * @return Attempt - If return, type Success, If Thrown, type Failure
   */
  abstract public function recover(callable $rescueException);

  /**
   * Recovers using a $hof which returns either a Success or Failure.
   * @param callable $hof ($value, $container) : Attempt
   * @return Attempt
   * @throws \Exception When $rescueException does not return an Attempt type
   */
  abstract public function recoverWith(callable $hof);


  /**
   * Convert a Success into a failure based on the result of the callback
   * If the return is true or the container is Failure, it will return an identity
   * If the callback throws or returns false, it will produce a new Failure with the exception.
   * @param callable $hof ($value, $key, $container)-> boolean
   * @return Attempt
   */
  abstract public function filter(callable $hof);
  
  /**
   * Returns an array with the value at the { @see static::shortName ::shortName } offset
   * @return array
   */
  public function toArray()
  {
    try {
      return [$this::shortName => $this->get()];
    } catch (\Exception $e) {
      return [$this::shortName => $e];
    }
{'fraction_non_alphanumeric': 0.10665491405905686, 'fraction_numerical': 0.003819597473189364, 'mean_word_length': 3.0596302921884315, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 16, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4976064', 'n_tokens_mistral': 2001, 'n_tokens_neox': 1890, 'n_words': 762}