(*
copyright (c) 2013, simon cruanes
all rights reserved.

redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.  redistributions in binary
form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with
the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*)

(** {1 Composable State Machines}

This module defines state machines that should help design applications
with a more explicit control of state (e.g. for networking applications. *)

type ('a, 's, 'b) t = 's -> 'a -> ('b * 's) option
(** transition function that fully describes an automaton *)

type ('a, 's, 'b) automaton = ('a, 's, 'b) t

(** {2 Basic Interface} *)

val empty : ('a, 's, 'b) t
(** empty automaton, ignores state and input, stops *)

val id : ('a, unit, 'a) t
(** automaton that simply returns its inputs, forever *)

val repeat : 'a -> (unit, unit, 'a) t
(** repeat the same output forever, disregarding its inputs *)

val get_state : ('a, 's, _) t -> ('a, 's, 's) t
(** Ignore output and output state instead *)

val next : ('a, 's, 'b) t -> 's -> 'a -> ('b * 's) option
(** feed an input into the automaton, obtaining an output and
    a new state (unless the automaton has stopped) *)

val scan : ('a, 's, 'b) t -> ('a, 's * 'b list, 'b list) t
(** [scan a] accumulates all the successive outputs of [a]
    as its output *)

val map_in : ('a2 -> 'a) -> ('a, 's, 'b) t -> ('a2, 's, 'b) t

val map_out : ('b -> 'b2) -> ('a, 's, 'b) t -> ('a, 's, 'b2) t

val nest : ('a, 's, 'b) t list -> ('a, 's list, 'b list) t
(** runs all automata in parallel on the input.
    The state must be a list of the same length as the list of automata. 
    @raise Invalid_argument otherwise *)

val split : ('a, 's, 'b) t -> ('a, 's, ('b * 'b)) t
(** duplicates outputs *)

val unsplit : ('b -> 'c -> 'd) -> ('a, 's, 'b * 'c) t ->
              ('a, 's, 'd) t
(** combines the two outputs into one using the function *)

val pair : ('a1, 's1, 'b1) t -> ('a2, 's2, 'b2) t ->
           ('a1 * 'a2, 's1 * 's2, 'b1 * 'b2) t
(** pairs two automata together *)

val ( *** ) : ('a1, 's1, 'b1) t -> ('a2, 's2, 'b2) t ->
              ('a1 * 'a2, 's1 * 's2, 'b1 * 'b2) t
(** alias for {!pair} *)

val first : ('a1, 's1, 'b1) t -> (('a1 * 'keep), 's1, ('b1 * 'keep)) t

val second : ('a1, 's1, 'b1) t -> (('keep * 'a1), 's1, ('keep * 'b1)) t

val (>>>) : ('a, 's1, 'b) t -> ('b, 's2, 'c) t ->
            ('a, 's1 * 's2, 'c) t
(** composition (outputs of the first automaton are fed to
    the second one's input) *)

val append : ('a, 's1, 'b) t -> ('a, 's2, 'b) t ->
             ('a, [`Left of 's1 | `Right of 's2], 'b) t
(** [append a b] first behaves like [a], then behaves like [a2]
    once [a1] is exhausted. *)

val flatten : ('a, ('a, 's, 'b) t list * 's, 'b) t
(** runs all automata on the input stream, one by one, until they
    stop. *)

val filter : ('b -> bool) -> ('a, 's, 'b) t -> ('a, 's, 'b option) t
(** [filter f a] yields only the outputs of [a] that satisfy [a] *)

type ('a, 'c, 's1, 's2) flat_map_state =
  ('s1 * (('a, 's2, 'c) t * 's2) option)

val flat_map : ('b -> ('a, 's2, 'c) t * 's2) -> ('a, 's1, 'b) t ->
               ('a, ('a, 'c, 's1, 's2) flat_map_state, 'c) t
(** maps outputs of the first automaton to sub-automata, that are used
    to produce outputs until they are exhausted, at which point the
    first one is used again, and so on *)

(** {2 Mutable Interface} *)

module Mut : sig
  type ('a, 's, 'b) t = {
    next : ('a, 's, 'b) automaton;
    mutable state : 's;
  } (** mutable automaton, with in-place modification *)

  val create : ('a, 's, 'b) automaton -> init:'s -> ('a, 's, 'b) t
  (** create a new mutable automaton *)

  val next : ('a, 's, 'b) t -> 'a -> 'b option
  (** feed an input into the automaton, obtainin and output (unless
      the automaton has stopped) and updating the automaton's state *)

  val copy : ('a, 's, 'b) t -> ('a, 's, 'b) t
  (** copy the automaton into a new one, that can evolve independently *)
end

(** {2 Instances} *)

module Int : sig
  val range : int -> (unit, int, int) t
  (** yields all integers smaller than the argument, then stops *)
end