-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | CAES Language for Synchronous Hardware - Prelude library
--   
--   CλaSH (pronounced ‘clash’) is a functional hardware description
--   language that borrows both its syntax and semantics from the
--   functional programming language Haskell. The CλaSH compiler transforms
--   these high-level descriptions to low-level synthesizable VHDL,
--   Verilog, or SystemVerilog.
--   
--   Features of CλaSH:
--   
--   <ul>
--   <li>Strongly typed, but with a very high degree of type inference,
--   enabling both safe and fast prototyping using concise
--   descriptions.</li>
--   <li>Interactive REPL: load your designs in an interpreter and easily
--   test all your component without needing to setup a test bench.</li>
--   <li>Higher-order functions, with type inference, result in designs
--   that are fully parametric by default.</li>
--   <li>Synchronous sequential circuit design based on streams of values,
--   called <tt>Signal</tt>s, lead to natural descriptions of feedback
--   loops.</li>
--   <li>Support for multiple clock domains, with type safe clock domain
--   crossing.</li>
--   </ul>
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a></li>
--   <li>Alternatively, if you want to explicitly route clock and reset
--   ports, for more straightforward multi-clock designs, you can import
--   the <a>Clash.Explicit.Prelude</a> module. Note that you should not
--   import <a>Clash.Prelude</a> and <a>Clash.Explicit.Prelude</a> at the
--   same time as they have overlapping definitions.</li>
--   </ul>
--   
--   A preliminary version of a tutorial can be found in
--   <a>Clash.Tutorial</a>, for a general overview of the library you
--   should however check out <a>Clash.Prelude</a>. Some circuit examples
--   can be found in <a>Clash.Examples</a>.
@package clash-prelude
@version 0.99.2


-- | Instruct the clash compiler to look for primitive HDL templates in the
--   indicated directory. For distribution of new packages with primitive
--   HDL templates.
module Clash.Annotations.Primitive
data HDL
SystemVerilog :: HDL
Verilog :: HDL
VHDL :: HDL

-- | The <a>Primitive</a> constructor instructs the clash compiler to look
--   for primitive HDL templates in the indicated directory.
--   <a>InlinePrimitive</a> is equivalent but provides the HDL template
--   inline. They are intended for the distribution of new packages with
--   primitive HDL templates.
--   
--   <h3>Example of <a>Primitive</a></h3>
--   
--   You have some existing IP written in one of HDLs supported by Clash,
--   and you want to distribute some bindings so that the IP can be easily
--   instantiated from Clash.
--   
--   You create a package which has a <tt>myfancyip.cabal</tt> file with
--   the following stanza:
--   
--   <pre>
--   data-files: path/to/MyFancyIP.json
--   cpp-options: -DCABAL
--   </pre>
--   
--   and a <tt>MyFancyIP.hs</tt> module with the simulation definition and
--   primitive.
--   
--   <pre>
--   module MyFancyIP where
--   
--   import Clash.Prelude
--   
--   myFancyIP :: ...
--   myFancyIP = ...
--   {-# NOINLINE myFancyIP #-}
--   </pre>
--   
--   The <tt>NOINLINE</tt> pragma is needed so that GHC will never inline
--   the definition.
--   
--   Now you need to add the following imports and <tt>ANN</tt> pragma:
--   
--   <pre>
--   #ifdef CABAL
--   import           Clash.Annotations.Primitive
--   import           System.FilePath
--   import qualified Paths_myfancyip
--   import           System.IO.Unsafe
--   
--   {-# ANN module (Primitive VHDL (unsafePerformIO Paths_myfancyip.getDataDir &lt;/&gt; "path" &lt;/&gt; "to")) #-}
--   #endif
--   </pre>
--   
--   Add more files to the <tt>data-files</tt> stanza in your
--   <tt>.cabal</tt> files and more <tt>ANN</tt> pragma's if you want to
--   add more primitive templates for other HDLs
--   
--   <h3>Example of <a>InlinePrimitive</a></h3>
--   
--   The following example shows off an inline HDL primitive template. It
--   uses the <a>interpolate</a> package for nicer multiline strings.
--   
--   <pre>
--   {-# LANGUAGE DataKinds   #-}
--   {-# LANGUAGE QuasiQuotes #-}
--   
--   module InlinePrimitive where
--   
--   import           Clash.Annotations.Primitive
--   import           Clash.Prelude
--   import           Data.String.Interpolate      (i)
--   import           Data.String.Interpolate.Util (unindent)
--   
--   {-# ANN example (InlinePrimitive VHDL $ unindent [i|
--     [ { "BlackBox" :
--         { "name" : "InlinePrimitive.example"
--         , "templateD" :
--     "-- begin InlinePrimitive example:
--     ~GENSYM[example][0] : block
--     ~RESULT &lt;= 1 + ~ARG[0];
--     end block;
--     -- end InlinePrimitive example"
--         }
--       }
--     ]
--     |]) #-}
--   {-# NOINLINE example #-}
--   example :: Signal System (BitVector 2) -&gt; Signal System (BitVector 2)
--   example = fmap succ
--   </pre>
data Primitive

-- | Description of a primitive for a given <a>HDL</a> in a file at
--   <a>FilePath</a>
Primitive :: HDL -> FilePath -> Primitive

-- | Description of a primitive for a given <a>HDL</a> as an inline
--   <a>String</a>
InlinePrimitive :: HDL -> String -> Primitive
instance Data.Data.Data Clash.Annotations.Primitive.Primitive
instance GHC.Read.Read Clash.Annotations.Primitive.Primitive
instance GHC.Show.Show Clash.Annotations.Primitive.Primitive
instance Data.Data.Data Clash.Annotations.Primitive.HDL
instance GHC.Read.Read Clash.Annotations.Primitive.HDL
instance GHC.Show.Show Clash.Annotations.Primitive.HDL
instance GHC.Classes.Eq Clash.Annotations.Primitive.HDL


-- | <a>TopEntity</a> annotations allow us to control hierarchy and naming
--   aspects of the CλaSH compiler. We have the <a>Synthesize</a> and
--   <a>TestBench</a> annotation.
--   
--   <h3><a>Synthesize</a> annotation</h3>
--   
--   The <a>Synthesize</a> annotation allows us to:
--   
--   <ul>
--   <li>Assign names to entities (VHDL) / modules ((System)Verilog), and
--   their ports.</li>
--   <li>Put generated HDL files of a logical (sub)entity in their own
--   directory.</li>
--   <li>Use cached versions of generated HDL, i.e., prevent recompilation
--   of (sub)entities that have not changed since the last run. Caching is
--   based on a <tt>.manifest</tt> which is generated alongside the HDL;
--   deleting this file means deleting the cache; changing this file will
--   result in <i>undefined</i> behaviour.</li>
--   </ul>
--   
--   Functions with a <a>Synthesize</a> annotation must adhere to the
--   following restrictions:
--   
--   <ul>
--   <li>Although functions with a <a>Synthesize</a> annotation can of
--   course depend on functions with another <a>Synthesize</a> annotation,
--   they must not be mutually recursive.</li>
--   <li>Functions with a <a>Synthesize</a> annotation must be completely
--   <i>monomorphic</i> and <i>first-order</i>, and cannot have any
--   <i>non-representable</i> arguments or result.</li>
--   </ul>
--   
--   Also take the following into account when using <a>Synthesize</a>
--   annotations.
--   
--   <ul>
--   <li>The CλaSH compiler is based on the GHC Haskell compiler, and the
--   GHC machinery does not understand <a>Synthesize</a> annotations and it
--   might subsequently decide to inline those functions. You should
--   therefor also add a <tt>{-# NOINLINE f #-}</tt> pragma to the
--   functions which you give a <a>Synthesize</a> functions.</li>
--   <li>Functions with a <a>Synthesize</a> annotation will not be
--   specialised on constants.</li>
--   </ul>
--   
--   Finally, the root module, the module which you pass as an argument to
--   the CλaSH compiler must either have:
--   
--   <ul>
--   <li>A function with a <a>Synthesize</a> annotation.</li>
--   <li>A function called <i>topEntity</i>.</li>
--   </ul>
--   
--   You apply <a>Synthesize</a> annotations to functions using an
--   <tt>ANN</tt> pragma:
--   
--   <pre>
--   {-# ANN f (Synthesize {t_name = ..., ...  }) #-}
--   f x = ...
--   </pre>
--   
--   For example, given the following specification:
--   
--   <pre>
--   module Blinker where
--   
--   import Clash.Prelude
--   import Clash.Intel.ClockGen
--   
--   type Dom50 = Dom "System" 20000
--   
--   topEntity
--     :: Clock Dom50 Source
--     -&gt; Reset Dom50 Asynchronous
--     -&gt; Signal Dom50 Bit
--     -&gt; Signal Dom50 (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = <a>altpll</a> (SSymbol @ "altpll50") clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (<a>unsafeToAsyncReset</a> pllStable)
--       in   <a>exposeClockReset</a> leds pllOut rstSync
--     where
--       key1R  = <a>isRising</a> 1 key1
--       leds   = <a>mealy</a> blinkerT (1,False,0) key1R
--   
--   blinkerT (leds,mode,cntr) key1R = ((leds',mode',cntr'),leds)
--     where
--       -- clock frequency = 50e6  (50 MHz)
--       -- led update rate = 333e-3 (every 333ms)
--       cnt_max = 16650000 -- 50e6 * 333e-3
--   
--       cntr' | cntr == cnt_max = 0
--             | otherwise       = cntr + 1
--   
--       mode' | key1R     = not mode
--             | otherwise = mode
--   
--       leds' | cntr == 0 = if mode then complement leds
--                                   else rotateL leds 1
--             | otherwise = leds
--   </pre>
--   
--   The CλaSH compiler would normally generate the following
--   <tt>blinker_topentity.vhdl</tt> file:
--   
--   <pre>
--   -- Automatically generated VHDL-93
--   library IEEE;
--   use IEEE.STD_LOGIC_1164.ALL;
--   use IEEE.NUMERIC_STD.ALL;
--   use IEEE.MATH_REAL.ALL;
--   use std.textio.all;
--   use work.all;
--   use work.blinker_types.all;
--   
--   entity blinker_topentity is
--     port(-- clock
--          input_0  : in std_logic;
--          -- asynchronous reset: active high
--          input_1  : in std_logic;
--          input_2  : in std_logic_vector(0 downto 0);
--          output_0 : out std_logic_vector(7 downto 0));
--   end;
--   
--   architecture structural of blinker_topentity is
--   begin
--     blinker_topentity_0_inst : entity blinker_topentity_0
--       port map
--         (clk    =&gt; input_0
--         ,rst    =&gt; input_1
--         ,key1   =&gt; input_2
--         ,result =&gt; output_0);
--   end;
--   </pre>
--   
--   However, if we add the following <a>Synthesize</a> annotation in the
--   file:
--   
--   <pre>
--   {-# ANN topEntity
--     (<a>Synthesize</a>
--       { t_name   = "blinker"
--       , t_inputs = [ PortName "CLOCK_50"
--                    , PortName "KEY0"
--                    , PortName "KEY1" ]
--       , t_output = PortName "LED"
--       }) #-}
--   </pre>
--   
--   The CλaSH compiler will generate the following <tt>blinker.vhdl</tt>
--   file instead:
--   
--   <pre>
--   -- Automatically generated VHDL-93
--   library IEEE;
--   use IEEE.STD_LOGIC_1164.ALL;
--   use IEEE.NUMERIC_STD.ALL;
--   use IEEE.MATH_REAL.ALL;
--   use std.textio.all;
--   use work.all;
--   use work.blinker_types.all;
--   
--   entity blinker is
--     port(-- clock
--          CLOCK_50 : in std_logic;
--          -- asynchronous reset: active high
--          KEY0     : in std_logic;
--          KEY1     : in std_logic_vector(0 downto 0);
--          LED      : out std_logic_vector(7 downto 0));
--   end;
--   
--   architecture structural of blinker is
--   begin
--     blinker_topentity_inst : entity blinker_topentity
--       port map
--         (clk    =&gt; CLOCK_50
--         ,rst    =&gt; KEY0
--         ,key1   =&gt; KEY1
--         ,result =&gt; LED);
--   end;
--   </pre>
--   
--   Where we now have:
--   
--   <ul>
--   <li>A top-level component that is called <tt>blinker</tt>.</li>
--   <li>Inputs and outputs that have a <i>user</i>-chosen name:
--   <tt>CLOCK_50</tt>, <tt>KEY0</tt>, <tt>KEY1</tt>, <tt>LED</tt>,
--   etc.</li>
--   </ul>
--   
--   See the documentation of <a>Synthesize</a> for the meaning of all its
--   fields.
--   
--   <h3><a>TestBench</a> annotation</h3>
--   
--   Tell what binder is the <a>TestBench</a> for a
--   <a>Synthesize</a>-annotated binder.
--   
--   So in the following example, <i>f</i> has a <a>Synthesize</a>
--   annotation, and <i>g</i> is the HDL test bench for <i>f</i>.
--   
--   <pre>
--   f :: Bool -&gt; Bool
--   f = ...
--   {-# ANN f (defSyn "f") #-}
--   {-# ANN f (TestBench 'g) #-}
--   
--   g :: Signal Bool
--   g = ...
--   </pre>
module Clash.Annotations.TopEntity

-- | TopEntity annotation
data TopEntity

-- | Instruct the Clash compiler to use this top-level function as a
--   separately synthesizable component.
Synthesize :: String -> [PortName] -> PortName -> TopEntity

-- | The name the top-level component should have, put in a correspondingly
--   named file.
[t_name] :: TopEntity -> String

-- | List of names that are assigned in-order to the inputs of the
--   component.
[t_inputs] :: TopEntity -> [PortName]

-- | Name assigned in-order to the outputs of the component. As a Haskell
--   function can only truly return a single value -- with multiple values
--   "wrapped" by a tuple -- this field is not a list, but a single
--   <tt><a>PortName</a></tt>. Use <tt><a>PortProduct</a></tt> to give
--   names to the individual components of the output tuple.
[t_output] :: TopEntity -> PortName

-- | Tell what binder is the <a>TestBench</a> for a
--   <a>Synthesize</a>-annotated binder.
--   
--   So in the following example, <i>f</i> has a <a>Synthesize</a>
--   annotation, and <i>g</i> is the HDL test bench for <i>f</i>.
--   
--   <pre>
--   f :: Bool -&gt; Bool
--   f = ...
--   {-# ANN f (defSyn "f") #-}
--   {-# ANN f (TestBench 'g) #-}
--   
--   g :: Signal Bool
--   g = ...
--   </pre>
TestBench :: Name -> TopEntity

-- | Give port names for arguments/results.
--   
--   Give a data type and function:
--   
--   <pre>
--   data T = MkT Int Bool
--   
--   {-# ANN topEntity (defSyn "f") #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   Clash would normally generate the following VHDL entity:
--   
--   <pre>
--   entity f is
--     port(input_0      : in signed(63 downto 0);
--          input_1_0    : in signed(63 downto 0);
--          input_1_1    : in boolean;
--          output_0_0_0 : out signed(63 downto 0);
--          output_0_0_1 : out boolean;
--          output_0_1   : out boolean);
--   end;
--   </pre>
--   
--   However, we can change this by using <a>PortName</a>s. So by:
--   
--   <pre>
--   {-# ANN topEntity
--      (Synthesize
--         { t_name   = "f"
--         , t_inputs = [ PortName "a"
--                      , PortName "b" ]
--         , t_output = PortName "res" }) #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   we get:
--   
--   <pre>
--   entity f is
--     port(a   : in signed(63 downto 0);
--          b   : in f_types.t;
--          res : out f_types.tup2);
--   end;
--   </pre>
--   
--   If we want to name fields for tuples/records we have to use
--   <a>PortProduct</a>
--   
--   <pre>
--   {-# ANN topEntity
--      (Synthesize
--         { t_name   = "f"
--         , t_inputs = [ PortName "a"
--                      , PortProduct "" [ PortName "b", PortName "c" ] ]
--         , t_output = PortProduct "res" [PortName "q"] }) #-}
--   f :: Int -&gt; T -&gt; (T,Bool)
--   f a b = ...
--   </pre>
--   
--   So that we get:
--   
--   <pre>
--   entity f is
--     port(a     : in signed(63 downto 0);
--          b     : in signed(63 downto 0);
--          c     : in boolean;
--          q     : out f_types.t;
--          res_1 : out boolean);
--   end;
--   </pre>
--   
--   Notice how we didn't name the second field of the result, and the
--   second output port got <a>PortProduct</a> name, "res", as a prefix for
--   its name.
data PortName

-- | You want a port, with the given name, for the entire argument/type
--   
--   You can use an empty String ,"" , in case you want an auto-generated
--   name.
PortName :: String -> PortName

-- | You want to assign ports to fields of a product argument/type
--   
--   The first argument of <a>PortProduct</a> is the name of:
--   
--   <ol>
--   <li>The signal/wire to which the individual ports are aggregated.</li>
--   <li>The prefix for any unnamed ports below the <a>PortProduct</a></li>
--   </ol>
--   
--   You can use an empty String ,"" , in case you want an auto-generated
--   name.
PortProduct :: String -> [PortName] -> PortName

-- | Default <a>Synthesize</a> annotation which has no specified names for
--   the input and output ports.
--   
--   <pre>
--   &gt;&gt;&gt; defSyn "foo"
--   Synthesize {t_name = "foo", t_inputs = [], t_output = PortName ""}
--   </pre>
defSyn :: String -> TopEntity
instance GHC.Generics.Generic Clash.Annotations.TopEntity.TopEntity
instance GHC.Show.Show Clash.Annotations.TopEntity.TopEntity
instance Data.Data.Data Clash.Annotations.TopEntity.TopEntity
instance GHC.Generics.Generic Clash.Annotations.TopEntity.PortName
instance GHC.Show.Show Clash.Annotations.TopEntity.PortName
instance Data.Data.Data Clash.Annotations.TopEntity.PortName
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.TopEntity.TopEntity
instance Language.Haskell.TH.Syntax.Lift Clash.Annotations.TopEntity.PortName


module Clash.Class.Num

-- | Adding, subtracting, and multiplying values of two different
--   (sub-)types.
class ExtendingNum a b where {
    type family AResult a b;
    type family MResult a b;
}

-- | Add values of different (sub-)types, return a value of a (sub-)type
--   that is potentially different from either argument.
plus :: ExtendingNum a b => a -> b -> AResult a b

-- | Subtract values of different (sub-)types, return a value of a
--   (sub-)type that is potentially different from either argument.
minus :: ExtendingNum a b => a -> b -> AResult a b

-- | Multiply values of different (sub-)types, return a value of a
--   (sub-)type that is potentially different from either argument.
times :: ExtendingNum a b => a -> b -> MResult a b

-- | Determine how overflow and underflow are handled by the functions in
--   <a>SaturatingNum</a>
data SaturationMode

-- | Wrap around on overflow and underflow
SatWrap :: SaturationMode

-- | Become <a>maxBound</a> on overflow, and <a>minBound</a> on underflow
SatBound :: SaturationMode

-- | Become <tt>0</tt> on overflow and underflow
SatZero :: SaturationMode

-- | Become <a>maxBound</a> on overflow, and (<tt><a>minBound</a> + 1</tt>)
--   on underflow for signed numbers, and <a>minBound</a> for unsigned
--   numbers.
SatSymmetric :: SaturationMode

-- | <a>Num</a> operators in which overflow and underflow behaviour can be
--   specified using <a>SaturationMode</a>.
class (Bounded a, Num a) => SaturatingNum a

-- | Addition with parametrisable over- and underflow behaviour
satPlus :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Subtraction with parametrisable over- and underflow behaviour
satMin :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Multiplication with parametrisable over- and underflow behaviour
satMult :: SaturatingNum a => SaturationMode -> a -> a -> a

-- | Addition that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedPlus :: SaturatingNum a => a -> a -> a

-- | Subtraction that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedMin :: SaturatingNum a => a -> a -> a

-- | Multiplication that clips to <a>maxBound</a> on overflow, and
--   <a>minBound</a> on underflow
boundedMult :: SaturatingNum a => a -> a -> a
instance GHC.Classes.Eq Clash.Class.Num.SaturationMode


module Clash.Class.Resize

-- | Coerce a value to be represented by a different number of bits
class Resize (f :: Nat -> *)

-- | A sign-preserving resize operation
--   
--   <ul>
--   <li>For signed datatypes: Increasing the size of the number replicates
--   the sign bit to the left. Truncating a number to length L keeps the
--   sign bit and the rightmost L-1 bits.</li>
--   <li>For unsigned datatypes: Increasing the size of the number extends
--   with zeros to the left. Truncating a number of length N to a length L
--   just removes the left (most significant) N-L bits.</li>
--   </ul>
resize :: (Resize f, KnownNat a, KnownNat b) => f a -> f b

-- | Perform a <a>zeroExtend</a> for unsigned datatypes, and
--   <a>signExtend</a> for a signed datatypes
extend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Add extra zero bits in front of the MSB
zeroExtend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Add extra sign bits in front of the MSB
signExtend :: (Resize f, KnownNat a, KnownNat b) => f a -> f (b + a)

-- | Remove bits from the MSB
truncateB :: (Resize f, KnownNat a) => f (a + b) -> f a


-- | Hidden arguments
module Clash.Hidden

-- | A value reflected to, or <i>hiding</i> at, the <i>Constraint</i> level
--   
--   e.g. a function:
--   
--   <pre>
--   f :: Hidden "foo" Int
--     =&gt; Bool
--     -&gt; Int
--   f = ...
--   </pre>
--   
--   has a <i>normal</i> argument of type <tt>Bool</tt>, and a
--   <i>hidden</i> argument called "foo" of type <tt>Int</tt>. In order to
--   apply the <tt>Int</tt> argument we have to use the <a>expose</a>
--   function, so that the <i>hidden</i> argument becomes a normal argument
--   again.
--   
--   <h3><b>Original implementation</b></h3>
--   
--   <a>Hidden</a> used to be implemented by:
--   
--   <pre>
--   class Hidden (x :: Symbol) a | x -&gt; a where
--     hidden :: a
--   </pre>
--   
--   which is equivalent to <i>IP</i>, except that <i>IP</i> has magic
--   inference rules bestowed by GHC so that there's never any ambiguity.
--   We need these magic inference rules so we don't end up in type
--   inference absurdity where asking for the type of an type-annotated
--   value results in a <i>no-instance-in-scope</i> error.
type Hidden (x :: Symbol) a = IP x a

-- | Expose a <a>Hidden</a> argument so that it can be applied normally,
--   e.g.
--   
--   <pre>
--   f :: Hidden "foo" Int
--     =&gt; Bool
--     -&gt; Int
--   f = ...
--   
--   g :: Int -&gt; Bool -&gt; Int
--   g = <a>expose</a> @"foo" f
--   </pre>
expose :: forall x a r. (Hidden x a => r) -> (a -> r)

-- | Using <i>-XOverloadedLabels</i> and <i>-XRebindableSyntax</i>, we can
--   turn any value into a <i>hidden</i> argument using the <tt>#foo</tt>
--   notation, e.g.:
--   
--   <pre>
--   f :: Int -&gt; Bool -&gt; Int
--   f = ...
--   
--   g :: Hidden "foo" Bool
--     =&gt; Int -&gt; Int
--   g i = f i #foo
--   </pre>
fromLabel :: forall x a. Hidden x a => a


-- | Add inline documentation to types:
--   
--   <pre>
--   fifo
--     :: Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; SNat addrSize
--     -&gt; "read request" ::: Signal domain Bool
--     -&gt; "write request" ::: Signal domain (Maybe (BitVector dataSize))
--     -&gt; ( "q"     ::: Signal domain (BitVector dataSize)
--        , "full"  ::: Signal domain Bool
--        , "empty" ::: Signal domain Bool
--        )
--   </pre>
--   
--   which can subsequently be inspected in the interactive environment:
--   
--   <pre>
--   &gt;&gt;&gt; :t fifo @System
--   fifo @System
--     :: Clock System gated
--        -&gt; Reset System synchronous
--        -&gt; SNat addrSize
--        -&gt; ("read request" ::: Signal System Bool)
--        -&gt; ("write request" ::: Signal System (Maybe (BitVector dataSize)))
--        -&gt; ("q" ::: Signal System (BitVector dataSize),
--            "full" ::: Signal System Bool, "empty" ::: Signal System Bool)
--   </pre>
module Clash.NamedTypes

-- | Annotate a type with a name
type (name :: k) ::: a = a


module Clash.Promoted.Symbol

-- | Singleton value for a type-level string <tt>s</tt>
data SSymbol (s :: Symbol)
[SSymbol] :: KnownSymbol s => SSymbol s

-- | Create a singleton symbol literal <tt><a>SSymbol</a> s</tt> from a
--   proxy for <i>s</i>
ssymbolProxy :: KnownSymbol s => proxy s -> SSymbol s

-- | Reify the type-level <a>Symbol</a> <tt>s</tt> to it's term-level
--   <a>String</a> representation.
ssymbolToString :: SSymbol s -> String
instance GHC.Show.Show (Clash.Promoted.Symbol.SSymbol s)


-- | <tt>X</tt>: An exception for uninitialized values
--   
--   <pre>
--   &gt;&gt;&gt; show (errorX "undefined" :: Integer, 4 :: Int)
--   "(*** Exception: X: undefined
--   CallStack (from HasCallStack):
--   ...
--   
--   &gt;&gt;&gt; showX (errorX "undefined" :: Integer, 4 :: Int)
--   "(X,4)"
--   </pre>
module Clash.XException

-- | An exception representing an "uninitialised" value.
data XException

-- | Like <a>error</a>, but throwing an <a>XException</a> instead of an
--   <tt>ErrorCall</tt>
--   
--   The <a>ShowX</a> methods print these error-values as "X"; instead of
--   error'ing out with an exception.
errorX :: HasCallStack => String -> a

-- | Fully evaluate a value, returning <tt><a>Left</a> msg</tt> if is
--   throws <a>XException</a>.
--   
--   <pre>
--   isX 42               = Right 42
--   isX (XException msg) = Left msg
--   isX _|_              = _|_
--   </pre>
isX :: NFData a => a -> Either String a

-- | Fully evaluate a value, returning <a>Nothing</a> if is throws
--   <a>XException</a>.
--   
--   <pre>
--   maybeX 42               = Just 42
--   maybeX (XException msg) = Nothing
--   maybeX _|_              = _|_
--   </pre>
maybeX :: NFData a => a -> Maybe a

-- | Like the <a>Show</a> class, but values that normally throw an
--   <tt>X</tt> exception are converted to "X", instead of error'ing out
--   with an exception.
--   
--   <pre>
--   &gt;&gt;&gt; show (errorX "undefined" :: Integer, 4 :: Int)
--   "(*** Exception: X: undefined
--   CallStack (from HasCallStack):
--   ...
--   
--   &gt;&gt;&gt; showX (errorX "undefined" :: Integer, 4 :: Int)
--   "(X,4)"
--   </pre>
--   
--   Can be derived using <a>Generics</a>:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import Clash.Prelude
--   import GHC.Generics
--   
--   data T = MkTA Int | MkTB Bool
--     deriving (Show,Generic,ShowX)
--   </pre>
class ShowX a

-- | Like <a>showsPrec</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception.
showsPrecX :: ShowX a => Int -> a -> ShowS

-- | Like <a>show</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception.
showX :: ShowX a => a -> String

-- | Like <a>showList</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception.
showListX :: ShowX a => [a] -> ShowS

-- | Like <a>showsPrec</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception.
showsPrecX :: (ShowX a, Generic a, GShowX (Rep a)) => Int -> a -> ShowS

-- | Like <a>shows</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception.
showsX :: ShowX a => a -> ShowS

-- | Like <a>print</a>, but values that normally throw an <tt>X</tt>
--   exception are converted to "X", instead of error'ing out with an
--   exception
printX :: ShowX a => a -> IO ()

-- | Use when you want to create a <a>ShowX</a> instance where:
--   
--   <ul>
--   <li>There is no <a>Generic</a> instance for your data type</li>
--   <li>The <a>Generic</a> derived ShowX method would traverse into the
--   (hidden) implementation details of your data type, and you just want
--   to show the entire value as "X".</li>
--   </ul>
--   
--   Can be used like:
--   
--   <pre>
--   data T = ...
--   
--   instance Show T where ...
--   
--   instance ShowX T where
--     showsPrecX = showsPrecXWith showsPrec
--   </pre>
showsPrecXWith :: (Int -> a -> ShowS) -> Int -> a -> ShowS

-- | Like <a>seq</a>, however, whereas <a>seq</a> will always do:
--   
--   <pre>
--   seq  _|_              b = _|_
--   </pre>
--   
--   <a>seqX</a> will do:
--   
--   <pre>
--   seqX (XException msg) b = b
--   seqX _|_              b = _|_
--   </pre>
seqX :: a -> b -> b
infixr 0 `seqX`
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j, k)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j, k, l)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j, k, l, m)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
instance GHC.Generics.Generic (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
instance Clash.XException.ShowX ()
instance (Clash.XException.ShowX a, Clash.XException.ShowX b) => Clash.XException.ShowX (a, b)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c) => Clash.XException.ShowX (a, b, c)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d) => Clash.XException.ShowX (a, b, c, d)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e) => Clash.XException.ShowX (a, b, c, d, e)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f) => Clash.XException.ShowX (a, b, c, d, e, f)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g) => Clash.XException.ShowX (a, b, c, d, e, f, g)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h) => Clash.XException.ShowX (a, b, c, d, e, f, g, h)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j, Clash.XException.ShowX k) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j, k)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j, Clash.XException.ShowX k, Clash.XException.ShowX l) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j, k, l)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j, Clash.XException.ShowX k, Clash.XException.ShowX l, Clash.XException.ShowX m) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j, k, l, m)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j, Clash.XException.ShowX k, Clash.XException.ShowX l, Clash.XException.ShowX m, Clash.XException.ShowX n) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
instance (Clash.XException.ShowX a, Clash.XException.ShowX b, Clash.XException.ShowX c, Clash.XException.ShowX d, Clash.XException.ShowX e, Clash.XException.ShowX f, Clash.XException.ShowX g, Clash.XException.ShowX h, Clash.XException.ShowX i, Clash.XException.ShowX j, Clash.XException.ShowX k, Clash.XException.ShowX l, Clash.XException.ShowX m, Clash.XException.ShowX n, Clash.XException.ShowX o) => Clash.XException.ShowX (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
instance Clash.XException.ShowX a => Clash.XException.ShowX [a]
instance Clash.XException.ShowX GHC.Types.Char
instance Clash.XException.ShowX GHC.Types.Bool
instance Clash.XException.ShowX GHC.Types.Double
instance (Clash.XException.ShowX a, Clash.XException.ShowX b) => Clash.XException.ShowX (Data.Either.Either a b)
instance Clash.XException.ShowX GHC.Types.Float
instance Clash.XException.ShowX GHC.Types.Int
instance Clash.XException.ShowX GHC.Int.Int8
instance Clash.XException.ShowX GHC.Int.Int16
instance Clash.XException.ShowX GHC.Int.Int32
instance Clash.XException.ShowX GHC.Int.Int64
instance Clash.XException.ShowX GHC.Integer.Type.Integer
instance Clash.XException.ShowX GHC.Types.Word
instance Clash.XException.ShowX GHC.Word.Word8
instance Clash.XException.ShowX GHC.Word.Word16
instance Clash.XException.ShowX GHC.Word.Word32
instance Clash.XException.ShowX GHC.Word.Word64
instance Clash.XException.ShowX a => Clash.XException.ShowX (GHC.Base.Maybe a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (GHC.Real.Ratio a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Data.Complex.Complex a)
instance Clash.XException.ShowX GHC.Base.String
instance Clash.XException.ShowX c => Clash.XException.GShowX (GHC.Generics.K1 i c)
instance Clash.XException.GShowX GHC.Generics.U1
instance (Clash.XException.GShowX a, GHC.Generics.Constructor c) => Clash.XException.GShowX (GHC.Generics.M1 GHC.Generics.C c a)
instance (GHC.Generics.Selector s, Clash.XException.GShowX a) => Clash.XException.GShowX (GHC.Generics.M1 GHC.Generics.S s a)
instance Clash.XException.GShowX a => Clash.XException.GShowX (GHC.Generics.M1 GHC.Generics.D d a)
instance (Clash.XException.GShowX a, Clash.XException.GShowX b) => Clash.XException.GShowX (a GHC.Generics.:+: b)
instance (Clash.XException.GShowX a, Clash.XException.GShowX b) => Clash.XException.GShowX (a GHC.Generics.:*: b)
instance Clash.XException.GShowX GHC.Generics.UChar
instance Clash.XException.GShowX GHC.Generics.UDouble
instance Clash.XException.GShowX GHC.Generics.UFloat
instance Clash.XException.GShowX GHC.Generics.UInt
instance Clash.XException.GShowX GHC.Generics.UWord
instance GHC.Show.Show Clash.XException.XException
instance GHC.Exception.Exception Clash.XException.XException


module Clash.Promoted.Nat

-- | Singleton value for a type-level natural number <tt>n</tt>
--   
--   <ul>
--   <li><a>Clash.Promoted.Nat.Literals</a> contains a list of predefined
--   <a>SNat</a> literals</li>
--   <li><a>Clash.Promoted.Nat.TH</a> has functions to easily create large
--   ranges of new <a>SNat</a> literals</li>
--   </ul>
data SNat (n :: Nat)
[SNat] :: KnownNat n => SNat n

-- | Create an <tt><a>SNat</a> n</tt> from a proxy for <i>n</i>
snatProxy :: KnownNat n => proxy n -> SNat n

-- | Supply a function with a singleton natural <tt>n</tt> according to the
--   context
withSNat :: KnownNat n => (SNat n -> a) -> a

-- | Reify the type-level <a>Nat</a> <tt>n</tt> to it's term-level
--   <a>Integer</a> representation.
snatToInteger :: SNat n -> Integer

-- | Reify the type-level <a>Nat</a> <tt>n</tt> to it's term-level
--   <a>Num</a>ber.
snatToNum :: Num a => SNat n -> a

-- | Add two singleton natural numbers
addSNat :: SNat a -> SNat b -> SNat (a + b)
infixl 6 `addSNat`

-- | Multiply two singleton natural numbers
mulSNat :: SNat a -> SNat b -> SNat (a * b)
infixl 7 `mulSNat`

-- | Power of two singleton natural numbers
powSNat :: SNat a -> SNat b -> SNat (a ^ b)
infixr 8 `powSNat`

-- | Subtract two singleton natural numbers
subSNat :: SNat (a + b) -> SNat b -> SNat a
infixl 6 `subSNat`

-- | Division of two singleton natural numbers
divSNat :: (1 <= b) => SNat a -> SNat b -> SNat (Div a b)
infixl 7 `divSNat`

-- | Modulo of two singleton natural numbers
modSNat :: (1 <= b) => SNat a -> SNat b -> SNat (Mod a b)
infixl 7 `modSNat`

-- | Floor of the logarithm of a natural number
flogBaseSNat :: (2 <= base, 1 <= x) => SNat base -> SNat x -> SNat (FLog base x)

-- | Ceiling of the logarithm of a natural number
clogBaseSNat :: (2 <= base, 1 <= x) => SNat base -> SNat x -> SNat (CLog base x)

-- | Exact integer logarithm of a natural number
--   
--   <b>NB</b>: Only works when the argument is a power of the base
logBaseSNat :: (FLog base x ~ CLog base x) => SNat base -> SNat x -> SNat (Log base x)

-- | Power of two of a singleton natural number
pow2SNat :: SNat a -> SNat (2 ^ a)

-- | Unary representation of a type-level natural
--   
--   <b>NB</b>: Not synthesisable
data UNat :: Nat -> *
[UZero] :: UNat 0
[USucc] :: UNat n -> UNat (n + 1)

-- | Convert a singleton natural number to its unary representation
--   
--   <b>NB</b>: Not synthesisable
toUNat :: SNat n -> UNat n

-- | Convert a unary-encoded natural number to its singleton representation
--   
--   <b>NB</b>: Not synthesisable
fromUNat :: UNat n -> SNat n

-- | Add two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
addUNat :: UNat n -> UNat m -> UNat (n + m)

-- | Multiply two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
mulUNat :: UNat n -> UNat m -> UNat (n * m)

-- | Power of two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
powUNat :: UNat n -> UNat m -> UNat (n ^ m)

-- | Predecessor of a unary-encoded natural number
--   
--   <b>NB</b>: Not synthesisable
predUNat :: UNat (n + 1) -> UNat n

-- | Subtract two unary-encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
subUNat :: UNat (m + n) -> UNat n -> UNat m

-- | Base-2 encoded natural number
--   
--   <ul>
--   <li><b>NB</b>: The LSB is the left/outer-most constructor:</li>
--   <li><b>NB</b>: Not synthesisable</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; B0 (B1 (B1 BT))
--   b6
--   </pre>
--   
--   <h2>Constructors</h2>
--   
--   <ul>
--   <li>Starting/Terminating element:<pre><b>BT</b> :: <a>BNat</a> 0
--   </pre></li>
--   </ul>
--   
--   <ul>
--   <li>Append a zero (<i>0</i>):<pre><b>B0</b> :: <a>BNat</a> n -&gt;
--   <a>BNat</a> (2 <a>*</a> n) </pre></li>
--   <li>Append a one (<i>1</i>):<pre><b>B1</b> :: <a>BNat</a> n -&gt;
--   <a>BNat</a> ((2 <a>*</a> n) <a>+</a> 1) </pre></li>
--   </ul>
data BNat :: Nat -> *
[BT] :: BNat 0
[B0] :: BNat n -> BNat (2 * n)
[B1] :: BNat n -> BNat ((2 * n) + 1)

-- | Convert a singleton natural number to its base-2 representation
--   
--   <b>NB</b>: Not synthesisable
toBNat :: SNat n -> BNat n

-- | Convert a base-2 encoded natural number to its singleton
--   representation
--   
--   <b>NB</b>: Not synthesisable
fromBNat :: BNat n -> SNat n

-- | Show a base-2 encoded natural as a binary literal
--   
--   <b>NB</b>: The LSB is shown as the right-most bit
--   
--   <pre>
--   &gt;&gt;&gt; d789
--   d789
--   
--   &gt;&gt;&gt; toBNat d789
--   b789
--   
--   &gt;&gt;&gt; showBNat (toBNat d789)
--   "0b1100010101"
--   
--   &gt;&gt;&gt; 0b1100010101 :: Integer
--   789
--   </pre>
showBNat :: BNat n -> String

-- | Successor of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesisable
succBNat :: BNat n -> BNat (n + 1)

-- | Add two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
addBNat :: BNat n -> BNat m -> BNat (n + m)

-- | Multiply two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
mulBNat :: BNat n -> BNat m -> BNat (n * m)

-- | Power of two base-2 encoded natural numbers
--   
--   <b>NB</b>: Not synthesisable
powBNat :: BNat n -> BNat m -> BNat (n ^ m)

-- | Predecessor of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesisable
predBNat :: (1 <= n) => BNat n -> BNat (n - 1)

-- | Divide a base-2 encoded natural number by 2
--   
--   <b>NB</b>: Not synthesisable
div2BNat :: BNat (2 * n) -> BNat n

-- | Subtract 1 and divide a base-2 encoded natural number by 2
--   
--   <b>NB</b>: Not synthesisable
div2Sub1BNat :: BNat (2 * n + 1) -> BNat n

-- | Get the log2 of a base-2 encoded natural number
--   
--   <b>NB</b>: Not synthesisable
log2BNat :: BNat (2 ^ n) -> BNat n

-- | Strip non-contributing zero's from a base-2 encoded natural number
--   
--   <pre>
--   &gt;&gt;&gt; B1 (B0 (B0 (B0 BT)))
--   b1
--   
--   &gt;&gt;&gt; showBNat (B1 (B0 (B0 (B0 BT))))
--   "0b0001"
--   
--   &gt;&gt;&gt; showBNat (stripZeros (B1 (B0 (B0 (B0 BT)))))
--   "0b1"
--   
--   &gt;&gt;&gt; stripZeros (B1 (B0 (B0 (B0 BT))))
--   b1
--   </pre>
--   
--   <b>NB</b>: Not synthesisable
stripZeros :: BNat n -> BNat n

-- | Change a function that has an argument with an <tt>(n + k)</tt>
--   constraint to a function with an argument that has an <tt>(k &lt;=
--   n)</tt> constraint.
--   
--   <b>NB</b> It is the dual to <a>plusToLe</a>
--   
--   <h3><b>Examples</b></h3>
--   
--   Example 1
--   
--   <pre>
--   f :: Index (n+1) -&gt; Index (n + 1) -&gt; Bool
--   
--   g :: (1 <a>&lt;=</a> n) =&gt; Index n -&gt; Index n -&gt; Bool
--   g a b = <a>leToPlus</a> @1 $ \a' -&gt; <a>leToPlus</a> @1 $ \b' -&gt; f a' b'
--   </pre>
--   
--   Example 2
--   
--   <pre>
--   import Data.Bifunctor.Flip
--   
--   head :: Vec (n + 1) a -&gt; a
--   
--   head' :: (1 <a>&lt;=</a> n) =&gt; Vec n a -&gt; a
--   head' a = <a>leToPlus</a> @1 (Flip a) (head . runFlip)
--   </pre>
leToPlus :: forall (k :: Nat) (n :: Nat) f r. (k <= n) => f n -> (forall m. f (m + k) -> r) -> r

-- | Same as <a>leToPlus</a> with added <a>KnownNat</a> constraints
leToPlusKN :: forall (k :: Nat) (n :: Nat) f r. (k <= n, KnownNat n, KnownNat k) => f n -> (forall m. KnownNat m => f (m + k) -> r) -> r

-- | Change a function that has an argument with an <tt>(k &lt;= n)</tt>
--   constraint to a function with an argument that has an <tt>(n + k)</tt>
--   constraint.
--   
--   <b>NB</b> It is the dual to <a>leToPlus</a>
--   
--   <h3><b>Examples</b></h3>
--   
--   Example 1
--   
--   <pre>
--   f :: (1 <a>&lt;=</a> n) =&gt; Index n -&gt; Index n -&gt; Bool
--   
--   g :: Index (n + 1) -&gt; Index (n + 1) -&gt; Bool
--   g a b = <a>plusToLe</a> @1 $ \a' -&gt; <a>plusToLe</a> @1 $ \b' -&gt; f a' b'
--   </pre>
--   
--   Example 2
--   
--   <pre>
--   import Datal.Bifunctor.Flip
--   
--   fold :: (1 <a>&lt;=</a> n) =&gt; (a -&gt; a -&gt; a) -&gt; Vec n a -&gt; a
--   
--   fold' :: (a -&gt; a -&gt; a) -&gt; Vec (n+1) a -&gt; a
--   fold' f a = <a>plusToLe</a> @1 (Flip a) (fold f . runFlip)
--   </pre>
plusToLe :: forall (k :: Nat) n f r. f (n + k) -> (forall m. (k <= m) => f m -> r) -> r

-- | Same as <a>plusToLe</a> with added <a>KnownNat</a> constraints
plusToLeKN :: forall (k :: Nat) n f r. (KnownNat n, KnownNat k) => f (n + k) -> (forall m. (KnownNat m, k <= m) => f m -> r) -> r
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Promoted.Nat.BNat n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Promoted.Nat.BNat n)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Promoted.Nat.UNat n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Promoted.Nat.UNat n)
instance Language.Haskell.TH.Syntax.Lift (Clash.Promoted.Nat.SNat n)
instance GHC.Show.Show (Clash.Promoted.Nat.SNat n)
instance Clash.XException.ShowX (Clash.Promoted.Nat.SNat n)


module Clash.Sized.Internal.BitVector

-- | Bit
newtype Bit

-- | The constructor, <a>Bit</a>, and the field, <a>unsafeToInteger#</a>,
--   are not synthesisable.
Bit :: Integer -> Bit
[unsafeToInteger#] :: Bit -> Integer

-- | logic '1'
high :: Bit

-- | logic '0'
low :: Bit
eq## :: Bit -> Bit -> Bool
neq## :: Bit -> Bit -> Bool
lt## :: Bit -> Bit -> Bool
ge## :: Bit -> Bit -> Bool
gt## :: Bit -> Bit -> Bool
le## :: Bit -> Bit -> Bool
fromInteger## :: Integer -> Bit
and## :: Bit -> Bit -> Bit
or## :: Bit -> Bit -> Bit
xor## :: Bit -> Bit -> Bit
complement## :: Bit -> Bit
pack# :: Bit -> BitVector 1
unpack# :: BitVector 1 -> Bit

-- | A vector of bits.
--   
--   <ul>
--   <li>Bit indices are descending</li>
--   <li><a>Num</a> instance performs <i>unsigned</i> arithmetic.</li>
--   </ul>
newtype BitVector (n :: Nat)

-- | The constructor, <a>BV</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesisable.
BV :: Integer -> BitVector
[unsafeToInteger] :: BitVector -> Integer
size# :: KnownNat n => BitVector n -> Int
maxIndex# :: KnownNat n => BitVector n -> Int

-- | Create a binary literal
--   
--   <pre>
--   &gt;&gt;&gt; $$(bLit "1001") :: BitVector 4
--   1001
--   
--   &gt;&gt;&gt; $$(bLit "1001") :: BitVector 3
--   001
--   </pre>
--   
--   <b>NB</b>: You can also just write:
--   
--   <pre>
--   &gt;&gt;&gt; 0b1001 :: BitVector 4
--   1001
--   </pre>
--   
--   The advantage of <a>bLit</a> is that you can use computations to
--   create the string literal:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; $$(bLit (List.replicate 4 '1')) :: BitVector 4
--   1111
--   </pre>
bLit :: KnownNat n => String -> Q (TExp (BitVector n))

-- | Concatenate two <a>BitVector</a>s
(++#) :: KnownNat m => BitVector n -> BitVector m -> BitVector (n + m)
reduceAnd# :: KnownNat n => BitVector n -> Bit
reduceOr# :: BitVector n -> Bit
reduceXor# :: BitVector n -> Bit
index# :: KnownNat n => BitVector n -> Int -> Bit
replaceBit# :: KnownNat n => BitVector n -> Int -> Bit -> BitVector n
setSlice# :: BitVector (m + 1 + i) -> SNat m -> SNat n -> BitVector (m + 1 - n) -> BitVector (m + 1 + i)
slice# :: BitVector (m + 1 + i) -> SNat m -> SNat n -> BitVector (m + 1 - n)
split# :: forall n m. KnownNat n => BitVector (m + n) -> (BitVector m, BitVector n)

-- | MSB
msb# :: forall n. KnownNat n => BitVector n -> Bit

-- | LSB
lsb# :: BitVector n -> Bit
eq# :: BitVector n -> BitVector n -> Bool
neq# :: BitVector n -> BitVector n -> Bool
lt# :: BitVector n -> BitVector n -> Bool
ge# :: BitVector n -> BitVector n -> Bool
gt# :: BitVector n -> BitVector n -> Bool
le# :: BitVector n -> BitVector n -> Bool
enumFrom# :: KnownNat n => BitVector n -> [BitVector n]
enumFromThen# :: KnownNat n => BitVector n -> BitVector n -> [BitVector n]
enumFromTo# :: BitVector n -> BitVector n -> [BitVector n]
enumFromThenTo# :: BitVector n -> BitVector n -> BitVector n -> [BitVector n]
minBound# :: BitVector n
maxBound# :: forall n. KnownNat n => BitVector n
(+#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
(-#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
(*#) :: forall n. KnownNat n => BitVector n -> BitVector n -> BitVector n
negate# :: forall n. KnownNat n => BitVector n -> BitVector n
fromInteger# :: KnownNat n => Integer -> BitVector n
plus# :: BitVector m -> BitVector n -> BitVector (Max m n + 1)
minus# :: forall m n. (KnownNat m, KnownNat n) => BitVector m -> BitVector n -> BitVector (Max m n + 1)
times# :: BitVector m -> BitVector n -> BitVector (m + n)
quot# :: BitVector n -> BitVector n -> BitVector n
rem# :: BitVector n -> BitVector n -> BitVector n
toInteger# :: BitVector n -> Integer
and# :: BitVector n -> BitVector n -> BitVector n
or# :: BitVector n -> BitVector n -> BitVector n
xor# :: BitVector n -> BitVector n -> BitVector n
complement# :: KnownNat n => BitVector n -> BitVector n
shiftL# :: KnownNat n => BitVector n -> Int -> BitVector n
shiftR# :: KnownNat n => BitVector n -> Int -> BitVector n
rotateL# :: KnownNat n => BitVector n -> Int -> BitVector n
rotateR# :: KnownNat n => BitVector n -> Int -> BitVector n
popCountBV :: forall n. KnownNat n => BitVector (n + 1) -> Index (n + 2)
countLeadingZerosBV :: KnownNat n => BitVector n -> Index (n + 1)
countTrailingZerosBV :: KnownNat n => BitVector n -> Index (n + 1)
resize# :: forall n m. KnownNat m => BitVector n -> BitVector m

-- | <a>shrink</a> for sized unsigned types
shrinkSizedUnsigned :: (KnownNat n, Integral (p n)) => p n -> [p n]
instance Data.Data.Data Clash.Sized.Internal.BitVector.Bit
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.BitVector.BitVector n)
instance Control.DeepSeq.NFData Clash.Sized.Internal.BitVector.Bit
instance GHC.Show.Show Clash.Sized.Internal.BitVector.Bit
instance Clash.XException.ShowX Clash.Sized.Internal.BitVector.Bit
instance Language.Haskell.TH.Syntax.Lift Clash.Sized.Internal.BitVector.Bit
instance GHC.Classes.Eq Clash.Sized.Internal.BitVector.Bit
instance GHC.Classes.Ord Clash.Sized.Internal.BitVector.Bit
instance GHC.Enum.Enum Clash.Sized.Internal.BitVector.Bit
instance GHC.Enum.Bounded Clash.Sized.Internal.BitVector.Bit
instance Data.Default.Class.Default Clash.Sized.Internal.BitVector.Bit
instance GHC.Num.Num Clash.Sized.Internal.BitVector.Bit
instance GHC.Real.Real Clash.Sized.Internal.BitVector.Bit
instance GHC.Real.Integral Clash.Sized.Internal.BitVector.Bit
instance Data.Bits.Bits Clash.Sized.Internal.BitVector.Bit
instance Data.Bits.FiniteBits Clash.Sized.Internal.BitVector.Bit
instance Control.DeepSeq.NFData (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Clash.XException.ShowX (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.Classes.Eq (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.Classes.Ord (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.BitVector.BitVector n)
instance (GHC.TypeNats.KnownNat m, GHC.TypeNats.KnownNat n) => Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.BitVector.BitVector m) (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.BitVector.BitVector n)
instance Data.Default.Class.Default (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.BitVector.BitVector
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.BitVector.BitVector n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.BitVector.BitVector n)


module Clash.Sized.BitVector

-- | Bit
data Bit

-- | logic '1'
high :: Bit

-- | logic '0'
low :: Bit

-- | A vector of bits.
--   
--   <ul>
--   <li>Bit indices are descending</li>
--   <li><a>Num</a> instance performs <i>unsigned</i> arithmetic.</li>
--   </ul>
data BitVector (n :: Nat)
size# :: KnownNat n => BitVector n -> Int
maxIndex# :: KnownNat n => BitVector n -> Int

-- | Create a binary literal
--   
--   <pre>
--   &gt;&gt;&gt; $$(bLit "1001") :: BitVector 4
--   1001
--   
--   &gt;&gt;&gt; $$(bLit "1001") :: BitVector 3
--   001
--   </pre>
--   
--   <b>NB</b>: You can also just write:
--   
--   <pre>
--   &gt;&gt;&gt; 0b1001 :: BitVector 4
--   1001
--   </pre>
--   
--   The advantage of <a>bLit</a> is that you can use computations to
--   create the string literal:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; $$(bLit (List.replicate 4 '1')) :: BitVector 4
--   1111
--   </pre>
bLit :: KnownNat n => String -> Q (TExp (BitVector n))

-- | Concatenate two <a>BitVector</a>s
(++#) :: KnownNat m => BitVector n -> BitVector m -> BitVector (n + m)


module Clash.Class.BitPack

-- | Convert to and from a <a>BitVector</a>
class BitPack a where {
    type family BitSize a :: Nat;
    type BitSize a = GBitSize (Rep a);
}

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   </pre>
pack :: BitPack a => a -> BitVector (BitSize a)

-- | Convert element of type <tt>a</tt> to a <a>BitVector</a>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   </pre>
pack :: (BitPack a, Generic a, GBitPack (Rep a), GBitSize (Rep a) ~ BitSize a) => a -> BitVector (BitSize a)

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   11_1011
--   </pre>
unpack :: BitPack a => BitVector (BitSize a) -> a

-- | Convert a <a>BitVector</a> to an element of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; let x = pack (-5 :: Signed 6)
--   
--   &gt;&gt;&gt; unpack x :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   11_1011
--   </pre>
unpack :: (BitPack a, Generic a, GBitPack (Rep a), GBitSize (Rep a) ~ BitSize a) => BitVector (BitSize a) -> a

-- | Coerce a value from one type to another through its bit
--   representation.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; bitCoerce (-5 :: Signed 6) :: Unsigned 6
--   59
--   
--   &gt;&gt;&gt; pack (59 :: Unsigned 6)
--   11_1011
--   </pre>
bitCoerce :: (BitPack a, BitPack b, BitSize a ~ BitSize b) => a -> b

-- | Zero-extend a <a>Bool</a>ean value to a <a>BitVector</a> of the
--   appropriate size.
--   
--   <pre>
--   &gt;&gt;&gt; boolToBV True :: BitVector 6
--   00_0001
--   
--   &gt;&gt;&gt; boolToBV False :: BitVector 6
--   00_0000
--   </pre>
boolToBV :: KnownNat n => Bool -> BitVector (n + 1)

-- | Convert a Bool to a Bit
boolToBit :: Bool -> Bit

-- | Convert a Bool to a Bit
bitToBool :: Bit -> Bool
instance Clash.Class.BitPack.BitPack GHC.Types.Bool
instance Clash.Class.BitPack.BitPack (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Class.BitPack.BitPack Clash.Sized.Internal.BitVector.Bit
instance Clash.Class.BitPack.BitPack GHC.Types.Int
instance Clash.Class.BitPack.BitPack GHC.Int.Int8
instance Clash.Class.BitPack.BitPack GHC.Int.Int16
instance Clash.Class.BitPack.BitPack GHC.Int.Int32
instance Clash.Class.BitPack.BitPack GHC.Int.Int64
instance Clash.Class.BitPack.BitPack GHC.Types.Word
instance Clash.Class.BitPack.BitPack GHC.Word.Word8
instance Clash.Class.BitPack.BitPack GHC.Word.Word16
instance Clash.Class.BitPack.BitPack GHC.Word.Word32
instance Clash.Class.BitPack.BitPack GHC.Word.Word64
instance Clash.Class.BitPack.BitPack GHC.Types.Float
instance Clash.Class.BitPack.BitPack GHC.Types.Double
instance Clash.Class.BitPack.BitPack Foreign.C.Types.CUShort
instance Clash.Class.BitPack.BitPack Numeric.Half.Half
instance Clash.Class.BitPack.BitPack ()
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize b), Clash.Class.BitPack.BitPack a, Clash.Class.BitPack.BitPack b) => Clash.Class.BitPack.BitPack (a, b)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize c), Clash.Class.BitPack.BitPack (a, b), Clash.Class.BitPack.BitPack c) => Clash.Class.BitPack.BitPack (a, b, c)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize d), Clash.Class.BitPack.BitPack (a, b, c), Clash.Class.BitPack.BitPack d) => Clash.Class.BitPack.BitPack (a, b, c, d)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize e), Clash.Class.BitPack.BitPack (a, b, c, d), Clash.Class.BitPack.BitPack e) => Clash.Class.BitPack.BitPack (a, b, c, d, e)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize f), Clash.Class.BitPack.BitPack (a, b, c, d, e), Clash.Class.BitPack.BitPack f) => Clash.Class.BitPack.BitPack (a, b, c, d, e, f)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize g), Clash.Class.BitPack.BitPack (a, b, c, d, e, f), Clash.Class.BitPack.BitPack g) => Clash.Class.BitPack.BitPack (a, b, c, d, e, f, g)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize h), Clash.Class.BitPack.BitPack (a, b, c, d, e, f, g), Clash.Class.BitPack.BitPack h) => Clash.Class.BitPack.BitPack (a, b, c, d, e, f, g, h)
instance (Clash.Class.BitPack.BitPack a, GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize a)) => Clash.Class.BitPack.BitPack (GHC.Base.Maybe a)
instance Clash.Class.BitPack.BitPack c => Clash.Class.BitPack.GBitPack (GHC.Generics.K1 i c)
instance Clash.Class.BitPack.GBitPack a => Clash.Class.BitPack.GBitPack (GHC.Generics.M1 m d a)
instance (GHC.TypeNats.KnownNat (Clash.Class.BitPack.GBitSize g), Clash.Class.BitPack.GBitPack f, Clash.Class.BitPack.GBitPack g) => Clash.Class.BitPack.GBitPack (f GHC.Generics.:*: g)


module Clash.Sized.Internal.Index

-- | Arbitrary-bounded unsigned integer represented by
--   <tt>ceil(log_2(n))</tt> bits.
--   
--   Given an upper bound <tt>n</tt>, an <a>Index</a> <tt>n</tt> number has
--   a range of: [0 .. <tt>n</tt>-1]
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Index 8
--   7
--   
--   &gt;&gt;&gt; minBound :: Index 8
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Index 8)) :: Index 8
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Index 8
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Index 8
--   *** Exception: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 1 - 3 :: Index 8
--   *** Exception: Clash.Sized.Index: result -2 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 2 * 3 :: Index 8
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Index 8
--   *** Exception: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   </pre>
newtype Index (n :: Nat)

-- | The constructor, <a>I</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesisable.
I :: Integer -> Index
[unsafeToInteger] :: Index -> Integer

-- | Safely convert an <a>SNat</a> value to an <a>Index</a>
fromSNat :: (KnownNat m, CmpNat n m ~  'LT) => SNat n -> Index m
pack# :: Index n -> BitVector (CLog 2 n)
unpack# :: KnownNat n => BitVector (CLog 2 n) -> Index n
eq# :: (Index n) -> (Index n) -> Bool
neq# :: (Index n) -> (Index n) -> Bool
lt# :: Index n -> Index n -> Bool
ge# :: Index n -> Index n -> Bool
gt# :: Index n -> Index n -> Bool
le# :: Index n -> Index n -> Bool
enumFrom# :: KnownNat n => Index n -> [Index n]
enumFromThen# :: KnownNat n => Index n -> Index n -> [Index n]
enumFromTo# :: Index n -> Index n -> [Index n]
enumFromThenTo# :: Index n -> Index n -> Index n -> [Index n]
maxBound# :: KnownNat n => Index n
(+#) :: KnownNat n => Index n -> Index n -> Index n
(-#) :: KnownNat n => Index n -> Index n -> Index n
(*#) :: KnownNat n => Index n -> Index n -> Index n
fromInteger# :: KnownNat n => Integer -> Index n
plus# :: Index m -> Index n -> Index (m + n - 1)
minus# :: Index m -> Index n -> Index (m + n - 1)
times# :: Index m -> Index n -> Index (((m - 1) * (n - 1)) + 1)
quot# :: Index n -> Index n -> Index n
rem# :: Index n -> Index n -> Index n
toInteger# :: Index n -> Integer
resize# :: KnownNat m => Index n -> Index m
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Index.Index n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Clash.Class.BitPack.BitPack (Clash.Sized.Internal.Index.Index n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Index.Index n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Index.Index n)
instance Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Index.Index m) (Clash.Sized.Internal.Index.Index n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Index.Index n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Index.Index
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Index.Index n)
instance GHC.Show.Show (Clash.Sized.Internal.Index.Index n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Data.Default.Class.Default (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Index.Index n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Index.Index n)


module Clash.Prelude.BitReduction

-- | Are all bits set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (-2 :: Signed 6)
--   11_1110
--   
--   &gt;&gt;&gt; reduceAnd (-2 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (-1 :: Signed 6)
--   11_1111
--   
--   &gt;&gt;&gt; reduceAnd (-1 :: Signed 6)
--   1
--   </pre>
reduceAnd :: (BitPack a, KnownNat (BitSize a)) => a -> Bit

-- | Is there at least one bit set to '1'?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   00_0101
--   
--   &gt;&gt;&gt; reduceOr (5 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (0 :: Signed 6)
--   00_0000
--   
--   &gt;&gt;&gt; reduceOr (0 :: Signed 6)
--   0
--   </pre>
reduceOr :: BitPack a => a -> Bit

-- | Is the number of bits set to '1' uneven?
--   
--   <pre>
--   &gt;&gt;&gt; pack (5 :: Signed 6)
--   00_0101
--   
--   &gt;&gt;&gt; reduceXor (5 :: Signed 6)
--   0
--   
--   &gt;&gt;&gt; pack (28 :: Signed 6)
--   01_1100
--   
--   &gt;&gt;&gt; reduceXor (28 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; reduceXor (-5 :: Signed 6)
--   1
--   </pre>
reduceXor :: BitPack a => a -> Bit


module Clash.Sized.Index

-- | Arbitrary-bounded unsigned integer represented by
--   <tt>ceil(log_2(n))</tt> bits.
--   
--   Given an upper bound <tt>n</tt>, an <a>Index</a> <tt>n</tt> number has
--   a range of: [0 .. <tt>n</tt>-1]
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Index 8
--   7
--   
--   &gt;&gt;&gt; minBound :: Index 8
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Index 8)) :: Index 8
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Index 8
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Index 8
--   *** Exception: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 1 - 3 :: Index 8
--   *** Exception: Clash.Sized.Index: result -2 is out of bounds: [0..7]
--   ...
--   
--   &gt;&gt;&gt; 2 * 3 :: Index 8
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Index 8
--   *** Exception: Clash.Sized.Index: result 8 is out of bounds: [0..7]
--   ...
--   </pre>
data Index (n :: Nat)

-- | An alternative implementation of <a>unpack</a> for the <a>Index</a>
--   data type; for when you know the size of the <a>BitVector</a> and want
--   to determine the size of the <a>Index</a>.
--   
--   That is, the type of <a>unpack</a> is:
--   
--   <pre>
--   <b>unpack</b> :: <a>BitVector</a> (<a>CLog</a> 2 n) -&gt; <a>Index</a> n
--   </pre>
--   
--   And is useful when you know the size of the <a>Index</a>, and want to
--   get a value from a <a>BitVector</a> that is large enough (<tt>CLog 2
--   n</tt>) enough to hold an <a>Index</a>. Note that <a>unpack</a> can
--   fail at <i>run-time</i> when the value inside the <a>BitVector</a> is
--   higher than 'n-1'.
--   
--   <a>bv2i</a> on the other hand will <i>never</i> fail at run-time,
--   because the <a>BitVector</a> argument determines the size.
bv2i :: KnownNat n => BitVector n -> Index (2 ^ n)


module Clash.Signal.Internal

-- | A domain with a name (<tt>Symbol</tt>) and a clock period
--   (<tt>Nat</tt>) in <i>ps</i>
data Domain
Dom :: Symbol -> Nat -> Domain
[domainName] :: Domain -> Symbol
[clkPeriod] :: Domain -> Nat

-- | CλaSH has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (domain :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>domain</i> is the
--   <i>clock-</i> (and <i>reset-</i>) domain to which the memory elements
--   manipulating these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>domain</i>, is of the kind <a>Domain</a> which
--   has types of the following shape:
--   
--   <pre>
--   data Domain = Dom { domainName :: <a>Symbol</a>, clkPeriod :: <a>Nat</a> }
--   </pre>
--   
--   Where <i>domainName</i> is a type-level string (<a>Symbol</a>)
--   representing the name of the <i>clock-</i> (and <i>reset-</i>) domain,
--   and <i>clkPeriod</i> is a type-level natural number (<a>Nat</a>)
--   representing the clock period (in <b>ps</b>) of the clock lines in the
--   <i>clock-domain</i>.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   </ul>
data Signal (domain :: Domain) a

-- | The constructor, <tt>(<a>:-</a>)</tt>, is <b>not</b> synthesisable.
(:-) :: a -> Signal domain a -> Signal a

-- | A clock signal belonging to a <tt>domain</tt>
data Clock (domain :: Domain) (gated :: ClockKind)
[Clock] :: (domain ~ ( 'Dom name period)) => SSymbol name -> SNat period -> Clock domain  'Source
[GatedClock] :: (domain ~ ( 'Dom name period)) => SSymbol name -> SNat period -> Signal domain Bool -> Clock domain  'Gated

-- | Distinction between gated and ungated clocks
data ClockKind

-- | A clock signal coming straight from the clock source
Source :: ClockKind

-- | A clock signal that has been gated
Gated :: ClockKind

-- | Get the clock period of a <a>Clock</a> (in <i>ps</i>) as a <a>Num</a>
clockPeriod :: Num a => Clock domain gated -> a

-- | If the clock is gated, return <a>Just</a> the <i>enable</i> signal,
--   <a>Nothing</a> otherwise
clockEnable :: Clock domain gated -> Maybe (Signal domain Bool)

-- | Clock gating primitive
clockGate :: Clock domain gated -> Signal domain Bool -> Clock domain  'Gated

-- | A reset signal belonging to a <tt>domain</tt>.
--   
--   The underlying representation of resets is <a>Bool</a>. Note that all
--   components in the <b>clash-prelude</b> package have an
--   <i>active-high</i> reset port, i.e., the component is reset when the
--   reset port is <a>True</a>.
data Reset (domain :: Domain) (synchronous :: ResetKind)
[Sync] :: Signal domain Bool -> Reset domain  'Synchronous
[Async] :: Signal domain Bool -> Reset domain  'Asynchronous

-- | The "kind" of reset
--   
--   Given a situation where a reset is asserted, and then de-asserted at
--   the active flank of the clock, we can observe the difference between a
--   synchronous reset and an asynchronous reset:
--   
--   <h3>Synchronous reset</h3>
--   
--   <pre>
--   registerS
--     :: Clock domain gated -&gt; Reset domain Synchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerS = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 4 (registerS (clockGen @System) (syncResetGen @System) 0 (fromList [1,2,3])))
--   [X,0,2,3]
--   </pre>
--   
--   <h3>Asynchronous reset</h3>
--   
--   <pre>
--   registerA
--     :: Clock domain gated -&gt; Reset domain Asynchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerA = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 4 (registerA (clockGen @System) (asyncResetGen @System) 0 (fromList [1,2,3]))
--   [0,1,2,3]
--   </pre>
data ResetKind

-- | Components with a synchronous reset port produce the reset value when:
--   
--   <ul>
--   <li>The reset is asserted during the active flank of the clock to
--   which the component is synchronized.</li>
--   </ul>
Synchronous :: ResetKind

-- | Components with an asynchronous reset port produce the reset value
--   when:
--   
--   <ul>
--   <li>Immediately when the reset is asserted.</li>
--   </ul>
Asynchronous :: ResetKind

-- | <a>unsafeFromAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
unsafeFromAsyncReset :: Reset domain  'Asynchronous -> Signal domain Bool

-- | <a>unsafeToAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li>combinational loops</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   resetSynchronizer
--     :: Clock domain gated
--     -&gt; Reset domain 'Asynchronous
--     -&gt; Reset domain 'Asynchronous
--   resetSynchronizer clk rst  =
--     let r1 = register clk rst True (pure False)
--         r2 = register clk rst True r1
--     in  <a>unsafeToAsyncReset</a> r2
--   </pre>
unsafeToAsyncReset :: Signal domain Bool -> Reset domain  'Asynchronous

-- | It is safe to treat synchronous resets as <tt>Bool</tt> signals
fromSyncReset :: Reset domain  'Synchronous -> Signal domain Bool

-- | <a>unsafeToSyncReset</a> is unsafe because:
--   
--   <ul>
--   <li>It can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.</li>
--   </ul>
unsafeToSyncReset :: Signal domain Bool -> Reset domain  'Synchronous
delay# :: HasCallStack => Clock domain gated -> Signal domain a -> Signal domain a
register# :: HasCallStack => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA = clockGen @DomA
--   </pre>
clockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Clock domain  'Source

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA en = clockGen @DomA en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type DomA1 = Dom "A" 1 -- fast, twice as fast as slow
--   type DomB2 = Dom "B" 2 -- slow
--   
--   topEntity
--     :: Clock DomA1 Source
--     -&gt; Reset DomA1 Asynchronous
--     -&gt; Clock DomB2 Source
--     -&gt; Signal DomA1 (Unsigned 8)
--     -&gt; Signal DomB2 (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 clk2 i =
--     let h = register clk1 rst1 0 (register clk1 rst1 0 i)
--         l = register clk1 rst1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h,l))
--   
--   testBench
--     :: Signal DomB2 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clkA1 rstA1 $(listToVecTH [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = outputVerifier   clkB2 rstB2 $(listToVecTH [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 clkB2 testInput)
--       done'          = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @DomA1 (unsafeSynchronizer clkB2 clkA1 done')
--       clkB2          = <a>tbClockGen</a> @DomB2 done'
--       rstA1          = asyncResetGen @DomA1
--       rstB2          = asyncResetGen @DomB2
--   </pre>
tbClockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Signal domain Bool -> Clock domain  'Source

-- | Asynchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = asyncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type Dom2 = Dom "dom" 2
--   type Dom7 = Dom "dom" 7
--   type Dom9 = Dom "dom" 9
--   
--   topEntity
--     :: Clock Dom2 Source
--     -&gt; Clock Dom7 Source
--     -&gt; Clock Dom9 Source
--     -&gt; Signal Dom7 Integer
--     -&gt; Signal Dom9 Integer
--   topEntity clk2 clk7 clk9 i = delay clk9 (unsafeSynchronizer clk2 clk9 (delay clk2 (unsafeSynchronizer clk7 clk2 (delay clk7 i))))
--   {--}
--   
--   testBench
--     :: Signal Dom9 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clk7 rst7 $(listToVecTH [(1::Integer)..10])
--       expectedOutput = outputVerifier   clk9 rst9
--                           ((undefined :&gt; undefined :&gt; Nil) ++ $(listToVecTH ([2,3,4,5,7,8,9,10]::[Integer])))
--       done           = expectedOutput (topEntity clk2 clk7 clk9 testInput)
--       done'          = not &lt;$&gt; done
--       clk2           = tbClockGen @Dom2 (unsafeSynchronizer clk9 clk2 done')
--       clk7           = tbClockGen @Dom7 (unsafeSynchronizer clk9 clk7 done')
--       clk9           = tbClockGen @Dom9 done'
--       rst7           = <a>asyncResetGen</a> @Dom7
--       rst9           = <a>asyncResetGen</a> @Dom9
--   </pre>
asyncResetGen :: Reset domain  'Asynchronous

-- | Synchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = syncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
syncResetGen :: (domain ~  'Dom n clkPeriod, KnownNat clkPeriod) => Reset domain  'Synchronous

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen systemResetGen 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate :: (NFData a, NFData b) => (Signal domain1 a -> Signal domain2 b) -> [a] -> [b]

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen systemResetGen 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate_lazy :: (Signal domain1 a -> Signal domain2 b) -> [a] -> [b]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample :: (Foldable f, NFData a) => f a -> [a]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN :: (Foldable f, NFData a) => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList :: NFData a => [a] -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample_lazy :: Foldable f => f a -> [a]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN_lazy :: Foldable f => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList_lazy :: [a] -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>testFor</b> :: <a>Int</a> -&gt; <a>Signal</a> Bool -&gt; <a>Property</a>
--   </pre>
--   
--   <tt>testFor n s</tt> tests the signal <tt>s</tt> for <tt>n</tt>
--   cycles.
testFor :: Foldable f => Int -> f Bool -> Property

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.
mapSignal# :: (a -> b) -> Signal domain a -> Signal domain b
signal# :: a -> Signal domain a
appSignal# :: Signal domain (a -> b) -> Signal domain a -> Signal domain b

-- | <b>NB</b>: Not synthesisable
--   
--   <b>NB</b>: In "<tt><a>foldr#</a> f z s</tt>":
--   
--   <ul>
--   <li>The function <tt>f</tt> should be <i>lazy</i> in its second
--   argument.</li>
--   <li>The <tt>z</tt> element will never be used.</li>
--   </ul>
foldr# :: (a -> b -> b) -> b -> Signal domain a -> b
traverse# :: Applicative f => (a -> f b) -> Signal domain a -> f (Signal domain b)

-- | <b>WARNING: EXTREMELY EXPERIMENTAL</b>
--   
--   The circuit semantics of this operation are unclear and/or
--   non-existent. There is a good reason there is no <a>Monad</a> instance
--   for <tt>Signal'</tt>.
--   
--   Is currently treated as <a>id</a> by the Clash compiler.
joinSignal# :: Signal domain (Signal domain a) -> Signal domain a
instance Control.DeepSeq.NFData Clash.Signal.Internal.ResetKind
instance GHC.Generics.Generic Clash.Signal.Internal.ResetKind
instance GHC.Show.Show Clash.Signal.Internal.ResetKind
instance GHC.Classes.Ord Clash.Signal.Internal.ResetKind
instance GHC.Classes.Eq Clash.Signal.Internal.ResetKind
instance Control.DeepSeq.NFData Clash.Signal.Internal.ClockKind
instance GHC.Generics.Generic Clash.Signal.Internal.ClockKind
instance GHC.Show.Show Clash.Signal.Internal.ClockKind
instance GHC.Classes.Ord Clash.Signal.Internal.ClockKind
instance GHC.Classes.Eq Clash.Signal.Internal.ClockKind
instance GHC.Show.Show (Clash.Signal.Internal.Clock domain gated)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Signal.Internal.Signal domain a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Signal.Internal.Signal domain a)
instance Data.Default.Class.Default a => Data.Default.Class.Default (Clash.Signal.Internal.Signal domain a)
instance GHC.Base.Functor (Clash.Signal.Internal.Signal domain)
instance GHC.Base.Applicative (Clash.Signal.Internal.Signal domain)
instance GHC.Num.Num a => GHC.Num.Num (Clash.Signal.Internal.Signal domain a)
instance Data.Foldable.Foldable (Clash.Signal.Internal.Signal domain)
instance Data.Traversable.Traversable (Clash.Signal.Internal.Signal domain)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Clash.Signal.Internal.Signal domain a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Signal.Internal.Signal domain a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Signal.Internal.Signal domain a)


-- | PLL and other clock-related components for Intel (Altera) FPGAs
module Clash.Intel.ClockGen

-- | A clock source that corresponds to the Intel/Quartus "ALTPLL"
--   component with settings to provide a stable <a>Clock</a> from a single
--   free-running input
--   
--   Only works when configured with:
--   
--   <ul>
--   <li>1 reference clock</li>
--   <li>1 output clock</li>
--   <li>a reset port</li>
--   <li>a locked port</li>
--   </ul>
--   
--   You must use type applications to specify the output clock domain,
--   e.g.:
--   
--   <pre>
--   type Dom100MHz = Dom "A" 10000
--   
--   -- outputs a clock running at 100 MHz
--   altpll @<tt>Dom100MHz (SSymbol </tt>@"altpll50to100") clk50 rst
--   </pre>
altpll :: forall pllOut pllIn name. SSymbol name -> Clock pllIn  'Source -> Reset pllIn  'Asynchronous -> (Clock pllOut  'Source, Signal pllOut Bool)

-- | A clock source that corresponds to the Intel/Quartus "Altera PLL"
--   component with settings to provide a stable <a>Clock</a> from a single
--   free-running input
--   
--   Only works when configured with:
--   
--   <ul>
--   <li>1 reference clock</li>
--   <li>1 output clock</li>
--   <li>a reset port</li>
--   <li>a locked port</li>
--   </ul>
--   
--   You must use type applications to specify the output clock domain,
--   e.g.:
--   
--   <pre>
--   type Dom100MHz = Dom "A" 10000
--   
--   -- outputs a clock running at 100 MHz
--   alteraPll @<tt>Dom100MHz (SSymbol </tt>@"alteraPll50to100") clk50 rst
--   </pre>
alteraPll :: forall pllOut pllIn name. SSymbol name -> Clock pllIn  'Source -> Reset pllIn  'Asynchronous -> (Clock pllOut  'Source, Signal pllOut Bool)


module Clash.Promoted.Nat.Unsafe

-- | I hope you know what you're doing
unsafeSNat :: Integer -> SNat k


module Clash.Promoted.Nat.TH

-- | Create an <a>SNat</a> literal
--   
--   <pre>
--   $(decLiteralD 1111)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t d1111
--   d1111 :: SNat 1111
--   </pre>
decLiteralD :: Integer -> Q [Dec]

-- | Create a range of <a>SNat</a> literals
--   
--   <pre>
--   $(decLiteralsD 1200 1202)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t d1200
--   d1200 :: SNat 1200
--   
--   &gt;&gt;&gt; :t d1201
--   d1201 :: SNat 1201
--   
--   &gt;&gt;&gt; :t d1202
--   d1202 :: SNat 1202
--   </pre>
decLiteralsD :: Integer -> Integer -> Q [Dec]


-- | Predefined <tt>SNat</tt> singleton literals in the range [0 .. 1024]
--   
--   Defines:
--   
--   <pre>
--   d0 = SNat :: SNat 0
--   d1 = SNat :: SNat 1
--   d2 = SNat :: SNat 2
--   ...
--   d1024 = SNat :: SNat 1024
--   </pre>
--   
--   You can generate more <tt>SNat</tt> literals using <a>decLiteralsD</a>
--   from <a>Clash.Promoted.Nat.TH</a>
module Clash.Promoted.Nat.Literals
d1024 :: SNat 1024
d1023 :: SNat 1023
d1022 :: SNat 1022
d1021 :: SNat 1021
d1020 :: SNat 1020
d1019 :: SNat 1019
d1018 :: SNat 1018
d1017 :: SNat 1017
d1016 :: SNat 1016
d1015 :: SNat 1015
d1014 :: SNat 1014
d1013 :: SNat 1013
d1012 :: SNat 1012
d1011 :: SNat 1011
d1010 :: SNat 1010
d1009 :: SNat 1009
d1008 :: SNat 1008
d1007 :: SNat 1007
d1006 :: SNat 1006
d1005 :: SNat 1005
d1004 :: SNat 1004
d1003 :: SNat 1003
d1002 :: SNat 1002
d1001 :: SNat 1001
d1000 :: SNat 1000
d999 :: SNat 999
d998 :: SNat 998
d997 :: SNat 997
d996 :: SNat 996
d995 :: SNat 995
d994 :: SNat 994
d993 :: SNat 993
d992 :: SNat 992
d991 :: SNat 991
d990 :: SNat 990
d989 :: SNat 989
d988 :: SNat 988
d987 :: SNat 987
d986 :: SNat 986
d985 :: SNat 985
d984 :: SNat 984
d983 :: SNat 983
d982 :: SNat 982
d981 :: SNat 981
d980 :: SNat 980
d979 :: SNat 979
d978 :: SNat 978
d977 :: SNat 977
d976 :: SNat 976
d975 :: SNat 975
d974 :: SNat 974
d973 :: SNat 973
d972 :: SNat 972
d971 :: SNat 971
d970 :: SNat 970
d969 :: SNat 969
d968 :: SNat 968
d967 :: SNat 967
d966 :: SNat 966
d965 :: SNat 965
d964 :: SNat 964
d963 :: SNat 963
d962 :: SNat 962
d961 :: SNat 961
d960 :: SNat 960
d959 :: SNat 959
d958 :: SNat 958
d957 :: SNat 957
d956 :: SNat 956
d955 :: SNat 955
d954 :: SNat 954
d953 :: SNat 953
d952 :: SNat 952
d951 :: SNat 951
d950 :: SNat 950
d949 :: SNat 949
d948 :: SNat 948
d947 :: SNat 947
d946 :: SNat 946
d945 :: SNat 945
d944 :: SNat 944
d943 :: SNat 943
d942 :: SNat 942
d941 :: SNat 941
d940 :: SNat 940
d939 :: SNat 939
d938 :: SNat 938
d937 :: SNat 937
d936 :: SNat 936
d935 :: SNat 935
d934 :: SNat 934
d933 :: SNat 933
d932 :: SNat 932
d931 :: SNat 931
d930 :: SNat 930
d929 :: SNat 929
d928 :: SNat 928
d927 :: SNat 927
d926 :: SNat 926
d925 :: SNat 925
d924 :: SNat 924
d923 :: SNat 923
d922 :: SNat 922
d921 :: SNat 921
d920 :: SNat 920
d919 :: SNat 919
d918 :: SNat 918
d917 :: SNat 917
d916 :: SNat 916
d915 :: SNat 915
d914 :: SNat 914
d913 :: SNat 913
d912 :: SNat 912
d911 :: SNat 911
d910 :: SNat 910
d909 :: SNat 909
d908 :: SNat 908
d907 :: SNat 907
d906 :: SNat 906
d905 :: SNat 905
d904 :: SNat 904
d903 :: SNat 903
d902 :: SNat 902
d901 :: SNat 901
d900 :: SNat 900
d899 :: SNat 899
d898 :: SNat 898
d897 :: SNat 897
d896 :: SNat 896
d895 :: SNat 895
d894 :: SNat 894
d893 :: SNat 893
d892 :: SNat 892
d891 :: SNat 891
d890 :: SNat 890
d889 :: SNat 889
d888 :: SNat 888
d887 :: SNat 887
d886 :: SNat 886
d885 :: SNat 885
d884 :: SNat 884
d883 :: SNat 883
d882 :: SNat 882
d881 :: SNat 881
d880 :: SNat 880
d879 :: SNat 879
d878 :: SNat 878
d877 :: SNat 877
d876 :: SNat 876
d875 :: SNat 875
d874 :: SNat 874
d873 :: SNat 873
d872 :: SNat 872
d871 :: SNat 871
d870 :: SNat 870
d869 :: SNat 869
d868 :: SNat 868
d867 :: SNat 867
d866 :: SNat 866
d865 :: SNat 865
d864 :: SNat 864
d863 :: SNat 863
d862 :: SNat 862
d861 :: SNat 861
d860 :: SNat 860
d859 :: SNat 859
d858 :: SNat 858
d857 :: SNat 857
d856 :: SNat 856
d855 :: SNat 855
d854 :: SNat 854
d853 :: SNat 853
d852 :: SNat 852
d851 :: SNat 851
d850 :: SNat 850
d849 :: SNat 849
d848 :: SNat 848
d847 :: SNat 847
d846 :: SNat 846
d845 :: SNat 845
d844 :: SNat 844
d843 :: SNat 843
d842 :: SNat 842
d841 :: SNat 841
d840 :: SNat 840
d839 :: SNat 839
d838 :: SNat 838
d837 :: SNat 837
d836 :: SNat 836
d835 :: SNat 835
d834 :: SNat 834
d833 :: SNat 833
d832 :: SNat 832
d831 :: SNat 831
d830 :: SNat 830
d829 :: SNat 829
d828 :: SNat 828
d827 :: SNat 827
d826 :: SNat 826
d825 :: SNat 825
d824 :: SNat 824
d823 :: SNat 823
d822 :: SNat 822
d821 :: SNat 821
d820 :: SNat 820
d819 :: SNat 819
d818 :: SNat 818
d817 :: SNat 817
d816 :: SNat 816
d815 :: SNat 815
d814 :: SNat 814
d813 :: SNat 813
d812 :: SNat 812
d811 :: SNat 811
d810 :: SNat 810
d809 :: SNat 809
d808 :: SNat 808
d807 :: SNat 807
d806 :: SNat 806
d805 :: SNat 805
d804 :: SNat 804
d803 :: SNat 803
d802 :: SNat 802
d801 :: SNat 801
d800 :: SNat 800
d799 :: SNat 799
d798 :: SNat 798
d797 :: SNat 797
d796 :: SNat 796
d795 :: SNat 795
d794 :: SNat 794
d793 :: SNat 793
d792 :: SNat 792
d791 :: SNat 791
d790 :: SNat 790
d789 :: SNat 789
d788 :: SNat 788
d787 :: SNat 787
d786 :: SNat 786
d785 :: SNat 785
d784 :: SNat 784
d783 :: SNat 783
d782 :: SNat 782
d781 :: SNat 781
d780 :: SNat 780
d779 :: SNat 779
d778 :: SNat 778
d777 :: SNat 777
d776 :: SNat 776
d775 :: SNat 775
d774 :: SNat 774
d773 :: SNat 773
d772 :: SNat 772
d771 :: SNat 771
d770 :: SNat 770
d769 :: SNat 769
d768 :: SNat 768
d767 :: SNat 767
d766 :: SNat 766
d765 :: SNat 765
d764 :: SNat 764
d763 :: SNat 763
d762 :: SNat 762
d761 :: SNat 761
d760 :: SNat 760
d759 :: SNat 759
d758 :: SNat 758
d757 :: SNat 757
d756 :: SNat 756
d755 :: SNat 755
d754 :: SNat 754
d753 :: SNat 753
d752 :: SNat 752
d751 :: SNat 751
d750 :: SNat 750
d749 :: SNat 749
d748 :: SNat 748
d747 :: SNat 747
d746 :: SNat 746
d745 :: SNat 745
d744 :: SNat 744
d743 :: SNat 743
d742 :: SNat 742
d741 :: SNat 741
d740 :: SNat 740
d739 :: SNat 739
d738 :: SNat 738
d737 :: SNat 737
d736 :: SNat 736
d735 :: SNat 735
d734 :: SNat 734
d733 :: SNat 733
d732 :: SNat 732
d731 :: SNat 731
d730 :: SNat 730
d729 :: SNat 729
d728 :: SNat 728
d727 :: SNat 727
d726 :: SNat 726
d725 :: SNat 725
d724 :: SNat 724
d723 :: SNat 723
d722 :: SNat 722
d721 :: SNat 721
d720 :: SNat 720
d719 :: SNat 719
d718 :: SNat 718
d717 :: SNat 717
d716 :: SNat 716
d715 :: SNat 715
d714 :: SNat 714
d713 :: SNat 713
d712 :: SNat 712
d711 :: SNat 711
d710 :: SNat 710
d709 :: SNat 709
d708 :: SNat 708
d707 :: SNat 707
d706 :: SNat 706
d705 :: SNat 705
d704 :: SNat 704
d703 :: SNat 703
d702 :: SNat 702
d701 :: SNat 701
d700 :: SNat 700
d699 :: SNat 699
d698 :: SNat 698
d697 :: SNat 697
d696 :: SNat 696
d695 :: SNat 695
d694 :: SNat 694
d693 :: SNat 693
d692 :: SNat 692
d691 :: SNat 691
d690 :: SNat 690
d689 :: SNat 689
d688 :: SNat 688
d687 :: SNat 687
d686 :: SNat 686
d685 :: SNat 685
d684 :: SNat 684
d683 :: SNat 683
d682 :: SNat 682
d681 :: SNat 681
d680 :: SNat 680
d679 :: SNat 679
d678 :: SNat 678
d677 :: SNat 677
d676 :: SNat 676
d675 :: SNat 675
d674 :: SNat 674
d673 :: SNat 673
d672 :: SNat 672
d671 :: SNat 671
d670 :: SNat 670
d669 :: SNat 669
d668 :: SNat 668
d667 :: SNat 667
d666 :: SNat 666
d665 :: SNat 665
d664 :: SNat 664
d663 :: SNat 663
d662 :: SNat 662
d661 :: SNat 661
d660 :: SNat 660
d659 :: SNat 659
d658 :: SNat 658
d657 :: SNat 657
d656 :: SNat 656
d655 :: SNat 655
d654 :: SNat 654
d653 :: SNat 653
d652 :: SNat 652
d651 :: SNat 651
d650 :: SNat 650
d649 :: SNat 649
d648 :: SNat 648
d647 :: SNat 647
d646 :: SNat 646
d645 :: SNat 645
d644 :: SNat 644
d643 :: SNat 643
d642 :: SNat 642
d641 :: SNat 641
d640 :: SNat 640
d639 :: SNat 639
d638 :: SNat 638
d637 :: SNat 637
d636 :: SNat 636
d635 :: SNat 635
d634 :: SNat 634
d633 :: SNat 633
d632 :: SNat 632
d631 :: SNat 631
d630 :: SNat 630
d629 :: SNat 629
d628 :: SNat 628
d627 :: SNat 627
d626 :: SNat 626
d625 :: SNat 625
d624 :: SNat 624
d623 :: SNat 623
d622 :: SNat 622
d621 :: SNat 621
d620 :: SNat 620
d619 :: SNat 619
d618 :: SNat 618
d617 :: SNat 617
d616 :: SNat 616
d615 :: SNat 615
d614 :: SNat 614
d613 :: SNat 613
d612 :: SNat 612
d611 :: SNat 611
d610 :: SNat 610
d609 :: SNat 609
d608 :: SNat 608
d607 :: SNat 607
d606 :: SNat 606
d605 :: SNat 605
d604 :: SNat 604
d603 :: SNat 603
d602 :: SNat 602
d601 :: SNat 601
d600 :: SNat 600
d599 :: SNat 599
d598 :: SNat 598
d597 :: SNat 597
d596 :: SNat 596
d595 :: SNat 595
d594 :: SNat 594
d593 :: SNat 593
d592 :: SNat 592
d591 :: SNat 591
d590 :: SNat 590
d589 :: SNat 589
d588 :: SNat 588
d587 :: SNat 587
d586 :: SNat 586
d585 :: SNat 585
d584 :: SNat 584
d583 :: SNat 583
d582 :: SNat 582
d581 :: SNat 581
d580 :: SNat 580
d579 :: SNat 579
d578 :: SNat 578
d577 :: SNat 577
d576 :: SNat 576
d575 :: SNat 575
d574 :: SNat 574
d573 :: SNat 573
d572 :: SNat 572
d571 :: SNat 571
d570 :: SNat 570
d569 :: SNat 569
d568 :: SNat 568
d567 :: SNat 567
d566 :: SNat 566
d565 :: SNat 565
d564 :: SNat 564
d563 :: SNat 563
d562 :: SNat 562
d561 :: SNat 561
d560 :: SNat 560
d559 :: SNat 559
d558 :: SNat 558
d557 :: SNat 557
d556 :: SNat 556
d555 :: SNat 555
d554 :: SNat 554
d553 :: SNat 553
d552 :: SNat 552
d551 :: SNat 551
d550 :: SNat 550
d549 :: SNat 549
d548 :: SNat 548
d547 :: SNat 547
d546 :: SNat 546
d545 :: SNat 545
d544 :: SNat 544
d543 :: SNat 543
d542 :: SNat 542
d541 :: SNat 541
d540 :: SNat 540
d539 :: SNat 539
d538 :: SNat 538
d537 :: SNat 537
d536 :: SNat 536
d535 :: SNat 535
d534 :: SNat 534
d533 :: SNat 533
d532 :: SNat 532
d531 :: SNat 531
d530 :: SNat 530
d529 :: SNat 529
d528 :: SNat 528
d527 :: SNat 527
d526 :: SNat 526
d525 :: SNat 525
d524 :: SNat 524
d523 :: SNat 523
d522 :: SNat 522
d521 :: SNat 521
d520 :: SNat 520
d519 :: SNat 519
d518 :: SNat 518
d517 :: SNat 517
d516 :: SNat 516
d515 :: SNat 515
d514 :: SNat 514
d513 :: SNat 513
d512 :: SNat 512
d511 :: SNat 511
d510 :: SNat 510
d509 :: SNat 509
d508 :: SNat 508
d507 :: SNat 507
d506 :: SNat 506
d505 :: SNat 505
d504 :: SNat 504
d503 :: SNat 503
d502 :: SNat 502
d501 :: SNat 501
d500 :: SNat 500
d499 :: SNat 499
d498 :: SNat 498
d497 :: SNat 497
d496 :: SNat 496
d495 :: SNat 495
d494 :: SNat 494
d493 :: SNat 493
d492 :: SNat 492
d491 :: SNat 491
d490 :: SNat 490
d489 :: SNat 489
d488 :: SNat 488
d487 :: SNat 487
d486 :: SNat 486
d485 :: SNat 485
d484 :: SNat 484
d483 :: SNat 483
d482 :: SNat 482
d481 :: SNat 481
d480 :: SNat 480
d479 :: SNat 479
d478 :: SNat 478
d477 :: SNat 477
d476 :: SNat 476
d475 :: SNat 475
d474 :: SNat 474
d473 :: SNat 473
d472 :: SNat 472
d471 :: SNat 471
d470 :: SNat 470
d469 :: SNat 469
d468 :: SNat 468
d467 :: SNat 467
d466 :: SNat 466
d465 :: SNat 465
d464 :: SNat 464
d463 :: SNat 463
d462 :: SNat 462
d461 :: SNat 461
d460 :: SNat 460
d459 :: SNat 459
d458 :: SNat 458
d457 :: SNat 457
d456 :: SNat 456
d455 :: SNat 455
d454 :: SNat 454
d453 :: SNat 453
d452 :: SNat 452
d451 :: SNat 451
d450 :: SNat 450
d449 :: SNat 449
d448 :: SNat 448
d447 :: SNat 447
d446 :: SNat 446
d445 :: SNat 445
d444 :: SNat 444
d443 :: SNat 443
d442 :: SNat 442
d441 :: SNat 441
d440 :: SNat 440
d439 :: SNat 439
d438 :: SNat 438
d437 :: SNat 437
d436 :: SNat 436
d435 :: SNat 435
d434 :: SNat 434
d433 :: SNat 433
d432 :: SNat 432
d431 :: SNat 431
d430 :: SNat 430
d429 :: SNat 429
d428 :: SNat 428
d427 :: SNat 427
d426 :: SNat 426
d425 :: SNat 425
d424 :: SNat 424
d423 :: SNat 423
d422 :: SNat 422
d421 :: SNat 421
d420 :: SNat 420
d419 :: SNat 419
d418 :: SNat 418
d417 :: SNat 417
d416 :: SNat 416
d415 :: SNat 415
d414 :: SNat 414
d413 :: SNat 413
d412 :: SNat 412
d411 :: SNat 411
d410 :: SNat 410
d409 :: SNat 409
d408 :: SNat 408
d407 :: SNat 407
d406 :: SNat 406
d405 :: SNat 405
d404 :: SNat 404
d403 :: SNat 403
d402 :: SNat 402
d401 :: SNat 401
d400 :: SNat 400
d399 :: SNat 399
d398 :: SNat 398
d397 :: SNat 397
d396 :: SNat 396
d395 :: SNat 395
d394 :: SNat 394
d393 :: SNat 393
d392 :: SNat 392
d391 :: SNat 391
d390 :: SNat 390
d389 :: SNat 389
d388 :: SNat 388
d387 :: SNat 387
d386 :: SNat 386
d385 :: SNat 385
d384 :: SNat 384
d383 :: SNat 383
d382 :: SNat 382
d381 :: SNat 381
d380 :: SNat 380
d379 :: SNat 379
d378 :: SNat 378
d377 :: SNat 377
d376 :: SNat 376
d375 :: SNat 375
d374 :: SNat 374
d373 :: SNat 373
d372 :: SNat 372
d371 :: SNat 371
d370 :: SNat 370
d369 :: SNat 369
d368 :: SNat 368
d367 :: SNat 367
d366 :: SNat 366
d365 :: SNat 365
d364 :: SNat 364
d363 :: SNat 363
d362 :: SNat 362
d361 :: SNat 361
d360 :: SNat 360
d359 :: SNat 359
d358 :: SNat 358
d357 :: SNat 357
d356 :: SNat 356
d355 :: SNat 355
d354 :: SNat 354
d353 :: SNat 353
d352 :: SNat 352
d351 :: SNat 351
d350 :: SNat 350
d349 :: SNat 349
d348 :: SNat 348
d347 :: SNat 347
d346 :: SNat 346
d345 :: SNat 345
d344 :: SNat 344
d343 :: SNat 343
d342 :: SNat 342
d341 :: SNat 341
d340 :: SNat 340
d339 :: SNat 339
d338 :: SNat 338
d337 :: SNat 337
d336 :: SNat 336
d335 :: SNat 335
d334 :: SNat 334
d333 :: SNat 333
d332 :: SNat 332
d331 :: SNat 331
d330 :: SNat 330
d329 :: SNat 329
d328 :: SNat 328
d327 :: SNat 327
d326 :: SNat 326
d325 :: SNat 325
d324 :: SNat 324
d323 :: SNat 323
d322 :: SNat 322
d321 :: SNat 321
d320 :: SNat 320
d319 :: SNat 319
d318 :: SNat 318
d317 :: SNat 317
d316 :: SNat 316
d315 :: SNat 315
d314 :: SNat 314
d313 :: SNat 313
d312 :: SNat 312
d311 :: SNat 311
d310 :: SNat 310
d309 :: SNat 309
d308 :: SNat 308
d307 :: SNat 307
d306 :: SNat 306
d305 :: SNat 305
d304 :: SNat 304
d303 :: SNat 303
d302 :: SNat 302
d301 :: SNat 301
d300 :: SNat 300
d299 :: SNat 299
d298 :: SNat 298
d297 :: SNat 297
d296 :: SNat 296
d295 :: SNat 295
d294 :: SNat 294
d293 :: SNat 293
d292 :: SNat 292
d291 :: SNat 291
d290 :: SNat 290
d289 :: SNat 289
d288 :: SNat 288
d287 :: SNat 287
d286 :: SNat 286
d285 :: SNat 285
d284 :: SNat 284
d283 :: SNat 283
d282 :: SNat 282
d281 :: SNat 281
d280 :: SNat 280
d279 :: SNat 279
d278 :: SNat 278
d277 :: SNat 277
d276 :: SNat 276
d275 :: SNat 275
d274 :: SNat 274
d273 :: SNat 273
d272 :: SNat 272
d271 :: SNat 271
d270 :: SNat 270
d269 :: SNat 269
d268 :: SNat 268
d267 :: SNat 267
d266 :: SNat 266
d265 :: SNat 265
d264 :: SNat 264
d263 :: SNat 263
d262 :: SNat 262
d261 :: SNat 261
d260 :: SNat 260
d259 :: SNat 259
d258 :: SNat 258
d257 :: SNat 257
d256 :: SNat 256
d255 :: SNat 255
d254 :: SNat 254
d253 :: SNat 253
d252 :: SNat 252
d251 :: SNat 251
d250 :: SNat 250
d249 :: SNat 249
d248 :: SNat 248
d247 :: SNat 247
d246 :: SNat 246
d245 :: SNat 245
d244 :: SNat 244
d243 :: SNat 243
d242 :: SNat 242
d241 :: SNat 241
d240 :: SNat 240
d239 :: SNat 239
d238 :: SNat 238
d237 :: SNat 237
d236 :: SNat 236
d235 :: SNat 235
d234 :: SNat 234
d233 :: SNat 233
d232 :: SNat 232
d231 :: SNat 231
d230 :: SNat 230
d229 :: SNat 229
d228 :: SNat 228
d227 :: SNat 227
d226 :: SNat 226
d225 :: SNat 225
d224 :: SNat 224
d223 :: SNat 223
d222 :: SNat 222
d221 :: SNat 221
d220 :: SNat 220
d219 :: SNat 219
d218 :: SNat 218
d217 :: SNat 217
d216 :: SNat 216
d215 :: SNat 215
d214 :: SNat 214
d213 :: SNat 213
d212 :: SNat 212
d211 :: SNat 211
d210 :: SNat 210
d209 :: SNat 209
d208 :: SNat 208
d207 :: SNat 207
d206 :: SNat 206
d205 :: SNat 205
d204 :: SNat 204
d203 :: SNat 203
d202 :: SNat 202
d201 :: SNat 201
d200 :: SNat 200
d199 :: SNat 199
d198 :: SNat 198
d197 :: SNat 197
d196 :: SNat 196
d195 :: SNat 195
d194 :: SNat 194
d193 :: SNat 193
d192 :: SNat 192
d191 :: SNat 191
d190 :: SNat 190
d189 :: SNat 189
d188 :: SNat 188
d187 :: SNat 187
d186 :: SNat 186
d185 :: SNat 185
d184 :: SNat 184
d183 :: SNat 183
d182 :: SNat 182
d181 :: SNat 181
d180 :: SNat 180
d179 :: SNat 179
d178 :: SNat 178
d177 :: SNat 177
d176 :: SNat 176
d175 :: SNat 175
d174 :: SNat 174
d173 :: SNat 173
d172 :: SNat 172
d171 :: SNat 171
d170 :: SNat 170
d169 :: SNat 169
d168 :: SNat 168
d167 :: SNat 167
d166 :: SNat 166
d165 :: SNat 165
d164 :: SNat 164
d163 :: SNat 163
d162 :: SNat 162
d161 :: SNat 161
d160 :: SNat 160
d159 :: SNat 159
d158 :: SNat 158
d157 :: SNat 157
d156 :: SNat 156
d155 :: SNat 155
d154 :: SNat 154
d153 :: SNat 153
d152 :: SNat 152
d151 :: SNat 151
d150 :: SNat 150
d149 :: SNat 149
d148 :: SNat 148
d147 :: SNat 147
d146 :: SNat 146
d145 :: SNat 145
d144 :: SNat 144
d143 :: SNat 143
d142 :: SNat 142
d141 :: SNat 141
d140 :: SNat 140
d139 :: SNat 139
d138 :: SNat 138
d137 :: SNat 137
d136 :: SNat 136
d135 :: SNat 135
d134 :: SNat 134
d133 :: SNat 133
d132 :: SNat 132
d131 :: SNat 131
d130 :: SNat 130
d129 :: SNat 129
d128 :: SNat 128
d127 :: SNat 127
d126 :: SNat 126
d125 :: SNat 125
d124 :: SNat 124
d123 :: SNat 123
d122 :: SNat 122
d121 :: SNat 121
d120 :: SNat 120
d119 :: SNat 119
d118 :: SNat 118
d117 :: SNat 117
d116 :: SNat 116
d115 :: SNat 115
d114 :: SNat 114
d113 :: SNat 113
d112 :: SNat 112
d111 :: SNat 111
d110 :: SNat 110
d109 :: SNat 109
d108 :: SNat 108
d107 :: SNat 107
d106 :: SNat 106
d105 :: SNat 105
d104 :: SNat 104
d103 :: SNat 103
d102 :: SNat 102
d101 :: SNat 101
d100 :: SNat 100
d99 :: SNat 99
d98 :: SNat 98
d97 :: SNat 97
d96 :: SNat 96
d95 :: SNat 95
d94 :: SNat 94
d93 :: SNat 93
d92 :: SNat 92
d91 :: SNat 91
d90 :: SNat 90
d89 :: SNat 89
d88 :: SNat 88
d87 :: SNat 87
d86 :: SNat 86
d85 :: SNat 85
d84 :: SNat 84
d83 :: SNat 83
d82 :: SNat 82
d81 :: SNat 81
d80 :: SNat 80
d79 :: SNat 79
d78 :: SNat 78
d77 :: SNat 77
d76 :: SNat 76
d75 :: SNat 75
d74 :: SNat 74
d73 :: SNat 73
d72 :: SNat 72
d71 :: SNat 71
d70 :: SNat 70
d69 :: SNat 69
d68 :: SNat 68
d67 :: SNat 67
d66 :: SNat 66
d65 :: SNat 65
d64 :: SNat 64
d63 :: SNat 63
d62 :: SNat 62
d61 :: SNat 61
d60 :: SNat 60
d59 :: SNat 59
d58 :: SNat 58
d57 :: SNat 57
d56 :: SNat 56
d55 :: SNat 55
d54 :: SNat 54
d53 :: SNat 53
d52 :: SNat 52
d51 :: SNat 51
d50 :: SNat 50
d49 :: SNat 49
d48 :: SNat 48
d47 :: SNat 47
d46 :: SNat 46
d45 :: SNat 45
d44 :: SNat 44
d43 :: SNat 43
d42 :: SNat 42
d41 :: SNat 41
d40 :: SNat 40
d39 :: SNat 39
d38 :: SNat 38
d37 :: SNat 37
d36 :: SNat 36
d35 :: SNat 35
d34 :: SNat 34
d33 :: SNat 33
d32 :: SNat 32
d31 :: SNat 31
d30 :: SNat 30
d29 :: SNat 29
d28 :: SNat 28
d27 :: SNat 27
d26 :: SNat 26
d25 :: SNat 25
d24 :: SNat 24
d23 :: SNat 23
d22 :: SNat 22
d21 :: SNat 21
d20 :: SNat 20
d19 :: SNat 19
d18 :: SNat 18
d17 :: SNat 17
d16 :: SNat 16
d15 :: SNat 15
d14 :: SNat 14
d13 :: SNat 13
d12 :: SNat 12
d11 :: SNat 11
d10 :: SNat 10
d9 :: SNat 9
d8 :: SNat 8
d7 :: SNat 7
d6 :: SNat 6
d5 :: SNat 5
d4 :: SNat 4
d3 :: SNat 3
d2 :: SNat 2
d1 :: SNat 1
d0 :: SNat 0


module Clash.Sized.Vector

-- | Fixed size vectors.
--   
--   <ul>
--   <li>Lists with their length encoded in their type</li>
--   <li><a>Vec</a>tor elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.</li>
--   </ul>
data Vec :: Nat -> * -> *
[Nil] :: Vec 0 a

-- | The length of a <a>Vec</a>tor as an <a>Int</a> value.
--   
--   <pre>
--   &gt;&gt;&gt; length (6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   3
--   </pre>
length :: KnownNat n => Vec n a -> Int

-- | Length of a <a>Vec</a>tor as an <a>SNat</a> value
lengthS :: KnownNat n => Vec n a -> SNat n

-- | "<tt>xs</tt> <a>!!</a> <tt>n</tt>" returns the <i>n</i>'th element of
--   <i>xs</i>.
--   
--   <b>NB</b>: vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 4
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! (length (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) - 1)
--   5
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 1
--   2
--   
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) !! 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 4
--   ...
--   </pre>
(!!) :: (KnownNat n, Enum i) => Vec n a -> i -> a

-- | Extract the first element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; head (1:&gt;2:&gt;3:&gt;Nil)
--   1
--   
--   &gt;&gt;&gt; head Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘head’, namely ‘Nil’
--         In the expression: head Nil
--         In an equation for ‘it’: it = head Nil
--   </pre>
head :: Vec (n + 1) a -> a

-- | Extract the last element of a vector
--   
--   <pre>
--   &gt;&gt;&gt; last (1:&gt;2:&gt;3:&gt;Nil)
--   3
--   
--   &gt;&gt;&gt; last Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘last’, namely ‘Nil’
--         In the expression: last Nil
--         In an equation for ‘it’: it = last Nil
--   </pre>
last :: Vec (n + 1) a -> a

-- | "<a>at</a> <tt>n xs</tt>" returns <i>n</i>'th element of <i>xs</i>
--   
--   <b>NB</b>: vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; at (SNat :: SNat 1) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   
--   &gt;&gt;&gt; at d1               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   2
--   </pre>
at :: SNat m -> Vec (m + (n + 1)) a -> a

-- | Generate a vector of indices.
--   
--   <pre>
--   &gt;&gt;&gt; indices d4
--   &lt;0,1,2,3&gt;
--   </pre>
indices :: KnownNat n => SNat n -> Vec n (Index n)

-- | Generate a vector of indices, where the length of the vector is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; indicesI :: Vec 4 (Index 4)
--   &lt;0,1,2,3&gt;
--   </pre>
indicesI :: KnownNat n => Vec n (Index n)

-- | "<a>findIndex</a> <tt>p xs</tt>" returns the index of the <i>first</i>
--   element of <i>xs</i> satisfying the predicate <i>p</i>, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 3) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 3
--   
--   &gt;&gt;&gt; findIndex (&gt; 8) (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
findIndex :: KnownNat n => (a -> Bool) -> Vec n a -> Maybe (Index n)

-- | "<a>elemIndex</a> <tt>a xs</tt>" returns the index of the <i>first</i>
--   element which is equal (by <a>==</a>) to the query element <i>a</i>,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   &gt;&gt;&gt; elemIndex 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; elemIndex 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
elemIndex :: (KnownNat n, Eq a) => a -> Vec n a -> Maybe (Index n)

-- | Extract the elements after the head of a vector
--   
--   <pre>
--   &gt;&gt;&gt; tail (1:&gt;2:&gt;3:&gt;Nil)
--   &lt;2,3&gt;
--   
--   &gt;&gt;&gt; tail Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘tail’, namely ‘Nil’
--         In the expression: tail Nil
--         In an equation for ‘it’: it = tail Nil
--   </pre>
tail :: Vec (n + 1) a -> Vec n a

-- | Extract all the elements of a vector except the last element
--   
--   <pre>
--   &gt;&gt;&gt; init (1:&gt;2:&gt;3:&gt;Nil)
--   &lt;1,2&gt;
--   
--   &gt;&gt;&gt; init Nil
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘1’ with ‘0’
--         Expected type: Vec (0 + 1) a
--           Actual type: Vec 0 a
--       • In the first argument of ‘init’, namely ‘Nil’
--         In the expression: init Nil
--         In an equation for ‘it’: it = init Nil
--   </pre>
init :: Vec (n + 1) a -> Vec n a

-- | "<a>take</a> <tt>n xs</tt>" returns the <i>n</i>-length prefix of
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; take (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;1,2,3&gt;
--   
--   &gt;&gt;&gt; take d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;1,2,3&gt;
--   
--   &gt;&gt;&gt; take d0               (1:&gt;2:&gt;Nil)
--   &lt;&gt;
--   
--   &gt;&gt;&gt; take d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘4 + n0’ with ‘2’
--         Expected type: Vec (4 + n0) a
--           Actual type: Vec (1 + 1) a
--         The type variable ‘n0’ is ambiguous
--       • In the second argument of ‘take’, namely ‘(1 :&gt; 2 :&gt; Nil)’
--         In the expression: take d4 (1 :&gt; 2 :&gt; Nil)
--         In an equation for ‘it’: it = take d4 (1 :&gt; 2 :&gt; Nil)
--   </pre>
take :: SNat m -> Vec (m + n) a -> Vec m a

-- | "<a>takeI</a> <tt>xs</tt>" returns the prefix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; takeI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   &lt;1,2&gt;
--   </pre>
takeI :: KnownNat m => Vec (m + n) a -> Vec m a

-- | "<a>drop</a> <tt>n xs</tt>" returns the suffix of <i>xs</i> after the
--   first <i>n</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; drop (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;4,5&gt;
--   
--   &gt;&gt;&gt; drop d3               (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;4,5&gt;
--   
--   &gt;&gt;&gt; drop d0               (1:&gt;2:&gt;Nil)
--   &lt;1,2&gt;
--   
--   &gt;&gt;&gt; drop d4               (1:&gt;2:&gt;Nil)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match expected type ‘2’ with actual type ‘4 + n0’
--         The type variable ‘n0’ is ambiguous
--       • In the first argument of ‘print’, namely ‘it’
--         In a stmt of an interactive GHCi command: print it
--   </pre>
drop :: SNat m -> Vec (m + n) a -> Vec n a

-- | "<a>dropI</a> <tt>xs</tt>" returns the suffix of <i>xs</i> as demanded
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; dropI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 2 Int
--   &lt;4,5&gt;
--   </pre>
dropI :: KnownNat m => Vec (m + n) a -> Vec n a

-- | "<a>select</a> <tt>f s n xs</tt>" selects <i>n</i> elements with
--   step-size <i>s</i> and offset <tt>f</tt> from <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; select (SNat :: SNat 1) (SNat :: SNat 2) (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   &lt;2,4,6&gt;
--   
--   &gt;&gt;&gt; select d1 d2 d3 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   &lt;2,4,6&gt;
--   </pre>
select :: (CmpNat (i + s) (s * n) ~  'GT) => SNat f -> SNat s -> SNat n -> Vec (f + i) a -> Vec n a

-- | "<a>selectI</a> <tt>f s xs</tt>" selects as many elements as demanded
--   by the context with step-size <i>s</i> and offset <i>f</i> from
--   <i>xs</i>.
--   
--   <pre>
--   &gt;&gt;&gt; selectI d1 d2 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;Nil) :: Vec 2 Int
--   &lt;2,4&gt;
--   </pre>
selectI :: (CmpNat (i + s) (s * n) ~  'GT, KnownNat n) => SNat f -> SNat s -> Vec (f + i) a -> Vec n a

-- | Split a vector into two vectors at the given point.
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (SNat :: SNat 3) (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (&lt;1,2,3&gt;,&lt;7,8&gt;)
--   
--   &gt;&gt;&gt; splitAt d3 (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil)
--   (&lt;1,2,3&gt;,&lt;7,8&gt;)
--   </pre>
splitAt :: SNat m -> Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector into two vectors where the length of the two is
--   determined by the context.
--   
--   <pre>
--   &gt;&gt;&gt; splitAtI (1:&gt;2:&gt;3:&gt;7:&gt;8:&gt;Nil) :: (Vec 2 Int, Vec 3 Int)
--   (&lt;1,2&gt;,&lt;3,7,8&gt;)
--   </pre>
splitAtI :: KnownNat m => Vec (m + n) a -> (Vec m a, Vec n a)

-- | Split a vector of (n * m) elements into a vector of "vectors of length
--   <i>m</i>", where the length <i>m</i> is given.
--   
--   <pre>
--   &gt;&gt;&gt; unconcat d4 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil)
--   &lt;&lt;1,2,3,4&gt;,&lt;5,6,7,8&gt;,&lt;9,10,11,12&gt;&gt;
--   </pre>
unconcat :: KnownNat n => SNat m -> Vec (n * m) a -> Vec n (Vec m a)

-- | Split a vector of <i>(n * m)</i> elements into a vector of "vectors of
--   length <i>m</i>", where the length <i>m</i> is determined by the
--   context.
--   
--   <pre>
--   &gt;&gt;&gt; unconcatI (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;7:&gt;8:&gt;9:&gt;10:&gt;11:&gt;12:&gt;Nil) :: Vec 2 (Vec 6 Int)
--   &lt;&lt;1,2,3,4,5,6&gt;,&lt;7,8,9,10,11,12&gt;&gt;
--   </pre>
unconcatI :: (KnownNat n, KnownNat m) => Vec (n * m) a -> Vec n (Vec m a)

-- | Create a vector of one element
--   
--   <pre>
--   &gt;&gt;&gt; singleton 5
--   &lt;5&gt;
--   </pre>
singleton :: a -> Vec 1 a

-- | "<a>replicate</a> <tt>n a</tt>" returns a vector that has <i>n</i>
--   copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; replicate (SNat :: SNat 3) 6
--   &lt;6,6,6&gt;
--   
--   &gt;&gt;&gt; replicate d3 6
--   &lt;6,6,6&gt;
--   </pre>
replicate :: SNat n -> a -> Vec n a

-- | "<a>repeat</a> <tt>a</tt>" creates a vector with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; repeat 6 :: Vec 5 Int
--   &lt;6,6,6,6,6&gt;
--   </pre>
repeat :: KnownNat n => a -> Vec n a

-- | "<a>iterate</a> <tt>n f x</tt>" returns a vector starting with
--   <i>x</i> followed by <i>n</i> repeated applications of <i>f</i> to
--   <i>x</i>.
--   
--   <pre>
--   iterate (SNat :: SNat 4) f x == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   iterate d4 f x               == (x :&gt; f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterate d4 (+1) 1
--   &lt;1,2,3,4&gt;
--   </pre>
--   
--   "<tt>interate</tt> <tt>n f z</tt>" corresponds to the following
--   circuit layout:
--   
iterate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>iterate</a> <tt>f x</tt>" returns a vector starting with
--   <tt>x</tt> followed by <tt>n</tt> repeated applications of <tt>f</tt>
--   to <tt>x</tt>, where <tt>n</tt> is determined by the context.
--   
--   <pre>
--   iterateI f x :: Vec 3 a == (x :&gt; f x :&gt; f (f x) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; iterateI (+1) 1 :: Vec 3 Int
--   &lt;1,2,3&gt;
--   </pre>
--   
--   "<tt>interateI</tt> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
iterateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | "<a>generate</a> <tt>n f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>.
--   
--   <pre>
--   generate (SNat :: SNat 4) f x == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   generate d4 f x               == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; f (f (f (f x))) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generate d4 (+1) 1
--   &lt;2,3,4,5&gt;
--   </pre>
--   
--   "<a>generate</a> <tt>n f z</tt>" corresponds to the following circuit
--   layout:
--   
generate :: SNat n -> (a -> a) -> a -> Vec n a

-- | "<a>generateI</a> <tt>f x</tt>" returns a vector with <tt>n</tt>
--   repeated applications of <tt>f</tt> to <tt>x</tt>, where <tt>n</tt> is
--   determined by the context.
--   
--   <pre>
--   generateI f x :: Vec 3 a == (f x :&gt; f (f x) :&gt; f (f (f x)) :&gt; Nil)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; generateI (+1) 1 :: Vec 3 Int
--   &lt;2,3,4&gt;
--   </pre>
--   
--   "<a>generateI</a> <tt>f z</tt>" corresponds to the following circuit
--   layout:
--   
generateI :: KnownNat n => (a -> a) -> a -> Vec n a

-- | Create a vector literal from a list literal.
--   
--   <pre>
--   $(listToVecTH [1::Signed 8,2,3,4,5]) == (8:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil) :: Vec 5 (Signed 8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1 :: Signed 8,2,3,4,5]
--   [1,2,3,4,5]
--   
--   &gt;&gt;&gt; $(listToVecTH [1::Signed 8,2,3,4,5])
--   &lt;1,2,3,4,5&gt;
--   </pre>
listToVecTH :: Lift a => [a] -> ExpQ

-- | Append two vectors.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;Nil) ++ (7:&gt;8:&gt;Nil)
--   &lt;1,2,3,7,8&gt;
--   </pre>
(++) :: Vec n a -> Vec m a -> Vec (n + m) a
infixr 5 ++

-- | Add an element to the head of a vector, and extract all but the last
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil)
--   &lt;1,3,4&gt;
--   
--   &gt;&gt;&gt; 1 +&gt;&gt; Nil
--   &lt;&gt;
--   </pre>
(+>>) :: KnownNat n => a -> Vec n a -> Vec n a
infixr 4 +>>

-- | Add an element to the tail of a vector, and extract all but the first
--   element.
--   
--   <pre>
--   &gt;&gt;&gt; (3:&gt;4:&gt;5:&gt;Nil) &lt;&lt;+ 1
--   &lt;4,5,1&gt;
--   
--   &gt;&gt;&gt; Nil &lt;&lt;+ 1
--   &lt;&gt;
--   </pre>
(<<+) :: Vec n a -> a -> Vec n a
infixl 4 <<+

-- | Concatenate a vector of vectors.
--   
--   <pre>
--   &gt;&gt;&gt; concat ((1:&gt;2:&gt;3:&gt;Nil) :&gt; (4:&gt;5:&gt;6:&gt;Nil) :&gt; (7:&gt;8:&gt;9:&gt;Nil) :&gt; (10:&gt;11:&gt;12:&gt;Nil) :&gt; Nil)
--   &lt;1,2,3,4,5,6,7,8,9,10,11,12&gt;
--   </pre>
concat :: Vec n (Vec m a) -> Vec (n * m) a

-- | Shift in elements to the head of a vector, bumping out elements at the
--   tail. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (&lt;-1,0,1,2&gt;,&lt;3,4&gt;)
--   
--   &gt;&gt;&gt; shiftInAt0 (1 :&gt; Nil) ((-1) :&gt; 0 :&gt; Nil)
--   (&lt;-1&gt;,&lt;0,1&gt;)
--   </pre>
shiftInAt0 :: KnownNat n => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift in element to the tail of a vector, bumping out elements at the
--   head. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out elements</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; Nil)
--   (&lt;3,4,5,6&gt;,&lt;1,2&gt;)
--   
--   &gt;&gt;&gt; shiftInAtN (1 :&gt; Nil) (2 :&gt; 3 :&gt; Nil)
--   (&lt;3&gt;,&lt;1,2&gt;)
--   </pre>
shiftInAtN :: KnownNat m => Vec n a -> Vec m a -> (Vec n a, Vec m a)

-- | Shift <i>m</i> elements out from the head of a vector, filling up the
--   tail with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFrom0 d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (&lt;3,4,5,0,0&gt;,&lt;1,2&gt;)
--   </pre>
shiftOutFrom0 :: (Default a, KnownNat m) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Shift <i>m</i> elements out from the tail of a vector, filling up the
--   head with <a>Default</a> values. The result is a tuple containing:
--   
--   <ul>
--   <li>The new vector</li>
--   <li>The shifted out values</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; shiftOutFromN d2 ((1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; Nil) :: Vec 5 Integer)
--   (&lt;0,0,1,2,3&gt;,&lt;4,5&gt;)
--   </pre>
shiftOutFromN :: (Default a, KnownNat n) => SNat m -> Vec (m + n) a -> (Vec (m + n) a, Vec m a)

-- | Merge two vectors, alternating their elements, i.e.,
--   
--   <pre>
--   &gt;&gt;&gt; merge (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil) (5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; Nil)
--   &lt;1,5,2,6,3,7,4,8&gt;
--   </pre>
merge :: KnownNat n => Vec n a -> Vec n a -> Vec (2 * n) a

-- | "<a>replace</a> <tt>n a xs</tt>" returns the vector <i>xs</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   <b>NB</b>: vector elements have an <b>ASCENDING</b> subscript starting
--   from 0 and ending at <tt><a>length</a> - 1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; replace 3 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;1,2,3,7,5&gt;
--   
--   &gt;&gt;&gt; replace 0 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;7,2,3,4,5&gt;
--   
--   &gt;&gt;&gt; replace 9 7 (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;Nil)
--   &lt;1,2,3,4,*** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 4
--   ...
--   </pre>
replace :: (KnownNat n, Enum i) => i -> a -> Vec n a -> Vec n a

-- | Forward permutation specified by an index mapping, <i>ix</i>. The
--   result vector is initialised by the given defaults, <i>def</i>, and an
--   further values that are permuted into the result are added to the
--   current value using the given combination function, <i>f</i>.
--   
--   The combination function must be <i>associative</i> and
--   <i>commutative</i>.
permute :: (Enum i, KnownNat n, KnownNat m) => (a -> a -> a) -> Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>backpermute</a> <tt>xs is</tt>" is equivalent to "<a>map</a>
--   <tt>(xs <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; backpermute input from
--   &lt;9,4,1,6,2,4&gt;
--   </pre>
backpermute :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | Copy elements from the source vector, <i>xs</i>, to the destination
--   vector according to an index mapping <i>is</i>. This is a forward
--   permute operation where a <i>to</i> vector encodes an input to output
--   index mapping. Output elements for indices that are not mapped assume
--   the value in the default vector <i>def</i>.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let defVec = 0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;0:&gt;Nil
--   
--   &gt;&gt;&gt; let to = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;8:&gt;Nil
--   
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;5:&gt;Nil
--   
--   &gt;&gt;&gt; scatter defVec to input
--   &lt;0,1,4,9,0,4,0,6,2&gt;
--   </pre>
--   
--   <b>NB</b>: If the same index appears in the index mapping more than
--   once, the latest mapping is chosen.
scatter :: (Enum i, KnownNat n, KnownNat m) => Vec n a -> Vec m i -> Vec (m + k) a -> Vec n a

-- | Backwards permutation specified by an index mapping, <i>is</i>, from
--   the destination vector specifying which element of the source vector
--   <i>xs</i> to read.
--   
--   "<a>gather</a> <tt>xs is</tt>" is equivalent to "<a>map</a> <tt>(xs
--   <a>!!</a>) is</tt>".
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; let input = 1:&gt;9:&gt;6:&gt;4:&gt;4:&gt;2:&gt;0:&gt;1:&gt;2:&gt;Nil
--   
--   &gt;&gt;&gt; let from  = 1:&gt;3:&gt;7:&gt;2:&gt;5:&gt;3:&gt;Nil
--   
--   &gt;&gt;&gt; gather input from
--   &lt;9,4,1,6,2,4&gt;
--   </pre>
gather :: (Enum i, KnownNat n) => Vec n a -> Vec m i -> Vec m a

-- | The elements in a vector in reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; reverse (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   &lt;4,3,2,1&gt;
--   </pre>
reverse :: Vec n a -> Vec n a

-- | Transpose a matrix: go from row-major to column-major
--   
--   <pre>
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;Nil):&gt;(3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   &lt;&lt;1,2&gt;,&lt;3,4&gt;,&lt;5,6&gt;&gt;
--   
--   &gt;&gt;&gt; transpose xss
--   &lt;&lt;1,3,5&gt;,&lt;2,4,6&gt;&gt;
--   </pre>
transpose :: KnownNat n => Vec m (Vec n a) -> Vec n (Vec m a)

-- | "<a>interleave</a> <tt>d xs</tt>" creates a vector:
--   
--   <pre>
--   &lt;x_0,x_d,x_(2d),...,x_1,x_(d+1),x_(2d+1),...,x_(d-1),x_(2d-1),x_(3d-1)&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; 5 :&gt; 6 :&gt; 7 :&gt; 8 :&gt; 9 :&gt; Nil
--   
--   &gt;&gt;&gt; interleave d3 xs
--   &lt;1,4,7,2,5,8,3,6,9&gt;
--   </pre>
interleave :: (KnownNat n, KnownNat d) => SNat d -> Vec (n * d) a -> Vec (d * n) a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeft xs 1
--   &lt;2,3,4,1&gt;
--   
--   &gt;&gt;&gt; rotateLeft xs 2
--   &lt;3,4,1,2&gt;
--   
--   &gt;&gt;&gt; rotateLeft xs (-1)
--   &lt;4,1,2,3&gt;
--   </pre>
--   
--   <b>NB:</b> use <a>rotateLeftS</a> if you want to rotate left by a
--   <i>static</i> amount.
rotateLeft :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Dynamically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRight xs 1
--   &lt;4,1,2,3&gt;
--   
--   &gt;&gt;&gt; rotateRight xs 2
--   &lt;3,4,1,2&gt;
--   
--   &gt;&gt;&gt; rotateRight xs (-1)
--   &lt;2,3,4,1&gt;
--   </pre>
--   
--   <b>NB:</b> use <a>rotateRightS</a> if you want to rotate right by a
--   <i>static</i> amount.
rotateRight :: (Enum i, KnownNat n) => Vec n a -> i -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the left:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateLeftS xs d1
--   &lt;2,3,4,1&gt;
--   </pre>
--   
--   <b>NB:</b> use <a>rotateLeft</a> if you want to rotate left by a
--   <i>dynamic</i> amount.
rotateLeftS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | <i>Statically</i> rotate a <a>Vec</a>tor to the right:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = 1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil
--   
--   &gt;&gt;&gt; rotateRightS xs d1
--   &lt;4,1,2,3&gt;
--   </pre>
--   
--   <b>NB:</b> use <a>rotateRight</a> if you want to rotate right by a
--   <i>dynamic</i> amount.
rotateRightS :: KnownNat n => Vec n a -> SNat d -> Vec n a

-- | "<a>map</a> <tt>f xs</tt>" is the vector obtained by applying <i>f</i>
--   to each element of <i>xs</i>, i.e.,
--   
--   <pre>
--   map f (x1 :&gt; x2 :&gt;  ... :&gt; xn :&gt; Nil) == (f x1 :&gt; f x2 :&gt; ... :&gt; f xn :&gt; Nil)
--   </pre>
--   
--   and corresponds to the following circuit layout:
--   
map :: (a -> b) -> Vec n a -> Vec n b

-- | Apply a function of every element of a vector and its index.
--   
--   <pre>
--   &gt;&gt;&gt; :t imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Index 4)
--   
--   &gt;&gt;&gt; imap (+) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil)
--   &lt;2,3,*** Exception: Clash.Sized.Index: result 4 is out of bounds: [0..3]
--   ...
--   
--   &gt;&gt;&gt; imap (\i a -&gt; fromIntegral i + a) (2 :&gt; 2 :&gt; 2 :&gt; 2 :&gt; Nil) :: Vec 4 (Unsigned 8)
--   &lt;2,3,4,5&gt;
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
imap :: forall n a b. KnownNat n => (Index n -> a -> b) -> Vec n a -> Vec n b

-- | Apply a function to every element of a vector and the element's
--   position (as an <a>SNat</a> value) in the vector.
--   
--   <pre>
--   &gt;&gt;&gt; let rotateMatrix = smap (flip rotateRightS)
--   
--   &gt;&gt;&gt; let xss = (1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;(1:&gt;2:&gt;3:&gt;Nil):&gt;Nil
--   
--   &gt;&gt;&gt; xss
--   &lt;&lt;1,2,3&gt;,&lt;1,2,3&gt;,&lt;1,2,3&gt;&gt;
--   
--   &gt;&gt;&gt; rotateMatrix xss
--   &lt;&lt;1,2,3&gt;,&lt;3,1,2&gt;,&lt;2,3,1&gt;&gt;
--   </pre>
smap :: forall k a b. KnownNat k => (forall l. SNat l -> a -> b) -> Vec k a -> Vec k b

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "<a>zipWith</a> <tt>(+)</tt>" applied to two vectors produces
--   the vector of corresponding sums.
--   
--   <pre>
--   zipWith f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) == (f x1 y1 :&gt; f x2 y2 :&gt; ... :&gt; f xn yn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith</a> <tt>f xs ys</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB:</b> <a>zipWith</a> is <i>strict</i> in its second argument, and
--   <i>lazy</i> in its third. This matters when <a>zipWith</a> is used in
--   a recursive setting. See <a>lazyV</a> for more information.
zipWith :: (a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>zipWith3</a> generalises <a>zip3</a> by zipping with the function
--   given as the first argument, instead of a tupling function.
--   
--   <pre>
--   zipWith3 f (x1 :&gt; x2 :&gt; ... xn :&gt; Nil) (y1 :&gt; y2 :&gt; ... :&gt; yn :&gt; Nil) (z1 :&gt; z2 :&gt; ... :&gt; zn :&gt; Nil) == (f x1 y1 z1 :&gt; f x2 y2 z2 :&gt; ... :&gt; f xn yn zn :&gt; Nil)
--   </pre>
--   
--   "<a>zipWith3</a> <tt>f xs ys zs</tt>" corresponds to the following
--   circuit layout:
--   
--   
--   <b>NB:</b> <a>zipWith3</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third and fourth. This matters when
--   <a>zipWith3</a> is used in a recursive setting. See <a>lazyV</a> for
--   more information.
zipWith3 :: (a -> b -> c -> d) -> Vec n a -> Vec n b -> Vec n c -> Vec n d

-- | <a>zip</a> takes two vectors and returns a vector of corresponding
--   pairs.
--   
--   <pre>
--   &gt;&gt;&gt; zip (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil)
--   &lt;(1,4),(2,3),(3,2),(4,1)&gt;
--   </pre>
zip :: Vec n a -> Vec n b -> Vec n (a, b)

-- | <a>zip</a> takes three vectors and returns a vector of corresponding
--   triplets.
--   
--   <pre>
--   &gt;&gt;&gt; zip3 (1:&gt;2:&gt;3:&gt;4:&gt;Nil) (4:&gt;3:&gt;2:&gt;1:&gt;Nil) (5:&gt;6:&gt;7:&gt;8:&gt;Nil)
--   &lt;(1,4,5),(2,3,6),(3,2,7),(4,1,8)&gt;
--   </pre>
zip3 :: Vec n a -> Vec n b -> Vec n c -> Vec n (a, b, c)

-- | Zip two vectors with a functions that also takes the elements'
--   indices.
--   
--   <pre>
--   &gt;&gt;&gt; izipWith (\i a b -&gt; i + a + b) (2 :&gt; 2 :&gt; Nil)  (3 :&gt; 3:&gt; Nil)
--   &lt;*** Exception: Clash.Sized.Index: result 3 is out of bounds: [0..1]
--   ...
--   
--   &gt;&gt;&gt; izipWith (\i a b -&gt; fromIntegral i + a + b) (2 :&gt; 2 :&gt; Nil) (3 :&gt; 3 :&gt; Nil) :: Vec 2 (Unsigned 8)
--   &lt;5,6&gt;
--   </pre>
--   
--   "<a>imap</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB:</b> <a>izipWith</a> is <i>strict</i> in its second argument,
--   and <i>lazy</i> in its third. This matters when <a>izipWith</a> is
--   used in a recursive setting. See <a>lazyV</a> for more information.
izipWith :: KnownNat n => (Index n -> a -> b -> c) -> Vec n a -> Vec n b -> Vec n c

-- | <a>unzip</a> transforms a vector of pairs into a vector of first
--   components and a vector of second components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip ((1,4):&gt;(2,3):&gt;(3,2):&gt;(4,1):&gt;Nil)
--   (&lt;1,2,3,4&gt;,&lt;4,3,2,1&gt;)
--   </pre>
unzip :: Vec n (a, b) -> (Vec n a, Vec n b)

-- | <a>unzip3</a> transforms a vector of triplets into a vector of first
--   components, a vector of second components, and a vector of third
--   components.
--   
--   <pre>
--   &gt;&gt;&gt; unzip3 ((1,4,5):&gt;(2,3,6):&gt;(3,2,7):&gt;(4,1,8):&gt;Nil)
--   (&lt;1,2,3,4&gt;,&lt;4,3,2,1&gt;,&lt;5,6,7,8&gt;)
--   </pre>
unzip3 :: Vec n (a, b, c) -> (Vec n a, Vec n b, Vec n c)

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z (x1 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn1 `f` (xn `f` z))...)
--   foldr r z Nil                             == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldr :: (a -> b -> b) -> b -> Vec n a -> b

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a vector, reduces
--   the vector using the binary operator, from left to right:
--   
--   <pre>
--   foldl f z (x1 :&gt; x2 :&gt; ... :&gt; xn :&gt; Nil) == (...((z `f` x1) `f` x2) `f`...) `f` xn
--   foldl f z Nil                            == z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (/) 1 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl</a> f z xs"</tt> produces a linear structure,
--   which has a depth, or delay, of O(<tt><a>length</a> xs</tt>). Use
--   <a>fold</a> if your binary operator <tt>f</tt> is associative, as
--   <tt>"<a>fold</a> f xs"</tt> produces a structure with a depth of
--   O(log_2(<tt><a>length</a> xs</tt>)).
foldl :: (b -> a -> b) -> b -> Vec n a -> b

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldr1 f (x1 :&gt; ... :&gt; xn2 :&gt; xn1 :&gt; xn :&gt; Nil) == x1 `f` (... (xn2 `f` (xn1 `f` xn))...)
--   foldr1 f (x1 :&gt; Nil)                            == x1
--   foldr1 f Nil                                    == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (/) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   1.875
--   </pre>
--   
--   "<a>foldr1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldr1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldr1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty vectors.
--   
--   <pre>
--   foldl1 f (x1 :&gt; x2 :&gt; x3 :&gt; ... :&gt; xn :&gt; Nil) == (...((x1 `f` x2) `f` x3) `f`...) `f` xn
--   foldl1 f (x1 :&gt; Nil)                          == x1
--   foldl1 f Nil                                  == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (/) (1 :&gt; 5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   8.333333333333333e-3
--   </pre>
--   
--   "<a>foldl1</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>: <tt>"<a>foldl1</a> f z xs"</tt> produces a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Use <a>fold</a> if your binary operator <tt>f</tt> is
--   associative, as <tt>"<a>fold</a> f xs"</tt> produces a structure with
--   a depth of O(log_2(<tt><a>length</a> xs</tt>)).
foldl1 :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | <a>fold</a> is a variant of <a>foldr1</a> and <a>foldl1</a>, but
--   instead of reducing from right to left, or left to right, it reduces a
--   vector using a tree-like structure. The depth, or delay, of the
--   structure produced by "<tt><a>fold</a> f xs</tt>", is hence
--   <tt>O(log_2(<a>length</a> xs))</tt>, and not <tt>O(<a>length</a>
--   xs)</tt>.
--   
--   <b>NB</b>: The binary operator "<tt>f</tt>" in "<tt><a>fold</a> f
--   xs</tt>" must be associative.
--   
--   <pre>
--   fold f (x1 :&gt; x2 :&gt; ... :&gt; xn1 :&gt; xn :&gt; Nil) == ((x1 `f` x2) `f` ...) `f` (... `f` (xn1 `f` xn))
--   fold f (x1 :&gt; Nil)                           == x1
--   fold f Nil                                   == TYPE ERROR
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fold (+) (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; 1 :&gt; Nil)
--   15
--   </pre>
--   
--   "<a>fold</a> <tt>f xs</tt>" corresponds to the following circuit
--   layout:
--   
fold :: (a -> a -> a) -> Vec (n + 1) a -> a

-- | Right fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findLeftmost x xs = ifoldr (\i a b -&gt; if a == x then Just i else b) Nothing xs
--   
--   &gt;&gt;&gt; findLeftmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 1
--   
--   &gt;&gt;&gt; findLeftmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldr :: KnownNat n => (Index n -> a -> b -> b) -> b -> Vec n a -> b

-- | Left fold (function applied to each element and its index)
--   
--   <pre>
--   &gt;&gt;&gt; let findRightmost x xs = ifoldl (\a i b -&gt; if b == x then Just i else a) Nothing xs
--   
--   &gt;&gt;&gt; findRightmost 3 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Just 4
--   
--   &gt;&gt;&gt; findRightmost 8 (1:&gt;3:&gt;2:&gt;4:&gt;3:&gt;5:&gt;6:&gt;Nil)
--   Nothing
--   </pre>
--   
--   "<a>ifoldl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
ifoldl :: KnownNat n => (a -> Index n -> b -> a) -> a -> Vec n b -> a

-- | A <i>dependently</i> typed fold.
--   
--   Using lists, we can define <i>append</i> (a.k.a.
--   <tt>Data.List.</tt><a>++</a>) in terms of
--   <tt>Data.List.</tt><a>foldr</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List
--   
--   &gt;&gt;&gt; let append xs ys = Data.List.foldr (:) ys xs
--   
--   &gt;&gt;&gt; append [1,2] [3,4]
--   [1,2,3,4]
--   </pre>
--   
--   However, when we try to do the same for <a>Vec</a>, by defining
--   <i>append'</i> in terms of <tt>Clash.Sized.Vector.</tt><a>foldr</a>:
--   
--   <pre>
--   append' xs ys = <a>foldr</a> (:&gt;) ys xs
--   </pre>
--   
--   we get a type error:
--   
--   <pre>
--   <b>&gt;&gt;&gt; let append' xs ys = foldr (:&gt;) ys xs</b>
--   
--   &lt;interactive&gt;:...
--       • Occurs check: cannot construct the infinite type: ... ~ ... + 1
--         Expected type: a -&gt; Vec ... a -&gt; Vec ... a
--           Actual type: a -&gt; Vec ... a -&gt; Vec (... + 1) a
--       • In the first argument of ‘foldr’, namely ‘(:&gt;)’
--         In the expression: foldr (:&gt;) ys xs
--         In an equation for ‘append'’: append' xs ys = foldr (:&gt;) ys xs
--       • Relevant bindings include
--           ys :: Vec ... a (bound at ...)
--           append' :: Vec n a -&gt; Vec ... a -&gt; Vec ... a
--             (bound at ...)
--   </pre>
--   
--   The reason is that the type of <a>foldr</a> is:
--   
--   <pre>
--   &gt;&gt;&gt; :t foldr
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; Vec n a -&gt; b
--   </pre>
--   
--   While the type of (<a>:&gt;</a>) is:
--   
--   <pre>
--   &gt;&gt;&gt; :t (:&gt;)
--   (:&gt;) :: a -&gt; Vec n a -&gt; Vec (n + 1) a
--   </pre>
--   
--   We thus need a <tt>fold</tt> function that can handle the growing
--   vector type: <a>dfold</a>. Compared to <a>foldr</a>, <a>dfold</a>
--   takes an extra parameter, called the <i>motive</i>, that allows the
--   folded function to have an argument and result type that
--   <i>depends</i> on the current length of the vector. Using
--   <a>dfold</a>, we can now correctly define <i>append'</i>:
--   
--   <pre>
--   import Data.Singletons.Prelude
--   import Data.Proxy
--   
--   data Append (m :: Nat) (a :: *) (f :: <a>TyFun</a> Nat *) :: *
--   type instance <a>Apply</a> (Append m a) l = <a>Vec</a> (l + m) a
--   
--   append' xs ys = <a>dfold</a> (Proxy :: Proxy (Append m a)) (const (<a>:&gt;</a>)) ys xs
--   </pre>
--   
--   We now see that <i>append'</i> has the appropriate type:
--   
--   <pre>
--   &gt;&gt;&gt; :t append'
--   append' :: KnownNat k =&gt; Vec k a -&gt; Vec m a -&gt; Vec (k + m) a
--   </pre>
--   
--   And that it works:
--   
--   <pre>
--   &gt;&gt;&gt; append' (1 :&gt; 2 :&gt; Nil) (3 :&gt; 4 :&gt; Nil)
--   &lt;1,2,3,4&gt;
--   </pre>
--   
--   <b>NB</b>: "<tt><a>dfold</a> m f z xs</tt>" creates a linear
--   structure, which has a depth, or delay, of O(<tt><a>length</a>
--   xs</tt>). Look at <a>dtfold</a> for a <i>dependently</i> typed fold
--   that produces a structure with a depth of O(log_2(<tt><a>length</a>
--   xs</tt>)).
dfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat * -> *) -> (forall l. SNat l -> a -> (p @@ l) -> (p @@ (l + 1))) -> (p @@ 0) -> Vec k a -> (p @@ k)

-- | A combination of <a>dfold</a> and <a>fold</a>: a <i>dependently</i>
--   typed fold that reduces a vector in a tree-like structure.
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <a>BitVector</a>. Given a vector of <i>n</i> bits, we
--   only need we need a data type that can represent the number <i>n</i>:
--   <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a range of
--   <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits), hence we need
--   <a>Index</a> <tt>n+1</tt>. As an initial attempt we will use
--   <a>sum</a>, because it gives a nice (<tt>log2(n)</tt>) tree-structure
--   of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (n+1), KnownNat (n+2))
--                   =&gt; <a>BitVector</a> (n+1) -&gt; <a>Index</a> (n+2)
--   populationCount = sum . map fromIntegral . <a>bv2v</a>
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2) -&gt; <a>Index</a> (n+2).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>plus</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <a>fold</a> to create a tree-structure
--   of <a>plus</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (n+1), KnownNat (n+2))
--                        =&gt; BitVector (n+1) -&gt; Index (n+2)
--       populationCount' = fold plus . map fromIntegral . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘((n + 2) + (n + 2)) - 1’ with ‘n + 2’
--         Expected type: Index (n + 2) -&gt; Index (n + 2) -&gt; Index (n + 2)
--           Actual type: Index (n + 2)
--                        -&gt; Index (n + 2) -&gt; AResult (Index (n + 2)) (Index (n + 2))
--       • In the first argument of ‘fold’, namely ‘plus’
--         In the first argument of ‘(.)’, namely ‘fold plus’
--         In the expression: fold plus . map fromIntegral . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (n + 1) -&gt; Index (n + 2)
--             (bound at ...)
--   </pre>
--   
--   because <a>fold</a> expects a function of type "<tt>a -&gt; a -&gt;
--   a</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>plus</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons.Prelude
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat *) :: *
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>dtfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>plus</a> x y)
--                                (<a>bv2v</a> bv)
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
--   
--   Some final remarks:
--   
--   <ul>
--   <li>By using <a>dtfold</a> instead of <a>fold</a>, we had to restrict
--   our <a>BitVector</a> argument to have bit-width that is a power of
--   2.</li>
--   <li>Even though our original <i>populationCount</i> function specified
--   a structure where all adders had the same width. Most
--   VHDL/(System)Verilog synthesis tools will create a more efficient
--   circuit, i.e. one where the adders have an increasing bit-width for
--   every layer, from the VHDL/(System)Verilog produced by the Clash
--   compiler.</li>
--   </ul>
--   
--   <b>NB</b>: The depth, or delay, of the structure produced by
--   "<tt><a>dtfold</a> m f g xs</tt>" is O(log_2(<tt><a>length</a>
--   xs</tt>)).
dtfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat * -> *) -> (a -> (p @@ 0)) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> (p @@ (l + 1))) -> Vec (2 ^ k) a -> (p @@ k)

-- | Specialised version of <a>dfold</a> that builds a triangular
--   computational structure.
--   
--   Example:
--   
--   <pre>
--   compareSwap a b = if a &gt; b then (a,b) else (b,a)
--   insert y xs     = let (y',xs') = <a>mapAccumL</a> compareSwap y xs in xs' <a>:&lt;</a> y'
--   insertionSort   = <a>vfold</a> (const insert)
--   </pre>
--   
--   Builds a triangular structure of compare and swaps to sort a row.
--   
--   <pre>
--   &gt;&gt;&gt; insertionSort (7 :&gt; 3 :&gt; 9 :&gt; 1 :&gt; Nil)
--   &lt;1,3,7,9&gt;
--   </pre>
--   
--   The circuit layout of <tt>insertionSort</tt>, build using
--   <a>vfold</a>, is:
--   
vfold :: forall k a b. KnownNat k => (forall l. SNat l -> a -> Vec l b -> Vec (l + 1) b) -> Vec k a -> Vec k b

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a vector of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == z :&gt; (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   &lt;0,5,9,12,14&gt;
--   </pre>
--   
--   "<a>scanl</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>:
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs
--   </pre>
scanl :: (b -> a -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a vector of
--   successive reduced values from the right:
--   
--   <pre>
--   scanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; z :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; scanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   &lt;14,9,5,2,0&gt;
--   </pre>
--   
--   "<a>scanr</a> <tt>f z xs</tt>" corresponds to the following circuit
--   layout:
--   
--   
--   <b>NB</b>:
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs
--   </pre>
scanr :: (a -> b -> b) -> b -> Vec n a -> Vec (n + 1) b

-- | <a>postscanl</a> is a variant of <a>scanl</a> where the first result
--   is dropped:
--   
--   <pre>
--   postscanl f z (x1 :&gt; x2 :&gt; ... :&gt; Nil) == (z `f` x1) :&gt; ((z `f` x1) `f` x2) :&gt; ... :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanl (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   &lt;5,9,12,14&gt;
--   </pre>
--   
--   "<a>postscanl</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanl :: (b -> a -> b) -> b -> Vec n a -> Vec n b

-- | <a>postscanr</a> is a variant of <a>scanr</a> that where the last
--   result is dropped:
--   
--   <pre>
--   postscanr f z (... :&gt; xn1 :&gt; xn :&gt; Nil) == ... :&gt; (xn1 `f` (xn `f` z)) :&gt; (xn `f` z) :&gt; Nil
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; postscanr (+) 0 (5 :&gt; 4 :&gt; 3 :&gt; 2 :&gt; Nil)
--   &lt;14,9,5,2&gt;
--   </pre>
--   
--   "<a>postscanr</a> <tt>f z xs</tt>" corresponds to the following
--   circuit layout:
--   
postscanr :: (a -> b -> b) -> b -> Vec n a -> Vec n b

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from left to right, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumL (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,&lt;1,2,4,7&gt;)
--   </pre>
--   
--   "<a>mapAccumL</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumL :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a vector,
--   passing an accumulating parameter from right to left, and returning a
--   final value of this accumulator together with the new vector.
--   
--   <pre>
--   &gt;&gt;&gt; mapAccumR (\acc x -&gt; (acc + x,acc + 1)) 0 (1 :&gt; 2 :&gt; 3 :&gt; 4 :&gt; Nil)
--   (10,&lt;10,8,5,1&gt;)
--   </pre>
--   
--   "<a>mapAccumR</a> <tt>f acc xs</tt>" corresponds to the following
--   circuit layout:
--   
mapAccumR :: (acc -> x -> (acc, y)) -> acc -> Vec n x -> (acc, Vec n y)

-- | 1-dimensional stencil computations
--   
--   "<a>stencil1d</a> <tt>stX f xs</tt>", where <i>xs</i> has <i>stX +
--   n</i> elements, applies the stencil computation <i>f</i> on: <i>n +
--   1</i> overlapping (1D) windows of length <i>stX</i>, drawn from
--   <i>xs</i>. The resulting vector has <i>n + 1</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t stencil1d d2 sum xs
--   stencil1d d2 sum xs :: Num b =&gt; Vec 5 b
--   
--   &gt;&gt;&gt; stencil1d d2 sum xs
--   &lt;3,5,7,9,11&gt;
--   </pre>
stencil1d :: KnownNat n => SNat (stX + 1) -> (Vec (stX + 1) a -> b) -> Vec ((stX + n) + 1) a -> Vec (n + 1) b

-- | 2-dimensional stencil computations
--   
--   "<a>stencil2d</a> <tt>stY stX f xss</tt>", where <i>xss</i> is a
--   matrix of <i>stY + m</i> rows of <i>stX + n</i> elements, applies the
--   stencil computation <i>f</i> on: <i>(m + 1) * (n + 1)</i> overlapping
--   (2D) windows of <i>stY</i> rows of <i>stX</i> elements, drawn from
--   <i>xss</i>. The result matrix has <i>m + 1</i> rows of <i>n + 1</i>
--   elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t stencil2d d2 d2 (sum . map sum) xss
--   stencil2d d2 d2 (sum . map sum) xss :: Num b =&gt; Vec 3 (Vec 3 b)
--   
--   &gt;&gt;&gt; stencil2d d2 d2 (sum . map sum) xss
--   &lt;&lt;14,18,22&gt;,&lt;30,34,38&gt;,&lt;46,50,54&gt;&gt;
--   </pre>
stencil2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> (Vec (stY + 1) (Vec (stX + 1) a) -> b) -> Vec ((stY + m) + 1) (Vec ((stX + n) + 1) a) -> Vec (m + 1) (Vec (n + 1) b)

-- | "<a>windows1d</a> <tt>stX xs</tt>", where the vector <i>xs</i> has
--   <i>stX + n</i> elements, returns a vector of <i>n + 1</i> overlapping
--   (1D) windows of <i>xs</i> of length <i>stX</i>.
--   
--   <pre>
--   &gt;&gt;&gt; let xs = (1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil)
--   
--   &gt;&gt;&gt; :t xs
--   xs :: Num a =&gt; Vec 6 a
--   
--   &gt;&gt;&gt; :t windows1d d2 xs
--   windows1d d2 xs :: Num a =&gt; Vec 5 (Vec 2 a)
--   
--   &gt;&gt;&gt; windows1d d2 xs
--   &lt;&lt;1,2&gt;,&lt;2,3&gt;,&lt;3,4&gt;,&lt;4,5&gt;,&lt;5,6&gt;&gt;
--   </pre>
windows1d :: KnownNat n => SNat (stX + 1) -> Vec ((stX + n) + 1) a -> Vec (n + 1) (Vec (stX + 1) a)

-- | "<a>windows2d</a> <tt>stY stX xss</tt>", where matrix <i>xss</i> has
--   <i>stY + m</i> rows of <i>stX + n</i>, returns a matrix of <i>m+1</i>
--   rows of <i>n+1</i> elements. The elements of this new matrix are the
--   overlapping (2D) windows of <i>xss</i>, where every window has
--   <i>stY</i> rows of <i>stX</i> elements.
--   
--   <pre>
--   &gt;&gt;&gt; let xss = ((1:&gt;2:&gt;3:&gt;4:&gt;Nil):&gt;(5:&gt;6:&gt;7:&gt;8:&gt;Nil):&gt;(9:&gt;10:&gt;11:&gt;12:&gt;Nil):&gt;(13:&gt;14:&gt;15:&gt;16:&gt;Nil):&gt;Nil)
--   
--   &gt;&gt;&gt; :t xss
--   xss :: Num a =&gt; Vec 4 (Vec 4 a)
--   
--   &gt;&gt;&gt; :t windows2d d2 d2 xss
--   windows2d d2 d2 xss :: Num a =&gt; Vec 3 (Vec 3 (Vec 2 (Vec 2 a)))
--   
--   &gt;&gt;&gt; windows2d d2 d2 xss
--   &lt;&lt;&lt;&lt;1,2&gt;,&lt;5,6&gt;&gt;,&lt;&lt;2,3&gt;,&lt;6,7&gt;&gt;,&lt;&lt;3,4&gt;,&lt;7,8&gt;&gt;&gt;,&lt;&lt;&lt;5,6&gt;,&lt;9,10&gt;&gt;,&lt;&lt;6,7&gt;,&lt;10,11&gt;&gt;,&lt;&lt;7,8&gt;,&lt;11,12&gt;&gt;&gt;,&lt;&lt;&lt;9,10&gt;,&lt;13,14&gt;&gt;,&lt;&lt;10,11&gt;,&lt;14,15&gt;&gt;,&lt;&lt;11,12&gt;,&lt;15,16&gt;&gt;&gt;&gt;
--   </pre>
windows2d :: (KnownNat n, KnownNat m) => SNat (stY + 1) -> SNat (stX + 1) -> Vec ((stY + m) + 1) (Vec (stX + n + 1) a) -> Vec (m + 1) (Vec (n + 1) (Vec (stY + 1) (Vec (stX + 1) a)))

-- | Convert a vector to a list.
--   
--   <pre>
--   &gt;&gt;&gt; toList (1:&gt;2:&gt;3:&gt;Nil)
--   [1,2,3]
--   </pre>
toList :: Vec n a -> [a]

-- | Convert a <a>BitVector</a> to a <a>Vec</a> of <a>Bit</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 6 :: BitVector 8
--   
--   &gt;&gt;&gt; x
--   0000_0110
--   
--   &gt;&gt;&gt; bv2v x
--   &lt;0,0,0,0,0,1,1,0&gt;
--   </pre>
bv2v :: KnownNat n => BitVector n -> Vec n Bit

-- | Convert a <a>Vec</a> of <a>Bit</a>s to a <a>BitVector</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = (0:&gt;0:&gt;0:&gt;1:&gt;0:&gt;0:&gt;1:&gt;0:&gt;Nil) :: Vec 8 Bit
--   
--   &gt;&gt;&gt; x
--   &lt;0,0,0,1,0,0,1,0&gt;
--   
--   &gt;&gt;&gt; v2bv x
--   0001_0010
--   </pre>
v2bv :: KnownNat n => Vec n Bit -> BitVector n

-- | What you should use when your vector functions are too strict in their
--   arguments.
--   
--   For example:
--   
--   <pre>
--   -- Bubble sort for 1 iteration
--   sortV xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL lefts rights
--   
--   -- Compare and swap
--   compareSwapL a b = if a &lt; b then (a,b)
--                               else (b,a)
--   </pre>
--   
--   Will not terminate because <a>zipWith</a> is too strict in its second
--   argument.
--   
--   In this case, adding <a>lazyV</a> on <a>zipWith</a>s second argument:
--   
--   <pre>
--   sortVL xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; map snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> compareSwapL (<a>lazyV</a> lefts) rights
--   </pre>
--   
--   Results in a successful computation:
--   
--   <pre>
--   &gt;&gt;&gt; sortVL (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   &lt;1,2,3,4&gt;
--   </pre>
--   
--   <b>NB</b>: There is also a solution using <a>flip</a>, but it slightly
--   obfuscates the meaning of the code:
--   
--   <pre>
--   sortV_flip xs = <a>map</a> fst sorted <a>:&lt;</a> (snd (<a>last</a> sorted))
--    where
--      lefts  = <a>head</a> xs :&gt; <a>map</a> snd (<a>init</a> sorted)
--      rights = <a>tail</a> xs
--      sorted = <a>zipWith</a> (<a>flip</a> compareSwapL) rights lefts
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sortV_flip (4 :&gt; 1 :&gt; 2 :&gt; 3 :&gt; Nil)
--   &lt;1,2,3,4&gt;
--   </pre>
lazyV :: KnownNat n => Vec n a -> Vec n a

-- | To be used as the motive <i>p</i> for <a>dfold</a>, when the <i>f</i>
--   in "<a>dfold</a> <tt>p f</tt>" is a variation on (<a>:&gt;</a>), e.g.:
--   
--   <pre>
--   map' :: forall n a b . KnownNat n =&gt; (a -&gt; b) -&gt; Vec n a -&gt; Vec n b
--   map' f = <a>dfold</a> (Proxy @(<a>VCons</a> b)) (_ x xs -&gt; f x :&gt; xs)
--   </pre>
data VCons (a :: *) (f :: TyFun Nat *) :: *

-- | <a>Vec</a>tor as a <a>Proxy</a> for <a>Nat</a>
asNatProxy :: Vec n a -> Proxy n
traverse# :: forall a f b n. Applicative f => (a -> f b) -> Vec n a -> f (Vec n b)
concatBitVector# :: (KnownNat n, KnownNat m) => Vec n (BitVector m) -> BitVector (n * m)
unconcatBitVector# :: forall n m. (KnownNat n, KnownNat m) => BitVector (n * m) -> Vec n (BitVector m)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Clash.Sized.Vector.Vec n a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Sized.Vector.Vec n a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Classes.Eq a) => GHC.Classes.Eq (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.Classes.Ord a) => GHC.Classes.Ord (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat n => GHC.Base.Applicative (Clash.Sized.Vector.Vec n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Foldable.Foldable (Clash.Sized.Vector.Vec n)
instance GHC.Base.Functor (Clash.Sized.Vector.Vec n)
instance (GHC.TypeNats.KnownNat n, 1 GHC.TypeNats.<= n) => Data.Traversable.Traversable (Clash.Sized.Vector.Vec n)
instance (Data.Default.Class.Default a, GHC.TypeNats.KnownNat n) => Data.Default.Class.Default (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize a), Clash.Class.BitPack.BitPack a) => Clash.Class.BitPack.BitPack (Clash.Sized.Vector.Vec n a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Vector.Vec n a)
instance (GHC.TypeNats.KnownNat n, Test.QuickCheck.Arbitrary.Arbitrary a) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Vector.Vec n a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Vector.Vec n a)


module Clash.Sized.RTree

-- | Perfect depth binary tree.
--   
--   <ul>
--   <li>Only has elements at the leaf of the tree</li>
--   <li>A tree of depth <i>d</i> has <i>2^d</i> elements.</li>
--   </ul>
data RTree :: Nat -> * -> *

-- | "<a>treplicate</a> <tt>d a</tt>" returns a tree of depth <i>d</i>, and
--   has <i>2^d</i> copies of <i>a</i>.
--   
--   <pre>
--   &gt;&gt;&gt; treplicate (SNat :: SNat 3) 6
--   &lt;&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;,&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;&gt;
--   
--   &gt;&gt;&gt; treplicate d3 6
--   &lt;&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;,&lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;&gt;
--   </pre>
treplicate :: forall d a. SNat d -> a -> RTree d a

-- | "<a>trepeat</a> <tt>a</tt>" creates a tree with as many copies of
--   <i>a</i> as demanded by the context.
--   
--   <pre>
--   &gt;&gt;&gt; trepeat 6 :: RTree 2 Int
--   &lt;&lt;6,6&gt;,&lt;6,6&gt;&gt;
--   </pre>
trepeat :: KnownNat d => a -> RTree d a

-- | "<a>indexTree</a> <tt>t n</tt>" returns the <i>n</i>'th element of
--   <i>t</i>.
--   
--   The bottom-left leaf had index <i>0</i>, and the bottom-right leaf has
--   index <i>2^d-1</i>, where <i>d</i> is the depth of the tree
--   
--   <pre>
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 0
--   1
--   
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 2
--   3
--   
--   &gt;&gt;&gt; indexTree (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4))) 14
--   *** Exception: Clash.Sized.Vector.(!!): index 14 is larger than maximum index 3
--   ...
--   </pre>
indexTree :: (KnownNat d, Enum i) => RTree d a -> i -> a

-- | Generate a tree of indices, where the depth of the tree is determined
--   by the context.
--   
--   <pre>
--   &gt;&gt;&gt; tindices :: RTree 3 (Index 8)
--   &lt;&lt;&lt;0,1&gt;,&lt;2,3&gt;&gt;,&lt;&lt;4,5&gt;,&lt;6,7&gt;&gt;&gt;
--   </pre>
tindices :: forall d. KnownNat d => RTree d (Index (2 ^ d))

-- | "<a>replaceTree</a> <tt>n a t</tt>" returns the tree <i>t</i> where
--   the <i>n</i>'th element is replaced by <i>a</i>.
--   
--   The bottom-left leaf had index <i>0</i>, and the bottom-right leaf has
--   index <i>2^d-1</i>, where <i>d</i> is the depth of the tree
--   
--   <pre>
--   &gt;&gt;&gt; replaceTree 0 5 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;5,2&gt;,&lt;3,4&gt;&gt;
--   
--   &gt;&gt;&gt; replaceTree 2 7 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;7,4&gt;&gt;
--   
--   &gt;&gt;&gt; replaceTree 9 6 (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;3,*** Exception: Clash.Sized.Vector.replace: index 9 is larger than maximum index 3
--   ...
--   </pre>
replaceTree :: (KnownNat d, Enum i) => i -> a -> RTree d a -> RTree d a

-- | "<a>tmap</a> <tt>f t</tt>" is the tree obtained by apply <i>f</i> to
--   each element of <i>t</i>, i.e.,
--   
--   <pre>
--   tmap f (BR (LR a) (LR b)) == BR (LR (f a)) (LR (f b))
--   </pre>
tmap :: forall d a b. KnownNat d => (a -> b) -> RTree d a -> RTree d b

-- | <a>tzipWith</a> generalises <a>tzip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, "tzipWith (+)" applied to two trees produces the tree of
--   corresponding sums.
--   
--   <pre>
--   tzipWith f (BR (LR a1) (LR b1)) (BR (LR a2) (LR b2)) == BR (LR (f a1 a2)) (LR (f b1 b2))
--   </pre>
tzipWith :: forall a b c d. KnownNat d => (a -> b -> c) -> RTree d a -> RTree d b -> RTree d c

-- | <a>tzip</a> takes two trees and returns a tree of corresponding pairs.
tzip :: KnownNat d => RTree d a -> RTree d b -> RTree d (a, b)

-- | <a>tunzip</a> transforms a tree of pairs into a tree of first
--   components and a tree of second components.
tunzip :: forall d a b. KnownNat d => RTree d (a, b) -> (RTree d a, RTree d b)

-- | Reduce a tree to a single element
tfold :: forall d a b. KnownNat d => (a -> b) -> (b -> b -> b) -> RTree d a -> b

-- | A <i>dependently</i> typed fold over trees.
--   
--   As an example of when you might want to use <a>dtfold</a> we will
--   build a population counter: a circuit that counts the number of bits
--   set to '1' in a <tt>BitVector</tt>. Given a vector of <i>n</i> bits,
--   we only need we need a data type that can represent the number
--   <i>n</i>: <a>Index</a> <tt>(n+1)</tt>. <a>Index</a> <tt>k</tt> has a
--   range of <tt>[0 .. k-1]</tt> (using <tt>ceil(log2(k))</tt> bits),
--   hence we need <a>Index</a> <tt>n+1</tt>. As an initial attempt we will
--   use <a>tfold</a>, because it gives a nice (<tt>log2(n)</tt>)
--   tree-structure of adders:
--   
--   <pre>
--   populationCount :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1))
--                   =&gt; BitVector (2^d) -&gt; Index (2^d+1)
--   populationCount = tfold fromIntegral (+) . v2t . bv2v
--   </pre>
--   
--   The "problem" with this description is that all adders have the same
--   bit-width, i.e. all adders are of the type:
--   
--   <pre>
--   (+) :: <a>Index</a> (2^d+1) -&gt; <a>Index</a> (2^d+1) -&gt; <a>Index</a> (2^d+1).
--   </pre>
--   
--   This is a "problem" because we could have a more efficient structure:
--   one where each layer of adders is <i>precisely</i> wide enough to
--   count the number of bits at that layer. That is, at height <i>d</i> we
--   want the adder to be of type:
--   
--   <pre>
--   <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^d)+1) -&gt; <a>Index</a> ((2^(d+1))+1)
--   </pre>
--   
--   We have such an adder in the form of the <a>plus</a> function, as
--   defined in the instance <a>ExtendingNum</a> instance of <a>Index</a>.
--   However, we cannot simply use <tt>fold</tt> to create a tree-structure
--   of <a>plus</a>es:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let populationCount' :: (KnownNat (2^d), KnownNat d, KnownNat (2^d+1))
--                        =&gt; BitVector (2^d) -&gt; Index (2^d+1)
--       populationCount' = tfold fromIntegral plus . v2t . bv2v
--   :}
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘(((2 ^ d) + 1) + ((2 ^ d) + 1)) - 1’
--                        with ‘(2 ^ d) + 1’
--         Expected type: Index ((2 ^ d) + 1)
--                        -&gt; Index ((2 ^ d) + 1) -&gt; Index ((2 ^ d) + 1)
--           Actual type: Index ((2 ^ d) + 1)
--                        -&gt; Index ((2 ^ d) + 1)
--                        -&gt; AResult (Index ((2 ^ d) + 1)) (Index ((2 ^ d) + 1))
--       • In the second argument of ‘tfold’, namely ‘plus’
--         In the first argument of ‘(.)’, namely ‘tfold fromIntegral plus’
--         In the expression: tfold fromIntegral plus . v2t . bv2v
--       • Relevant bindings include
--           populationCount' :: BitVector (2 ^ d) -&gt; Index ((2 ^ d) + 1)
--             (bound at ...)
--   </pre>
--   
--   because <a>tfold</a> expects a function of type "<tt>b -&gt; b -&gt;
--   b</tt>", i.e. a function where the arguments and result all have
--   exactly the same type.
--   
--   In order to accommodate the type of our <a>plus</a>, where the result
--   is larger than the arguments, we must use a dependently typed fold in
--   the the form of <a>dtfold</a>:
--   
--   <pre>
--   {-# LANGUAGE UndecidableInstances #-}
--   import Data.Singletons.Prelude
--   import Data.Proxy
--   
--   data IIndex (f :: <a>TyFun</a> Nat *) :: *
--   type instance <a>Apply</a> IIndex l = <a>Index</a> ((2^l)+1)
--   
--   populationCount' :: (KnownNat k, KnownNat (2^k))
--                    =&gt; BitVector (2^k) -&gt; Index ((2^k)+1)
--   populationCount' bv = <a>tdfold</a> (Proxy @IIndex)
--                                fromIntegral
--                                (\_ x y -&gt; <a>plus</a> x y)
--                                (<a>v2t</a> (<a>bv2v</a> bv))
--   </pre>
--   
--   And we can test that it works:
--   
--   <pre>
--   &gt;&gt;&gt; :t populationCount' (7 :: BitVector 16)
--   populationCount' (7 :: BitVector 16) :: Index 17
--   
--   &gt;&gt;&gt; populationCount' (7 :: BitVector 16)
--   3
--   </pre>
tdfold :: forall p k a. KnownNat k => Proxy (p :: TyFun Nat * -> *) -> (a -> (p @@ 0)) -> (forall l. SNat l -> (p @@ l) -> (p @@ l) -> (p @@ (l + 1))) -> RTree k a -> (p @@ k)

-- | Convert a vector with <i>2^d</i> elements to a tree of depth <i>d</i>.
--   
--   <pre>
--   &gt;&gt;&gt; (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   &lt;1,2,3,4&gt;
--   
--   &gt;&gt;&gt; v2t (1:&gt;2:&gt;3:&gt;4:&gt;Nil)
--   &lt;&lt;1,2&gt;,&lt;3,4&gt;&gt;
--   </pre>
v2t :: forall d a. KnownNat d => Vec (2 ^ d) a -> RTree d a

-- | Convert a tree of depth <i>d</i> to a vector of <i>2^d</i> elements
--   
--   <pre>
--   &gt;&gt;&gt; (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;&lt;1,2&gt;,&lt;3,4&gt;&gt;
--   
--   &gt;&gt;&gt; t2v (BR (BR (LR 1) (LR 2)) (BR (LR 3) (LR 4)))
--   &lt;1,2,3,4&gt;
--   </pre>
t2v :: forall d a. KnownNat d => RTree d a -> Vec (2 ^ d) a

-- | Given a function <tt>f</tt> that is strict in its <i>n</i>th
--   <a>RTree</a> argument, make it lazy by applying <a>lazyT</a> to this
--   argument:
--   
--   <pre>
--   f x0 x1 .. (lazyT xn) .. xn_plus_k
--   </pre>
lazyT :: KnownNat d => RTree d a -> RTree d a
instance GHC.TypeNats.KnownNat d => Data.Traversable.Traversable (Clash.Sized.RTree.RTree d)
instance (GHC.TypeNats.KnownNat d, GHC.Classes.Eq a) => GHC.Classes.Eq (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, GHC.Classes.Ord a) => GHC.Classes.Ord (Clash.Sized.RTree.RTree d a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Sized.RTree.RTree n a)
instance Clash.XException.ShowX a => Clash.XException.ShowX (Clash.Sized.RTree.RTree n a)
instance GHC.TypeNats.KnownNat d => GHC.Base.Functor (Clash.Sized.RTree.RTree d)
instance GHC.TypeNats.KnownNat d => GHC.Base.Applicative (Clash.Sized.RTree.RTree d)
instance GHC.TypeNats.KnownNat d => Data.Foldable.Foldable (Clash.Sized.RTree.RTree d)
instance (GHC.TypeNats.KnownNat d, GHC.TypeNats.KnownNat (Clash.Class.BitPack.BitSize a), Clash.Class.BitPack.BitPack a) => Clash.Class.BitPack.BitPack (Clash.Sized.RTree.RTree d a)
instance GHC.TypeNats.KnownNat d => Control.Lens.At.Ixed (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Data.Default.Class.Default a) => Data.Default.Class.Default (Clash.Sized.RTree.RTree d a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Test.QuickCheck.Arbitrary.Arbitrary a) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.RTree.RTree d a)
instance (GHC.TypeNats.KnownNat d, Test.QuickCheck.Arbitrary.CoArbitrary a) => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.RTree.RTree d a)


module Clash.Prelude.BitIndex

-- | Get the bit at the specified bit index.
--   
--   <b>NB:</b> Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   00_0111
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 1
--   1
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 5
--   0
--   
--   &gt;&gt;&gt; (7 :: Unsigned 6) ! 6
--   *** Exception: (!): 6 is out of range [5..0]
--   ...
--   </pre>
(!) :: (BitPack a, KnownNat (BitSize a), Enum i) => a -> i -> Bit

-- | Get a slice between bit index <tt>m</tt> and and bit index <tt>n</tt>.
--   
--   <b>NB:</b> Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   00_0111
--   
--   &gt;&gt;&gt; slice d4 d2 (7 :: Unsigned 6)
--   001
--   
--   &gt;&gt;&gt; slice d6 d4 (7 :: Unsigned 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘slice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: slice d6 d4 (7 :: Unsigned 6)
--         In an equation for ‘it’: it = slice d6 d4 (7 :: Unsigned 6)
--   </pre>
slice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> a -> BitVector (m + 1 - n)

-- | Split a value of a bit size <tt>m + n</tt> into a tuple of values with
--   size <tt>m</tt> and size <tt>n</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (7 :: Unsigned 6)
--   00_0111
--   
--   &gt;&gt;&gt; split (7 :: Unsigned 6) :: (BitVector 2, BitVector 4)
--   (00,0111)
--   </pre>
split :: (BitPack a, BitSize a ~ (m + n), KnownNat n) => a -> (BitVector m, BitVector n)

-- | Set the bit at the specified index
--   
--   <b>NB:</b> Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; replaceBit 4 0 (-5 :: Signed 6)
--   -21
--   
--   &gt;&gt;&gt; pack (-21 :: Signed 6)
--   10_1011
--   
--   &gt;&gt;&gt; replaceBit 5 0 (-5 :: Signed 6)
--   27
--   
--   &gt;&gt;&gt; pack (27 :: Signed 6)
--   01_1011
--   
--   &gt;&gt;&gt; replaceBit 6 0 (-5 :: Signed 6)
--   *** Exception: replaceBit: 6 is out of range [5..0]
--   ...
--   </pre>
replaceBit :: (BitPack a, KnownNat (BitSize a), Enum i) => i -> Bit -> a -> a

-- | Set the bits between bit index <tt>m</tt> and bit index <tt>n</tt>.
--   
--   <b>NB:</b> Bit indices are <b>DESCENDING</b>.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-5 :: Signed 6)
--   11_1011
--   
--   &gt;&gt;&gt; setSlice d4 d3 0 (-5 :: Signed 6)
--   -29
--   
--   &gt;&gt;&gt; pack (-29 :: Signed 6)
--   10_0011
--   
--   &gt;&gt;&gt; setSlice d6 d5 0 (-5 :: Signed 6)
--   
--   &lt;interactive&gt;:...
--       • Couldn't match type ‘7 + i0’ with ‘6’
--           arising from a use of ‘setSlice’
--         The type variable ‘i0’ is ambiguous
--       • In the expression: setSlice d6 d5 0 (- 5 :: Signed 6)
--         In an equation for ‘it’: it = setSlice d6 d5 0 (- 5 :: Signed 6)
--   </pre>
setSlice :: (BitPack a, BitSize a ~ ((m + 1) + i)) => SNat m -> SNat n -> BitVector (m + 1 - n) -> a -> a

-- | Get the most significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-4 :: Signed 6)
--   11_1100
--   
--   &gt;&gt;&gt; msb (-4 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (4 :: Signed 6)
--   00_0100
--   
--   &gt;&gt;&gt; msb (4 :: Signed 6)
--   0
--   </pre>
msb :: (BitPack a, KnownNat (BitSize a)) => a -> Bit

-- | Get the least significant bit.
--   
--   <pre>
--   &gt;&gt;&gt; pack (-9 :: Signed 6)
--   11_0111
--   
--   &gt;&gt;&gt; lsb (-9 :: Signed 6)
--   1
--   
--   &gt;&gt;&gt; pack (-8 :: Signed 6)
--   11_1000
--   
--   &gt;&gt;&gt; lsb (-8 :: Signed 6)
--   0
--   </pre>
lsb :: BitPack a => a -> Bit


module Clash.Sized.Internal.Unsigned

-- | Arbitrary-width unsigned integer represented by <tt>n</tt> bits
--   
--   Given <tt>n</tt> bits, an <a>Unsigned</a> <tt>n</tt> number has a
--   range of: [0 .. 2^<tt>n</tt>-1]
--   
--   <b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt> on
--   overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; minBound :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Unsigned 3)) :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Unsigned 3
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; 1 - 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `times` (4 :: Unsigned 3) :: Unsigned 6
--   8
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `plus` (6 :: Unsigned 3) :: Unsigned 4
--   8
--   
--   &gt;&gt;&gt; satPlus SatSymmetric 2 6 :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; satMin SatSymmetric 2 3 :: Unsigned 3
--   0
--   </pre>
newtype Unsigned (n :: Nat)

-- | The constructor, <a>U</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesisable.
U :: Integer -> Unsigned
[unsafeToInteger] :: Unsigned -> Integer
size# :: KnownNat n => Unsigned n -> Int
pack# :: Unsigned n -> BitVector n
unpack# :: BitVector n -> Unsigned n
eq# :: Unsigned n -> Unsigned n -> Bool
neq# :: Unsigned n -> Unsigned n -> Bool
lt# :: Unsigned n -> Unsigned n -> Bool
ge# :: Unsigned n -> Unsigned n -> Bool
gt# :: Unsigned n -> Unsigned n -> Bool
le# :: Unsigned n -> Unsigned n -> Bool
enumFrom# :: KnownNat n => Unsigned n -> [Unsigned n]
enumFromThen# :: KnownNat n => Unsigned n -> Unsigned n -> [Unsigned n]
enumFromTo# :: Unsigned n -> Unsigned n -> [Unsigned n]
enumFromThenTo# :: Unsigned n -> Unsigned n -> Unsigned n -> [Unsigned n]
minBound# :: Unsigned n
maxBound# :: forall n. KnownNat n => Unsigned n
(+#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
(-#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
(*#) :: forall n. KnownNat n => Unsigned n -> Unsigned n -> Unsigned n
negate# :: forall n. KnownNat n => Unsigned n -> Unsigned n
fromInteger# :: KnownNat n => Integer -> Unsigned n
plus# :: Unsigned m -> Unsigned n -> Unsigned (Max m n + 1)
minus# :: forall m n. (KnownNat m, KnownNat n) => Unsigned m -> Unsigned n -> Unsigned (Max m n + 1)
times# :: Unsigned m -> Unsigned n -> Unsigned (m + n)
quot# :: Unsigned n -> Unsigned n -> Unsigned n
rem# :: Unsigned n -> Unsigned n -> Unsigned n
toInteger# :: Unsigned n -> Integer
and# :: Unsigned n -> Unsigned n -> Unsigned n
or# :: Unsigned n -> Unsigned n -> Unsigned n
xor# :: Unsigned n -> Unsigned n -> Unsigned n
complement# :: KnownNat n => Unsigned n -> Unsigned n
shiftL# :: KnownNat n => Unsigned n -> Int -> Unsigned n
shiftR# :: KnownNat n => Unsigned n -> Int -> Unsigned n
rotateL# :: KnownNat n => Unsigned n -> Int -> Unsigned n
rotateR# :: KnownNat n => Unsigned n -> Int -> Unsigned n
resize# :: forall n m. KnownNat m => Unsigned n -> Unsigned m
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Show.Show (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Class.BitPack.BitPack (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Unsigned.Unsigned n)
instance (GHC.TypeNats.KnownNat m, GHC.TypeNats.KnownNat n) => Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Unsigned.Unsigned m) (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Unsigned.Unsigned
instance Data.Default.Class.Default (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Unsigned.Unsigned n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.Unsigned.Unsigned n)


module Clash.Sized.Unsigned

-- | Arbitrary-width unsigned integer represented by <tt>n</tt> bits
--   
--   Given <tt>n</tt> bits, an <a>Unsigned</a> <tt>n</tt> number has a
--   range of: [0 .. 2^<tt>n</tt>-1]
--   
--   <b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt> on
--   overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; minBound :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; read (show (maxBound :: Unsigned 3)) :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; 1 + 2 :: Unsigned 3
--   3
--   
--   &gt;&gt;&gt; 2 + 6 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; 1 - 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 3 :: Unsigned 3
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Unsigned 3
--   0
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `times` (4 :: Unsigned 3) :: Unsigned 6
--   8
--   
--   &gt;&gt;&gt; (2 :: Unsigned 3) `plus` (6 :: Unsigned 3) :: Unsigned 4
--   8
--   
--   &gt;&gt;&gt; satPlus SatSymmetric 2 6 :: Unsigned 3
--   7
--   
--   &gt;&gt;&gt; satMin SatSymmetric 2 3 :: Unsigned 3
--   0
--   </pre>
data Unsigned (n :: Nat)


module Clash.Sized.Internal.Signed

-- | Arbitrary-width signed integer represented by <tt>n</tt> bits,
--   including the sign bit.
--   
--   Uses standard 2-complements representation. Meaning that, given
--   <tt>n</tt> bits, a <a>Signed</a> <tt>n</tt> number has a range of:
--   [-(2^(<tt>n</tt>-1)) .. 2^(<tt>n</tt>-1)-1]
--   
--   <b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt> on
--   overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Signed 3
--   3
--   
--   &gt;&gt;&gt; minBound :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; read (show (minBound :: Signed 3)) :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; 1 + 2 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 + 3 :: Signed 3
--   -3
--   
--   &gt;&gt;&gt; (-2) + (-3) :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 * 3 :: Signed 4
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Signed 4
--   -8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `times` (4 :: Signed 4) :: Signed 7
--   8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `plus` (3 :: Signed 3) :: Signed 4
--   5
--   
--   &gt;&gt;&gt; (-2 :: Signed 3) `plus` (-3 :: Signed 3) :: Signed 4
--   -5
--   
--   &gt;&gt;&gt; satPlus SatSymmetric 2 3 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; satPlus SatSymmetric (-2) (-3) :: Signed 3
--   -3
--   </pre>
newtype Signed (n :: Nat)

-- | The constructor, <a>S</a>, and the field, <a>unsafeToInteger</a>, are
--   not synthesisable.
S :: Integer -> Signed
[unsafeToInteger] :: Signed -> Integer
size# :: KnownNat n => Signed n -> Int
pack# :: forall n. KnownNat n => Signed n -> BitVector n
unpack# :: forall n. KnownNat n => BitVector n -> Signed n
eq# :: Signed n -> Signed n -> Bool
neq# :: Signed n -> Signed n -> Bool
lt# :: Signed n -> Signed n -> Bool
ge# :: Signed n -> Signed n -> Bool
gt# :: Signed n -> Signed n -> Bool
le# :: Signed n -> Signed n -> Bool
enumFrom# :: KnownNat n => Signed n -> [Signed n]
enumFromThen# :: KnownNat n => Signed n -> Signed n -> [Signed n]
enumFromTo# :: Signed n -> Signed n -> [Signed n]
enumFromThenTo# :: Signed n -> Signed n -> Signed n -> [Signed n]
minBound# :: KnownNat n => Signed n
maxBound# :: KnownNat n => Signed n
(+#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
(-#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
(*#) :: forall n. KnownNat n => Signed n -> Signed n -> Signed n
negate# :: forall n. KnownNat n => Signed n -> Signed n
abs# :: forall n. KnownNat n => Signed n -> Signed n
fromInteger# :: KnownNat n => Integer -> Signed (n :: Nat)
plus# :: Signed m -> Signed n -> Signed (Max m n + 1)
minus# :: Signed m -> Signed n -> Signed (Max m n + 1)
times# :: Signed m -> Signed n -> Signed (m + n)
quot# :: Signed n -> Signed n -> Signed n
rem# :: Signed n -> Signed n -> Signed n
div# :: Signed n -> Signed n -> Signed n
mod# :: Signed n -> Signed n -> Signed n
toInteger# :: Signed n -> Integer
and# :: KnownNat n => Signed n -> Signed n -> Signed n
or# :: KnownNat n => Signed n -> Signed n -> Signed n
xor# :: KnownNat n => Signed n -> Signed n -> Signed n
complement# :: KnownNat n => Signed n -> Signed n
shiftL# :: KnownNat n => Signed n -> Int -> Signed n
shiftR# :: KnownNat n => Signed n -> Int -> Signed n
rotateL# :: KnownNat n => Signed n -> Int -> Signed n
rotateR# :: KnownNat n => Signed n -> Int -> Signed n
resize# :: forall m n. (KnownNat n, KnownNat m) => Signed n -> Signed m
truncateB# :: KnownNat m => Signed (m + n) -> Signed m
minBoundSym# :: KnownNat n => Signed n
instance GHC.TypeNats.KnownNat n => Data.Data.Data (Clash.Sized.Internal.Signed.Signed n)
instance Control.DeepSeq.NFData (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Show.Show (Clash.Sized.Internal.Signed.Signed n)
instance Clash.XException.ShowX (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Read.Read (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.BitPack.BitPack (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Classes.Eq (Clash.Sized.Internal.Signed.Signed n)
instance GHC.Classes.Ord (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Enum (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Enum.Bounded (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Num.Num (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Class.Num.ExtendingNum (Clash.Sized.Internal.Signed.Signed m) (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Real (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => GHC.Real.Integral (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Data.Bits.Bits (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Data.Bits.FiniteBits (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Class.Resize.Resize Clash.Sized.Internal.Signed.Signed
instance GHC.TypeNats.KnownNat n => Data.Default.Class.Default (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Clash.Class.Num.SaturatingNum (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Internal.Signed.Signed n)
instance GHC.TypeNats.KnownNat n => Control.Lens.At.Ixed (Clash.Sized.Internal.Signed.Signed n)


module Clash.Sized.Signed

-- | Arbitrary-width signed integer represented by <tt>n</tt> bits,
--   including the sign bit.
--   
--   Uses standard 2-complements representation. Meaning that, given
--   <tt>n</tt> bits, a <a>Signed</a> <tt>n</tt> number has a range of:
--   [-(2^(<tt>n</tt>-1)) .. 2^(<tt>n</tt>-1)-1]
--   
--   <b>NB</b>: The <a>Num</a> operators perform <tt>wrap-around</tt> on
--   overflow. If you want saturation on overflow, check out the
--   <a>SaturatingNum</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: Signed 3
--   3
--   
--   &gt;&gt;&gt; minBound :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; read (show (minBound :: Signed 3)) :: Signed 3
--   -4
--   
--   &gt;&gt;&gt; 1 + 2 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 + 3 :: Signed 3
--   -3
--   
--   &gt;&gt;&gt; (-2) + (-3) :: Signed 3
--   3
--   
--   &gt;&gt;&gt; 2 * 3 :: Signed 4
--   6
--   
--   &gt;&gt;&gt; 2 * 4 :: Signed 4
--   -8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `times` (4 :: Signed 4) :: Signed 7
--   8
--   
--   &gt;&gt;&gt; (2 :: Signed 3) `plus` (3 :: Signed 3) :: Signed 4
--   5
--   
--   &gt;&gt;&gt; (-2 :: Signed 3) `plus` (-3 :: Signed 3) :: Signed 4
--   -5
--   
--   &gt;&gt;&gt; satPlus SatSymmetric 2 3 :: Signed 3
--   3
--   
--   &gt;&gt;&gt; satPlus SatSymmetric (-2) (-3) :: Signed 3
--   -3
--   </pre>
data Signed (n :: Nat)


-- | Fixed point numbers
--   
--   <ul>
--   <li>The <a>Num</a> operators for the given types saturate on overflow,
--   and use truncation as the rounding method.</li>
--   <li><a>Fixed</a> has an instance for <a>Fractional</a> meaning you use
--   fractional literals <tt>(3.75 :: <a>SFixed</a> 4 18)</tt>.</li>
--   <li>Both integer literals and fractional literals are clipped to
--   <a>minBound</a> and <a>maxBound</a>.</li>
--   <li>There is no <a>Floating</a> instance for <a>Fixed</a>, but you can
--   use <tt>$$(<a>fLit</a> d)</tt> to create <a>Fixed</a> point literal
--   from <a>Double</a> constant at compile-time.</li>
--   <li>Use <a>Constraint synonyms</a> when writing type signatures for
--   polymorphic functions that use <a>Fixed</a> point numbers.</li>
--   </ul>
--   
--   BEWARE: rounding by truncation introduces a sign bias!
--   
--   <ul>
--   <li>Truncation for positive numbers effectively results in: round
--   towards zero.</li>
--   <li>Truncation for negative numbers effectively results in: round
--   towards -infinity.</li>
--   </ul>
module Clash.Sized.Fixed

-- | Signed <a>Fixed</a>-point number, with <tt>int</tt> integer bits
--   (including sign-bit) and <tt>frac</tt> fractional bits.
--   
--   <ul>
--   <li>The range <a>SFixed</a> <tt>int</tt> <tt>frac</tt> numbers is:
--   [-(2^(<tt>int</tt> -1)) .. 2^(<tt>int</tt>-1) - 2^-<tt>frac</tt>
--   ]</li>
--   <li>The resolution of <a>SFixed</a> <tt>int</tt> <tt>frac</tt> numbers
--   is: 2^<tt>frac</tt></li>
--   <li>The <a>Num</a> operators for this type saturate on overflow, and
--   use truncation as the rounding method.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; minBound :: SFixed 3 4
--   -4.0
--   
--   &gt;&gt;&gt; read (show (maxBound :: SFixed 3 4)) :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; 1 + 2 :: SFixed 3 4
--   3.0
--   
--   &gt;&gt;&gt; 2 + 3 :: SFixed 3 4
--   3.9375
--   
--   &gt;&gt;&gt; (-2) + (-3) :: SFixed 3 4
--   -4.0
--   
--   &gt;&gt;&gt; 1.375 * (-0.8125) :: SFixed 3 4
--   -1.125
--   
--   &gt;&gt;&gt; (1.375 :: SFixed 3 4) `times` (-0.8125 :: SFixed 3 4) :: SFixed 6 8
--   -1.1171875
--   
--   &gt;&gt;&gt; (2 :: SFixed 3 4) `plus` (3 :: SFixed 3 4) :: SFixed 4 4
--   5.0
--   
--   &gt;&gt;&gt; (-2 :: SFixed 3 4) `plus` (-3 :: SFixed 3 4) :: SFixed 4 4
--   -5.0
--   </pre>
type SFixed = Fixed Signed

-- | Treat a <a>Signed</a> integer as a <tt>Signed</tt>
--   <a>Fixed</a>-<tt>point</tt> integer
--   
--   <pre>
--   &gt;&gt;&gt; sf d4 (-22 :: Signed 7)
--   -1.375
--   </pre>
sf :: SNat frac -> Signed (int + frac) -> SFixed int frac

-- | See the underlying representation of a Signed Fixed-point integer
unSF :: SFixed int frac -> Signed (int + frac)

-- | Unsigned <a>Fixed</a>-point number, with <tt>int</tt> integer bits and
--   <tt>frac</tt> fractional bits
--   
--   <ul>
--   <li>The range <a>UFixed</a> <tt>int</tt> <tt>frac</tt> numbers is: [0
--   .. 2^<tt>int</tt> - 2^-<tt>frac</tt> ]</li>
--   <li>The resolution of <a>UFixed</a> <tt>int</tt> <tt>frac</tt> numbers
--   is: 2^<tt>frac</tt></li>
--   <li>The <a>Num</a> operators for this type saturate on overflow, and
--   use truncation as the rounding method.</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; maxBound :: UFixed 3 4
--   7.9375
--   
--   &gt;&gt;&gt; minBound :: UFixed 3 4
--   0.0
--   
--   &gt;&gt;&gt; 1 + 2 :: UFixed 3 4
--   3.0
--   
--   &gt;&gt;&gt; 2 + 6 :: UFixed 3 4
--   7.9375
--   
--   &gt;&gt;&gt; 1 - 3 :: UFixed 3 4
--   0.0
--   
--   &gt;&gt;&gt; 1.375 * 0.8125 :: UFixed 3 4
--   1.0625
--   
--   &gt;&gt;&gt; (1.375 :: UFixed 3 4) `times` (0.8125 :: UFixed 3 4) :: UFixed 6 8
--   1.1171875
--   
--   &gt;&gt;&gt; (2 :: UFixed 3 4) `plus` (6 :: UFixed 3 4) :: UFixed 4 4
--   8.0
--   </pre>
--   
--   However, <a>minus</a> does not saturate to <a>minBound</a> on
--   underflow:
--   
--   <pre>
--   &gt;&gt;&gt; (1 :: UFixed 3 4) `minus` (3 :: UFixed 3 4) :: UFixed 4 4
--   14.0
--   </pre>
type UFixed = Fixed Unsigned

-- | Treat an <a>Unsigned</a> integer as a <tt>Unsigned</tt>
--   <a>Fixed</a>-<tt>point</tt> number
--   
--   <pre>
--   &gt;&gt;&gt; uf d4 (92 :: Unsigned 7)
--   5.75
--   </pre>
uf :: SNat frac -> Unsigned (int + frac) -> UFixed int frac

-- | See the underlying representation of an Unsigned Fixed-point integer
unUF :: UFixed int frac -> Unsigned (int + frac)

-- | Fixed point division
--   
--   When used in a polymorphic setting, use the following <a>Constraint
--   synonyms</a> for less verbose type signatures:
--   
--   <ul>
--   <li><tt><a>DivideC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>Fixed</a> rep int1 frac1 -&gt; <a>Fixed</a> rep int2 frac2
--   -&gt; <a>Fixed</a> rep (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   <li><tt><a>DivideSC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>SFixed</a> int1 frac1 -&gt; <a>SFixed</a> int2 frac2 -&gt;
--   <a>SFixed</a> (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   <li><tt><a>DivideUC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>UFixed</a> int1 frac1 -&gt; <a>UFixed</a> int2 frac2 -&gt;
--   <a>UFixed</a> (int1 + frac2 + 1) (int2 + frac1)</tt></li>
--   </ul>
divide :: DivideC rep int1 frac1 int2 frac2 => Fixed rep int1 frac1 -> Fixed rep int2 frac2 -> Fixed rep (int1 + frac2 + 1) (int2 + frac1)

-- | Convert, at compile-time, a <a>Double</a> <i>constant</i> to a
--   <a>Fixed</a>-point <i>literal</i>. The conversion saturates on
--   overflow, and uses truncation as its rounding method.
--   
--   So when you type:
--   
--   <pre>
--   n = $$(<a>fLit</a> pi) :: <a>SFixed</a> 4 4
--   </pre>
--   
--   The compiler sees:
--   
--   <pre>
--   n = <a>Fixed</a> (fromInteger 50) :: <a>SFixed</a> 4 4
--   </pre>
--   
--   Upon evaluation you see that the value is rounded / truncated in
--   accordance to the fixed point representation:
--   
--   <pre>
--   &gt;&gt;&gt; n
--   3.125
--   </pre>
--   
--   Further examples:
--   
--   <pre>
--   &gt;&gt;&gt; sin 0.5 :: Double
--   0.479425538604203
--   
--   &gt;&gt;&gt; $$(fLit (sin 0.5)) :: SFixed 1 8
--   0.4765625
--   
--   &gt;&gt;&gt; atan 0.2 :: Double
--   0.19739555984988078
--   
--   &gt;&gt;&gt; $$(fLit (atan 0.2)) :: SFixed 1 8
--   0.1953125
--   
--   &gt;&gt;&gt; $$(fLit (atan 0.2)) :: SFixed 1 20
--   0.19739532470703125
--   </pre>
fLit :: forall rep int frac size. (size ~ (int + frac), KnownNat frac, Bounded (rep size), Integral (rep size)) => Double -> Q (TExp (Fixed rep int frac))

-- | Convert, at run-time, a <a>Double</a> to a <a>Fixed</a>-point.
--   
--   <b>NB</b>: this functions is <i>not</i> synthesisable
--   
--   <h1>Creating data-files </h1>
--   
--   An example usage of this function is for example to convert a data
--   file containing <a>Double</a>s to a data file with ASCI-encoded binary
--   numbers to be used by a synthesisable function like
--   <a>asyncRomFile</a>. For example, given a file <tt>Data.txt</tt>
--   containing:
--   
--   <pre>
--   1.2 2.0 3.0 4.0
--   -1.0 -2.0 -3.5 -4.0
--   </pre>
--   
--   which we want to put in a ROM, interpreting them as <tt>8.8</tt>
--   signed fixed point numbers. What we do is that we first create a
--   conversion utility, <tt>createRomFile</tt>, which uses <a>fLitR</a>:
--   
--   <tt>createRomFile.hs</tt>:
--   
--   <pre>
--   module Main where
--   
--   import Clash.Prelude
--   import System.Environment
--   import qualified Data.List as L
--   
--   createRomFile :: KnownNat n =&gt; (Double -&gt; BitVector n)
--                 -&gt; FilePath -&gt; FilePath -&gt; IO ()
--   createRomFile convert fileR fileW = do
--     f &lt;- readFile fileR
--     let ds :: [Double]
--         ds = L.concat . (L.map . L.map) read . L.map words $ lines f
--         bvs = L.map (filter (/= '_') . show . convert) ds
--     writeFile fileW (unlines bvs)
--   
--   toSFixed8_8 :: Double -&gt; SFixed 8 8
--   toSFixed8_8 = <a>fLitR</a>
--   
--   main :: IO ()
--   main = do
--     [fileR,fileW] &lt;- getArgs
--     createRomFile (<a>pack</a> . toSFixed8_8) fileR fileW
--   </pre>
--   
--   We then compile this to an executable:
--   
--   <pre>
--   $ clash --make createRomFile.hs
--   </pre>
--   
--   We can then use this utility to convert our <tt>Data.txt</tt> file
--   which contains <a>Double</a>s to a <tt>Data.bin</tt> file which will
--   containing the desired ASCI-encoded binary data:
--   
--   <pre>
--   $ ./createRomFile "Data.txt" "Data.bin"
--   </pre>
--   
--   Which results in a <tt>Data.bin</tt> file containing:
--   
--   <pre>
--   0000000100110011
--   0000001000000000
--   0000001100000000
--   0000010000000000
--   1111111100000000
--   1111111000000000
--   1111110010000000
--   1111110000000000
--   </pre>
--   
--   We can then use this <tt>Data.bin</tt> file in for our ROM:
--   
--   <pre>
--   romF :: Unsigned 3 -&gt; Unsigned 3 -&gt; SFixed 8 8
--   romF rowAddr colAddr = <a>unpack</a>
--                        $ <a>asyncRomFile</a> d8 "Data.bin" ((rowAddr * 4) + colAddr)
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; romF 1 2</b>
--   -3.5
--   <b>&gt;&gt;&gt; romF 0 0</b>
--   1.19921875
--   </pre>
--   
--   <h2>Using Template Haskell</h2>
--   
--   For those of us who like to live on the edge, another option is to
--   convert our <tt>Data.txt</tt> at compile-time using <a>Template
--   Haskell</a>. For this we first create a module
--   <tt>CreateRomFileTH.hs</tt>:
--   
--   <pre>
--   module CreateRomFileTH (romDataFromFile) where
--   
--   import Clash.Prelude
--   import qualified Data.List        as L
--   import Language.Haskell.TH        (ExpQ, litE, stringL)
--   import Language.Haskell.TH.Syntax (qRunIO)
--   
--   createRomFile :: KnownNat n =&gt; (Double -&gt; BitVector n)
--                 -&gt; FilePath -&gt; FilePath -&gt; IO ()
--   createRomFile convert fileR fileW = do
--     f &lt;- readFile fileR
--     let ds :: [Double]
--         ds = L.concat . (L.map . L.map) read . L.map words $ lines f
--         bvs = L.map (filter (/= '_') . show . convert) ds
--     writeFile fileW (unlines bvs)
--   
--   romDataFromFile :: KnownNat n =&gt; (Double -&gt; BitVector n) -&gt; String -&gt; ExpQ
--   romDataFromFile convert fileR = do
--     let fileW = fileR L.++ ".bin"
--     bvF &lt;- qRunIO (createRomFile convert fileR fileW)
--     litE (stringL fileW)
--   </pre>
--   
--   Instead of first converting <tt>Data.txt</tt> to <tt>Data.bin</tt>, we
--   will now use the <tt>romDataFromFile</tt> function to convert
--   <tt>Data.txt</tt> to a new file in the proper format at compile-time
--   of our new <tt>romF'</tt> function:
--   
--   <pre>
--   import Clash.Prelude
--   import CreateRomFileTH
--   
--   toSFixed8_8 :: Double -&gt; SFixed 8 8
--   toSFixed8_8 = <a>fLitR</a>
--   
--   romF' :: Unsigned 3 -&gt; Unsigned 3 -&gt; SFixed 8 8
--   romF' rowAddr colAddr = unpack $
--     asyncRomFile d8
--                  $(romDataFromFile (pack . toSFixed8_8) "Data.txt") -- Template Haskell splice
--                  ((rowAddr * 4) + colAddr)
--   </pre>
--   
--   And see that it works just like the <tt>romF</tt> function from
--   earlier:
--   
--   <pre>
--   <b>&gt;&gt;&gt; romF' 1 2</b>
--   -3.5
--   <b>&gt;&gt;&gt; romF' 0 0</b>
--   1.19921875
--   </pre>
fLitR :: forall rep int frac size. (size ~ (int + frac), KnownNat frac, Bounded (rep size), Integral (rep size)) => Double -> Fixed rep int frac

-- | <a>Fixed</a>-point number
--   
--   Where:
--   
--   <ul>
--   <li><tt>rep</tt> is the underlying representation</li>
--   <li><tt>int</tt> is the number of bits used to represent the integer
--   part</li>
--   <li><tt>frac</tt> is the number of bits used to represent the
--   fractional part</li>
--   </ul>
--   
--   The <a>Num</a> operators for this type saturate to <a>maxBound</a> on
--   overflow and <a>minBound</a> on underflow, and use truncation as the
--   rounding method.
newtype Fixed (rep :: Nat -> *) (int :: Nat) (frac :: Nat)
Fixed :: rep (int + frac) -> Fixed
[unFixed] :: Fixed -> rep (int + frac)

-- | Saturating resize operation, truncates for rounding
--   
--   <pre>
--   &gt;&gt;&gt; 0.8125 :: SFixed 3 4
--   0.8125
--   
--   &gt;&gt;&gt; resizeF (0.8125 :: SFixed 3 4) :: SFixed 2 3
--   0.75
--   
--   &gt;&gt;&gt; 3.4 :: SFixed 3 4
--   3.375
--   
--   &gt;&gt;&gt; resizeF (3.4 :: SFixed 3 4) :: SFixed 2 3
--   1.875
--   
--   &gt;&gt;&gt; maxBound :: SFixed 2 3
--   1.875
--   </pre>
--   
--   When used in a polymorphic setting, use the following <a>Constraint
--   synonyms</a> for less verbose type signatures:
--   
--   <ul>
--   <li><tt><a>ResizeFC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>Fixed</a> rep int1 frac1 -&gt; <a>Fixed</a> rep int2
--   frac2</tt></li>
--   <li><tt><a>ResizeSFC</a> int1 frac1 int2 frac2</tt> for:
--   <tt><a>SFixed</a> int1 frac1 -&gt; <a>SFixed</a> int2 frac2</tt></li>
--   <li><tt><a>ResizeUFC</a> rep int1 frac1 int2 frac2</tt> for:
--   <tt><a>UFixed</a> int1 frac1 -&gt; <a>UFixed</a> int2 frac2</tt></li>
--   </ul>
resizeF :: forall rep int1 frac1 int2 frac2. ResizeFC rep int1 frac1 int2 frac2 => Fixed rep int1 frac1 -> Fixed rep int2 frac2

-- | Get the position of the virtual <tt>point</tt> of a
--   <a>Fixed</a>-<tt>point</tt> number
fracShift :: KnownNat frac => Fixed rep int frac -> Int

-- | Constraint for the <a>Num</a> instance of <a>SFixed</a>
type NumSFixedC int frac = (KnownNat ((int + int) + (frac + frac)), KnownNat (frac + frac), KnownNat (int + int), KnownNat (int + frac), KnownNat frac, KnownNat int)

-- | Constraint for the <a>ExtendingNum</a> instance of <a>SFixed</a>
type ENumSFixedC int1 frac1 int2 frac2 = (KnownNat (int2 + frac2), KnownNat (1 + Max int1 int2 + Max frac1 frac2), KnownNat (Max frac1 frac2), KnownNat (1 + Max int1 int2), KnownNat (int1 + frac1), KnownNat frac2, KnownNat int2, KnownNat frac1, KnownNat int1)

-- | Constraint for the <a>Fractional</a> instance of <a>SFixed</a>
type FracSFixedC int frac = (NumSFixedC int frac, KnownNat ((int + frac + 1) + (int + frac)))

-- | Constraint for the <a>resizeF</a> function, specialized for
--   <a>SFixed</a>
type ResizeSFC int1 frac1 int2 frac2 = (KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2, KnownNat (int2 + frac2), KnownNat (int1 + frac1))

-- | Constraint for the <a>divide</a> function, specialized for
--   <a>SFixed</a>
type DivideSC int1 frac1 int2 frac2 = (KnownNat (((int1 + frac2) + 1) + (int2 + frac1)), KnownNat frac2, KnownNat int2, KnownNat frac1, KnownNat int1)

-- | Constraint for the <a>Num</a> instance of <a>UFixed</a>
type NumUFixedC int frac = NumSFixedC int frac

-- | Constraint for the <a>ExtendingNum</a> instance of <a>UFixed</a>
type ENumUFixedC int1 frac1 int2 frac2 = ENumSFixedC int1 frac1 int2 frac2

-- | Constraint for the <a>Fractional</a> instance of <a>UFixed</a>
type FracUFixedC int frac = FracSFixedC int frac

-- | Constraint for the <a>resizeF</a> function, specialized for
--   <a>UFixed</a>
type ResizeUFC int1 frac1 int2 frac2 = ResizeSFC int1 frac1 int2 frac2

-- | Constraint for the <a>divide</a> function, specialized for
--   <a>UFixed</a>
type DivideUC int1 frac1 int2 frac2 = DivideSC int1 frac1 int2 frac2

-- | Constraint for the <a>Num</a> instance of <a>Fixed</a>
type NumFixedC rep int frac = (SaturatingNum (rep (int + frac)), ExtendingNum (rep (int + frac)) (rep (int + frac)), MResult (rep (int + frac)) (rep (int + frac)) ~ rep ((int + int) + (frac + frac)), BitSize (rep ((int + int) + (frac + frac))) ~ (int + ((int + frac) + frac)), BitPack (rep ((int + int) + (frac + frac))), Bits (rep ((int + int) + (frac + frac))), KnownNat (BitSize (rep (int + frac))), BitPack (rep (int + frac)), Enum (rep (int + frac)), Bits (rep (int + frac)), Resize rep, KnownNat int, KnownNat frac)

-- | Constraint for the <a>ExtendingNum</a> instance of <a>Fixed</a>
type ENumFixedC rep int1 frac1 int2 frac2 = (Bounded (rep ((1 + Max int1 int2) + Max frac1 frac2)), Num (rep ((1 + Max int1 int2) + Max frac1 frac2)), Bits (rep ((1 + Max int1 int2) + Max frac1 frac2)), ExtendingNum (rep (int1 + frac1)) (rep (int2 + frac2)), MResult (rep (int1 + frac1)) (rep (int2 + frac2)) ~ rep ((int1 + int2) + (frac1 + frac2)), KnownNat int1, KnownNat int2, KnownNat frac1, KnownNat frac2, Resize rep)

-- | Constraint for the <a>Fractional</a> instance of <a>Fixed</a>
type FracFixedC rep int frac = (NumFixedC rep int frac, DivideC rep int frac int frac, Integral (rep (int + frac)), KnownNat int, KnownNat frac)

-- | Constraint for the <a>resizeF</a> function
type ResizeFC rep int1 frac1 int2 frac2 = (Resize rep, Ord (rep (int1 + frac1)), Num (rep (int1 + frac1)), Bits (rep (int1 + frac1)), Bits (rep (int2 + frac2)), Bounded (rep (int2 + frac2)), KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2)

-- | Constraint for the <a>divide</a> function
type DivideC rep int1 frac1 int2 frac2 = (Resize rep, Integral (rep (((int1 + frac2) + 1) + (int2 + frac1))), Bits (rep (((int1 + frac2) + 1) + (int2 + frac1))), KnownNat int1, KnownNat frac1, KnownNat int2, KnownNat frac2)

-- | <a>Fixed</a> as a <a>Proxy</a> for it's representation type
--   <tt>rep</tt>
asRepProxy :: Fixed rep int frac -> Proxy rep

-- | <a>Fixed</a> as a <a>Proxy</a> for the number of integer bits
--   <tt>int</tt>
asIntProxy :: Fixed rep int frac -> Proxy int
instance Control.DeepSeq.NFData (rep (int GHC.TypeNats.+ frac)) => Control.DeepSeq.NFData (Clash.Sized.Fixed.Fixed rep int frac)
instance (Data.Typeable.Internal.Typeable rep, Data.Typeable.Internal.Typeable int, Data.Typeable.Internal.Typeable frac, Data.Data.Data (rep (int GHC.TypeNats.+ frac))) => Data.Data.Data (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Classes.Eq (rep (int GHC.TypeNats.+ frac)) => GHC.Classes.Eq (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Classes.Ord (rep (int GHC.TypeNats.+ frac)) => GHC.Classes.Ord (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Enum.Enum (rep (int GHC.TypeNats.+ frac)) => GHC.Enum.Enum (Clash.Sized.Fixed.Fixed rep int frac)
instance GHC.Enum.Bounded (rep (int GHC.TypeNats.+ frac)) => GHC.Enum.Bounded (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Default.Class.Default (rep (int GHC.TypeNats.+ frac)) => Data.Default.Class.Default (Clash.Sized.Fixed.Fixed rep int frac)
instance Test.QuickCheck.Arbitrary.Arbitrary (rep (int GHC.TypeNats.+ frac)) => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Sized.Fixed.Fixed rep int frac)
instance Test.QuickCheck.Arbitrary.CoArbitrary (rep (int GHC.TypeNats.+ frac)) => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Bits.FiniteBits (rep (int GHC.TypeNats.+ frac)) => Data.Bits.FiniteBits (Clash.Sized.Fixed.Fixed rep int frac)
instance Data.Bits.Bits (rep (int GHC.TypeNats.+ frac)) => Data.Bits.Bits (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.FracFixedC rep int frac => GHC.Real.Fractional (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => GHC.Num.Num (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.NumFixedC rep int frac => Clash.Class.Num.SaturatingNum (Clash.Sized.Fixed.Fixed rep int frac)
instance (Clash.Sized.Fixed.NumFixedC rep int frac, GHC.Real.Integral (rep (int GHC.TypeNats.+ frac))) => GHC.Real.Real (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Sized.Fixed.ENumFixedC rep int1 frac1 int2 frac2 => Clash.Class.Num.ExtendingNum (Clash.Sized.Fixed.Fixed rep int1 frac1) (Clash.Sized.Fixed.Fixed rep int2 frac2)
instance (size ~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Real.Integral (rep size)) => GHC.Show.Show (Clash.Sized.Fixed.Fixed rep int frac)
instance (size ~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Real.Integral (rep size)) => Clash.XException.ShowX (Clash.Sized.Fixed.Fixed rep int frac)
instance (size ~ (int GHC.TypeNats.+ frac), GHC.TypeNats.KnownNat frac, GHC.Enum.Bounded (rep size), GHC.Real.Integral (rep size)) => GHC.Read.Read (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Class.BitPack.BitPack (rep (int GHC.TypeNats.+ frac)) => Clash.Class.BitPack.BitPack (Clash.Sized.Fixed.Fixed rep int frac)
instance (Language.Haskell.TH.Syntax.Lift (rep (int GHC.TypeNats.+ frac)), GHC.TypeNats.KnownNat frac, GHC.TypeNats.KnownNat int, Data.Typeable.Internal.Typeable rep) => Language.Haskell.TH.Syntax.Lift (Clash.Sized.Fixed.Fixed rep int frac)


-- | The Product/Signal isomorphism
module Clash.Signal.Bundle

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal'</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <tt>Unbundled'</tt> clk D = <tt>Signal'</tt> clk D
--     <a>bundle</a>   _ s = s
--     <a>unbundle</a> _ s = s
--   </pre>
class Bundle a where {
    type family Unbundled (domain :: Domain) a = res | res -> domain a;
    type Unbundled domain a = Signal domain a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: (Bundle a, (Signal domain a ~ Unbundled domain a)) => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal domain a -> Unbundled domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, (Unbundled domain a ~ Signal domain a)) => Signal domain a -> Unbundled domain a
instance Clash.Signal.Bundle.Bundle GHC.Types.Bool
instance Clash.Signal.Bundle.Bundle GHC.Integer.Type.Integer
instance Clash.Signal.Bundle.Bundle GHC.Types.Int
instance Clash.Signal.Bundle.Bundle GHC.Types.Float
instance Clash.Signal.Bundle.Bundle GHC.Types.Double
instance Clash.Signal.Bundle.Bundle (GHC.Base.Maybe a)
instance Clash.Signal.Bundle.Bundle (Data.Either.Either a b)
instance Clash.Signal.Bundle.Bundle Clash.Sized.Internal.BitVector.Bit
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.BitVector.BitVector n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Index.Index n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Fixed.Fixed rep int frac)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Signed.Signed n)
instance Clash.Signal.Bundle.Bundle (Clash.Sized.Internal.Unsigned.Unsigned n)
instance Clash.Signal.Bundle.Bundle ()
instance Clash.Signal.Bundle.Bundle (a, b)
instance Clash.Signal.Bundle.Bundle (a, b, c)
instance Clash.Signal.Bundle.Bundle (a, b, c, d)
instance Clash.Signal.Bundle.Bundle (a, b, c, d, e)
instance Clash.Signal.Bundle.Bundle (a, b, c, d, e, f)
instance Clash.Signal.Bundle.Bundle (a, b, c, d, e, f, g)
instance Clash.Signal.Bundle.Bundle (a, b, c, d, e, f, g, h)
instance GHC.TypeNats.KnownNat n => Clash.Signal.Bundle.Bundle (Clash.Sized.Vector.Vec n a)
instance GHC.TypeNats.KnownNat d => Clash.Signal.Bundle.Bundle (Clash.Sized.RTree.RTree d a)


-- | CλaSH has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (domain :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>domain</i> is the
--   <i>clock-</i> (and <i>reset-</i>) domain to which the memory elements
--   manipulating these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>domain</i>, is of the kind <a>Domain</a> which
--   has types of the following shape:
--   
--   <pre>
--   data Domain = Dom { domainName :: <a>Symbol</a>, clkPeriod :: <a>Nat</a> }
--   </pre>
--   
--   Where <i>domainName</i> is a type-level string (<a>Symbol</a>)
--   representing the name of the <i>clock-</i> (and <i>reset-</i>) domain,
--   and <i>clkPeriod</i> is a type-level natural number (<a>Nat</a>)
--   representing the clock period (in <b>ps</b>) of the clock lines in the
--   <i>clock-domain</i>.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   </ul>
--   
--   <h3>Explicit clocks and resets, and meta-stability </h3>
--   
--   When <a>clocks and resets are implicitly routed</a> using the
--   mechanisms provided by the <b>clash-prelude</b>, then clocks and
--   resets are also implicitly unique.
--   
--   The protection against accidental <a>metastability</a> offered by
--   Clash's <i>domain</i> annotation on <a>Signal</a>s is based on the
--   uniqueness of clocks and resets. But with explicit clock and reset
--   lines, there are ways to (accidentally) introduce situations that are
--   prone to metastability.
--   
--   There are four different clock and reset lines:
--   
--   <pre>
--   <a>Reset</a> domain <a>Synchronous</a>
--   <a>Reset</a> domain <a>Asynchronous</a>
--   <a>Clock</a> domain <a>Source</a>
--   <a>Clock</a> domain <a>Gated</a>
--   </pre>
--   
--   We now go over the combinations over these clock and reset line
--   combinations and explain when they can potentially introduce
--   situations prone to meta-stability:
--   
--   <ul>
--   <li><i>Reset situation 1</i>:<pre>f :: Reset domain Synchronous -&gt;
--   Reset domain Synchronous -&gt; .. f x y = .. </pre>There are no
--   problems here, because although <i>x</i> and <i>y</i> can have
--   different values, components to these reset lines are reset
--   <i>synchronously</i>, and there is no metastability situation.</li>
--   <li><i>Reset situation 2</i>:<pre>g :: Reset domain Asynchronous -&gt;
--   Reset domain Asynchronous -&gt; .. g x y = .. </pre>This situation can
--   be prone to metastability, because although <i>x</i> and <i>y</i>
--   belong to the same <i>domain</i> according to their type, there is no
--   guarantee that they actually originate from the same source. This
--   means that one component can enter its reset state asynchronously to
--   another component, inducing metastability in the other
--   component.<ul><li>The Clash compiler will give a warning whenever a
--   function has a type-signature similar to the one above.</li><li>This
--   is the reason why <a>unsafeFromAsyncReset</a> is prefixed with the
--   word <i>unsafe</i>.</li></ul></li>
--   <li><i>Reset situation 3</i>:<pre>h :: Reset domain Asynchronous -&gt;
--   Reset domain Synchronous -&gt; .. h x y = .. </pre>Also this situation
--   is prone to metastability, because again, one component can enter its
--   reset state asynchronously to the other, inducing metastability in the
--   other component.<ul><li>The Clash compiler will give a warning
--   whenever a function has a type-signature similar to the one
--   above.</li><li>Although in a standalone context, converting between
--   <tt><a>Reset</a> domain <a>Synchronous</a></tt> and <tt><a>Signal</a>
--   domain <a>Bool</a></tt> would be safe from a metastability point of
--   view, it is not when we're in a context where there are also
--   asynchronous resets. That is why <a>unsafeToSyncReset</a> is prefixed
--   with the word <i>unsafe</i>.</li></ul></li>
--   <li><i>Clock situations 1, 2, and 3</i>:<pre>k :: Clock domain Source
--   -&gt; Clock domain source -&gt; .. k x y = .. l :: Clock domain Source
--   -&gt; Clock domain Gated -&gt; .. l x y = .. m :: Clock domain Gated
--   -&gt; Clock domain Gated -&gt; .. m x y = .. </pre>All the above
--   situations are potentially prone to metastability, because even though
--   <i>x</i> and <i>y</i> belong to the same <i>domain</i> according to
--   their type, there is no guarantee that they actually originate from
--   the same source. They could hence be connected to completely unrelated
--   clock sources, and components can then induce metastable states in
--   others.<ul><li>The Clash compiler will give a warning whenever a
--   function has a type-signature similar to one of the above three
--   situations.</li></ul></li>
--   </ul>
module Clash.Explicit.Signal

-- | CλaSH has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (domain :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>domain</i> is the
--   <i>clock-</i> (and <i>reset-</i>) domain to which the memory elements
--   manipulating these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>domain</i>, is of the kind <a>Domain</a> which
--   has types of the following shape:
--   
--   <pre>
--   data Domain = Dom { domainName :: <a>Symbol</a>, clkPeriod :: <a>Nat</a> }
--   </pre>
--   
--   Where <i>domainName</i> is a type-level string (<a>Symbol</a>)
--   representing the name of the <i>clock-</i> (and <i>reset-</i>) domain,
--   and <i>clkPeriod</i> is a type-level natural number (<a>Nat</a>)
--   representing the clock period (in <b>ps</b>) of the clock lines in the
--   <i>clock-domain</i>.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   </ul>
data Signal (domain :: Domain) a

-- | A domain with a name (<tt>Symbol</tt>) and a clock period
--   (<tt>Nat</tt>) in <i>ps</i>
data Domain
Dom :: Symbol -> Nat -> Domain
[domainName] :: Domain -> Symbol
[clkPeriod] :: Domain -> Nat

-- | A <i>clock</i> (and <i>reset</i>) domain with clocks running at 100
--   MHz
type System =  'Dom "system" 10000

-- | A clock signal belonging to a <tt>domain</tt>
data Clock (domain :: Domain) (gated :: ClockKind)

-- | Distinction between gated and ungated clocks
data ClockKind

-- | A clock signal coming straight from the clock source
Source :: ClockKind

-- | A clock signal that has been gated
Gated :: ClockKind

-- | Calculate the period, in <b>ps</b>, given a frequency in <b>Hz</b>
--   
--   i.e. to calculate the clock period for a circuit to run at 240 MHz we
--   get
--   
--   <pre>
--   &gt;&gt;&gt; freqCalc 240e6
--   4167
--   </pre>
--   
--   <b>NB</b>: This function is <i>not</i> synthesisable
freqCalc :: Double -> Integer

-- | The <a>unsafeSynchronizer</a> function is a primitive that must be
--   used to connect one clock domain to the other, and will be synthesised
--   to a (bundle of) wire(s) in the eventual circuit. This function should
--   only be used as part of a proper synchronisation component, such as
--   the following dual flip-flop synchronizer:
--   
--   <pre>
--   dualFlipFlop :: Clock domA gatedA -&gt; Clock domB gatedB
--                -&gt; Signal domA Bit -&gt; Signal domB Bit
--   dualFlipFlop clkA clkB = <a>delay</a> clkB . <a>delay</a> clkB
--                          . <a>unsafeSynchronizer</a> clkA clkB
--   </pre>
--   
--   The <a>unsafeSynchronizer</a> works in such a way that, given 2
--   clocks:
--   
--   <pre>
--   type Dom7 = <a>Dom</a> "dom" 7
--   
--   clk7 :: <a>Clock</a> Dom7 Source
--   clk7 = <a>clockGen</a>
--   </pre>
--   
--   and
--   
--   <pre>
--   type Dom2 = <a>Dom</a> "dom" 2
--   
--   clk2 :: <a>Clock</a> Dom2 Source
--   clk2 = <a>clockGen</a>
--   </pre>
--   
--   Oversampling followed by compression is the identity function plus 2
--   initial values:
--   
--   <pre>
--   <a>delay</a> clkB $
--   <a>unsafeSynchronizer</a> clkA clkB $
--   <a>delay</a> clkA $
--   <a>unsafeSynchronizer</a> clkB clkA $
--   <a>delay</a> clkB s
--   
--   ==
--   
--   X :- X :- s
--   </pre>
--   
--   Something we can easily observe:
--   
--   <pre>
--   oversampling clkA clkB = <a>delay</a> clkB . <a>unsafeSynchronizer</a> clkA clkB
--                          . <a>delay</a> clkA
--   almostId clkA clkB = <a>delay</a> clkB . <a>unsafeSynchronizer</a> clkA clkB
--                      . <a>delay</a> clkA . <a>unsafeSynchronizer</a> clkB clkA
--                      . <a>delay</a> clkB
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 37 (oversampling clk7 clk2 (fromList [(1::Int)..10])))
--   [X,X,1,1,1,2,2,2,2,3,3,3,4,4,4,4,5,5,5,6,6,6,6,7,7,7,8,8,8,8,9,9,9,10,10,10,10]
--   
--   &gt;&gt;&gt; printX (sampleN 12 (almostId clk2 clk7 (fromList [(1::Int)..10])))
--   [X,X,1,2,3,4,5,6,7,8,9,10]
--   </pre>
unsafeSynchronizer :: Clock domain1 gated1 -> Clock domain2 gated2 -> Signal domain1 a -> Signal domain2 a

-- | Clock gating primitive
clockGate :: Clock domain gated -> Signal domain Bool -> Clock domain  'Gated

-- | A reset signal belonging to a <tt>domain</tt>.
--   
--   The underlying representation of resets is <a>Bool</a>. Note that all
--   components in the <b>clash-prelude</b> package have an
--   <i>active-high</i> reset port, i.e., the component is reset when the
--   reset port is <a>True</a>.
data Reset (domain :: Domain) (synchronous :: ResetKind)

-- | The "kind" of reset
--   
--   Given a situation where a reset is asserted, and then de-asserted at
--   the active flank of the clock, we can observe the difference between a
--   synchronous reset and an asynchronous reset:
--   
--   <h3>Synchronous reset</h3>
--   
--   <pre>
--   registerS
--     :: Clock domain gated -&gt; Reset domain Synchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerS = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 4 (registerS (clockGen @System) (syncResetGen @System) 0 (fromList [1,2,3])))
--   [X,0,2,3]
--   </pre>
--   
--   <h3>Asynchronous reset</h3>
--   
--   <pre>
--   registerA
--     :: Clock domain gated -&gt; Reset domain Asynchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerA = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 4 (registerA (clockGen @System) (asyncResetGen @System) 0 (fromList [1,2,3]))
--   [0,1,2,3]
--   </pre>
data ResetKind

-- | Components with a synchronous reset port produce the reset value when:
--   
--   <ul>
--   <li>The reset is asserted during the active flank of the clock to
--   which the component is synchronized.</li>
--   </ul>
Synchronous :: ResetKind

-- | Components with an asynchronous reset port produce the reset value
--   when:
--   
--   <ul>
--   <li>Immediately when the reset is asserted.</li>
--   </ul>
Asynchronous :: ResetKind

-- | <a>unsafeFromAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
unsafeFromAsyncReset :: Reset domain  'Asynchronous -> Signal domain Bool

-- | <a>unsafeToAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li>combinational loops</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   resetSynchronizer
--     :: Clock domain gated
--     -&gt; Reset domain 'Asynchronous
--     -&gt; Reset domain 'Asynchronous
--   resetSynchronizer clk rst  =
--     let r1 = register clk rst True (pure False)
--         r2 = register clk rst True r1
--     in  <a>unsafeToAsyncReset</a> r2
--   </pre>
unsafeToAsyncReset :: Signal domain Bool -> Reset domain  'Asynchronous

-- | It is safe to treat synchronous resets as <tt>Bool</tt> signals
fromSyncReset :: Reset domain  'Synchronous -> Signal domain Bool

-- | <a>unsafeToSyncReset</a> is unsafe because:
--   
--   <ul>
--   <li>It can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.</li>
--   </ul>
unsafeToSyncReset :: Signal domain Bool -> Reset domain  'Synchronous

-- | Normally, asynchronous resets can be both asynchronously asserted and
--   de-asserted. Asynchronous de-assertion can induce meta-stability in
--   the component which is being reset. To ensure this doesn't happen,
--   <a>resetSynchronizer</a> ensures that de-assertion of a reset happens
--   synchronously. Assertion of the reset remains asynchronous.
--   
--   Note that asynchronous assertion does not induce meta-stability in the
--   component whose reset is asserted. However, when a component "A" in
--   another clock or reset domain depends on the value of a component "B"
--   being reset, then asynchronous assertion of the reset of component "B"
--   can induce meta-stability in component "A". To prevent this from
--   happening you need to use a proper synchronizer, for example one of
--   the synchronizers in <a>Clash.Explicit.Synchronizer</a>
--   
--   <b>NB:</b> Assumes the component(s) being reset have an
--   <i>active-high</i> reset port, which all components in
--   <b>clash-prelude</b> have.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity
--     :: Clock  System Source
--     -&gt; Reset  System Asynchronous
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = altpll (SSymbol @ "altpll50") clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (unsafeToAsyncReset pllStable)
--       in   exposeClockReset leds pllOut rstSync
--     where
--       key1R  = isRising 1 key1
--       leds   = mealy blinkerT (1,False,0) key1R
--   </pre>
resetSynchronizer :: Clock domain gated -> Reset domain  'Asynchronous -> Reset domain  'Asynchronous

-- | "<tt><a>delay</a> clk s</tt>" delays the values in <a>Signal</a>
--   <i>s</i> for once cycle, the value at time 0 is <i>undefined</i>.
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 3 (delay systemClockGen (fromList [1,2,3,4])))
--   [X,1,2]
--   </pre>
delay :: HasCallStack => Clock domain gated -> Signal domain a -> Signal domain a

-- | "<tt><a>register</a> clk rst i s</tt>" delays the values in
--   <a>Signal</a> <i>s</i> for one cycle, and sets the value to <tt>i</tt>
--   the moment the reset becomes <a>False</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 3 (register systemClockGen systemResetGen 8 (fromList [1,2,3,4]))
--   [8,1,2]
--   </pre>
register :: HasCallStack => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain a

-- | Version of <a>register</a> that only updates its content when its
--   fourth argument is a <a>Just</a> value. So given:
--   
--   <pre>
--   sometimes1 clk rst = s where
--     s = <a>register</a> clk rst Nothing (switch <a>&lt;$&gt;</a> s)
--   
--     switch Nothing = Just 1
--     switch _       = Nothing
--   
--   countSometimes clk rst = s where
--     s     = <a>regMaybe</a> clk rst 0 (plusM (<a>pure</a> <a>&lt;$&gt;</a> s) (sometimes1 clk rst))
--     plusM = liftA2 (liftA2 (+))
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 (sometimes1 systemClockGen systemResetGen)
--   [Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
--   
--   &gt;&gt;&gt; sampleN 8 (count systemClockGen systemResetGen)
--   [0,0,1,1,2,2,3,3]
--   </pre>
regMaybe :: HasCallStack => Clock domain gated -> Reset domain synchronous -> a -> Signal domain (Maybe a) -> Signal domain a

-- | Version of <a>register</a> that only updates its content when its
--   fourth argument is asserted. So given:
--   
--   <pre>
--   oscillate clk rst = let s = <a>register</a> clk rst False (not &lt;$&gt; s) in s
--   count clk rst     = let s = 'regEn clk rst 0 (oscillate clk rst) (s + 1) in s
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 (oscillate systemClockGen systemResetGen)
--   [False,True,False,True,False,True,False,True]
--   
--   &gt;&gt;&gt; sampleN 8 (count systemClockGen systemResetGen)
--   [0,0,1,1,2,2,3,3]
--   </pre>
regEn :: Clock domain clk -> Reset domain synchronous -> a -> Signal domain Bool -> Signal domain a -> Signal domain a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA = clockGen @DomA
--   </pre>
clockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Clock domain  'Source

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA en = clockGen @DomA en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type DomA1 = Dom "A" 1 -- fast, twice as fast as slow
--   type DomB2 = Dom "B" 2 -- slow
--   
--   topEntity
--     :: Clock DomA1 Source
--     -&gt; Reset DomA1 Asynchronous
--     -&gt; Clock DomB2 Source
--     -&gt; Signal DomA1 (Unsigned 8)
--     -&gt; Signal DomB2 (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 clk2 i =
--     let h = register clk1 rst1 0 (register clk1 rst1 0 i)
--         l = register clk1 rst1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h,l))
--   
--   testBench
--     :: Signal DomB2 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clkA1 rstA1 $(listToVecTH [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = outputVerifier   clkB2 rstB2 $(listToVecTH [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 clkB2 testInput)
--       done'          = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @DomA1 (unsafeSynchronizer clkB2 clkA1 done')
--       clkB2          = <a>tbClockGen</a> @DomB2 done'
--       rstA1          = asyncResetGen @DomA1
--       rstB2          = asyncResetGen @DomB2
--   </pre>
tbClockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Signal domain Bool -> Clock domain  'Source

-- | Asynchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = asyncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type Dom2 = Dom "dom" 2
--   type Dom7 = Dom "dom" 7
--   type Dom9 = Dom "dom" 9
--   
--   topEntity
--     :: Clock Dom2 Source
--     -&gt; Clock Dom7 Source
--     -&gt; Clock Dom9 Source
--     -&gt; Signal Dom7 Integer
--     -&gt; Signal Dom9 Integer
--   topEntity clk2 clk7 clk9 i = delay clk9 (unsafeSynchronizer clk2 clk9 (delay clk2 (unsafeSynchronizer clk7 clk2 (delay clk7 i))))
--   {--}
--   
--   testBench
--     :: Signal Dom9 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clk7 rst7 $(listToVecTH [(1::Integer)..10])
--       expectedOutput = outputVerifier   clk9 rst9
--                           ((undefined :&gt; undefined :&gt; Nil) ++ $(listToVecTH ([2,3,4,5,7,8,9,10]::[Integer])))
--       done           = expectedOutput (topEntity clk2 clk7 clk9 testInput)
--       done'          = not &lt;$&gt; done
--       clk2           = tbClockGen @Dom2 (unsafeSynchronizer clk9 clk2 done')
--       clk7           = tbClockGen @Dom7 (unsafeSynchronizer clk9 clk7 done')
--       clk9           = tbClockGen @Dom9 done'
--       rst7           = <a>asyncResetGen</a> @Dom7
--       rst9           = <a>asyncResetGen</a> @Dom9
--   </pre>
asyncResetGen :: Reset domain  'Asynchronous

-- | Synchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = syncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
syncResetGen :: (domain ~  'Dom n clkPeriod, KnownNat clkPeriod) => Reset domain  'Synchronous

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: should only be used for simulation, and <b>not</b> for the
--   <i>testBench</i> function. For the <i>testBench</i> function, used
--   <a>tbSystemClockGen</a>
systemClockGen :: Clock System  'Source

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: can be used in the <i>testBench</i> function
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockReset (expectedOutput (topEntity <a>$</a> testInput)) clk rst
--       clk            = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--       rst            = systemResetGen
--   </pre>
tbSystemClockGen :: Signal System Bool -> Clock System  'Source

-- | Reset generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: should only be used for simulation or the testBench
--   function.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockReset (expectedOutput (topEntity <a>$</a> testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System  'Asynchronous

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal'</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <tt>Unbundled'</tt> clk D = <tt>Signal'</tt> clk D
--     <a>bundle</a>   _ s = s
--     <a>unbundle</a> _ s = s
--   </pre>
class Bundle a where {
    type family Unbundled (domain :: Domain) a = res | res -> domain a;
    type Unbundled domain a = Signal domain a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: (Bundle a, (Signal domain a ~ Unbundled domain a)) => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal domain a -> Unbundled domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, (Unbundled domain a ~ Signal domain a)) => Signal domain a -> Unbundled domain a

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen systemResetGen 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate :: (NFData a, NFData b) => (Signal domain1 a -> Signal domain2 b) -> [a] -> [b]

-- | Simulate a (<tt><a>Unbundled</a> a -&gt; <a>Unbundled</a> b</tt>)
--   function given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register systemClockGen systemResetGen (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulateB :: (Bundle a, Bundle b, NFData a, NFData b) => (Unbundled domain1 a -> Unbundled domain2 b) -> [a] -> [b]

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register systemClockGen systemResetGen 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate_lazy :: (Signal domain1 a -> Signal domain2 b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Unbundled</a> a -&gt;
--   <a>Unbundled</a> b</tt>) function given a list of samples of type
--   <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register systemClockGen systemResetGen (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulateB_lazy :: (Bundle a, Bundle b) => (Unbundled domain1 a -> Unbundled domain2 b) -> [a] -> [b]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample :: (Foldable f, NFData a) => f a -> [a]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN :: (Foldable f, NFData a) => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList :: NFData a => [a] -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sample</b> :: <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample_lazy :: Foldable f => f a -> [a]

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>sampleN</b> :: Int -&gt; <a>Signal</a> a -&gt; [a]
--   </pre>
--   
--   Get a list of <tt>n</tt> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN_lazy :: Foldable f => Int -> f a -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList_lazy :: [a] -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>testFor</b> :: <a>Int</a> -&gt; <a>Signal</a> Bool -&gt; <a>Property</a>
--   </pre>
--   
--   <tt>testFor n s</tt> tests the signal <tt>s</tt> for <tt>n</tt>
--   cycles.
testFor :: Foldable f => Int -> f Bool -> Property

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.


-- | CλaSH has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (domain :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>domain</i> is the
--   <i>clock-</i> (and <i>reset-</i>) domain to which the memory elements
--   manipulating these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>domain</i>, is of the kind <a>Domain</a> which
--   has types of the following shape:
--   
--   <pre>
--   data Domain = Dom { domainName :: <a>Symbol</a>, clkPeriod :: <a>Nat</a> }
--   </pre>
--   
--   Where <i>domainName</i> is a type-level string (<a>Symbol</a>)
--   representing the name of the <i>clock-</i> (and <i>reset-</i>) domain,
--   and <i>clkPeriod</i> is a type-level natural number (<a>Nat</a>)
--   representing the clock period (in <b>ps</b>) of the clock lines in the
--   <i>clock-domain</i>.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   </ul>
module Clash.Signal

-- | CλaSH has synchronous <a>Signal</a>s in the form of:
--   
--   <pre>
--   <a>Signal</a> (domain :: <a>Domain</a>) a
--   </pre>
--   
--   Where <i>a</i> is the type of the value of the <a>Signal</a>, for
--   example <i>Int</i> or <i>Bool</i>, and <i>domain</i> is the
--   <i>clock-</i> (and <i>reset-</i>) domain to which the memory elements
--   manipulating these <a>Signal</a>s belong.
--   
--   The type-parameter, <i>domain</i>, is of the kind <a>Domain</a> which
--   has types of the following shape:
--   
--   <pre>
--   data Domain = Dom { domainName :: <a>Symbol</a>, clkPeriod :: <a>Nat</a> }
--   </pre>
--   
--   Where <i>domainName</i> is a type-level string (<a>Symbol</a>)
--   representing the name of the <i>clock-</i> (and <i>reset-</i>) domain,
--   and <i>clkPeriod</i> is a type-level natural number (<a>Nat</a>)
--   representing the clock period (in <b>ps</b>) of the clock lines in the
--   <i>clock-domain</i>.
--   
--   <ul>
--   <li><b>NB</b>: "Bad things"™ happen when you actually use a clock
--   period of <tt>0</tt>, so do <b>not</b> do that!</li>
--   <li><b>NB</b>: You should be judicious using a clock with period of
--   <tt>1</tt> as you can never create a clock that goes any faster!</li>
--   </ul>
data Signal (domain :: Domain) a

-- | A domain with a name (<tt>Symbol</tt>) and a clock period
--   (<tt>Nat</tt>) in <i>ps</i>
data Domain
Dom :: Symbol -> Nat -> Domain
[domainName] :: Domain -> Symbol
[clkPeriod] :: Domain -> Nat

-- | A <i>clock</i> (and <i>reset</i>) domain with clocks running at 100
--   MHz
type System =  'Dom "system" 10000

-- | A clock signal belonging to a <tt>domain</tt>
data Clock (domain :: Domain) (gated :: ClockKind)

-- | Distinction between gated and ungated clocks
data ClockKind

-- | A clock signal coming straight from the clock source
Source :: ClockKind

-- | A clock signal that has been gated
Gated :: ClockKind

-- | A reset signal belonging to a <tt>domain</tt>.
--   
--   The underlying representation of resets is <a>Bool</a>. Note that all
--   components in the <b>clash-prelude</b> package have an
--   <i>active-high</i> reset port, i.e., the component is reset when the
--   reset port is <a>True</a>.
data Reset (domain :: Domain) (synchronous :: ResetKind)

-- | The "kind" of reset
--   
--   Given a situation where a reset is asserted, and then de-asserted at
--   the active flank of the clock, we can observe the difference between a
--   synchronous reset and an asynchronous reset:
--   
--   <h3>Synchronous reset</h3>
--   
--   <pre>
--   registerS
--     :: Clock domain gated -&gt; Reset domain Synchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerS = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 4 (registerS (clockGen @System) (syncResetGen @System) 0 (fromList [1,2,3])))
--   [X,0,2,3]
--   </pre>
--   
--   <h3>Asynchronous reset</h3>
--   
--   <pre>
--   registerA
--     :: Clock domain gated -&gt; Reset domain Asynchronous
--     -&gt; Signal domain Int -&gt; Signal domain Int
--   registerA = register
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 4 (registerA (clockGen @System) (asyncResetGen @System) 0 (fromList [1,2,3]))
--   [0,1,2,3]
--   </pre>
data ResetKind

-- | Components with a synchronous reset port produce the reset value when:
--   
--   <ul>
--   <li>The reset is asserted during the active flank of the clock to
--   which the component is synchronized.</li>
--   </ul>
Synchronous :: ResetKind

-- | Components with an asynchronous reset port produce the reset value
--   when:
--   
--   <ul>
--   <li>Immediately when the reset is asserted.</li>
--   </ul>
Asynchronous :: ResetKind

-- | <a>unsafeFromAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li><a>meta-stability</a></li>
--   </ul>
unsafeFromAsyncReset :: Reset domain  'Asynchronous -> Signal domain Bool

-- | <a>unsafeToAsyncReset</a> is unsafe because it can introduce:
--   
--   <ul>
--   <li>combinational loops</li>
--   </ul>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   resetSynchronizer
--     :: Clock domain gated
--     -&gt; Reset domain 'Asynchronous
--     -&gt; Reset domain 'Asynchronous
--   resetSynchronizer clk rst  =
--     let r1 = register clk rst True (pure False)
--         r2 = register clk rst True r1
--     in  <a>unsafeToAsyncReset</a> r2
--   </pre>
unsafeToAsyncReset :: Signal domain Bool -> Reset domain  'Asynchronous

-- | It is safe to treat synchronous resets as <tt>Bool</tt> signals
fromSyncReset :: Reset domain  'Synchronous -> Signal domain Bool

-- | <a>unsafeToSyncReset</a> is unsafe because:
--   
--   <ul>
--   <li>It can lead to <a>meta-stability</a> issues in the presence of
--   asynchronous resets.</li>
--   </ul>
unsafeToSyncReset :: Signal domain Bool -> Reset domain  'Synchronous

-- | Normally, asynchronous resets can be both asynchronously asserted and
--   de-asserted. Asynchronous de-assertion can induce meta-stability in
--   the component which is being reset. To ensure this doesn't happen,
--   <a>resetSynchronizer</a> ensures that de-assertion of a reset happens
--   synchronously. Assertion of the reset remains asynchronous.
--   
--   Note that asynchronous assertion does not induce meta-stability in the
--   component whose reset is asserted. However, when a component "A" in
--   another clock or reset domain depends on the value of a component "B"
--   being reset, then asynchronous assertion of the reset of component "B"
--   can induce meta-stability in component "A". To prevent this from
--   happening you need to use a proper synchronizer, for example one of
--   the synchronizers in <a>Clash.Explicit.Synchronizer</a>
--   
--   <b>NB:</b> Assumes the component(s) being reset have an
--   <i>active-high</i> reset port, which all components in
--   <b>clash-prelude</b> have.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity
--     :: Clock  System Source
--     -&gt; Reset  System Asynchronous
--     -&gt; Signal System Bit
--     -&gt; Signal System (BitVector 8)
--   topEntity clk rst key1 =
--       let  (pllOut,pllStable) = altpll (SSymbol @ "altpll50") clk rst
--            rstSync            = <a>resetSynchronizer</a> pllOut (unsafeToAsyncReset pllStable)
--       in   exposeClockReset leds pllOut rstSync
--     where
--       key1R  = isRising 1 key1
--       leds   = mealy blinkerT (1,False,0) key1R
--   </pre>
resetSynchronizer :: Clock domain gated -> Reset domain  'Asynchronous -> Reset domain  'Asynchronous

-- | A <i>constraint</i> that indicates the component has a hidden
--   <a>Clock</a>
--   
--   <a>Click here to read more about hidden clocks and resets</a>
type HiddenClock domain gated = Hidden "clk" (Clock domain gated)

-- | Hide the <a>Clock</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
hideClock :: HiddenClock domain gated => (Clock domain gated -> r) -> r

-- | Expose the hidden <a>Clock</a> argument of a component, so it can be
--   applied explicitly
--   
--   <a>Click here to read more about hidden clocks and resets</a>
exposeClock :: (HiddenClock domain gated => r) -> (Clock domain gated -> r)

-- | Connect an explicit <a>Clock</a> to a function with a hidden
--   <a>Clock</a> argument.
--   
--   <pre>
--   withClock = <a>flip</a> exposeClock
--   </pre>
withClock :: Clock domain gated -> (HiddenClock domain gated => r) -> r

-- | Connect a hidden <a>Clock</a> to an argument where a normal
--   <a>Clock</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
hasClock :: HiddenClock domain gated => Clock domain gated

-- | A <i>constraint</i> that indicates the component needs a <a>Reset</a>
--   
--   <a>Click here to read more about hidden clocks and resets</a>
type HiddenReset domain synchronous = Hidden "rst" (Reset domain synchronous)

-- | Hide the <a>Reset</a> argument of a component, so it can be routed
--   implicitly.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
hideReset :: HiddenReset domain synchronous => (Reset domain synchronous -> r) -> r

-- | Expose the hidden <a>Reset</a> argument of a component, so it can be
--   applied explicitly
--   
--   <a>Click here to read more about hidden clocks and resets</a>
exposeReset :: (HiddenReset domain synchronous => r) -> (Reset domain synchronous -> r)

-- | Connect an explicit <a>Reset</a> to a function with a hidden
--   <a>Reset</a> argument.
--   
--   <pre>
--   withReset = <a>flip</a> exposeReset
--   </pre>
--   
--   <a>Click here to read more about hidden clocks and resets</a>
withReset :: Reset domain synchronous -> (HiddenReset domain synchronous => r) -> r

-- | Connect a hidden <a>Reset</a> to an argument where a normal
--   <a>Reset</a> argument was expected.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
hasReset :: HiddenReset domain synchronous => Reset domain synchronous

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>
--   and <a>Reset</a>
--   
--   <a>Click here to read more about hidden clocks and resets</a>
type HiddenClockReset domain gated synchronous = (HiddenClock domain gated, HiddenReset domain synchronous)
hideClockReset :: HiddenClockReset domain gated synchronous => (Clock domain gated -> Reset domain synchronous -> r) -> r

-- | Expose the hidden <a>Clock</a> and <a>Reset</a> arguments of a
--   component, so they can be applied explicitly
--   
--   <a>Click here to read more about hidden clocks and resets</a>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockReset (expectedOutput (topEntity <a>$</a> testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = systemResetGen
--   </pre>
exposeClockReset :: (HiddenClockReset domain gated synchronous => r) -> (Clock domain gated -> Reset domain synchronous -> r)

-- | Connect an explicit <a>Clock</a> and <a>Reset</a> to a function with a
--   hidden <a>Clock</a> and <a>Reset</a> argument.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
withClockReset :: Clock domain gated -> Reset domain synchronous -> (HiddenClockReset domain gated synchronous => r) -> r

-- | A <i>constraint</i> that indicates the component needs a <a>Clock</a>
--   and a <a>Reset</a> belonging to the <a>System</a> domain.
--   
--   <a>Click here to read more about hidden clocks and resets</a>
type SystemClockReset = HiddenClockReset System  'Source  'Asynchronous

-- | <a>delay</a> <tt>s</tt> delays the values in <a>Signal</a> <tt>s</tt>
--   for once cycle, the value at time 0 is undefined.
--   
--   <pre>
--   &gt;&gt;&gt; printX (sampleN 3 (delay (fromList [1,2,3,4])))
--   [X,1,2]
--   </pre>
delay :: (HiddenClock domain gated, HasCallStack) => Signal domain a -> Signal domain a

-- | <a>register</a> <tt>i s</tt> delays the values in <a>Signal</a>
--   <tt>s</tt> for one cycle, and sets the value at time 0 to <tt>i</tt>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 3 (register 8 (fromList [1,2,3,4]))
--   [8,1,2]
--   </pre>
register :: (HiddenClockReset domain gated synchronous, HasCallStack) => a -> Signal domain a -> Signal domain a
infixr 3 `register`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is a <a>Just</a> value. So given:
--   
--   <pre>
--   sometimes1 = s where
--     s = <a>register</a> Nothing (switch <a>&lt;$&gt;</a> s)
--   
--     switch Nothing = Just 1
--     switch _       = Nothing
--   
--   countSometimes = s where
--     s     = <a>regMaybe</a> 0 (plusM (<a>pure</a> <a>&lt;$&gt;</a> s) sometimes1)
--     plusM = <tt>liftA2</tt> (liftA2 (+))
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 sometimes1
--   [Nothing,Just 1,Nothing,Just 1,Nothing,Just 1,Nothing,Just 1]
--   
--   &gt;&gt;&gt; sampleN 8 countSometimes
--   [0,0,1,1,2,2,3,3]
--   </pre>
regMaybe :: (HiddenClockReset domain gated synchronous, HasCallStack) => a -> Signal domain (Maybe a) -> Signal domain a
infixr 3 `regMaybe`

-- | Version of <a>register</a> that only updates its content when its
--   second argument is asserted. So given:
--   
--   <pre>
--   oscillate = <a>register</a> False (<a>not</a> <a>&lt;$&gt;</a> oscillate)
--   count     = <a>regEn</a> 0 oscillate (count + 1)
--   </pre>
--   
--   We get:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 8 oscillate
--   [False,True,False,True,False,True,False,True]
--   
--   &gt;&gt;&gt; sampleN 8 count
--   [0,0,1,1,2,2,3,3]
--   </pre>
regEn :: (HiddenClockReset domain gated synchronous, HasCallStack) => a -> Signal domain Bool -> Signal domain a -> Signal domain a

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>mux</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> a
--   </pre>
--   
--   A multiplexer. Given "<tt><a>mux</a> b t f</tt>", output <tt>t</tt>
--   when <tt>b</tt> is <a>True</a>, and <tt>f</tt> when <tt>b</tt> is
--   <a>False</a>.
mux :: Applicative f => f Bool -> f a -> f a -> f a

-- | Clock generator for simulations. Do <b>not</b> use this clock
--   generator for for the <i>testBench</i> function, use <a>tbClockGen</a>
--   instead.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA = clockGen @DomA
--   </pre>
clockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Clock domain  'Source

-- | Clock generator to be used in the <i>testBench</i> function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   clkA en = clockGen @DomA en
--   </pre>
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type DomA1 = Dom "A" 1 -- fast, twice as fast as slow
--   type DomB2 = Dom "B" 2 -- slow
--   
--   topEntity
--     :: Clock DomA1 Source
--     -&gt; Reset DomA1 Asynchronous
--     -&gt; Clock DomB2 Source
--     -&gt; Signal DomA1 (Unsigned 8)
--     -&gt; Signal DomB2 (Unsigned 8, Unsigned 8)
--   topEntity clk1 rst1 clk2 i =
--     let h = register clk1 rst1 0 (register clk1 rst1 0 i)
--         l = register clk1 rst1 0 i
--     in  unsafeSynchronizer clk1 clk2 (bundle (h,l))
--   
--   testBench
--     :: Signal DomB2 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clkA1 rstA1 $(listToVecTH [1::Unsigned 8,2,3,4,5,6,7,8])
--       expectedOutput = outputVerifier   clkB2 rstB2 $(listToVecTH [(0,0) :: (Unsigned 8, Unsigned 8),(1,2),(3,4),(5,6),(7,8)])
--       done           = expectedOutput (topEntity clkA1 rstA1 clkB2 testInput)
--       done'          = not &lt;$&gt; done
--       clkA1          = <a>tbClockGen</a> @DomA1 (unsafeSynchronizer clkB2 clkA1 done')
--       clkB2          = <a>tbClockGen</a> @DomB2 done'
--       rstA1          = asyncResetGen @DomA1
--       rstB2          = asyncResetGen @DomB2
--   </pre>
tbClockGen :: (domain ~  'Dom nm period, KnownSymbol nm, KnownNat period) => Signal domain Bool -> Clock domain  'Source

-- | Asynchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = asyncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   type Dom2 = Dom "dom" 2
--   type Dom7 = Dom "dom" 7
--   type Dom9 = Dom "dom" 9
--   
--   topEntity
--     :: Clock Dom2 Source
--     -&gt; Clock Dom7 Source
--     -&gt; Clock Dom9 Source
--     -&gt; Signal Dom7 Integer
--     -&gt; Signal Dom9 Integer
--   topEntity clk2 clk7 clk9 i = delay clk9 (unsafeSynchronizer clk2 clk9 (delay clk2 (unsafeSynchronizer clk7 clk2 (delay clk7 i))))
--   {--}
--   
--   testBench
--     :: Signal Dom9 Bool
--   testBench = done
--     where
--       testInput      = stimuliGenerator clk7 rst7 $(listToVecTH [(1::Integer)..10])
--       expectedOutput = outputVerifier   clk9 rst9
--                           ((undefined :&gt; undefined :&gt; Nil) ++ $(listToVecTH ([2,3,4,5,7,8,9,10]::[Integer])))
--       done           = expectedOutput (topEntity clk2 clk7 clk9 testInput)
--       done'          = not &lt;$&gt; done
--       clk2           = tbClockGen @Dom2 (unsafeSynchronizer clk9 clk2 done')
--       clk7           = tbClockGen @Dom7 (unsafeSynchronizer clk9 clk7 done')
--       clk9           = tbClockGen @Dom9 done'
--       rst7           = <a>asyncResetGen</a> @Dom7
--       rst9           = <a>asyncResetGen</a> @Dom9
--   </pre>
asyncResetGen :: Reset domain  'Asynchronous

-- | Synchronous reset generator, for simulations and the <i>testBench</i>
--   function.
--   
--   To be used like:
--   
--   <pre>
--   type DomA = Dom "A" 1000
--   rstA = syncResetGen @DomA
--   </pre>
--   
--   <b>NB</b>: Can only be used for components with an <i>active-high</i>
--   reset port, which all <b>clash-prelude</b> components are.
syncResetGen :: (domain ~  'Dom n clkPeriod, KnownNat clkPeriod) => Reset domain  'Synchronous

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: should only be used for simulation, and <b>not</b> for the
--   <i>testBench</i> function. For the <i>testBench</i> function, used
--   <a>tbSystemClockGen</a>
systemClockGen :: Clock System  'Source

-- | Clock generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: can be used in the <i>testBench</i> function
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockReset (expectedOutput (topEntity <a>$</a> testInput)) clk rst
--       clk            = <a>tbSystemClockGen</a> (not &lt;$&gt; done)
--       rst            = systemResetGen
--   </pre>
tbSystemClockGen :: Signal System Bool -> Clock System  'Source

-- | Reset generator for the <a>System</a> clock domain.
--   
--   <b>NB</b>: should only be used for simulation or the testBench
--   function.
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   topEntity :: Vec 2 (Vec 3 (Unsigned 8)) -&gt; Vec 6 (Unsigned 8)
--   topEntity = concat
--   
--   testBench :: Signal System Bool
--   testBench = done
--     where
--       testInput      = pure ((1 :&gt; 2 :&gt; 3 :&gt; Nil) :&gt; (4 :&gt; 5 :&gt; 6 :&gt; Nil) :&gt; Nil)
--       expectedOutput = outputVerifier ((1:&gt;2:&gt;3:&gt;4:&gt;5:&gt;6:&gt;Nil):&gt;Nil)
--       done           = exposeClockReset (expectedOutput (topEntity <a>$</a> testInput)) clk rst
--       clk            = tbSystemClockGen (not &lt;$&gt; done)
--       rst            = <a>systemResetGen</a>
--   </pre>
systemResetGen :: Reset System  'Asynchronous

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&amp;&amp;.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&amp;&amp;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.&&.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 3 .&&.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.||.)</b> :: <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a> -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>||</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.||.) :: Applicative f => f Bool -> f Bool -> f Bool
infixr 2 .||.

-- | Isomorphism between a <a>Signal</a> of a product type (e.g. a tuple)
--   and a product type of <a>Signal'</a>s.
--   
--   Instances of <a>Bundle</a> must satisfy the following laws:
--   
--   <pre>
--   <a>bundle</a> . <a>unbundle</a> = <a>id</a>
--   <a>unbundle</a> . <a>bundle</a> = <a>id</a>
--   </pre>
--   
--   By default, <a>bundle</a> and <a>unbundle</a>, are defined as the
--   identity, that is, writing:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   data D = A | B
--   
--   instance Bundle D where
--     type <tt>Unbundled'</tt> clk D = <tt>Signal'</tt> clk D
--     <a>bundle</a>   _ s = s
--     <a>unbundle</a> _ s = s
--   </pre>
class Bundle a where {
    type family Unbundled (domain :: Domain) a = res | res -> domain a;
    type Unbundled domain a = Signal domain a;
}

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: Bundle a => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>bundle</b> :: (<a>Signal</a> domain a, <a>Signal</a> domain b) -&gt; <a>Signal</a> clk (a,b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>bundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
bundle :: (Bundle a, (Signal domain a ~ Unbundled domain a)) => Unbundled domain a -> Signal domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: Bundle a => Signal domain a -> Unbundled domain a

-- | Example:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain (a,b) -&gt; (<a>Signal</a> domain a, <a>Signal</a> domain b)
--   </pre>
--   
--   However:
--   
--   <pre>
--   <b>unbundle</b> :: <a>Signal</a> domain <a>Bit</a> -&gt; <a>Signal</a> domain <a>Bit</a>
--   </pre>
unbundle :: (Bundle a, (Unbundled domain a ~ Signal domain a)) => Signal domain a -> Unbundled domain a

-- | Simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a> b</tt>) function
--   given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate :: forall gated synchronous domain a b. (NFData a, NFData b) => (HiddenClockReset domain gated synchronous => Signal domain a -> Signal domain b) -> [a] -> [b]

-- | Simulate a (<tt><a>Unbundled</a> a -&gt; <a>Unbundled</a> b</tt>)
--   function given a list of samples of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulateB :: forall gated synchronous domain a b. (Bundle a, Bundle b, NFData a, NFData b) => (HiddenClockReset domain gated synchronous => Unbundled domain a -> Unbundled domain b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Signal</a> a -&gt; <a>Signal</a>
--   b</tt>) function given a list of samples of type <i>a</i>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (register 8) [1, 2, 3]
--   [8,1,2,3...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulate_lazy :: forall gated synchronous domain a b. (HiddenClockReset domain gated synchronous => Signal domain a -> Signal domain b) -> [a] -> [b]

-- | <i>Lazily</i> simulate a (<tt><a>Unbundled</a> a -&gt;
--   <a>Unbundled</a> b</tt>) function given a list of samples of type
--   <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (unbundle . register (8,8) . bundle) [(1,1), (2,2), (3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
simulateB_lazy :: forall gated synchronous domain a b. (Bundle a, Bundle b) => (HiddenClockReset domain gated synchronous => Unbundled domain a -> Unbundled domain b) -> [a] -> [b]

-- | Get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample :: forall gated synchronous domain a. NFData a => (HiddenClockReset domain gated synchronous => Signal domain a) -> [a]

-- | Get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN :: forall gated synchronous domain a. NFData a => Int -> (HiddenClockReset domain gated synchronous => Signal domain a) -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList :: NFData a => [a] -> Signal domain a

-- | <i>Lazily</i> get an infinite list of samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sample s == [s0, s1, s2, s3, ...
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sample_lazy :: forall gated synchronous domain a. (HiddenClockReset domain gated synchronous => Signal domain a) -> [a]

-- | Lazily get a list of <i>n</i> samples from a <a>Signal</a>
--   
--   The elements in the list correspond to the values of the <a>Signal</a>
--   at consecutive clock cycles
--   
--   <pre>
--   sampleN 3 s == [s0, s1, s2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
sampleN_lazy :: forall gated synchronous domain a. Int -> (HiddenClockReset domain gated synchronous => Signal domain a) -> [a]

-- | Create a <a>Signal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (fromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
fromList_lazy :: [a] -> Signal domain a

-- | <tt>testFor n s</tt> tests the signal <i>s</i> for <i>n</i> cycles.
testFor :: Int -> (HiddenClockReset domain gated synchronous => Signal domain Bool) -> Property

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.==.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>==</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.==.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 .==.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(./=.)</b> :: <a>Eq</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>/=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(./=.) :: (Eq a, Applicative f) => f a -> f a -> f Bool
infix 4 ./=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&lt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&lt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.<=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .<=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;=.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;=</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>=.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>=.

-- | The above type is a generalisation for:
--   
--   <pre>
--   <b>(.&gt;.)</b> :: <a>Ord</a> a =&gt; <a>Signal</a> a -&gt; <a>Signal</a> a -&gt; <a>Signal</a> <a>Bool</a>
--   </pre>
--   
--   It is a version of (<a>&gt;</a>) that returns a <a>Signal</a> of
--   <a>Bool</a>
(.>.) :: (Ord a, Applicative f) => f a -> f a -> f Bool
infix 4 .>.


-- | ROMs
module Clash.Explicit.ROM

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, Enum addr) => Clock domain gated -> Vec n a -> Signal domain addr -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: KnownNat n => Clock domain gated -> Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | ROM primitive
rom# :: KnownNat n => Clock domain gated -> Vec n a -> Signal domain Int -> Signal domain a


-- | ROMs
module Clash.Prelude.ROM

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRomPow2 :: KnownNat n => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, KnownNat m, HiddenClock domain gated) => Vec n a -> Signal domain (Unsigned m) -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: (KnownNat n, HiddenClock domain gated) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | asyncROM primitive
asyncRom# :: KnownNat n => Vec n a -> Int -> a


-- | Whereas the output of a Mealy machine depends on <i>current
--   transition</i>, the output of a Moore machine depends on the
--   <i>previous state</i>.
--   
--   Moore machines are strictly less expressive, but may impose laxer
--   timing requirements.
module Clash.Explicit.Moore

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>Clock</a> mac Source
--     -&gt; <a>Reset</a> mac Asynchronous
--     -&gt; <a>Signal</a> mac (Int, Int)
--     -&gt; <a>Signal</a> mac Int
--   mac clk rst = <a>moore</a> clk rst macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <tt>moore'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mooreB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o) => Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine without any output logic
medvedev :: Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> s -> (Signal domain i -> Signal domain s)

-- | A version of <a>medvedev</a> that does automatic <a>Bundle</a>ing
medvedevB :: (Bundle i, Bundle s) => Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> s -> (Unbundled domain i -> Unbundled domain s)


-- | Whereas the output of a Mealy machine depends on <i>current
--   transition</i>, the output of a Moore machine depends on the
--   <i>previous state</i>.
--   
--   Moore machines are strictly less expressive, but may impose laxer
--   timing requirements.
module Clash.Prelude.Moore

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT :: Int        -- Current state
--        -&gt; (Int,Int)  -- Input
--        -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: HiddenClockReset domain gated synchronous => (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine without any output logic
medvedev :: HiddenClockReset domain gated synchronous => (s -> i -> s) -> s -> (Signal domain i -> Signal domain s)

-- | A version of <a>medvedev</a> that does automatic <a>Bundle</a>ing
medvedevB :: (Bundle i, Bundle s, HiddenClockReset domain gated synchronous) => (s -> i -> s) -> s -> (Unbundled domain i -> Unbundled domain s)


-- | Whereas the output of a Moore machine depends on the <i>previous
--   state</i>, the output of a Mealy machine depends on <i>current
--   transition</i>.
--   
--   Mealy machines are strictly more expressive, but may impose stricter
--   timing requirements.
module Clash.Explicit.Mealy

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>Clock</a> domain Source
--     -&gt; <a>Reset</a> domain Asynchronous
--     -&gt; <a>Signal</a> domain (Int, Int)
--     -&gt; <a>Signal</a> domain Int
--   mac clk rst = <a>mealy</a> clk rst macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>Clock</a> domain gated -&gt; <a>Reset</a> domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Signal dom i -> Signal dom o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <tt>mealy'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mealyB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o) => Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Unbundled dom i -> Unbundled dom o)


-- | Whereas the output of a Moore machine depends on the <i>previous
--   state</i>, the output of a Mealy machine depends on <i>current
--   transition</i>.
--   
--   Mealy machines are strictly more expressive, but may impose stricter
--   timing requirements.
module Clash.Prelude.Mealy

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: HiddenClockReset domain gated synchronous => (s -> i -> (s, o)) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Infix version of <a>mealyB</a>
(<^>) :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)


-- | Self-synchronising circuits based on data-flow principles.
module Clash.Prelude.DataFlow

-- | Dataflow circuit with bidirectional synchronisation channels.
--   
--   In the <i>forward</i> direction we assert <i>validity</i> of the data.
--   In the <i>backward</i> direction we assert that the circuit is
--   <i>ready</i> to receive new data. A circuit adhering to the
--   <a>DataFlow</a> type should:
--   
--   <ul>
--   <li>Not consume data when validity is deasserted.</li>
--   <li>Only update its output when readiness is asserted.</li>
--   </ul>
--   
--   The <tt>DataFlow'</tt> type is defined as:
--   
--   <pre>
--   newtype DataFlow' dom iEn oEn i o
--     = DF
--     { df :: <tt>Signal'</tt> dom i     -- Incoming data
--          -&gt; <tt>Signal'</tt> dom iEn   -- Flagged with <i>valid</i> bits <tt>iEn</tt>.
--          -&gt; <tt>Signal'</tt> dom oEn   -- Incoming back-pressure, <i>ready</i> edge.
--          -&gt; ( <tt>Signal'</tt> dom o   -- Outgoing data.
--             , <tt>Signal'</tt> dom oEn -- Flagged with <i>valid</i> bits <tt>oEn</tt>.
--             , <tt>Signal'</tt> dom iEn -- Outgoing back-pressure, <i>ready</i> edge.
--             )
--     }
--   </pre>
--   
--   where:
--   
--   <ul>
--   <li><tt>dom</tt> is the clock to which the circuit is
--   synchronised.</li>
--   <li><tt>iEn</tt> is the type of the bidirectional incoming
--   synchronisation channel.</li>
--   <li><tt>oEn</tt> is the type of the bidirectional outgoing
--   synchronisation channel.</li>
--   <li><tt>i</tt> is the incoming data type.</li>
--   <li><tt>o</tt> is the outgoing data type.</li>
--   </ul>
--   
--   We define several composition operators for our <a>DataFlow</a>
--   circuits:
--   
--   <ul>
--   <li><a>seqDF</a> sequential composition.</li>
--   <li><a>parDF</a> parallel composition.</li>
--   <li><a>loopDF</a> add a feedback arc.</li>
--   <li><a>lockStep</a> proceed in lock-step.</li>
--   </ul>
--   
--   When you look at the types of the above operators it becomes clear why
--   we parametrise in the types of the synchronisation channels.
newtype DataFlow domain iEn oEn i o
DF :: Signal domain i -> Signal domain iEn -> Signal domain oEn -> (Signal domain o, Signal domain oEn, Signal domain iEn) -> DataFlow domain iEn oEn i o

-- | Create an ordinary circuit from a <a>DataFlow</a> circuit
[df] :: DataFlow domain iEn oEn i o -> Signal domain i -> Signal domain iEn -> Signal domain oEn -> (Signal domain o, Signal domain oEn, Signal domain iEn)

-- | Dataflow circuit synchronised to the <tt>systemClockGen</tt>. type
--   DataFlow iEn oEn i o = DataFlow' systemClockGen iEn oEn i o
--   
--   Create a <a>DataFlow</a> circuit from a circuit description with the
--   appropriate type:
--   
--   <pre>
--   <tt>Signal'</tt> dom i        -- Incoming data.
--   -&gt; <tt>Signal'</tt> dom Bool  -- Flagged with a single <i>valid</i> bit.
--   -&gt; <tt>Signal'</tt> dom Bool  -- Incoming back-pressure, <i>ready</i> bit.
--   -&gt; ( <tt>Signal'</tt> dom o   -- Outgoing data.
--      , <tt>Signal'</tt> dom oEn -- Flagged with a single <i>valid</i> bit.
--      , <tt>Signal'</tt> dom iEn -- Outgoing back-pressure, <i>ready</i> bit.
--      )
--   </pre>
--   
--   A circuit adhering to the <a>DataFlow</a> type should:
--   
--   <ul>
--   <li>Not consume data when validity is deasserted.</li>
--   <li>Only update its output when readiness is asserted.</li>
--   </ul>
liftDF :: (Signal dom i -> Signal dom Bool -> Signal dom Bool -> (Signal dom o, Signal dom Bool, Signal dom Bool)) -> DataFlow dom Bool Bool i o

-- | Create a <a>DataFlow</a> circuit where the given function <tt>f</tt>
--   operates on the data, and the synchronisation channels are passed
--   unaltered.
pureDF :: (i -> o) -> DataFlow dom Bool Bool i o

-- | Create a <a>DataFlow</a> circuit from a Mealy machine description as
--   those of <a>Clash.Prelude.Mealy</a>
mealyDF :: Clock domain gated -> Reset domain synchronous -> (s -> i -> (s, o)) -> s -> DataFlow domain Bool Bool i o

-- | Create a <a>DataFlow</a> circuit from a Moore machine description as
--   those of <a>Clash.Prelude.Moore</a>
mooreDF :: Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> DataFlow domain Bool Bool i o

-- | Create a FIFO buffer adhering to the <a>DataFlow</a> protocol. Can be
--   filled with initial content.
--   
--   To create a FIFO of size 4, with two initial values 2 and 3 you would
--   write:
--   
--   <pre>
--   fifo4 = <a>fifoDF</a> d4 (2 :&gt; 3 :&gt; Nil)
--   </pre>
fifoDF :: forall addrSize m n a domain gated synchronous. (KnownNat addrSize, KnownNat n, KnownNat m, (m + n) ~ (2 ^ addrSize)) => Clock domain gated -> Reset domain synchronous -> SNat (m + n) -> Vec m a -> DataFlow domain Bool Bool a a

-- | Identity circuit
--   
idDF :: DataFlow dom en en a a

-- | Sequential composition of two <a>DataFlow</a> circuits.
--   
seqDF :: DataFlow dom aEn bEn a b -> DataFlow dom bEn cEn b c -> DataFlow dom aEn cEn a c

-- | Apply the circuit to the first halve of the communication channels,
--   leave the second halve unchanged.
--   
firstDF :: DataFlow dom aEn bEn a b -> DataFlow dom (aEn, cEn) (bEn, cEn) (a, c) (b, c)

-- | Swap the two communication channels.
--   
swapDF :: DataFlow dom (aEn, bEn) (bEn, aEn) (a, b) (b, a)

-- | Apply the circuit to the second halve of the communication channels,
--   leave the first halve unchanged.
--   
secondDF :: DataFlow dom aEn bEn a b -> DataFlow dom (cEn, aEn) (cEn, bEn) (c, a) (c, b)

-- | Compose two <a>DataFlow</a> circuits in parallel.
--   
parDF :: DataFlow dom aEn bEn a b -> DataFlow dom cEn dEn c d -> DataFlow dom (aEn, cEn) (bEn, dEn) (a, c) (b, d)

-- | Compose <i>n</i> <a>DataFlow</a> circuits in parallel.
parNDF :: KnownNat n => Vec n (DataFlow dom aEn bEn a b) -> DataFlow dom (Vec n aEn) (Vec n bEn) (Vec n a) (Vec n b)

-- | Feed back the second halve of the communication channel. The feedback
--   loop is buffered by a <a>fifoDF</a> circuit.
--   
--   So given a circuit <i>h</i> with two synchronisation channels:
--   
--   <pre>
--   <b>h</b> :: <a>DataFlow</a> (Bool,Bool) (Bool,Bool) (a,d) (b,d)
--   </pre>
--   
--   Feeding back the <i>d</i> part (including its synchronisation
--   channels) results in:
--   
--   <pre>
--   <a>loopDF</a> d4 Nil h
--   </pre>
--   
--   
--   When you have a circuit <tt>h'</tt>, with only a single
--   synchronisation channel:
--   
--   <pre>
--   <b>h'</b> :: <a>DataFlow</a> Bool Bool (a,d) (b,d)
--   </pre>
--   
--   and you want to compose <i>h'</i> in a feedback loop, the following
--   will not work:
--   
--   <pre>
--   f `<tt><a>seqDF</a></tt>` (<a>loopDF</a> d4 Nil h') `<tt><a>seqDF</a></tt>` g
--   </pre>
--   
--   The circuits <tt>f</tt>, <tt>h</tt>, and <tt>g</tt>, must operate in
--   <i>lock-step</i> because the <i>h'</i> circuit only has a single
--   synchronisation channel. Consequently, there should only be progress
--   when all three circuits are producing <i>valid</i> data and all three
--   circuits are <i>ready</i> to receive new data. We need to compose
--   <i>h'</i> with the <a>lockStep</a> and <a>stepLock</a> functions to
--   achieve the <i>lock-step</i> operation.
--   
--   <pre>
--   f `<tt><a>seqDF</a></tt>` (<a>lockStep</a> `<tt><a>seqDF</a></tt>` <a>loopDF</a> d4 Nil h' `<tt><a>seqDF</a></tt>` <a>stepLock</a>) `<tt><a>seqDF</a></tt>` g
--   </pre>
--   
loopDF :: (KnownNat m, KnownNat n, KnownNat addrSize, (m + n) ~ (2 ^ addrSize)) => Clock dom gated -> Reset dom synchronous -> SNat (m + n) -> Vec m d -> DataFlow dom (Bool, Bool) (Bool, Bool) (a, d) (b, d) -> DataFlow dom Bool Bool a b

-- | Feed back the second halve of the communication channel. Unlike
--   <a>loopDF</a>, the feedback loop is <i>not</i> buffered.
loopDF_nobuf :: DataFlow dom (Bool, Bool) (Bool, Bool) (a, d) (b, d) -> DataFlow dom Bool Bool a b

-- | Reduce or extend the synchronisation granularity of parallel
--   compositions.
class LockStep a b

-- | Reduce the synchronisation granularity to a single <a>Bool</a>ean
--   value.
--   
--   Given:
--   
--   <pre>
--   <b>f</b> :: <a>DataFlow</a> Bool Bool a b
--   <b>g</b> :: <a>DataFlow</a> Bool Bool c d
--   <b>h</b> :: <a>DataFlow</a> Bool Bool (b,d) (p,q)
--   </pre>
--   
--   We <i>cannot</i> simply write:
--   
--   <pre>
--   (f `<tt><a>parDF</a></tt>` g) `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   because, <tt>f `parDF` g</tt>, has type, <tt><a>DataFlow</a>
--   (Bool,Bool) (Bool,Bool) (a,c) (b,d)</tt>, which does not match the
--   expected synchronisation granularity of <tt>h</tt>. We need a circuit
--   in between that has the type:
--   
--   <pre>
--   <a>DataFlow</a> (Bool,Bool) Bool (b,d) (b,d)
--   </pre>
--   
--   Simply <a>&amp;&amp;</a>-ing the <i>valid</i> signals in the forward
--   direction, and duplicating the <i>ready</i> signal in the backward
--   direction is however not enough. We also need to make sure that
--   <tt>f</tt> does not update its output when <tt>g</tt>'s output is
--   invalid and visa versa, as <tt>h</tt> can only consume its input when
--   both <tt>f</tt> and <tt>g</tt> are producing valid data. <tt>g</tt>'s
--   <i>ready</i> port is hence only asserted when <tt>h</tt> is ready and
--   <tt>f</tt> is producing <i>valid</i> data. And <tt>f</tt>'s ready port
--   is only asserted when <tt>h</tt> is ready and <tt>g</tt> is producing
--   valid data. <tt>f</tt> and <tt>g</tt> will hence be proceeding in
--   <i>lock-step</i>.
--   
--   The <a>lockStep</a> function ensures that all synchronisation signals
--   are properly connected:
--   
--   <pre>
--   (f `<tt><a>parDF</a></tt>` g) `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   
--   <b>Note 1</b>: ensure that the components that you are synchronising
--   have buffered/delayed <tt>ready</tt> and <tt>valid</tt> signals, or
--   <a>lockStep</a> has the potential to introduce combinational loops.
--   You can do this by placing <a>fifoDF</a>s on the parallel channels.
--   Extending the above example, you would write:
--   
--   <pre>
--   ((f `<tt><a>seqDF</a></tt>` <a>fifoDF</a> d4 Nil) `<tt><a>parDF</a></tt>` (g `<tt><a>seqDF</a></tt>` <a>fifoDF</a> d4 Nil)) `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` h
--   </pre>
--   
--   <b>Note 2</b>: <a>lockStep</a> works for arbitrarily nested tuples.
--   That is:
--   
--   <pre>
--   p :: <a>DataFlow</a> Bool Bool ((b,d),d) z
--   
--   q :: <a>DataFlow</a> ((Bool,Bool),Bool) ((Bool,Bool),Bool) ((a,c),c) ((b,d),d)
--   q = f `<tt><a>parDF</a></tt>` g `<tt><a>parDF</a></tt>` g
--   
--   r = q `<tt><a>seqDF</a></tt>` <a>lockStep</a> `<tt><a>seqDF</a></tt>` p
--   </pre>
--   
--   Does the right thing.
lockStep :: LockStep a b => DataFlow dom a Bool b b

-- | Extend the synchronisation granularity from a single <a>Bool</a>ean
--   value.
--   
--   Given:
--   
--   <pre>
--   <b>f</b> :: <a>DataFlow</a> Bool Bool a b
--   <b>g</b> :: <a>DataFlow</a> Bool Bool c d
--   <b>h</b> :: <a>DataFlow</a> Bool Bool (p,q) (a,c)
--   </pre>
--   
--   We <i>cannot</i> simply write:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` (f `<tt><a>parDF</a></tt>` g)
--   </pre>
--   
--   because, <tt>f `parDF` g</tt>, has type, <tt><a>DataFlow</a>
--   (Bool,Bool) (Bool,Bool) (a,c) (b,d)</tt>, which does not match the
--   expected synchronisation granularity of <tt>h</tt>. We need a circuit
--   in between that has the type:
--   
--   <pre>
--   <a>DataFlow</a> Bool (Bool,Bool) (a,c) (a,c)
--   </pre>
--   
--   Simply <a>&amp;&amp;</a>-ing the <i>ready</i> signals in the backward
--   direction, and duplicating the <i>valid</i> signal in the forward
--   direction is however not enough. We need to make sure that <tt>f</tt>
--   does not consume values when <tt>g</tt> is not <i>ready</i> and visa
--   versa, because <tt>h</tt> cannot update the values of its output tuple
--   independently. <tt>f</tt>'s <i>valid</i> port is hence only asserted
--   when <tt>h</tt> is valid and <tt>g</tt> is ready to receive new
--   values. <tt>g</tt>'s <i>valid</i> port is only asserted when
--   <tt>h</tt> is valid and <tt>f</tt> is ready to receive new values.
--   <tt>f</tt> and <tt>g</tt> will hence be proceeding in
--   <i>lock-step</i>.
--   
--   The <a>stepLock</a> function ensures that all synchronisation signals
--   are properly connected:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` (f `<tt><a>parDF</a></tt>` g)
--   </pre>
--   
--   
--   <b>Note 1</b>: ensure that the components that you are synchronising
--   have buffered/delayed <tt>ready</tt> and <tt>valid</tt> signals, or
--   <a>stepLock</a> has the potential to introduce combinational loops.
--   You can do this by placing <a>fifoDF</a>s on the parallel channels.
--   Extending the above example, you would write:
--   
--   <pre>
--   h `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` ((<a>fifoDF</a> d4 Nil `<tt><a>seqDF</a></tt>` f) `<tt><a>parDF</a></tt>` (<a>fifoDF</a> d4 Nil `<tt><a>seqDF</a></tt>` g))
--   </pre>
--   
--   <b>Note 2</b>: <a>stepLock</a> works for arbitrarily nested tuples.
--   That is:
--   
--   <pre>
--   p :: <a>DataFlow</a> Bool Bool z ((a,c),c)
--   
--   q :: <a>DataFlow</a> ((Bool,Bool),Bool) ((Bool,Bool),Bool) ((a,c),c) ((b,d),d)
--   q = f `<tt><a>parDF</a></tt>` g `<tt><a>parDF</a></tt>` g
--   
--   r = p `<tt><a>seqDF</a></tt>` <a>stepLock</a> `<tt><a>seqDF</a></tt>` q
--   </pre>
--   
--   Does the right thing.
stepLock :: LockStep a b => DataFlow dom Bool a b b
instance Clash.Prelude.DataFlow.LockStep GHC.Types.Bool c
instance (Clash.Prelude.DataFlow.LockStep a x, Clash.Prelude.DataFlow.LockStep b y) => Clash.Prelude.DataFlow.LockStep (a, b) (x, y)
instance (Clash.Prelude.DataFlow.LockStep en a, GHC.TypeNats.KnownNat n) => Clash.Prelude.DataFlow.LockStep (Clash.Sized.Vector.Vec n en) (Clash.Sized.Vector.Vec n a)


module Clash.Explicit.Signal.Delayed

-- | A synchronized signal with samples of type <tt>a</tt>, synchronized to
--   clock <tt>clk</tt>, that has accumulated <tt>delay</tt> amount of
--   samples delay along its path.
data DSignal (domain :: Domain) (delay :: Nat) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods.
--   
--   <pre>
--   delay3 :: Clock domain gated -&gt; Reset domain synchronous
--          -&gt; <a>DSignal</a> domain n Int -&gt; <a>DSignal</a> domain (n + 3) Int
--   delay3 clk rst = <a>delayed</a> clk rst (0 <tt>:&gt;</tt> 0 <tt>:&gt;</tt> 0 <tt>:&gt;</tt> <tt>Nil</tt>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (delay3 systemClockGen systemResetGen (dfromList [1..]))
--   [0,0,0,1,2,3]
--   </pre>
delayed :: forall domain gated synchronous a n d. KnownNat d => Clock domain gated -> Reset domain synchronous -> Vec d a -> DSignal domain n a -> DSignal domain (n + d) a

-- | Delay a <a>DSignal</a> for <tt>m</tt> periods, where <tt>m</tt> is
--   derived from the context.
--   
--   <pre>
--   delay2 :: Clock domain gated -&gt; Reset domain synchronous
--          -&gt; <a>DSignal</a> domain n Int -&gt; <a>DSignal</a> domain (n + 2) Int
--   delay2 = <tt>delayI</tt>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (delay2 systemClockGen systemResetGen (dfromList [1..]))
--   [0,0,1,2,3,4]
--   </pre>
delayedI :: (Default a, KnownNat d) => Clock domain gated -> Reset domain synchronous -> DSignal domain n a -> DSignal domain (n + d) a

-- | Feed the delayed result of a function back to its input:
--   
--   <pre>
--   mac :: Clock domain gated -&gt; Reset domain synchronous
--       -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--   mac clk rst x y = <a>feedback</a> (mac' x y)
--     where
--       mac' :: <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--            -&gt; (<a>DSignal</a> domain 0 Int, <a>DSignal</a> domain 1 Int)
--       mac' a b acc = let acc' = a * b + acc
--                      in  (acc, <tt>delay</tt> clk rst (<a>singleton</a> 0) acc')
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (mac systemClockGen systemResetGen (dfromList [1..]) (dfromList [1..]))
--   [0,1,5,14,30,55]
--   </pre>
feedback :: (DSignal domain n a -> (DSignal domain n a, DSignal domain (n + m + 1) a)) -> DSignal domain n a

-- | <a>Signal</a>s are not delayed
--   
--   <pre>
--   sample s == dsample (fromSignal s)
--   </pre>
fromSignal :: Signal domain a -> DSignal domain 0 a

-- | Strip a <a>DSignal</a> from its delay information.
toSignal :: DSignal domain delay a -> Signal domain a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (dfromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
dfromList :: NFData a => [a] -> DSignal domain 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (dfromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
dfromList_lazy :: [a] -> DSignal domain 0 a

-- | <b>EXPERIMENTAL</b>
--   
--   <b>Unsafely</b> convert a <a>Signal</a> to <i>any</i> <a>DSignal</a>
--   clk'.
--   
--   <b>NB</b>: Should only be used to interface with functions specified
--   in terms of <a>Signal</a>.
unsafeFromSignal :: Signal domain a -> DSignal domain n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal in the present.
--   
--   <pre>
--   mac :: Clock domain gated -&gt; Reset domain synchronous
--       -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--   mac clk rst x y = acc'
--     where
--       acc' = (x * y) + <a>antiDelay</a> d1 acc
--       acc  = <tt>delay</tt> clk rst (<a>singleton</a> 0) acc'
--   </pre>
antiDelay :: SNat d -> DSignal domain (n + d) a -> DSignal domain n a
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance Test.QuickCheck.Arbitrary.CoArbitrary a => Test.QuickCheck.Arbitrary.CoArbitrary (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance Test.QuickCheck.Arbitrary.Arbitrary a => Test.QuickCheck.Arbitrary.Arbitrary (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance Data.Traversable.Traversable (Clash.Explicit.Signal.Delayed.DSignal domain delay)
instance Data.Foldable.Foldable (Clash.Explicit.Signal.Delayed.DSignal domain delay)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance GHC.Num.Num a => GHC.Num.Num (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance GHC.Base.Applicative (Clash.Explicit.Signal.Delayed.DSignal domain delay)
instance GHC.Base.Functor (Clash.Explicit.Signal.Delayed.DSignal domain delay)
instance Data.Default.Class.Default a => Data.Default.Class.Default (Clash.Explicit.Signal.Delayed.DSignal domain delay a)
instance GHC.Show.Show a => GHC.Show.Show (Clash.Explicit.Signal.Delayed.DSignal domain delay a)


module Clash.Signal.Delayed

-- | A synchronized signal with samples of type <tt>a</tt>, synchronized to
--   clock <tt>clk</tt>, that has accumulated <tt>delay</tt> amount of
--   samples delay along its path.
data DSignal (domain :: Domain) (delay :: Nat) a

-- | Delay a <a>DSignal</a> for <tt>d</tt> periods.
--   
--   <pre>
--   delay3 :: <a>DSignal</a> n Int -&gt; <a>DSignal</a> (n + 3) Int
--   delay3 = <a>delayed</a> (0 <tt>:&gt;</tt> 0 <tt>:&gt;</tt> 0 <tt>:&gt;</tt> <tt>Nil</tt>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (toSignal (delay3 (dfromList [1..])))
--   [0,0,0,1,2,3]
--   </pre>
delayed :: (KnownNat d, HiddenClockReset domain gated synchronous) => Vec d a -> DSignal domain n a -> DSignal domain (n + d) a

-- | Delay a <a>DSignal</a> for <tt>m</tt> periods, where <tt>m</tt> is
--   derived from the context.
--   
--   <pre>
--   delay2 :: <a>DSignal</a> n Int -&gt; <a>DSignal</a> (n + 2) Int
--   delay2 = <a>delayedI</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (toSignal (delay2 (dfromList [1..])))
--   [0,0,1,2,3,4]
--   </pre>
delayedI :: (Default a, KnownNat d, HiddenClockReset domain gated synchronous) => DSignal domain n a -> DSignal domain (n + d) a

-- | Feed the delayed result of a function back to its input:
--   
--   <pre>
--   mac :: Clock domain gated -&gt; Reset domain synchronous
--       -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--   mac clk rst x y = <a>feedback</a> (mac' x y)
--     where
--       mac' :: <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--            -&gt; (<a>DSignal</a> domain 0 Int, <a>DSignal</a> domain 1 Int)
--       mac' a b acc = let acc' = a * b + acc
--                      in  (acc, <tt>delay</tt> clk rst (<a>singleton</a> 0) acc')
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 6 (mac systemClockGen systemResetGen (dfromList [1..]) (dfromList [1..]))
--   [0,1,5,14,30,55]
--   </pre>
feedback :: (DSignal domain n a -> (DSignal domain n a, DSignal domain (n + m + 1) a)) -> DSignal domain n a

-- | <a>Signal</a>s are not delayed
--   
--   <pre>
--   sample s == dsample (fromSignal s)
--   </pre>
fromSignal :: Signal domain a -> DSignal domain 0 a

-- | Strip a <a>DSignal</a> from its delay information.
toSignal :: DSignal domain delay a -> Signal domain a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (dfromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
dfromList :: NFData a => [a] -> DSignal domain 0 a

-- | Create a <a>DSignal</a> from a list
--   
--   Every element in the list will correspond to a value of the signal for
--   one clock cycle.
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 2 (dfromList [1,2,3,4,5])
--   [1,2]
--   </pre>
--   
--   <b>NB</b>: This function is not synthesisable
dfromList_lazy :: [a] -> DSignal domain 0 a

-- | <b>EXPERIMENTAL</b>
--   
--   <b>Unsafely</b> convert a <a>Signal</a> to <i>any</i> <a>DSignal</a>
--   clk'.
--   
--   <b>NB</b>: Should only be used to interface with functions specified
--   in terms of <a>Signal</a>.
unsafeFromSignal :: Signal domain a -> DSignal domain n a

-- | <b>EXPERIMENTAL</b>
--   
--   Access a <i>delayed</i> signal in the present.
--   
--   <pre>
--   mac :: Clock domain gated -&gt; Reset domain synchronous
--       -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int -&gt; <a>DSignal</a> domain 0 Int
--   mac clk rst x y = acc'
--     where
--       acc' = (x * y) + <a>antiDelay</a> d1 acc
--       acc  = <tt>delay</tt> clk rst (<a>singleton</a> 0) acc'
--   </pre>
antiDelay :: SNat d -> DSignal domain (n + d) a -> DSignal domain n a


module Clash.Explicit.Testbench

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third
--   <tt>Signal'</tt> unaltered as its result. This function is used by
--   <a>outputVerifier</a>.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (Eq a, ShowX a) => Clock domain gated -> Reset domain synchronous -> String -> Signal domain a -> Signal domain a -> Signal domain b -> Signal domain b

-- | To be used as one of the functions to create the "magical"
--   <tt>testInput</tt> value, which the CλaSH compiler looks for to create
--   the stimulus generator for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   testInput
--     :: Clock domain gated -&gt; Reset domain synchronous
--     -&gt; <a>Signal</a> domain Int
--   testInput clk rst = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 13 (testInput systemClockGen systemResetGen)
--   [1,3,5,7,9,11,13,15,17,19,21,21,21]
--   </pre>
stimuliGenerator :: forall l domain gated synchronous a. KnownNat l => Clock domain gated -> Reset domain synchronous -> Vec l a -> Signal domain a

-- | To be used as one of the functions to generate the "magical"
--   <tt>expectedOutput</tt> function, which the CλaSH compiler looks for
--   to create the signal verifier for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   expectedOutput
--     :: Clock domain gated -&gt; Reset domain synchronous
--     -&gt; <a>Signal</a> domain Int -&gt; <a>Signal</a> domain Bool
--   expectedOutput clk rst = <a>outputVerifier</a> clk rst $(<a>listToVecTH</a> ([70,99,2,3,4,5,7,8,9,10]::[Int]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; sampleN 12 (expectedOutput systemClockGen systemResetGen (fromList ([0..10] List.++ [10,10,10])))
--   
--   cycle(system10000): 0, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   [False
--   cycle(system10000): 1, outputVerifier
--   expected value: 99, not equal to actual value: 1
--   ,False,False,False,False,False
--   cycle(system10000): 6, outputVerifier
--   expected value: 7, not equal to actual value: 6
--   ,False
--   cycle(system10000): 7, outputVerifier
--   expected value: 8, not equal to actual value: 7
--   ,False
--   cycle(system10000): 8, outputVerifier
--   expected value: 9, not equal to actual value: 8
--   ,False
--   cycle(system10000): 9, outputVerifier
--   expected value: 10, not equal to actual value: 9
--   ,False,True,True]
--   </pre>
outputVerifier :: forall l domain gated synchronous a. (KnownNat l, Eq a, ShowX a) => Clock domain gated -> Reset domain synchronous -> Vec l a -> Signal domain a -> Signal domain Bool


module Clash.Prelude.Testbench

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third <a>Signal</a>
--   unaltered as its result. This function is used by
--   <a>outputVerifier</a>.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (Eq a, ShowX a, HiddenClockReset domain gated synchronous) => String -> Signal domain a -> Signal domain a -> Signal domain b -> Signal domain b

-- | To be used as one of the functions to create the "magical"
--   <tt>testInput</tt> value, which the CλaSH compiler looks for to create
--   the stimulus generator for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   testInput
--     :: HiddenClockReset domain gated synchronous
--     =&gt; <a>Signal</a> domain Int
--   testInput = <a>stimuliGenerator</a> $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 13 testInput
--   [1,3,5,7,9,11,13,15,17,19,21,21,21]
--   </pre>
stimuliGenerator :: (KnownNat l, HiddenClockReset domain gated synchronous) => Vec l a -> Signal domain a

-- | To be used as one of the functions to generate the "magical"
--   <tt>expectedOutput</tt> function, which the CλaSH compiler looks for
--   to create the signal verifier for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   expectedOutput
--     :: HiddenClockReset domain gated synchronous
--     -&gt; <a>Signal</a> domain Int -&gt; <a>Signal</a> domain Bool
--   expectedOutput = <a>outputVerifier</a> $(<a>listToVecTH</a> ([70,99,2,3,4,5,7,8,9,10]::[Int]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; sampleN 12 (expectedOutput (fromList ([0..10] List.++ [10,10,10])))
--   
--   cycle(system10000): 0, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   [False
--   cycle(system10000): 1, outputVerifier
--   expected value: 99, not equal to actual value: 1
--   ,False,False,False,False,False
--   cycle(system10000): 6, outputVerifier
--   expected value: 7, not equal to actual value: 6
--   ,False
--   cycle(system10000): 7, outputVerifier
--   expected value: 8, not equal to actual value: 7
--   ,False
--   cycle(system10000): 8, outputVerifier
--   expected value: 9, not equal to actual value: 8
--   ,False
--   cycle(system10000): 9, outputVerifier
--   expected value: 10, not equal to actual value: 9
--   ,False,True,True]
--   </pre>
outputVerifier :: (KnownNat l, Eq a, ShowX a, HiddenClockReset domain gated synchronous) => Vec l a -> Signal domain a -> Signal domain Bool


-- | RAM primitives with a combinational read port.
module Clash.Explicit.RAM

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom wgated rgated n a. (KnownNat n, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | RAM primitive
asyncRam# :: HasCallStack => Clock wdom wgated -> Clock rdom rgated -> SNat n -> Signal rdom Int -> Signal wdom Bool -> Signal wdom Int -> Signal wdom a -> Signal rdom a


-- | RAM primitives with a combinational read port.
module Clash.Prelude.RAM

-- | Create a RAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => SNat n -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a


-- | Synchronizer circuits for safe clock domain crossings
module Clash.Explicit.Synchronizer

-- | Synchroniser based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchroniser can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchroniser does reduce metastability,
--   it does not guarantee the proper synchronisation of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronisation use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: Clock domain1 gated1 -> Clock domain2 gated2 -> Reset domain2 synchronous -> a -> Signal domain1 a -> Signal domain2 a

-- | Synchroniser implemented as a FIFO around an asynchronous RAM. Based
--   on the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   
--   <b>NB</b>: This synchroniser can be used for
--   <b>word</b>-synchronization.
asyncFIFOSynchronizer :: (2 <= addrSize) => SNat addrSize -> Clock wdomain wgated -> Clock rdomain rgated -> Reset wdomain synchronous -> Reset rdomain synchronous -> Signal rdomain Bool -> Signal wdomain (Maybe a) -> (Signal rdomain a, Signal rdomain Bool, Signal wdomain Bool)


-- | <h1>Initialising a BlockRAM with a data file </h1>
--   
--   BlockRAM primitives that can be initialised with a data file. The BNF
--   grammar for this data file is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned number <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   We can instantiate a BlockRAM using the content of the above file like
--   so:
--   
--   <pre>
--   f
--     :: Clock  domain gated
--     -&gt; Signal domain (Unsigned 3)
--     -&gt; Signal domain (Unsigned 9)
--   f clk rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> clk d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   In the example above, we basically treat the BlockRAM as an
--   synchronous ROM. We can see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f systemClockGen (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g
--     :: Clock  domain Source
--     -&gt; Signal domain (Unsigned 3)
--     -&gt; Signal domain (Unsigned 6,Signed 3)
--   g clk rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>blockRamFile</a> clk d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g systemClockGen (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Explicit.BlockRam.File

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFile' clk size file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, HasCallStack) => Clock dom gated -> SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFilePow2' clk file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Explicit.Fixed#creatingdatafiles</a> for ideas on how
--   to create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom gated n m. (KnownNat m, KnownNat n, HasCallStack) => Clock dom gated -> FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | blockRamFile primitive
blockRamFile# :: (KnownNat m, HasCallStack) => Clock dom gated -> SNat n -> FilePath -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom (BitVector m) -> Signal dom (BitVector m)

-- | <b>NB:</b> Not synthesisable
initMem :: KnownNat n => FilePath -> IO [BitVector n]


-- | <h1>Initialising a BlockRAM with a data file </h1>
--   
--   BlockRAM primitives that can be initialised with a data file. The BNF
--   grammar for this data file is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned number <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   We can instantiate a BlockRAM using the content of the above file like
--   so:
--   
--   <pre>
--   f :: HiddenClock domain -&gt; Signal domain (Unsigned 3) -&gt; Signal domain (Unsigned 9)
--   f rd = <a>unpack</a> <a>&lt;$&gt;</a> exposeClock <a>blockRamFile</a> clk d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   In the example above, we basically treat the BlockRAM as an
--   synchronous ROM. We can see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: HiddenClock domain -&gt; Signal domain (Unsigned 3) -&gt; Signal domain (Unsigned 6,Signed 3)
--   g clk rd = <a>unpack</a> <a>&lt;$&gt;</a> exposeClock <a>blockRamFile</a> clk d7 "memory.bin" rd (signal Nothing)
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Prelude.BlockRam.File

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFile' clk size file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, HiddenClock domain gated, HasCallStack) => SNat n -> FilePath -> Signal domain addr -> Signal domain (Maybe (addr, BitVector m)) -> Signal domain (BitVector m)

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFilePow2' clk file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall domain gated n m. (KnownNat m, KnownNat n, HiddenClock domain gated, HasCallStack) => FilePath -> Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, BitVector m)) -> Signal domain (BitVector m)


-- | <h1>Initialising a ROM with a data file </h1>
--   
--   ROMs initialised with a data file. The BNF grammar for this data file
--   is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned number <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   We can instantiate a synchronous ROM using the content of the above
--   file like so:
--   
--   <pre>
--   f
--     :: Clock  domain gated
--     -&gt; Signal domain (Unsigned 3)
--     -&gt; Signal domain (Unsigned 9)
--   f clk rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> clk d7 "memory.bin" rd
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f systemClockGen (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g
--     :: Clock  domain Source
--     -&gt; Signal domain (Unsigned 3)
--     -&gt; Signal domain (Unsigned 6,Signed 3)
--   g clk rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> clk d7 "memory.bin" rd
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g systemClockGen (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Explicit.ROM.File

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, Enum addr) => Clock domain gated -> SNat n -> FilePath -> Signal domain addr -> Signal domain (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall domain gated n m. (KnownNat m, KnownNat n) => Clock domain gated -> FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | romFile primitive
romFile# :: KnownNat m => Clock domain gated -> SNat n -> FilePath -> Signal domain Int -> Signal domain (BitVector m)


-- | <h1>Initialising a ROM with a data file </h1>
--   
--   ROMs initialised with a data file. The BNF grammar for this data file
--   is simple:
--   
--   <pre>
--   FILE = LINE+
--   LINE = BIT+
--   BIT  = '0'
--        | '1'
--   </pre>
--   
--   Consecutive <tt>LINE</tt>s correspond to consecutive memory addresses
--   starting at <tt>0</tt>. For example, a data file <tt>memory.bin</tt>
--   containing the 9-bit unsigned number <tt>7</tt> to <tt>13</tt> looks
--   like:
--   
--   <pre>
--   000000111
--   000001000
--   000001001
--   000001010
--   000001011
--   000001100
--   000001101
--   </pre>
--   
--   We can instantiate a synchronous ROM using the content of the above
--   file like so:
--   
--   <pre>
--   f :: HiddenClock domain =&gt; Signal domain (Unsigned 3) -&gt; Signal domain (Unsigned 9)
--   f rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> d7 "memory.bin" rd
--   </pre>
--   
--   And see that it works as expected:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ f (fromList [3..5])</b>
--   [10,11,12]
--   </pre>
--   
--   However, we can also interpret the same data as a tuple of a 6-bit
--   unsigned number, and a 3-bit signed number:
--   
--   <pre>
--   g :: HiddenClock domain =&gt; Signal domain (Unsigned 3) -&gt; Signal domain (Unsigned 6,Signed 3)
--   g rd = <a>unpack</a> <a>&lt;$&gt;</a> <a>romFile</a> d7 "memory.bin" rd
--   </pre>
--   
--   And then we would see:
--   
--   <pre>
--   <b>&gt;&gt;&gt; import qualified Data.List as L</b>
--   <b>&gt;&gt;&gt; L.tail $ sampleN 4 $ g (fromList [3..5])</b>
--   [(1,2),(1,3)(1,-4)]
--   </pre>
module Clash.Prelude.ROM.File

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, KnownNat n, HiddenClock domain gated) => SNat n -> FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall n m domain gated. (KnownNat m, KnownNat n, HiddenClock domain gated) => FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | asyncROMFile primitive
asyncRomFile# :: KnownNat m => SNat n -> FilePath -> Int -> BitVector m


-- | BlockRAM primitives
--   
--   <h1>Using RAMs </h1>
--   
--   We will show a rather elaborate example on how you can, and why you
--   might want to use <a>blockRam</a>s. We will build a "small"
--   CPU+Memory+Program ROM where we will slowly evolve to using blockRams.
--   Note that the code is <i>not</i> meant as a de-facto standard on how
--   to do CPU design in CλaSH.
--   
--   We start with the definition of the Instructions, Register names and
--   machine codes:
--   
--   <pre>
--   {-# LANGUAGE RecordWildCards, TupleSections #-}
--   module CPU where
--   
--   import Clash.Explicit.Prelude
--   
--   type InstrAddr = Unsigned 8
--   type MemAddr   = Unsigned 5
--   type Value     = Signed 8
--   
--   data Instruction
--     = Compute Operator Reg Reg Reg
--     | Branch Reg Value
--     | Jump Value
--     | Load MemAddr Reg
--     | Store Reg MemAddr
--     | Nop
--     deriving (Eq,Show)
--   
--   data Reg
--     = Zero
--     | PC
--     | RegA
--     | RegB
--     | RegC
--     | RegD
--     | RegE
--     deriving (Eq,Show,Enum)
--   
--   data Operator = Add | Sub | Incr | Imm | CmpGt
--     deriving (Eq,Show)
--   
--   data MachCode
--     = MachCode
--     { inputX  :: Reg
--     , inputY  :: Reg
--     , result  :: Reg
--     , aluCode :: Operator
--     , ldReg   :: Reg
--     , rdAddr  :: MemAddr
--     , wrAddrM :: Maybe MemAddr
--     , jmpM    :: Maybe Value
--     }
--   
--   nullCode = MachCode { inputX = Zero, inputY = Zero, result = Zero, aluCode = Imm
--                       , ldReg = Zero, rdAddr = 0, wrAddrM = Nothing
--                       , jmpM = Nothing
--                       }
--   </pre>
--   
--   Next we define the CPU and its ALU:
--   
--   <pre>
--   cpu
--     :: Vec 7 Value
--     -- ^ Register bank
--     -&gt; (Value,Instruction)
--     -- ^ (Memory output, Current instruction)
--     -&gt; ( Vec 7 Value
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <a>&lt;$&gt;</a> wrAddrM,fromIntegral ipntr))
--     where
--       -- Current instruction pointer
--       ipntr = regbank <a>!!</a> PC
--   
--       -- Decoder
--       (MachCode {..}) = case instr of
--         Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--         Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--         Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--         Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--         Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--         Nop                  -&gt; nullCode
--   
--       -- ALU
--       regX   = regbank <a>!!</a> inputX
--       regY   = regbank <a>!!</a> inputY
--       aluOut = alu aluCode regX regY
--   
--       -- next instruction
--       nextPC = case jmpM of
--                  Just a | aluOut /= 0 -&gt; ipntr + a
--                  _                    -&gt; ipntr + 1
--   
--       -- update registers
--       regbank' = <tt>replace</tt> Zero   0
--                $ <tt>replace</tt> PC     nextPC
--                $ <tt>replace</tt> result aluOut
--                $ <tt>replace</tt> ldReg  memOut
--                $ regbank
--   
--   alu Add   x y = x + y
--   alu Sub   x y = x - y
--   alu Incr  x _ = x + 1
--   alu Imm   x _ = x
--   alu CmpGt x y = if x &gt; y then 1 else 0
--   </pre>
--   
--   We initially create a memory out of simple registers:
--   
--   <pre>
--   dataMem
--     :: Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; Signal domain MemAddr
--     -- ^ Read address
--     -&gt; Signal domain (Maybe (MemAddr,Value))
--     -- ^ (write address, data in)
--     -&gt; Signal domain Value
--     -- ^ data out
--   dataMem clk rst rd wrM = <a>mealy</a> clk rst dataMemT (<a>replicate</a> d32 0) (bundle (rd,wrM))
--     where
--       dataMemT mem (rd,wrM) = (mem',dout)
--         where
--           dout = mem <a>!!</a> rd
--           mem' = case wrM of
--                    Just (wr,din) -&gt; <tt>replace</tt> wr din mem
--                    _ -&gt; mem
--   </pre>
--   
--   And then connect everything:
--   
--   <pre>
--   system
--     :: KnownNat n
--     =&gt; Vec n Instruction
--     -&gt; Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; Signal domain Value
--   system instrs clk rst = memOut
--     where
--       memOut = dataMem clk rst rdAddr dout
--       (rdAddr,dout,ipntr) = <a>mealyB</a> clk rst cpu (<a>replicate</a> d7 0) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Create a simple program that calculates the GCD of 4 and 6:
--   
--   <pre>
--   -- Compute GCD of 4 and 6
--   prog = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   And test our system:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 31 $ system prog systemClockGen systemResetGen
--   [0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   to see that our system indeed calculates that the GCD of 6 and 4 is 2.
--   
--   <h3>Improvement 1: using <tt>asyncRam</tt></h3>
--   
--   As you can see, it's fairly straightforward to build a memory using
--   registers and read (<a>!!</a>) and write (<tt>replace</tt>) logic.
--   This might however not result in the most efficient hardware
--   structure, especially when building an ASIC.
--   
--   Instead it is preferable to use the <a>asyncRam</a> function which has
--   the potential to be translated to a more efficient structure:
--   
--   <pre>
--   system2
--     :: KnownNat n
--     =&gt; Vec n Instruction
--     -&gt; Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; Signal domain Value
--   system2 instrs clk rst = memOut
--     where
--       memOut = <a>asyncRam</a> clk clk d32 rdAddr dout
--       (rdAddr,dout,ipntr) = <tt>mealyB</tt> clk rst cpu (<a>replicate</a> d7 0) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Again, we can simulate our system and see that it works. This time
--   however, we need to disregard the first few output samples, because
--   the initial content of an <a>asyncRam</a> is <a>undefined</a>, and
--   consequently, the first few output samples are also <a>undefined</a>.
--   We use the utility function <tt>printX</tt> to conveniently filter out
--   the undefinedness and replace it with the string <a>X</a> in the few
--   leading outputs.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 31 $ system2 prog systemClockGen systemResetGen
--   [X,X,X,X,X,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   <h3>Improvement 2: using <tt>blockRam</tt></h3>
--   
--   Finally we get to using <a>blockRam</a>. On FPGAs, <a>asyncRam</a>
--   will be implemented in terms of LUTs, and therefore take up logic
--   resources. FPGAs also have large(r) memory structures called <i>Block
--   RAMs</i>, which are preferred, especially as the memories we need for
--   our application get bigger. The <a>blockRam</a> function will be
--   translated to such a <i>Block RAM</i>.
--   
--   One important aspect of Block RAMs have a <i>synchronous</i> read
--   port, meaning that, unlike the behaviour of <a>asyncRam</a>, given a
--   read address <tt>r</tt> at time <tt>t</tt>, the value <tt>v</tt> in
--   the RAM at address <tt>r</tt> is only available at time <tt>t+1</tt>.
--   
--   For us that means we need to change the design of our CPU. Right now,
--   upon a load instruction we generate a read address for the memory, and
--   the value at that read address is immediately available to be put in
--   the register bank. Because we will be using a BlockRAM, the value is
--   delayed until the next cycle. We hence need to also delay the register
--   address to which the memory address is loaded:
--   
--   <pre>
--   cpu2
--     :: (Vec 7 Value,Reg)
--     -- ^ (Register bank, Load reg addr)
--     -&gt; (Value,Instruction)
--     -- ^ (Memory output, Current instruction)
--     -&gt; ( (Vec 7 Value,Reg)
--        , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--        )
--   cpu2 (regbank,ldRegD) (memOut,instr) = ((regbank',ldRegD'),(rdAddr,(,aluOut) <a>&lt;$&gt;</a> wrAddrM,fromIntegral ipntr))
--     where
--       -- Current instruction pointer
--       ipntr = regbank <a>!!</a> PC
--   
--       -- Decoder
--       (MachCode {..}) = case instr of
--         Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--         Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--         Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--         Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--         Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--         Nop                  -&gt; nullCode
--   
--       -- ALU
--       regX   = regbank <a>!!</a> inputX
--       regY   = regbank <a>!!</a> inputY
--       aluOut = alu aluCode regX regY
--   
--       -- next instruction
--       nextPC = case jmpM of
--                  Just a | aluOut /= 0 -&gt; ipntr + a
--                  _                    -&gt; ipntr + 1
--   
--       -- update registers
--       ldRegD'  = ldReg -- Delay the ldReg by 1 cycle
--       regbank' = <tt>replace</tt> Zero   0
--                $ <tt>replace</tt> PC     nextPC
--                $ <tt>replace</tt> result aluOut
--                $ <tt>replace</tt> ldRegD memOut
--                $ regbank
--   </pre>
--   
--   We can now finally instantiate our system with a <a>blockRam</a>:
--   
--   <pre>
--   system3
--     :: KnownNat n
--     =&gt; Vec n Instruction
--     -&gt; Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; Signal domain Value
--   system3 instrs clk rst = memOut
--     where
--       memOut = <a>blockRam</a> clk (replicate d32 0) rdAddr dout
--       (rdAddr,dout,ipntr) = <tt>mealyB</tt> clk rst cpu2 ((<a>replicate</a> d7 0),Zero) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   We are, however, not done. We will also need to update our program.
--   The reason being that values that we try to load in our registers
--   won't be loaded into the register until the next cycle. This is a
--   problem when the next instruction immediately depended on this memory
--   value. In our case, this was only the case when the loaded the value
--   <tt>6</tt>, which was stored at address <tt>1</tt>, into
--   <tt>RegB</tt>. Our updated program is thus:
--   
--   <pre>
--   prog2 = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          Nop :&gt; -- Extra NOP
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   When we simulate our system we see that it works. This time again, we
--   need to disregard the first sample, because the initial output of a
--   <a>blockRam</a> is <a>undefined</a>. We use the utility function
--   <tt>printX</tt> to conveniently filter out the undefinedness and
--   replace it with the string <a>X</a>.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 33 $ system3 prog2 systemClockGen systemResetGen
--   [X,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   This concludes the short introduction to using <a>blockRam</a>.
module Clash.Explicit.BlockRam

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40 :: <a>Clock</a>  domain gated
--          -&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 clk = <a>blockRam</a> clk (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRam</a> clk
--   inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: HasCallStack => Enum addr => Clock dom gated -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32 :: <a>Signal</a> domain (<a>Unsigned</a> 5)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 clk = <a>blockRamPow2</a> clk (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRamPow2</a>
--   clk inits) rd wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HasCallStack) => Clock dom gated -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create read-after-write blockRAM from a read-before-write one
readNew :: Eq addr => Reset domain synchronous -> Clock domain gated -> (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | blockRAM primitive
blockRam# :: HasCallStack => Clock dom gated -> Vec n a -> Signal dom Int -> Signal dom Bool -> Signal dom Int -> Signal dom a -> Signal dom a


-- | BlockRAM primitives
--   
--   <h1>Using RAMs </h1>
--   
--   We will show a rather elaborate example on how you can, and why you
--   might want to use <a>blockRam</a>s. We will build a "small"
--   CPU+Memory+Program ROM where we will slowly evolve to using blockRams.
--   Note that the code is <i>not</i> meant as a de-facto standard on how
--   to do CPU design in CλaSH.
--   
--   We start with the definition of the Instructions, Register names and
--   machine codes:
--   
--   <pre>
--   {-# LANGUAGE RecordWildCards, TupleSections #-}
--   module CPU where
--   
--   import Clash.Prelude
--   
--   type InstrAddr = Unsigned 8
--   type MemAddr   = Unsigned 5
--   type Value     = Signed 8
--   
--   data Instruction
--     = Compute Operator Reg Reg Reg
--     | Branch Reg Value
--     | Jump Value
--     | Load MemAddr Reg
--     | Store Reg MemAddr
--     | Nop
--     deriving (Eq,Show)
--   
--   data Reg
--     = Zero
--     | PC
--     | RegA
--     | RegB
--     | RegC
--     | RegD
--     | RegE
--     deriving (Eq,Show,Enum)
--   
--   data Operator = Add | Sub | Incr | Imm | CmpGt
--     deriving (Eq,Show)
--   
--   data MachCode
--     = MachCode
--     { inputX  :: Reg
--     , inputY  :: Reg
--     , result  :: Reg
--     , aluCode :: Operator
--     , ldReg   :: Reg
--     , rdAddr  :: MemAddr
--     , wrAddrM :: Maybe MemAddr
--     , jmpM    :: Maybe Value
--     }
--   
--   nullCode = MachCode { inputX = Zero, inputY = Zero, result = Zero, aluCode = Imm
--                       , ldReg = Zero, rdAddr = 0, wrAddrM = Nothing
--                       , jmpM = Nothing
--                       }
--   </pre>
--   
--   Next we define the CPU and its ALU:
--   
--   <pre>
--   cpu :: Vec 7 Value          -- ^ Register bank
--       -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--       -&gt; ( Vec 7 Value
--          , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--          )
--   cpu regbank (memOut,instr) = (regbank',(rdAddr,(,aluOut) <a>&lt;$&gt;</a> wrAddrM,fromIntegral ipntr))
--     where
--       -- Current instruction pointer
--       ipntr = regbank <a>!!</a> PC
--   
--       -- Decoder
--       (MachCode {..}) = case instr of
--         Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--         Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--         Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--         Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--         Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--         Nop                  -&gt; nullCode
--   
--       -- ALU
--       regX   = regbank <a>!!</a> inputX
--       regY   = regbank <a>!!</a> inputY
--       aluOut = alu aluCode regX regY
--   
--       -- next instruction
--       nextPC = case jmpM of
--                  Just a | aluOut /= 0 -&gt; ipntr + a
--                  _                    -&gt; ipntr + 1
--   
--       -- update registers
--       regbank' = <tt>replace</tt> Zero   0
--                $ <tt>replace</tt> PC     nextPC
--                $ <tt>replace</tt> result aluOut
--                $ <tt>replace</tt> ldReg  memOut
--                $ regbank
--   
--   alu Add   x y = x + y
--   alu Sub   x y = x - y
--   alu Incr  x _ = x + 1
--   alu Imm   x _ = x
--   alu CmpGt x y = if x &gt; y then 1 else 0
--   </pre>
--   
--   We initially create a memory out of simple registers:
--   
--   <pre>
--   dataMem :: HiddenClockReset domain gated synchronous
--           =&gt; Signal domain MemAddr                 -- ^ Read address
--           -&gt; Signal domain (Maybe (MemAddr,Value)) -- ^ (write address, data in)
--           -&gt; Signal domain Value                   -- ^ data out
--   dataMem rd wrM = <a>mealy</a> dataMemT (<a>replicate</a> d32 0) (bundle (rd,wrM))
--     where
--       dataMemT mem (rd,wrM) = (mem',dout)
--         where
--           dout = mem <a>!!</a> rd
--           mem' = case wrM of
--                    Just (wr,din) -&gt; <tt>replace</tt> wr din mem
--                    _ -&gt; mem
--   </pre>
--   
--   And then connect everything:
--   
--   <pre>
--   system :: (KnownNat n, HiddenClockReset domain gated synchronous) =&gt; Vec n Instruction -&gt; Signal domain Value
--   system instrs = memOut
--     where
--       memOut = dataMem rdAddr dout
--       (rdAddr,dout,ipntr) = <a>mealyB</a> cpu (<a>replicate</a> d7 0) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Create a simple program that calculates the GCD of 4 and 6:
--   
--   <pre>
--   -- Compute GCD of 4 and 6
--   prog = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   And test our system:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 31 (system prog)
--   [0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   to see that our system indeed calculates that the GCD of 6 and 4 is 2.
--   
--   <h3>Improvement 1: using <tt>asyncRam</tt></h3>
--   
--   As you can see, it's fairly straightforward to build a memory using
--   registers and read (<a>!!</a>) and write (<tt>replace</tt>) logic.
--   This might however not result in the most efficient hardware
--   structure, especially when building an ASIC.
--   
--   Instead it is preferable to use the <a>asyncRam</a> function which has
--   the potential to be translated to a more efficient structure:
--   
--   <pre>
--   system2 :: (KnownNat n, HiddenClockReset domain gated synchronous) =&gt; Vec n Instruction -&gt; Signal domain Value
--   system2 instrs = memOut
--     where
--       memOut = <a>asyncRam</a> d32 rdAddr dout
--       (rdAddr,dout,ipntr) = <tt>mealyB</tt> cpu (<a>replicate</a> d7 0) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   Again, we can simulate our system and see that it works. This time
--   however, we need to disregard the first few output samples, because
--   the initial content of an <a>asyncRam</a> is <a>undefined</a>, and
--   consequently, the first few output samples are also <a>undefined</a>.
--   We use the utility function <tt>printX</tt> to conveniently filter out
--   the undefinedness and replace it with the string <a>X</a> in the few
--   leading outputs.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 31 (system2 prog)
--   [X,X,X,X,X,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   <h3>Improvement 2: using <tt>blockRam</tt></h3>
--   
--   Finally we get to using <a>blockRam</a>. On FPGAs, <a>asyncRam</a>
--   will be implemented in terms of LUTs, and therefore take up logic
--   resources. FPGAs also have large(r) memory structures called <i>Block
--   RAMs</i>, which are preferred, especially as the memories we need for
--   our application get bigger. The <a>blockRam</a> function will be
--   translated to such a <i>Block RAM</i>.
--   
--   One important aspect of Block RAMs have a <i>synchronous</i> read
--   port, meaning that, unlike the behaviour of <a>asyncRam</a>, given a
--   read address <tt>r</tt> at time <tt>t</tt>, the value <tt>v</tt> in
--   the RAM at address <tt>r</tt> is only available at time <tt>t+1</tt>.
--   
--   For us that means we need to change the design of our CPU. Right now,
--   upon a load instruction we generate a read address for the memory, and
--   the value at that read address is immediately available to be put in
--   the register bank. Because we will be using a BlockRAM, the value is
--   delayed until the next cycle. We hence need to also delay the register
--   address to which the memory address is loaded:
--   
--   <pre>
--   cpu2 :: (Vec 7 Value,Reg)    -- ^ (Register bank, Load reg addr)
--        -&gt; (Value,Instruction)  -- ^ (Memory output, Current instruction)
--        -&gt; ( (Vec 7 Value,Reg)
--           , (MemAddr, Maybe (MemAddr,Value), InstrAddr)
--           )
--   cpu2 (regbank,ldRegD) (memOut,instr) = ((regbank',ldRegD'),(rdAddr,(,aluOut) <a>&lt;$&gt;</a> wrAddrM,fromIntegral ipntr))
--     where
--       -- Current instruction pointer
--       ipntr = regbank <a>!!</a> PC
--   
--       -- Decoder
--       (MachCode {..}) = case instr of
--         Compute op rx ry res -&gt; nullCode {inputX=rx,inputY=ry,result=res,aluCode=op}
--         Branch cr a          -&gt; nullCode {inputX=cr,jmpM=Just a}
--         Jump a               -&gt; nullCode {aluCode=Incr,jmpM=Just a}
--         Load a r             -&gt; nullCode {ldReg=r,rdAddr=a}
--         Store r a            -&gt; nullCode {inputX=r,wrAddrM=Just a}
--         Nop                  -&gt; nullCode
--   
--       -- ALU
--       regX   = regbank <a>!!</a> inputX
--       regY   = regbank <a>!!</a> inputY
--       aluOut = alu aluCode regX regY
--   
--       -- next instruction
--       nextPC = case jmpM of
--                  Just a | aluOut /= 0 -&gt; ipntr + a
--                  _                    -&gt; ipntr + 1
--   
--       -- update registers
--       ldRegD'  = ldReg -- Delay the ldReg by 1 cycle
--       regbank' = <tt>replace</tt> Zero   0
--                $ <tt>replace</tt> PC     nextPC
--                $ <tt>replace</tt> result aluOut
--                $ <tt>replace</tt> ldRegD memOut
--                $ regbank
--   </pre>
--   
--   We can now finally instantiate our system with a <a>blockRam</a>:
--   
--   <pre>
--   system3 :: (KnownNat n, HiddenClockReset domain gated synchronous) =&gt; Vec n Instruction -&gt; Signal domain Value
--   system3 instrs = memOut
--     where
--       memOut = <a>blockRam</a> (replicate d32 0) rdAddr dout
--       (rdAddr,dout,ipntr) = <tt>mealyB</tt> cpu2 ((<a>replicate</a> d7 0),Zero) (memOut,instr)
--       instr  = <a>asyncRom</a> instrs <a>&lt;$&gt;</a> ipntr
--   </pre>
--   
--   We are, however, not done. We will also need to update our program.
--   The reason being that values that we try to load in our registers
--   won't be loaded into the register until the next cycle. This is a
--   problem when the next instruction immediately depended on this memory
--   value. In our case, this was only the case when the loaded the value
--   <tt>6</tt>, which was stored at address <tt>1</tt>, into
--   <tt>RegB</tt>. Our updated program is thus:
--   
--   <pre>
--   prog2 = -- 0 := 4
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d3 (Compute Incr RegA Zero RegA) ++
--          Store RegA 0 :&gt;
--          -- 1 := 6
--          Compute Incr Zero RegA RegA :&gt;
--          replicate d5 (Compute Incr RegA Zero RegA) ++
--          Store RegA 1 :&gt;
--          -- A := 4
--          Load 0 RegA :&gt;
--          -- B := 6
--          Load 1 RegB :&gt;
--          Nop :&gt; -- Extra NOP
--          -- start
--          Compute CmpGt RegA RegB RegC :&gt;
--          Branch RegC 4 :&gt;
--          Compute CmpGt RegB RegA RegC :&gt;
--          Branch RegC 4 :&gt;
--          Jump 5 :&gt;
--          -- (a &gt; b)
--          Compute Sub RegA RegB RegA :&gt;
--          Jump (-6) :&gt;
--          -- (b &gt; a)
--          Compute Sub RegB RegA RegB :&gt;
--          Jump (-8) :&gt;
--          -- end
--          Store RegA 2 :&gt;
--          Load 2 RegC :&gt;
--          Nil
--   </pre>
--   
--   When we simulate our system we see that it works. This time again, we
--   need to disregard the first sample, because the initial output of a
--   <a>blockRam</a> is <a>undefined</a>. We use the utility function
--   <tt>printX</tt> to conveniently filter out the undefinedness and
--   replace it with the string <a>X</a>.
--   
--   <pre>
--   &gt;&gt;&gt; printX $ sampleN 33 (system3 prog2)
--   [X,0,0,0,0,0,4,4,4,4,4,4,4,4,6,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,2]
--   </pre>
--   
--   This concludes the short introduction to using <a>blockRam</a>.
module Clash.Prelude.BlockRam

-- | Create a blockRAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRam inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => Vec n a -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRamPow2 inits) rd
--   wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a

-- | Create read-after-write blockRAM from a read-before-write one
--   (synchronised to system clock)
--   
--   <pre>
--   &gt;&gt;&gt; import Clash.Prelude
--   
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ... =&gt;
--        Signal domain addr
--        -&gt; Signal domain (Maybe (addr, a)) -&gt; Signal domain a
--   </pre>
readNew :: (Eq addr, HiddenClockReset domain gated synchronous) => (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a


-- | <b>This is the <a>Safe</a> API only of
--   <a>Clash.Explicit.Prelude</a></b>
--   
--   This module defines the explicitly clocked counterparts of the
--   functions defined in <a>Clash.Prelude</a>. Take a look at
--   <a>Clash.Signal.Explicit</a> to see how you can make multi-clock
--   designs.
module Clash.Explicit.Prelude.Safe

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>Clock</a> domain Source
--     -&gt; <a>Reset</a> domain Asynchronous
--     -&gt; <a>Signal</a> domain (Int, Int)
--     -&gt; <a>Signal</a> domain Int
--   mac clk rst = <a>mealy</a> clk rst macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>Clock</a> domain gated -&gt; <a>Reset</a> domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Signal dom i -> Signal dom o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <tt>mealy'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mealyB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o) => Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Unbundled dom i -> Unbundled dom o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>Clock</a> mac Source
--     -&gt; <a>Reset</a> mac Asynchronous
--     -&gt; <a>Signal</a> mac (Int, Int)
--     -&gt; <a>Signal</a> mac Int
--   mac clk rst = <a>moore</a> clk rst macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <tt>moore'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mooreB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o) => Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   <tt>(<a>Signal</a> a, <a>Signal</a> b)</tt>)
--   
--   <pre>
--   rP :: Clock domain gated -&gt; Reset domain synchronous
--      -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--      -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--   rP clk rst = <a>registerB</a> clk rst (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (rP systemClockGen systemResetGen) [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: Bundle a => Clock domain gated -> Reset domain synchronous -> a -> Unbundled domain a -> Unbundled domain a

-- | Synchroniser based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchroniser can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchroniser does reduce metastability,
--   it does not guarantee the proper synchronisation of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronisation use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: Clock domain1 gated1 -> Clock domain2 gated2 -> Reset domain2 synchronous -> a -> Signal domain1 a -> Signal domain2 a

-- | Synchroniser implemented as a FIFO around an asynchronous RAM. Based
--   on the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   
--   <b>NB</b>: This synchroniser can be used for
--   <b>word</b>-synchronization.
asyncFIFOSynchronizer :: (2 <= addrSize) => SNat addrSize -> Clock wdomain wgated -> Clock rdomain rgated -> Reset wdomain synchronous -> Reset rdomain synchronous -> Signal rdomain Bool -> Signal wdomain (Maybe a) -> (Signal rdomain a, Signal rdomain Bool, Signal wdomain Bool)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRomPow2 :: KnownNat n => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, Enum addr) => Clock domain gated -> Vec n a -> Signal domain addr -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: KnownNat n => Clock domain gated -> Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom wgated rgated n a. (KnownNat n, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40 :: <a>Clock</a>  domain gated
--          -&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 clk = <a>blockRam</a> clk (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRam</a> clk
--   inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: HasCallStack => Enum addr => Clock dom gated -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32 :: <a>Signal</a> domain (<a>Unsigned</a> 5)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 clk = <a>blockRamPow2</a> clk (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRamPow2</a>
--   clk inits) rd wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HasCallStack) => Clock dom gated -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create read-after-write blockRAM from a read-before-write one
readNew :: Eq addr => Reset domain synchronous -> Clock domain gated -> (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (Bounded a, Eq a) => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (Bounded a, Eq a) => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
riseEvery :: forall domain gated synchronous n. Clock domain gated -> Reset domain synchronous -> SNat n -> Signal domain Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles, given
--   the starting state.
oscillate :: forall domain gated synchronous n. Clock domain gated -> Reset domain synchronous -> Bool -> SNat n -> Signal domain Bool
undefined :: HasCallStack => a

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: () => a -> b -> b

-- | <a>filter</a>, applied to a predicate and a list, returns the list of
--   those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
filter :: () => a -> Bool -> [a] -> [a]

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. Printable types are those that are instances
--   of class <a>Show</a>; <a>print</a> converts values to strings for
--   output using the <a>show</a> operation and adds a newline.
--   
--   For example, a program to print the first 20 integers and their powers
--   of 2 could be written as:
--   
--   <pre>
--   main = print ([(n, 2^n) | n &lt;- [0..19]])
--   </pre>
print :: Show a => a -> IO ()

-- | Extract the first component of a pair.
fst :: () => (a, b) -> a

-- | Extract the second component of a pair.
snd :: () => (a, b) -> b

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
($) :: () => a -> b -> a -> b
infixr 0 $

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt>.
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt>.
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt>.
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt>.
enumFromThenTo :: Enum a => a -> a -> a -> [a]

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | Fractional numbers, supporting real division.
class Num a => Fractional a

-- | fractional division
(/) :: Fractional a => a -> a -> a

-- | reciprocal fraction
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> a -> m b -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | Fail with a message. This operation is not part of the mathematical
--   definition of a monad, but is invoked on pattern-match failure in a
--   <tt>do</tt> expression.
--   
--   As part of the MonadFail proposal (MFP), this function is moved to its
--   own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
--   details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a

-- | Basic numeric class.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | attempts to parse a value from the front of the string, returning a
--   list of (parsed value, remaining string) pairs. If there is no
--   successful parse, the returned list is empty.
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
readsPrec :: Read a => Int -> ReadS a

-- | The method <a>readList</a> is provided to allow the programmer to give
--   a specialised way of parsing lists of values. For example, this is
--   used by the predefined <a>Read</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be are expected to use
--   double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><tt>uncurry</tt> <a>encodeFloat</a> (<a>decodeFloat</a> x) =
--   x</tt>. <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <tt>&lt;$&gt;</tt> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a>
--   v = v</pre></li>
--   <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i><i>interchange</i></i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: * -> *)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
(<*>) :: Applicative f => f a -> b -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => a -> m -> t a -> m

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool

-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a

-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
--   <a>traverse</a> (t . f)</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
--   Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
--   <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
--   <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
--   <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
--   transformation <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
--   = Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
--   Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <ul>
--   <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre>t (x <a>&lt;*&gt;</a> y) = t x <a>&lt;*&gt;</a> t
--   y</pre></li>
--   </ul>
--   
--   and the identity functor <tt>Identity</tt> and composition of functors
--   <tt>Compose</tt> are defined as
--   
--   <pre>
--   newtype Identity a = Identity a
--   
--   instance Functor Identity where
--     fmap f (Identity x) = Identity (f x)
--   
--   instance Applicative Identity where
--     pure x = Identity x
--     Identity f &lt;*&gt; Identity x = Identity (f x)
--   
--   newtype Compose f g a = Compose (f (g a))
--   
--   instance (Functor f, Functor g) =&gt; Functor (Compose f g) where
--     fmap f (Compose x) = Compose (fmap (fmap f) x)
--   
--   instance (Applicative f, Applicative g) =&gt; Applicative (Compose f g) where
--     pure x = Compose (pure (pure x))
--     Compose f &lt;*&gt; Compose x = Compose ((&lt;*&gt;) &lt;$&gt; f &lt;*&gt; x)
--   </pre>
--   
--   (The naturality law is implied by parametricity.)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
class (Functor t, Foldable t) => Traversable (t :: * -> *)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => a -> f b -> t a -> f t b

-- | Evaluate each action in the structure from left to right, and and
--   collect the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t f a -> f t a

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the associativity law:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</pre></li>
--   </ul>
class Semigroup a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> <a>mempty</a> = x</pre></li>
--   <li><pre><a>mempty</a> <a>&lt;&gt;</a> x = x</pre></li>
--   <li><tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a> law)</li>
--   <li><pre><a>mconcat</a> = <a>foldr</a> '(&lt;&gt;)'
--   <a>mempty</a></pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = '(&lt;&gt;)'</tt> since
--   <i>base-4.11.0.0</i>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
--   <tt>chr</tt>).
data Char

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <tt>&gt;&gt;</tt> and <tt>&gt;&gt;=</tt>
--   operations from the <tt>Monad</tt> class.
data IO a

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
type String = [Char]

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: () => a -> a

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <tt>length</tt> function (if we have a <a>String</a>) or the
--   "times-two" function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: () => a -> c -> b -> c -> Either a b -> c

-- | The <a>readIO</a> function is similar to <a>read</a> except that it
--   signals parse failure to the <a>IO</a> monad instead of terminating
--   the program.
readIO :: Read a => String -> IO a

-- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>.
readLn :: Read a => IO a

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the string <tt>str</tt>, to the file <tt>file</tt>.
--   
--   Note that <a>writeFile</a> and <a>appendFile</a> write a literal
--   string to a file. To write a value of any printable type, as with
--   <a>print</a>, use the <a>show</a> function to convert the value to a
--   string first.
--   
--   <pre>
--   main = appendFile "squares" (show [(x,x*x) | x &lt;- [0,0.1..2]])
--   </pre>
appendFile :: FilePath -> String -> IO ()

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The <a>interact</a> function takes a function of type
--   <tt>String-&gt;String</tt> as its argument. The entire input from the
--   standard input device is passed to this function as its argument, and
--   the resulting string is output on the standard output device.
interact :: String -> String -> IO ()

-- | The <a>getContents</a> operation returns all user input as a single
--   string, which is read lazily as it is needed (same as
--   <a>hGetContents</a> <a>stdin</a>).
getContents :: IO String

-- | Read a line from the standard input device (same as <a>hGetLine</a>
--   <a>stdin</a>).
getLine :: IO String

-- | Read a character from the standard input device (same as
--   <a>hGetChar</a> <a>stdin</a>).
getChar :: IO Char

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Write a string to the standard output device (same as <a>hPutStr</a>
--   <a>stdout</a>).
putStr :: String -> IO ()

-- | Write a character to the standard output device (same as
--   <a>hPutChar</a> <a>stdout</a>).
putChar :: Char -> IO ()

-- | Raise an <a>IOError</a> in the <a>IO</a> monad.
ioError :: () => IOError -> IO a

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Construct an <a>IOError</a> value with a string describing the error.
--   The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a>
--   class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => a -> Bool -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => a -> Bool -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => a -> [b] -> t a -> [b]

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | The <a>lex</a> function reads a single lexeme from the input,
--   discarding initial white space, and returning the characters that
--   constitute the lexeme. If the input string contains only white space,
--   <a>lex</a> returns a single successful `lexeme' consisting of the
--   empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is
--   no legal lexeme at the beginning of the input string, <a>lex</a> fails
--   (i.e. returns <tt>[]</tt>).
--   
--   This lexer is not completely faithful to the Haskell lexical syntax in
--   the following respects:
--   
--   <ul>
--   <li>Qualified names are not handled properly</li>
--   <li>Octal and hexadecimal numerics are not recognized as a single
--   token</li>
--   <li>Comments are not treated properly</li>
--   </ul>
lex :: ReadS String

-- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses,
--   but surrounded with parentheses.
--   
--   <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt>
--   parses, but optionally surrounded with parentheses.
readParen :: () => Bool -> ReadS a -> ReadS a

-- | A parser for a type <tt>a</tt>, represented as a function that takes a
--   <a>String</a> and returns a list of possible parses as
--   <tt>(a,<a>String</a>)</tt> pairs.
--   
--   Note that this kind of backtracking parser is very inefficient;
--   reading a large structure may be quite slow (cf <a>ReadP</a>).
type ReadS a = String -> [(a, String)]

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <tt>$</tt>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <tt>$</tt> is function application, <a>&lt;$&gt;</a> is
--   function application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
--   <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
--   an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
--   <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <tt>even</tt> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => a -> b -> f a -> f b
infixl 4 <$>

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool

-- | utility function that surrounds the inner show function with
--   parentheses when the <a>Bool</a> parameter is <a>True</a>.
showParen :: Bool -> ShowS -> ShowS

-- | utility function converting a <a>String</a> to a show function that
--   simply prepends the string unchanged.
showString :: String -> ShowS

-- | utility function converting a <a>Char</a> to a show function that
--   simply prepends the character unchanged.
showChar :: Char -> ShowS

-- | equivalent to <a>showsPrec</a> with a precedence of 0.
shows :: Show a => a -> ShowS

-- | The <tt>shows</tt> functions return a function that prepends the
--   output <a>String</a> to an existing <a>String</a>. This allows
--   constant-time concatenation of results using function composition.
type ShowS = String -> String

-- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association
--   list.
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: () => [a] -> [a]

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: () => a -> a -> a -> [a] -> [a]

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: () => a -> a -> a -> [a] -> [a]

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
--   n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
--   we have <a>Nothing</a>, we return the empty string instead of (for
--   example) "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: () => b -> a -> b -> Maybe a -> b

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: () => a -> b -> c -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: () => (a, b) -> c -> a -> b -> c

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: () => a -> a -> a

-- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt>
--   until <tt>p</tt> holds.
until :: () => a -> Bool -> a -> a -> a -> a

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: () => a -> b -> a -> b
infixr 0 $!

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: () => a -> b -> c -> b -> a -> c

-- | Function composition.
(.) :: () => b -> c -> a -> b -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: () => a -> b -> a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => a -> m b -> m a -> m b
infixr 1 =<<

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: () => [Char] -> a

-- | <a>error</a> stops execution and displays an error message.
error :: HasCallStack => [Char] -> a

-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "not"
not :: Bool -> Bool


-- | <b>This is the <a>Safe</a> API only of <a>Clash.Prelude</a></b>
--   
--   CλaSH (pronounced ‘clash’) is a functional hardware description
--   language that borrows both its syntax and semantics from the
--   functional programming language Haskell. The merits of using a
--   functional language to describe hardware comes from the fact that
--   combinational circuits can be directly modeled as mathematical
--   functions and that functional languages lend themselves very well at
--   describing and (de-)composing mathematical functions.
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a></li>
--   <li>Additionally import <a>Clash.Explicit.Prelude</a> if you want to
--   design explicitly clocked circuits in a multi-clock setting</li>
--   </ul>
--   
--   For now, <a>Clash.Prelude</a> is also the best starting point for
--   exploring the library. A preliminary version of a tutorial can be
--   found in <a>Clash.Tutorial</a>. Some circuit examples can be found in
--   <a>Clash.Examples</a>.
module Clash.Prelude.Safe

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: HiddenClockReset domain gated synchronous => (s -> i -> (s, o)) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Infix version of <a>mealyB</a>
(<^>) :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT :: Int        -- Current state
--        -&gt; (Int,Int)  -- Input
--        -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: HiddenClockReset domain gated synchronous => (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   '(Signal a, Signal b)')
--   
--   <pre>
--   rP :: HiddenClockReset domain gated synchronous
--      =&gt; (Signal domain Int, Signal domain Int)
--      -&gt; (Signal domain Int, Signal domain Int)
--   rP = registerB (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (HiddenClockReset domain gated synchronous, Bundle a) => a -> Unbundled domain a -> Unbundled domain a
infixr 3 `registerB`

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRomPow2 :: KnownNat n => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, KnownNat m, HiddenClock domain gated) => Vec n a -> Signal domain (Unsigned m) -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: (KnownNat n, HiddenClock domain gated) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | Create a RAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => SNat n -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a

-- | Create a blockRAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRam inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => Vec n a -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRamPow2 inits) rd
--   wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a

-- | Create read-after-write blockRAM from a read-before-write one
--   (synchronised to system clock)
--   
--   <pre>
--   &gt;&gt;&gt; import Clash.Prelude
--   
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ... =&gt;
--        Signal domain addr
--        -&gt; Signal domain (Maybe (addr, a)) -&gt; Signal domain a
--   </pre>
readNew :: (Eq addr, HiddenClockReset domain gated synchronous) => (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (HiddenClockReset domain gated synchronous, Bounded a, Eq a) => a -> Signal domain a -> Signal domain Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (HiddenClockReset domain gated synchronous, Bounded a, Eq a) => a -> Signal domain a -> Signal domain Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
--   
--   To be precise: the given signal will be <tt><a>False</a></tt> for the
--   next <tt>n-1</tt> cycles, followed by a single <tt><a>True</a></tt>
--   value:
--   
--   <pre>
--   &gt;&gt;&gt; Prelude.last (sampleN 1024 (riseEvery d1024)) == True
--   True
--   
--   &gt;&gt;&gt; Prelude.or (sampleN 1023 (riseEvery d1024)) == False
--   True
--   </pre>
--   
--   For example, to update a counter once every 10 million cycles:
--   
--   <pre>
--   counter = <a>regEn</a> 0 (<a>riseEvery</a> (<a>SNat</a> :: <a>SNat</a> 10000000)) (counter + 1)
--   </pre>
riseEvery :: HiddenClockReset domain gated synchronous => SNat n -> Signal domain Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles. This is
--   a convenient function when combined with something like
--   <tt><a>regEn</a></tt>, as it allows you to easily hold a register
--   value for a given number of cycles. The input <tt><a>Bool</a></tt>
--   determines what the initial value is.
--   
--   To oscillate on an interval of 5 cycles:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 10 (oscillate False d5)
--   [False,False,False,False,False,True,True,True,True,True]
--   </pre>
--   
--   To oscillate between <tt><a>True</a></tt> and <tt><a>False</a></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 10 (oscillate False d1)
--   [False,True,False,True,False,True,False,True,False,True]
--   </pre>
--   
--   An alternative definition for the above could be:
--   
--   <pre>
--   &gt;&gt;&gt; let osc' = register False (not &lt;$&gt; osc')
--   
--   &gt;&gt;&gt; let sample' = sampleN 200
--   
--   &gt;&gt;&gt; sample' (oscillate False d1) == sample' osc'
--   True
--   </pre>
oscillate :: HiddenClockReset domain gated synchronous => Bool -> SNat n -> Signal domain Bool
undefined :: HasCallStack => a

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: () => a -> b -> b

-- | <a>filter</a>, applied to a predicate and a list, returns the list of
--   those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
filter :: () => a -> Bool -> [a] -> [a]

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. Printable types are those that are instances
--   of class <a>Show</a>; <a>print</a> converts values to strings for
--   output using the <a>show</a> operation and adds a newline.
--   
--   For example, a program to print the first 20 integers and their powers
--   of 2 could be written as:
--   
--   <pre>
--   main = print ([(n, 2^n) | n &lt;- [0..19]])
--   </pre>
print :: Show a => a -> IO ()

-- | Extract the first component of a pair.
fst :: () => (a, b) -> a

-- | Extract the second component of a pair.
snd :: () => (a, b) -> b

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
($) :: () => a -> b -> a -> b
infixr 0 $

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt>.
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt>.
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt>.
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt>.
enumFromThenTo :: Enum a => a -> a -> a -> [a]

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | Fractional numbers, supporting real division.
class Num a => Fractional a

-- | fractional division
(/) :: Fractional a => a -> a -> a

-- | reciprocal fraction
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> a -> m b -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | Fail with a message. This operation is not part of the mathematical
--   definition of a monad, but is invoked on pattern-match failure in a
--   <tt>do</tt> expression.
--   
--   As part of the MonadFail proposal (MFP), this function is moved to its
--   own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
--   details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a

-- | Basic numeric class.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | attempts to parse a value from the front of the string, returning a
--   list of (parsed value, remaining string) pairs. If there is no
--   successful parse, the returned list is empty.
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
readsPrec :: Read a => Int -> ReadS a

-- | The method <a>readList</a> is provided to allow the programmer to give
--   a specialised way of parsing lists of values. For example, this is
--   used by the predefined <a>Read</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be are expected to use
--   double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><tt>uncurry</tt> <a>encodeFloat</a> (<a>decodeFloat</a> x) =
--   x</tt>. <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <tt>&lt;$&gt;</tt> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a>
--   v = v</pre></li>
--   <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i><i>interchange</i></i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: * -> *)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
(<*>) :: Applicative f => f a -> b -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => a -> m -> t a -> m

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool

-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a

-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
--   <a>traverse</a> (t . f)</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
--   Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
--   <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
--   <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
--   <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
--   transformation <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
--   = Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
--   Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <ul>
--   <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre>t (x <a>&lt;*&gt;</a> y) = t x <a>&lt;*&gt;</a> t
--   y</pre></li>
--   </ul>
--   
--   and the identity functor <tt>Identity</tt> and composition of functors
--   <tt>Compose</tt> are defined as
--   
--   <pre>
--   newtype Identity a = Identity a
--   
--   instance Functor Identity where
--     fmap f (Identity x) = Identity (f x)
--   
--   instance Applicative Identity where
--     pure x = Identity x
--     Identity f &lt;*&gt; Identity x = Identity (f x)
--   
--   newtype Compose f g a = Compose (f (g a))
--   
--   instance (Functor f, Functor g) =&gt; Functor (Compose f g) where
--     fmap f (Compose x) = Compose (fmap (fmap f) x)
--   
--   instance (Applicative f, Applicative g) =&gt; Applicative (Compose f g) where
--     pure x = Compose (pure (pure x))
--     Compose f &lt;*&gt; Compose x = Compose ((&lt;*&gt;) &lt;$&gt; f &lt;*&gt; x)
--   </pre>
--   
--   (The naturality law is implied by parametricity.)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
class (Functor t, Foldable t) => Traversable (t :: * -> *)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => a -> f b -> t a -> f t b

-- | Evaluate each action in the structure from left to right, and and
--   collect the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t f a -> f t a

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the associativity law:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</pre></li>
--   </ul>
class Semigroup a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> <a>mempty</a> = x</pre></li>
--   <li><pre><a>mempty</a> <a>&lt;&gt;</a> x = x</pre></li>
--   <li><tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a> law)</li>
--   <li><pre><a>mconcat</a> = <a>foldr</a> '(&lt;&gt;)'
--   <a>mempty</a></pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = '(&lt;&gt;)'</tt> since
--   <i>base-4.11.0.0</i>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
--   <tt>chr</tt>).
data Char

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <tt>&gt;&gt;</tt> and <tt>&gt;&gt;=</tt>
--   operations from the <tt>Monad</tt> class.
data IO a

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
type String = [Char]

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: () => a -> a

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <tt>length</tt> function (if we have a <a>String</a>) or the
--   "times-two" function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: () => a -> c -> b -> c -> Either a b -> c

-- | The <a>readIO</a> function is similar to <a>read</a> except that it
--   signals parse failure to the <a>IO</a> monad instead of terminating
--   the program.
readIO :: Read a => String -> IO a

-- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>.
readLn :: Read a => IO a

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the string <tt>str</tt>, to the file <tt>file</tt>.
--   
--   Note that <a>writeFile</a> and <a>appendFile</a> write a literal
--   string to a file. To write a value of any printable type, as with
--   <a>print</a>, use the <a>show</a> function to convert the value to a
--   string first.
--   
--   <pre>
--   main = appendFile "squares" (show [(x,x*x) | x &lt;- [0,0.1..2]])
--   </pre>
appendFile :: FilePath -> String -> IO ()

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The <a>interact</a> function takes a function of type
--   <tt>String-&gt;String</tt> as its argument. The entire input from the
--   standard input device is passed to this function as its argument, and
--   the resulting string is output on the standard output device.
interact :: String -> String -> IO ()

-- | The <a>getContents</a> operation returns all user input as a single
--   string, which is read lazily as it is needed (same as
--   <a>hGetContents</a> <a>stdin</a>).
getContents :: IO String

-- | Read a line from the standard input device (same as <a>hGetLine</a>
--   <a>stdin</a>).
getLine :: IO String

-- | Read a character from the standard input device (same as
--   <a>hGetChar</a> <a>stdin</a>).
getChar :: IO Char

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Write a string to the standard output device (same as <a>hPutStr</a>
--   <a>stdout</a>).
putStr :: String -> IO ()

-- | Write a character to the standard output device (same as
--   <a>hPutChar</a> <a>stdout</a>).
putChar :: Char -> IO ()

-- | Raise an <a>IOError</a> in the <a>IO</a> monad.
ioError :: () => IOError -> IO a

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Construct an <a>IOError</a> value with a string describing the error.
--   The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a>
--   class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => a -> Bool -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => a -> Bool -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => a -> [b] -> t a -> [b]

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | The <a>lex</a> function reads a single lexeme from the input,
--   discarding initial white space, and returning the characters that
--   constitute the lexeme. If the input string contains only white space,
--   <a>lex</a> returns a single successful `lexeme' consisting of the
--   empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is
--   no legal lexeme at the beginning of the input string, <a>lex</a> fails
--   (i.e. returns <tt>[]</tt>).
--   
--   This lexer is not completely faithful to the Haskell lexical syntax in
--   the following respects:
--   
--   <ul>
--   <li>Qualified names are not handled properly</li>
--   <li>Octal and hexadecimal numerics are not recognized as a single
--   token</li>
--   <li>Comments are not treated properly</li>
--   </ul>
lex :: ReadS String

-- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses,
--   but surrounded with parentheses.
--   
--   <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt>
--   parses, but optionally surrounded with parentheses.
readParen :: () => Bool -> ReadS a -> ReadS a

-- | A parser for a type <tt>a</tt>, represented as a function that takes a
--   <a>String</a> and returns a list of possible parses as
--   <tt>(a,<a>String</a>)</tt> pairs.
--   
--   Note that this kind of backtracking parser is very inefficient;
--   reading a large structure may be quite slow (cf <a>ReadP</a>).
type ReadS a = String -> [(a, String)]

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <tt>$</tt>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <tt>$</tt> is function application, <a>&lt;$&gt;</a> is
--   function application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
--   <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
--   an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
--   <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <tt>even</tt> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => a -> b -> f a -> f b
infixl 4 <$>

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool

-- | utility function that surrounds the inner show function with
--   parentheses when the <a>Bool</a> parameter is <a>True</a>.
showParen :: Bool -> ShowS -> ShowS

-- | utility function converting a <a>String</a> to a show function that
--   simply prepends the string unchanged.
showString :: String -> ShowS

-- | utility function converting a <a>Char</a> to a show function that
--   simply prepends the character unchanged.
showChar :: Char -> ShowS

-- | equivalent to <a>showsPrec</a> with a precedence of 0.
shows :: Show a => a -> ShowS

-- | The <tt>shows</tt> functions return a function that prepends the
--   output <a>String</a> to an existing <a>String</a>. This allows
--   constant-time concatenation of results using function composition.
type ShowS = String -> String

-- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association
--   list.
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: () => [a] -> [a]

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: () => a -> a -> a -> [a] -> [a]

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: () => a -> a -> a -> [a] -> [a]

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
--   n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
--   we have <a>Nothing</a>, we return the empty string instead of (for
--   example) "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: () => b -> a -> b -> Maybe a -> b

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: () => a -> b -> c -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: () => (a, b) -> c -> a -> b -> c

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: () => a -> a -> a

-- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt>
--   until <tt>p</tt> holds.
until :: () => a -> Bool -> a -> a -> a -> a

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: () => a -> b -> a -> b
infixr 0 $!

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: () => a -> b -> c -> b -> a -> c

-- | Function composition.
(.) :: () => b -> c -> a -> b -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: () => a -> b -> a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => a -> m b -> m a -> m b
infixr 1 =<<

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: () => [Char] -> a

-- | <a>error</a> stops execution and displays an error message.
error :: HasCallStack => [Char] -> a

-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "not"
not :: Bool -> Bool


-- | This module defines the explicitly clocked counterparts of the
--   functions defined in <a>Clash.Prelude</a>. Take a look at
--   <a>Clash.Signal.Explicit</a> to see how you can make multi-clock
--   designs.
module Clash.Explicit.Prelude

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   import qualified Data.List as L
--   
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac
--     :: <a>Clock</a> domain Source
--     -&gt; <a>Reset</a> domain Asynchronous
--     -&gt; <a>Signal</a> domain (Int, Int)
--     -&gt; <a>Signal</a> domain Int
--   mac clk rst = <a>mealy</a> clk rst macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: <a>Clock</a> domain gated -&gt; <a>Reset</a> domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> clk rst mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Signal dom i -> Signal dom o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool,Int) -&gt; (Int,(Int,Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <tt>mealy'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (mealy clk rst f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (mealy clk rst f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mealyB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> clk rst f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> clk rst f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o) => Clock dom gated -> Reset dom synchronous -> (s -> i -> (s, o)) -> s -> (Unbundled dom i -> Unbundled dom o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac
--     :: <a>Clock</a> mac Source
--     -&gt; <a>Reset</a> mac Asynchronous
--     -&gt; <a>Signal</a> mac (Int, Int)
--     -&gt; <a>Signal</a> mac Int
--   mac clk rst = <a>moore</a> clk rst macT id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate (mac systemClockGen systemResetGen) [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: Clock domain gated
--     -&gt; Reset domain synchronous
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac clk rst (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> clk rst mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <tt>moore'</tt>, we have to write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (moore clk rst t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (moore clk rst t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <tt>mooreB'</tt> however we can write:
--   
--   <pre>
--   g clk rst a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> clk rst t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> clk rst t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o) => Clock domain gated -> Reset domain synchronous -> (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   <tt>(<a>Signal</a> a, <a>Signal</a> b)</tt>)
--   
--   <pre>
--   rP :: Clock domain gated -&gt; Reset domain synchronous
--      -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--      -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--   rP clk rst = <a>registerB</a> clk rst (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (rP systemClockGen systemResetGen) [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: Bundle a => Clock domain gated -> Reset domain synchronous -> a -> Unbundled domain a -> Unbundled domain a

-- | Synchroniser based on two sequentially connected flip-flops.
--   
--   <ul>
--   <li><b>NB</b>: This synchroniser can be used for
--   <b>bit</b>-synchronization.</li>
--   <li><b>NB</b>: Although this synchroniser does reduce metastability,
--   it does not guarantee the proper synchronisation of a whole
--   <b>word</b>. For example, given that the output is sampled twice as
--   fast as the input is running, and we have two samples in the input
--   stream that look like:<pre>[0111,1000]</pre>But the circuit driving
--   the input stream has a longer propagation delay on <b>msb</b> compared
--   to the <b>lsb</b>s. What can happen is an output stream that looks
--   like this:<pre>[0111,0111,0000,1000]</pre>Where the level-change of
--   the <b>msb</b> was not captured, but the level change of the
--   <b>lsb</b>s were.If you want to have <i>safe</i>
--   <b>word</b>-synchronisation use <a>asyncFIFOSynchronizer</a>.</li>
--   </ul>
dualFlipFlopSynchronizer :: Clock domain1 gated1 -> Clock domain2 gated2 -> Reset domain2 synchronous -> a -> Signal domain1 a -> Signal domain2 a

-- | Synchroniser implemented as a FIFO around an asynchronous RAM. Based
--   on the design described in <a>Clash.Tutorial#multiclock</a>, which is
--   itself based on the design described in
--   <a>http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf</a>.
--   
--   <b>NB</b>: This synchroniser can be used for
--   <b>word</b>-synchronization.
asyncFIFOSynchronizer :: (2 <= addrSize) => SNat addrSize -> Clock wdomain wgated -> Clock rdomain rgated -> Reset wdomain synchronous -> Reset rdomain synchronous -> Signal rdomain Bool -> Signal wdomain (Maybe a) -> (Signal rdomain a, Signal rdomain Bool, Signal wdomain Bool)

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRomPow2 :: KnownNat n => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, Enum addr) => Clock domain gated -> Vec n a -> Signal domain addr -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Explicit.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: KnownNat n => Clock domain gated -> Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, Enum addr) => Clock domain gated -> SNat n -> FilePath -> Signal domain addr -> Signal domain (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall domain gated n m. (KnownNat m, KnownNat n) => Clock domain gated -> FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> SNat n -> Signal rdom addr -> Signal wdom (Maybe (addr, a)) -> Signal rdom a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: forall wdom rdom wgated rgated n a. (KnownNat n, HasCallStack) => Clock wdom wgated -> Clock rdom rgated -> Signal rdom (Unsigned n) -> Signal wdom (Maybe (Unsigned n, a)) -> Signal rdom a

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40 :: <a>Clock</a>  domain gated
--          -&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 clk = <a>blockRam</a> clk (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRam</a> clk
--   inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: HasCallStack => Enum addr => Clock dom gated -> Vec n a -> Signal dom addr -> Signal dom (Maybe (addr, a)) -> Signal dom a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32 :: <a>Signal</a> domain (<a>Unsigned</a> 5)
--          -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--          -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 clk = <a>blockRamPow2</a> clk (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt><a>readNew</a> clk rst (<a>blockRamPow2</a>
--   clk inits) rd wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HasCallStack) => Clock dom gated -> Vec (2 ^ n) a -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, a)) -> Signal dom a

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Explicit.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFile' clk size file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, HasCallStack) => Clock dom gated -> SNat n -> FilePath -> Signal dom addr -> Signal dom (Maybe (addr, BitVector m)) -> Signal dom (BitVector m)

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFilePow2' clk file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Explicit.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Explicit.Fixed#creatingdatafiles</a> for ideas on how
--   to create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall dom gated n m. (KnownNat m, KnownNat n, HasCallStack) => Clock dom gated -> FilePath -> Signal dom (Unsigned n) -> Signal dom (Maybe (Unsigned n, BitVector m)) -> Signal dom (BitVector m)

-- | Create read-after-write blockRAM from a read-before-write one
readNew :: Eq addr => Reset domain synchronous -> Clock domain gated -> (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Give a window over a <a>Signal</a>
--   
--   @ window4
window :: (KnownNat n, Default a) => Clock domain gated -> Reset domain synchronous -> Signal domain a -> Vec (n + 1) (Signal domain a)

-- | Give a delayed window over a <a>Signal</a>
--   
--   <pre>
--   windowD3 :: Clock domain gated -&gt; Reset domain synchronous
--            -&gt; <a>Signal</a> domain Int -&gt; <a>Vec</a> 3 (<a>Signal</a> domain Int)
--   windowD3 = <a>windowD</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB (windowD3 systemClockGen systemResetGen) [1::Int,2,3,4] :: [Vec 3 Int]
--   [&lt;0,0,0&gt;,&lt;1,0,0&gt;,&lt;2,1,0&gt;,&lt;3,2,1&gt;,&lt;4,3,2&gt;...
--   ...
--   </pre>
windowD :: (KnownNat n, Default a) => Clock domain gated -> Reset domain synchronous -> Signal domain a -> Vec (n + 1) (Signal domain a)

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (Bounded a, Eq a) => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (Bounded a, Eq a) => Clock domain gated -> Reset domain synchronous -> a -> Signal domain a -> Signal domain Bool

-- | Compares the first two <a>Signal</a>s for equality and logs a warning
--   when they are not equal. The second <a>Signal</a> is considered the
--   expected value. This function simply returns the third
--   <tt>Signal'</tt> unaltered as its result. This function is used by
--   <a>outputVerifier</a>.
--   
--   <b>NB</b>: This function <i>can</i> be used in synthesizable designs.
assert :: (Eq a, ShowX a) => Clock domain gated -> Reset domain synchronous -> String -> Signal domain a -> Signal domain a -> Signal domain b -> Signal domain b

-- | To be used as one of the functions to create the "magical"
--   <tt>testInput</tt> value, which the CλaSH compiler looks for to create
--   the stimulus generator for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   testInput
--     :: Clock domain gated -&gt; Reset domain synchronous
--     -&gt; <a>Signal</a> domain Int
--   testInput clk rst = <a>stimuliGenerator</a> clk rst $(<a>listToVecTH</a> [(1::Int),3..21])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 13 (testInput systemClockGen systemResetGen)
--   [1,3,5,7,9,11,13,15,17,19,21,21,21]
--   </pre>
stimuliGenerator :: forall l domain gated synchronous a. KnownNat l => Clock domain gated -> Reset domain synchronous -> Vec l a -> Signal domain a

-- | To be used as one of the functions to generate the "magical"
--   <tt>expectedOutput</tt> function, which the CλaSH compiler looks for
--   to create the signal verifier for the generated VHDL testbench.
--   
--   Example:
--   
--   <pre>
--   expectedOutput
--     :: Clock domain gated -&gt; Reset domain synchronous
--     -&gt; <a>Signal</a> domain Int -&gt; <a>Signal</a> domain Bool
--   expectedOutput clk rst = <a>outputVerifier</a> clk rst $(<a>listToVecTH</a> ([70,99,2,3,4,5,7,8,9,10]::[Int]))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.List as List
--   
--   &gt;&gt;&gt; sampleN 12 (expectedOutput systemClockGen systemResetGen (fromList ([0..10] List.++ [10,10,10])))
--   
--   cycle(system10000): 0, outputVerifier
--   expected value: 70, not equal to actual value: 0
--   [False
--   cycle(system10000): 1, outputVerifier
--   expected value: 99, not equal to actual value: 1
--   ,False,False,False,False,False
--   cycle(system10000): 6, outputVerifier
--   expected value: 7, not equal to actual value: 6
--   ,False
--   cycle(system10000): 7, outputVerifier
--   expected value: 8, not equal to actual value: 7
--   ,False
--   cycle(system10000): 8, outputVerifier
--   expected value: 9, not equal to actual value: 8
--   ,False
--   cycle(system10000): 9, outputVerifier
--   expected value: 10, not equal to actual value: 9
--   ,False,True,True]
--   </pre>
outputVerifier :: forall l domain gated synchronous a. (KnownNat l, Eq a, ShowX a) => Clock domain gated -> Reset domain synchronous -> Vec l a -> Signal domain a -> Signal domain Bool

-- | A <a>Lift</a> instance can have any of its values turned into a
--   Template Haskell expression. This is needed when a value used within a
--   Template Haskell quotation is bound outside the Oxford brackets
--   (<tt>[| ... |]</tt>) but not at the top level. As an example:
--   
--   <pre>
--   add1 :: Int -&gt; Q Exp
--   add1 x = [| x + 1 |]
--   </pre>
--   
--   Template Haskell has no way of knowing what value <tt>x</tt> will take
--   on at splice-time, so it requires the type of <tt>x</tt> to be an
--   instance of <a>Lift</a>.
--   
--   A <a>Lift</a> instance must satisfy <tt>$(lift x) ≡ x</tt> for all
--   <tt>x</tt>, where <tt>$(...)</tt> is a Template Haskell splice.
--   
--   <a>Lift</a> instances can be derived automatically by use of the
--   <tt>-XDeriveLift</tt> GHC language extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveLift #-}
--   module Foo where
--   
--   import Language.Haskell.TH.Syntax
--   
--   data Bar a = Bar1 a (Bar a) | Bar2 String
--     deriving Lift
--   </pre>
class Lift t

-- | Turn a value into a Template Haskell expression, suitable for use in a
--   splice.
lift :: Lift t => t -> Q Exp
undefined :: HasCallStack => a

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: () => a -> b -> b

-- | <a>filter</a>, applied to a predicate and a list, returns the list of
--   those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
filter :: () => a -> Bool -> [a] -> [a]

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. Printable types are those that are instances
--   of class <a>Show</a>; <a>print</a> converts values to strings for
--   output using the <a>show</a> operation and adds a newline.
--   
--   For example, a program to print the first 20 integers and their powers
--   of 2 could be written as:
--   
--   <pre>
--   main = print ([(n, 2^n) | n &lt;- [0..19]])
--   </pre>
print :: Show a => a -> IO ()

-- | Extract the first component of a pair.
fst :: () => (a, b) -> a

-- | Extract the second component of a pair.
snd :: () => (a, b) -> b

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
($) :: () => a -> b -> a -> b
infixr 0 $

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt>.
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt>.
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt>.
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt>.
enumFromThenTo :: Enum a => a -> a -> a -> [a]

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | Fractional numbers, supporting real division.
class Num a => Fractional a

-- | fractional division
(/) :: Fractional a => a -> a -> a

-- | reciprocal fraction
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> a -> m b -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | Fail with a message. This operation is not part of the mathematical
--   definition of a monad, but is invoked on pattern-match failure in a
--   <tt>do</tt> expression.
--   
--   As part of the MonadFail proposal (MFP), this function is moved to its
--   own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
--   details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a

-- | Basic numeric class.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | attempts to parse a value from the front of the string, returning a
--   list of (parsed value, remaining string) pairs. If there is no
--   successful parse, the returned list is empty.
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
readsPrec :: Read a => Int -> ReadS a

-- | The method <a>readList</a> is provided to allow the programmer to give
--   a specialised way of parsing lists of values. For example, this is
--   used by the predefined <a>Read</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be are expected to use
--   double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><tt>uncurry</tt> <a>encodeFloat</a> (<a>decodeFloat</a> x) =
--   x</tt>. <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <tt>&lt;$&gt;</tt> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a>
--   v = v</pre></li>
--   <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i><i>interchange</i></i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: * -> *)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
(<*>) :: Applicative f => f a -> b -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => a -> m -> t a -> m

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool

-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a

-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
--   <a>traverse</a> (t . f)</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
--   Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
--   <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
--   <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
--   <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
--   transformation <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
--   = Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
--   Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <ul>
--   <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre>t (x <a>&lt;*&gt;</a> y) = t x <a>&lt;*&gt;</a> t
--   y</pre></li>
--   </ul>
--   
--   and the identity functor <tt>Identity</tt> and composition of functors
--   <tt>Compose</tt> are defined as
--   
--   <pre>
--   newtype Identity a = Identity a
--   
--   instance Functor Identity where
--     fmap f (Identity x) = Identity (f x)
--   
--   instance Applicative Identity where
--     pure x = Identity x
--     Identity f &lt;*&gt; Identity x = Identity (f x)
--   
--   newtype Compose f g a = Compose (f (g a))
--   
--   instance (Functor f, Functor g) =&gt; Functor (Compose f g) where
--     fmap f (Compose x) = Compose (fmap (fmap f) x)
--   
--   instance (Applicative f, Applicative g) =&gt; Applicative (Compose f g) where
--     pure x = Compose (pure (pure x))
--     Compose f &lt;*&gt; Compose x = Compose ((&lt;*&gt;) &lt;$&gt; f &lt;*&gt; x)
--   </pre>
--   
--   (The naturality law is implied by parametricity.)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
class (Functor t, Foldable t) => Traversable (t :: * -> *)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => a -> f b -> t a -> f t b

-- | Evaluate each action in the structure from left to right, and and
--   collect the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t f a -> f t a

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the associativity law:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</pre></li>
--   </ul>
class Semigroup a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> <a>mempty</a> = x</pre></li>
--   <li><pre><a>mempty</a> <a>&lt;&gt;</a> x = x</pre></li>
--   <li><tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a> law)</li>
--   <li><pre><a>mconcat</a> = <a>foldr</a> '(&lt;&gt;)'
--   <a>mempty</a></pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = '(&lt;&gt;)'</tt> since
--   <i>base-4.11.0.0</i>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
--   <tt>chr</tt>).
data Char

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <tt>&gt;&gt;</tt> and <tt>&gt;&gt;=</tt>
--   operations from the <tt>Monad</tt> class.
data IO a

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
type String = [Char]

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: () => a -> a

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <tt>length</tt> function (if we have a <a>String</a>) or the
--   "times-two" function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: () => a -> c -> b -> c -> Either a b -> c

-- | The <a>readIO</a> function is similar to <a>read</a> except that it
--   signals parse failure to the <a>IO</a> monad instead of terminating
--   the program.
readIO :: Read a => String -> IO a

-- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>.
readLn :: Read a => IO a

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the string <tt>str</tt>, to the file <tt>file</tt>.
--   
--   Note that <a>writeFile</a> and <a>appendFile</a> write a literal
--   string to a file. To write a value of any printable type, as with
--   <a>print</a>, use the <a>show</a> function to convert the value to a
--   string first.
--   
--   <pre>
--   main = appendFile "squares" (show [(x,x*x) | x &lt;- [0,0.1..2]])
--   </pre>
appendFile :: FilePath -> String -> IO ()

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The <a>interact</a> function takes a function of type
--   <tt>String-&gt;String</tt> as its argument. The entire input from the
--   standard input device is passed to this function as its argument, and
--   the resulting string is output on the standard output device.
interact :: String -> String -> IO ()

-- | The <a>getContents</a> operation returns all user input as a single
--   string, which is read lazily as it is needed (same as
--   <a>hGetContents</a> <a>stdin</a>).
getContents :: IO String

-- | Read a line from the standard input device (same as <a>hGetLine</a>
--   <a>stdin</a>).
getLine :: IO String

-- | Read a character from the standard input device (same as
--   <a>hGetChar</a> <a>stdin</a>).
getChar :: IO Char

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Write a string to the standard output device (same as <a>hPutStr</a>
--   <a>stdout</a>).
putStr :: String -> IO ()

-- | Write a character to the standard output device (same as
--   <a>hPutChar</a> <a>stdout</a>).
putChar :: Char -> IO ()

-- | Raise an <a>IOError</a> in the <a>IO</a> monad.
ioError :: () => IOError -> IO a

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Construct an <a>IOError</a> value with a string describing the error.
--   The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a>
--   class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => a -> Bool -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => a -> Bool -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => a -> [b] -> t a -> [b]

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | The <a>lex</a> function reads a single lexeme from the input,
--   discarding initial white space, and returning the characters that
--   constitute the lexeme. If the input string contains only white space,
--   <a>lex</a> returns a single successful `lexeme' consisting of the
--   empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is
--   no legal lexeme at the beginning of the input string, <a>lex</a> fails
--   (i.e. returns <tt>[]</tt>).
--   
--   This lexer is not completely faithful to the Haskell lexical syntax in
--   the following respects:
--   
--   <ul>
--   <li>Qualified names are not handled properly</li>
--   <li>Octal and hexadecimal numerics are not recognized as a single
--   token</li>
--   <li>Comments are not treated properly</li>
--   </ul>
lex :: ReadS String

-- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses,
--   but surrounded with parentheses.
--   
--   <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt>
--   parses, but optionally surrounded with parentheses.
readParen :: () => Bool -> ReadS a -> ReadS a

-- | A parser for a type <tt>a</tt>, represented as a function that takes a
--   <a>String</a> and returns a list of possible parses as
--   <tt>(a,<a>String</a>)</tt> pairs.
--   
--   Note that this kind of backtracking parser is very inefficient;
--   reading a large structure may be quite slow (cf <a>ReadP</a>).
type ReadS a = String -> [(a, String)]

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <tt>$</tt>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <tt>$</tt> is function application, <a>&lt;$&gt;</a> is
--   function application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
--   <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
--   an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
--   <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <tt>even</tt> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => a -> b -> f a -> f b
infixl 4 <$>

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool

-- | utility function that surrounds the inner show function with
--   parentheses when the <a>Bool</a> parameter is <a>True</a>.
showParen :: Bool -> ShowS -> ShowS

-- | utility function converting a <a>String</a> to a show function that
--   simply prepends the string unchanged.
showString :: String -> ShowS

-- | utility function converting a <a>Char</a> to a show function that
--   simply prepends the character unchanged.
showChar :: Char -> ShowS

-- | equivalent to <a>showsPrec</a> with a precedence of 0.
shows :: Show a => a -> ShowS

-- | The <tt>shows</tt> functions return a function that prepends the
--   output <a>String</a> to an existing <a>String</a>. This allows
--   constant-time concatenation of results using function composition.
type ShowS = String -> String

-- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association
--   list.
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: () => [a] -> [a]

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: () => a -> a -> a -> [a] -> [a]

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: () => a -> a -> a -> [a] -> [a]

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
--   n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
--   we have <a>Nothing</a>, we return the empty string instead of (for
--   example) "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: () => b -> a -> b -> Maybe a -> b

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: () => a -> b -> c -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: () => (a, b) -> c -> a -> b -> c

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: () => a -> a -> a

-- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt>
--   until <tt>p</tt> holds.
until :: () => a -> Bool -> a -> a -> a -> a

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: () => a -> b -> a -> b
infixr 0 $!

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: () => a -> b -> c -> b -> a -> c

-- | Function composition.
(.) :: () => b -> c -> a -> b -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: () => a -> b -> a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => a -> m b -> m a -> m b
infixr 1 =<<

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: () => [Char] -> a

-- | <a>error</a> stops execution and displays an error message.
error :: HasCallStack => [Char] -> a

-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "not"
not :: Bool -> Bool


-- | CλaSH (pronounced ‘clash’) is a functional hardware description
--   language that borrows both its syntax and semantics from the
--   functional programming language Haskell. The merits of using a
--   functional language to describe hardware comes from the fact that
--   combinational circuits can be directly modeled as mathematical
--   functions and that functional languages lend themselves very well at
--   describing and (de-)composing mathematical functions.
--   
--   This package provides:
--   
--   <ul>
--   <li>Prelude library containing datatypes and functions for circuit
--   design</li>
--   </ul>
--   
--   To use the library:
--   
--   <ul>
--   <li>Import <a>Clash.Prelude</a>; by default clock and reset lines are
--   implicitly routed for all the components found in
--   <a>Clash.Prelude</a>. You can read more about implicit clock and reset
--   lines in <a>Clash.Signal#implicitclockandreset</a></li>
--   <li>Alternatively, if you want to explicitly route clock and reset
--   ports, for more straightforward multi-clock designs, you can import
--   the <a>Clash.Explicit.Prelude</a> module. Note that you should not
--   import <a>Clash.Prelude</a> and <a>Clash.Explicit.Prelude</a> at the
--   same time as they have overlapping definitions.</li>
--   </ul>
--   
--   For now, <a>Clash.Prelude</a> is also the best starting point for
--   exploring the library. A preliminary version of a tutorial can be
--   found in <a>Clash.Tutorial</a>. Some circuit examples can be found in
--   <a>Clash.Examples</a>.
module Clash.Prelude

-- | Create a synchronous function from a combinational function describing
--   a mealy machine
--   
--   <pre>
--   macT
--     :: Int        -- Current state
--     -&gt; (Int,Int)  -- Input
--     -&gt; (Int,Int)  -- (Updated state, output)
--   macT s (x,y) = (s',s)
--     where
--       s' = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>mealy</a> macT 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>mealy</a> mac 0 (<a>bundle</a> (a,x))
--       s2 = <a>mealy</a> mac 0 (<a>bundle</a> (b,y))
--   </pre>
mealy :: HiddenClockReset domain gated synchronous => (s -> i -> (s, o)) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>mealy</a> that does automatic <a>Bundle</a>ing
--   
--   Given a function <tt>f</tt> of type:
--   
--   <pre>
--   <b>f</b> :: Int -&gt; (Bool, Int) -&gt; (Int, (Int, Bool))
--   </pre>
--   
--   When we want to make compositions of <tt>f</tt> in <tt>g</tt> using
--   <a>mealy</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>mealy</a> f 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>mealy</a> f 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mealyB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mealyB</a> f 0 (a,b)
--       (i2,b2) = <a>mealyB</a> f 3 (i1,c)
--   </pre>
mealyB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Infix version of <a>mealyB</a>
(<^>) :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> (s, o)) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a synchronous function from a combinational function describing
--   a moore machine
--   
--   <pre>
--   macT :: Int        -- Current state
--        -&gt; (Int,Int)  -- Input
--        -&gt; Int        -- Updated state
--   macT s (x,y) = x * y + s
--   
--   mac :: HiddenClockReset domain gated synchronous =&gt; <a>Signal</a> domain (Int, Int) -&gt; <a>Signal</a> domain Int
--   mac = <a>moore</a> mac id 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulate mac [(1,1),(2,2),(3,3),(4,4)]
--   [0,1,5,14...
--   ...
--   </pre>
--   
--   Synchronous sequential functions can be composed just like their
--   combinational counterpart:
--   
--   <pre>
--   dualMac
--     :: HiddenClockReset domain gated synchronous
--     =&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; (<a>Signal</a> domain Int, <a>Signal</a> domain Int)
--     -&gt; <a>Signal</a> domain Int
--   dualMac (a,b) (x,y) = s1 + s2
--     where
--       s1 = <a>moore</a> mac id 0 (<a>bundle</a> (a,x))
--       s2 = <a>moore</a> mac id 0 (<a>bundle</a> (b,y))
--   </pre>
moore :: HiddenClockReset domain gated synchronous => (s -> i -> s) -> (s -> o) -> s -> (Signal domain i -> Signal domain o)

-- | A version of <a>moore</a> that does automatic <a>Bundle</a>ing
--   
--   Given a functions <tt>t</tt> and <tt>o</tt> of types:
--   
--   <pre>
--   <b>t</b> :: Int -&gt; (Bool, Int) -&gt; Int
--   <b>o</b> :: Int -&gt; (Int, Bool)
--   </pre>
--   
--   When we want to make compositions of <tt>t</tt> and <tt>o</tt> in
--   <tt>g</tt> using <a>moore</a>, we have to write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>unbundle</a> (<a>moore</a> t o 0 (<a>bundle</a> (a,b)))
--       (i2,b2) = <a>unbundle</a> (<a>moore</a> t o 3 (<a>bundle</a> (i1,c)))
--   </pre>
--   
--   Using <a>mooreB</a> however we can write:
--   
--   <pre>
--   g a b c = (b1,b2,i2)
--     where
--       (i1,b1) = <a>mooreB</a> t o 0 (a,b)
--       (i2,b2) = <a>mooreB</a> t o 3 (i1,c)
--   </pre>
mooreB :: (Bundle i, Bundle o, HiddenClockReset domain gated synchronous) => (s -> i -> s) -> (s -> o) -> s -> (Unbundled domain i -> Unbundled domain o)

-- | Create a <a>register</a> function for product-type like signals (e.g.
--   '(Signal a, Signal b)')
--   
--   <pre>
--   rP :: HiddenClockReset domain gated synchronous
--      =&gt; (Signal domain Int, Signal domain Int)
--      -&gt; (Signal domain Int, Signal domain Int)
--   rP = registerB (8,8)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB rP [(1,1),(2,2),(3,3)] :: [(Int,Int)]
--   [(8,8),(1,1),(2,2),(3,3)...
--   ...
--   </pre>
registerB :: (HiddenClockReset domain gated synchronous, Bundle a) => a -> Unbundled domain a -> Unbundled domain a
infixr 3 `registerB`

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRom :: (KnownNat n, Enum addr) => Vec n a -> addr -> a

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
asyncRomPow2 :: KnownNat n => Vec (2 ^ n) a -> Unsigned n -> a

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
rom :: (KnownNat n, KnownNat m, HiddenClock domain gated) => Vec n a -> Signal domain (Unsigned m) -> Signal domain a

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> and
--   <a>Clash.Prelude.BlockRam#usingrams</a> for ideas on how to use ROMs
--   and RAMs</li>
--   </ul>
romPow2 :: (KnownNat n, HiddenClock domain gated) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain a

-- | An asynchronous/combinational ROM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFile</a> is significantly slowing
--   down your simulation, give it a <i>monomorphic</i> type signature. So
--   instead of leaving the type to be inferred:<pre>myRomData =
--   asyncRomFile d512 "memory.bin" </pre>or giving it a <i>polymorphic</i>
--   type signature:<pre>myRomData :: Enum addr =&gt; addr -&gt; BitVector
--   16 myRomData = asyncRomFile d512 "memory.bin" </pre>you <b>should</b>
--   give it a <i>monomorphic</i> type signature:<pre>myRomData :: Unsigned
--   9 -&gt; BitVector 16 myRomData = asyncRomFile d512 "memory.bin"
--   </pre></li>
--   </ul>
asyncRomFile :: (KnownNat m, Enum addr) => SNat n -> FilePath -> addr -> BitVector m

-- | An asynchronous/combinational ROM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   <li>When you notice that <a>asyncRomFilePow2</a> is significantly
--   slowing down your simulation, give it a <i>monomorphic</i> type
--   signature. So instead of leaving the type to be
--   inferred:<pre>myRomData = asyncRomFilePow2 "memory.bin" </pre>you
--   <b>should</b> give it a <i>monomorphic</i> type
--   signature:<pre>myRomData :: Unsigned 9 -&gt; BitVector 16 myRomData =
--   asyncRomFilePow2 "memory.bin" </pre></li>
--   </ul>
asyncRomFilePow2 :: forall n m. (KnownNat m, KnownNat n) => FilePath -> Unsigned n -> BitVector m

-- | A ROM with a synchronous read port, with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFile :: (KnownNat m, KnownNat n, HiddenClock domain gated) => SNat n -> FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | A ROM with a synchronous read port, with space for 2^<tt>n</tt>
--   elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.ROM.File#usingromfiles</a> for more
--   information on how to instantiate a ROM with the contents of a data
--   file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
romFilePow2 :: forall n m domain gated. (KnownNat m, KnownNat n, HiddenClock domain gated) => FilePath -> Signal domain (Unsigned n) -> Signal domain (BitVector m)

-- | Create a RAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => SNat n -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a RAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Initial content of the RAM is <a>undefined</a></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a RAM.</li>
--   </ul>
asyncRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a

-- | Create a blockRAM with space for <tt>n</tt> elements.
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram40
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 6)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 6, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram40 = <a>blockRam</a> (<a>replicate</a> d40 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRam inits) rd wrM</tt>.</li>
--   </ul>
blockRam :: (Enum addr, HiddenClock domain gated, HasCallStack) => Vec n a -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   </ul>
--   
--   <pre>
--   bram32
--     :: <a>HiddenClock</a> domain
--     =&gt; <a>Signal</a> domain (<a>Unsigned</a> 5)
--     -&gt; <a>Signal</a> domain (Maybe (<a>Unsigned</a> 5, <a>Bit</a>))
--     -&gt; <a>Signal</a> domain <a>Bit</a>
--   bram32 = <a>blockRamPow2</a> (<a>replicate</a> d32 1)
--   </pre>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <a>readNew</a> for obtaining write-before-read
--   semantics like this: <tt>readNew (blockRamPow2 inits) rd
--   wrM</tt>.</li>
--   </ul>
blockRamPow2 :: (KnownNat n, HiddenClock domain gated, HasCallStack) => Vec (2 ^ n) a -> Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, a)) -> Signal domain a

-- | Create a blockRAM with space for <tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFile' clk size file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFile :: (KnownNat m, Enum addr, HiddenClock domain gated, HasCallStack) => SNat n -> FilePath -> Signal domain addr -> Signal domain (Maybe (addr, BitVector m)) -> Signal domain (BitVector m)

-- | Create a blockRAM with space for 2^<tt>n</tt> elements
--   
--   <ul>
--   <li><b>NB</b>: Read value is delayed by 1 cycle</li>
--   <li><b>NB</b>: Initial output value is <a>undefined</a></li>
--   <li><b>NB</b>: This function might not work for specific combinations
--   of code-generation backends and hardware targets. Please check the
--   support table below:<pre> | VHDL | Verilog | SystemVerilog |
--   ===============+==========+==========+===============+ Altera/Quartus
--   | Broken | Works | Works | Xilinx/ISE | Works | Works | Works | ASIC |
--   Untested | Untested | Untested |
--   ===============+==========+==========+===============+ </pre></li>
--   </ul>
--   
--   Additional helpful information:
--   
--   <ul>
--   <li>See <a>Clash.Prelude.BlockRam#usingrams</a> for more information
--   on how to use a Block RAM.</li>
--   <li>Use the adapter <tt>readNew'</tt> for obtaining write-before-read
--   semantics like this: <tt>readNew' clk (blockRamFilePow2' clk file) rd
--   wrM</tt>.</li>
--   <li>See <a>Clash.Prelude.BlockRam.File#usingramfiles</a> for more
--   information on how to instantiate a Block RAM with the contents of a
--   data file.</li>
--   <li>See <a>Clash.Sized.Fixed#creatingdatafiles</a> for ideas on how to
--   create your own data files.</li>
--   </ul>
blockRamFilePow2 :: forall domain gated n m. (KnownNat m, KnownNat n, HiddenClock domain gated, HasCallStack) => FilePath -> Signal domain (Unsigned n) -> Signal domain (Maybe (Unsigned n, BitVector m)) -> Signal domain (BitVector m)

-- | Create read-after-write blockRAM from a read-before-write one
--   (synchronised to system clock)
--   
--   <pre>
--   &gt;&gt;&gt; import Clash.Prelude
--   
--   &gt;&gt;&gt; :t readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--   readNew (blockRam (0 :&gt; 1 :&gt; Nil))
--     :: ...
--        ... =&gt;
--        Signal domain addr
--        -&gt; Signal domain (Maybe (addr, a)) -&gt; Signal domain a
--   </pre>
readNew :: (Eq addr, HiddenClockReset domain gated synchronous) => (Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a) -> Signal domain addr -> Signal domain (Maybe (addr, a)) -> Signal domain a

-- | Give a window over a <a>Signal</a>
--   
--   <pre>
--   window4 :: HiddenClockReset domain gated synchronous
--           =&gt; Signal domain Int -&gt; Vec 4 (Signal domain Int)
--   window4 = window
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB window4 [1::Int,2,3,4,5] :: [Vec 4 Int]
--   [&lt;1,0,0,0&gt;,&lt;2,1,0,0&gt;,&lt;3,2,1,0&gt;,&lt;4,3,2,1&gt;,&lt;5,4,3,2&gt;...
--   ...
--   </pre>
window :: (KnownNat n, Default a, HiddenClockReset domain gated synchronous) => Signal domain a -> Vec (n + 1) (Signal domain a)

-- | Give a delayed window over a <a>Signal</a>
--   
--   <pre>
--   windowD3 :: HiddenClockReset domain gated synchronous
--            =&gt; Signal domain Int -&gt; Vec 3 (Signal domain Int)
--   windowD3 = windowD
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; simulateB windowD3 [1::Int,2,3,4] :: [Vec 3 Int]
--   [&lt;0,0,0&gt;,&lt;1,0,0&gt;,&lt;2,1,0&gt;,&lt;3,2,1&gt;,&lt;4,3,2&gt;...
--   ...
--   </pre>
windowD :: (KnownNat n, Default a, HiddenClockReset domain gated synchronous) => Signal domain a -> Vec (n + 1) (Signal domain a)

-- | Give a pulse when the <a>Signal</a> goes from <a>minBound</a> to
--   <a>maxBound</a>
isRising :: (HiddenClockReset domain gated synchronous, Bounded a, Eq a) => a -> Signal domain a -> Signal domain Bool

-- | Give a pulse when the <a>Signal</a> goes from <a>maxBound</a> to
--   <a>minBound</a>
isFalling :: (HiddenClockReset domain gated synchronous, Bounded a, Eq a) => a -> Signal domain a -> Signal domain Bool

-- | Give a pulse every <tt>n</tt> clock cycles. This is a useful helper
--   function when combined with functions like <tt><a>regEn</a></tt> or
--   <tt><a>mux</a></tt>, in order to delay a register by a known amount.
--   
--   To be precise: the given signal will be <tt><a>False</a></tt> for the
--   next <tt>n-1</tt> cycles, followed by a single <tt><a>True</a></tt>
--   value:
--   
--   <pre>
--   &gt;&gt;&gt; Prelude.last (sampleN 1024 (riseEvery d1024)) == True
--   True
--   
--   &gt;&gt;&gt; Prelude.or (sampleN 1023 (riseEvery d1024)) == False
--   True
--   </pre>
--   
--   For example, to update a counter once every 10 million cycles:
--   
--   <pre>
--   counter = <a>regEn</a> 0 (<a>riseEvery</a> (<a>SNat</a> :: <a>SNat</a> 10000000)) (counter + 1)
--   </pre>
riseEvery :: HiddenClockReset domain gated synchronous => SNat n -> Signal domain Bool

-- | Oscillate a <tt><a>Bool</a></tt> for a given number of cycles. This is
--   a convenient function when combined with something like
--   <tt><a>regEn</a></tt>, as it allows you to easily hold a register
--   value for a given number of cycles. The input <tt><a>Bool</a></tt>
--   determines what the initial value is.
--   
--   To oscillate on an interval of 5 cycles:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 10 (oscillate False d5)
--   [False,False,False,False,False,True,True,True,True,True]
--   </pre>
--   
--   To oscillate between <tt><a>True</a></tt> and <tt><a>False</a></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; sampleN 10 (oscillate False d1)
--   [False,True,False,True,False,True,False,True,False,True]
--   </pre>
--   
--   An alternative definition for the above could be:
--   
--   <pre>
--   &gt;&gt;&gt; let osc' = register False (not &lt;$&gt; osc')
--   
--   &gt;&gt;&gt; let sample' = sampleN 200
--   
--   &gt;&gt;&gt; sample' (oscillate False d1) == sample' osc'
--   True
--   </pre>
oscillate :: HiddenClockReset domain gated synchronous => Bool -> SNat n -> Signal domain Bool

-- | A <a>Lift</a> instance can have any of its values turned into a
--   Template Haskell expression. This is needed when a value used within a
--   Template Haskell quotation is bound outside the Oxford brackets
--   (<tt>[| ... |]</tt>) but not at the top level. As an example:
--   
--   <pre>
--   add1 :: Int -&gt; Q Exp
--   add1 x = [| x + 1 |]
--   </pre>
--   
--   Template Haskell has no way of knowing what value <tt>x</tt> will take
--   on at splice-time, so it requires the type of <tt>x</tt> to be an
--   instance of <a>Lift</a>.
--   
--   A <a>Lift</a> instance must satisfy <tt>$(lift x) ≡ x</tt> for all
--   <tt>x</tt>, where <tt>$(...)</tt> is a Template Haskell splice.
--   
--   <a>Lift</a> instances can be derived automatically by use of the
--   <tt>-XDeriveLift</tt> GHC language extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveLift #-}
--   module Foo where
--   
--   import Language.Haskell.TH.Syntax
--   
--   data Bar a = Bar1 a (Bar a) | Bar2 String
--     deriving Lift
--   </pre>
class Lift t

-- | Turn a value into a Template Haskell expression, suitable for use in a
--   splice.
lift :: Lift t => t -> Q Exp
undefined :: HasCallStack => a

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: () => a -> b -> b

-- | <a>filter</a>, applied to a predicate and a list, returns the list of
--   those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
filter :: () => a -> Bool -> [a] -> [a]

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. Printable types are those that are instances
--   of class <a>Show</a>; <a>print</a> converts values to strings for
--   output using the <a>show</a> operation and adds a newline.
--   
--   For example, a program to print the first 20 integers and their powers
--   of 2 could be written as:
--   
--   <pre>
--   main = print ([(n, 2^n) | n &lt;- [0..19]])
--   </pre>
print :: Show a => a -> IO ()

-- | Extract the first component of a pair.
fst :: () => (a, b) -> a

-- | Extract the second component of a pair.
snd :: () => (a, b) -> b

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
($) :: () => a -> b -> a -> b
infixr 0 $

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt>.
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt>.
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt>.
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt>.
enumFromThenTo :: Enum a => a -> a -> a -> [a]

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
log :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | Fractional numbers, supporting real division.
class Num a => Fractional a

-- | fractional division
(/) :: Fractional a => a -> a -> a

-- | reciprocal fraction
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> a -> m b -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | Fail with a message. This operation is not part of the mathematical
--   definition of a monad, but is invoked on pattern-match failure in a
--   <tt>do</tt> expression.
--   
--   As part of the MonadFail proposal (MFP), this function is moved to its
--   own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
--   details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a

-- | Basic numeric class.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | attempts to parse a value from the front of the string, returning a
--   list of (parsed value, remaining string) pairs. If there is no
--   successful parse, the returned list is empty.
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
readsPrec :: Read a => Int -> ReadS a

-- | The method <a>readList</a> is provided to allow the programmer to give
--   a specialised way of parsing lists of values. For example, this is
--   used by the predefined <a>Read</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be are expected to use
--   double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Efficient, machine-independent access to the components of a
--   floating-point number.
class (RealFrac a, Floating a) => RealFloat a

-- | a constant function, returning the radix of the representation (often
--   <tt>2</tt>)
floatRadix :: RealFloat a => a -> Integer

-- | a constant function, returning the number of digits of
--   <a>floatRadix</a> in the significand
floatDigits :: RealFloat a => a -> Int

-- | a constant function, returning the lowest and highest values the
--   exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)

-- | The function <a>decodeFloat</a> applied to a real floating-point
--   number returns the significand expressed as an <a>Integer</a> and an
--   appropriately scaled exponent (an <a>Int</a>). If
--   <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
--   is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
--   floating-point radix, and furthermore, either <tt>m</tt> and
--   <tt>n</tt> are both zero or else <tt>b^(d-1) &lt;= <a>abs</a> m &lt;
--   b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
--   x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
--   type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
--   (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
--   unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
--   <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
decodeFloat :: RealFloat a => a -> (Integer, Int)

-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
--   sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
--   <tt><tt>uncurry</tt> <a>encodeFloat</a> (<a>decodeFloat</a> x) =
--   x</tt>. <tt><a>encodeFloat</a> m n</tt> is one of the two closest
--   representable floating-point numbers to <tt>m*b^^n</tt> (or
--   <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
--   <tt>m</tt> contains too many bits, the result may be rounded in the
--   wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a

-- | <a>exponent</a> corresponds to the second component of
--   <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
--   nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
--   + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
--   number, it is equal in value to <tt><a>significand</a> x * b ^^
--   <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
--   The behaviour is unspecified on infinite or <tt>NaN</tt> values.
exponent :: RealFloat a => a -> Int

-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
--   interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
--   value <tt>&gt;= 1/b</tt>, where <tt>b</tt> is the floating-point
--   radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
--   values.
significand :: RealFloat a => a -> a

-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a

-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool

-- | <a>True</a> if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool

-- | a version of arctangent taking two real floating-point arguments. For
--   real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
--   computes the angle (from the positive x-axis) of the vector from the
--   origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
--   a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
--   Common Lisp semantics for the origin when signed zeroes are supported.
--   <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
--   <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
--   y</tt>. A default definition of <a>atan2</a> is provided, but
--   implementors can provide a more accurate implementation.
atan2 :: RealFloat a => a -> a -> a

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | Convert a value to a readable <a>String</a>.
--   
--   <a>showsPrec</a> should satisfy the law
--   
--   <pre>
--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--   </pre>
--   
--   Derived instances of <a>Read</a> and <a>Show</a> satisfy the
--   following:
--   
--   <ul>
--   <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
--   (<a>showsPrec</a> d x ""))</tt>.</li>
--   </ul>
--   
--   That is, <a>readsPrec</a> parses the string produced by
--   <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
--   with.
showsPrec :: Show a => Int -> a -> ShowS

-- | A specialised variant of <a>showsPrec</a>, using precedence context
--   zero, and returning an ordinary <a>String</a>.
show :: Show a => a -> String

-- | The method <a>showList</a> is provided to allow the programmer to give
--   a specialised way of showing lists of values. For example, this is
--   used by the predefined <a>Show</a> instance of the <a>Char</a> type,
--   where values of type <a>String</a> should be shown in double quotes,
--   rather than between square brackets.
showList :: Show a => [a] -> ShowS

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <tt>&lt;$&gt;</tt> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a>
--   v = v</pre></li>
--   <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i><i>interchange</i></i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: * -> *)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
(<*>) :: Applicative f => f a -> b -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => a -> m -> t a -> m

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool

-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a

-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a

-- | The <a>sum</a> function computes the sum of the numbers of a
--   structure.
sum :: (Foldable t, Num a) => t a -> a

-- | The <a>product</a> function computes the product of the numbers of a
--   structure.
product :: (Foldable t, Num a) => t a -> a

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
--   <a>traverse</a> (t . f)</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
--   Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
--   <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
--   <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
--   <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
--   transformation <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
--   = Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
--   Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <ul>
--   <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre>t (x <a>&lt;*&gt;</a> y) = t x <a>&lt;*&gt;</a> t
--   y</pre></li>
--   </ul>
--   
--   and the identity functor <tt>Identity</tt> and composition of functors
--   <tt>Compose</tt> are defined as
--   
--   <pre>
--   newtype Identity a = Identity a
--   
--   instance Functor Identity where
--     fmap f (Identity x) = Identity (f x)
--   
--   instance Applicative Identity where
--     pure x = Identity x
--     Identity f &lt;*&gt; Identity x = Identity (f x)
--   
--   newtype Compose f g a = Compose (f (g a))
--   
--   instance (Functor f, Functor g) =&gt; Functor (Compose f g) where
--     fmap f (Compose x) = Compose (fmap (fmap f) x)
--   
--   instance (Applicative f, Applicative g) =&gt; Applicative (Compose f g) where
--     pure x = Compose (pure (pure x))
--     Compose f &lt;*&gt; Compose x = Compose ((&lt;*&gt;) &lt;$&gt; f &lt;*&gt; x)
--   </pre>
--   
--   (The naturality law is implied by parametricity.)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
class (Functor t, Foldable t) => Traversable (t :: * -> *)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => a -> f b -> t a -> f t b

-- | Evaluate each action in the structure from left to right, and and
--   collect the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t f a -> f t a

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the associativity law:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</pre></li>
--   </ul>
class Semigroup a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> <a>mempty</a> = x</pre></li>
--   <li><pre><a>mempty</a> <a>&lt;&gt;</a> x = x</pre></li>
--   <li><tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a> law)</li>
--   <li><pre><a>mconcat</a> = <a>foldr</a> '(&lt;&gt;)'
--   <a>mempty</a></pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = '(&lt;&gt;)'</tt> since
--   <i>base-4.11.0.0</i>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
--   <tt>chr</tt>).
data Char

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <tt>&gt;&gt;</tt> and <tt>&gt;&gt;=</tt>
--   operations from the <tt>Monad</tt> class.
data IO a

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
type String = [Char]

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: () => a -> a

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <tt>length</tt> function (if we have a <a>String</a>) or the
--   "times-two" function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: () => a -> c -> b -> c -> Either a b -> c

-- | The <a>readIO</a> function is similar to <a>read</a> except that it
--   signals parse failure to the <a>IO</a> monad instead of terminating
--   the program.
readIO :: Read a => String -> IO a

-- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>.
readLn :: Read a => IO a

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the string <tt>str</tt>, to the file <tt>file</tt>.
--   
--   Note that <a>writeFile</a> and <a>appendFile</a> write a literal
--   string to a file. To write a value of any printable type, as with
--   <a>print</a>, use the <a>show</a> function to convert the value to a
--   string first.
--   
--   <pre>
--   main = appendFile "squares" (show [(x,x*x) | x &lt;- [0,0.1..2]])
--   </pre>
appendFile :: FilePath -> String -> IO ()

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The <a>interact</a> function takes a function of type
--   <tt>String-&gt;String</tt> as its argument. The entire input from the
--   standard input device is passed to this function as its argument, and
--   the resulting string is output on the standard output device.
interact :: String -> String -> IO ()

-- | The <a>getContents</a> operation returns all user input as a single
--   string, which is read lazily as it is needed (same as
--   <a>hGetContents</a> <a>stdin</a>).
getContents :: IO String

-- | Read a line from the standard input device (same as <a>hGetLine</a>
--   <a>stdin</a>).
getLine :: IO String

-- | Read a character from the standard input device (same as
--   <a>hGetChar</a> <a>stdin</a>).
getChar :: IO Char

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Write a string to the standard output device (same as <a>hPutStr</a>
--   <a>stdout</a>).
putStr :: String -> IO ()

-- | Write a character to the standard output device (same as
--   <a>hPutChar</a> <a>stdout</a>).
putChar :: Char -> IO ()

-- | Raise an <a>IOError</a> in the <a>IO</a> monad.
ioError :: () => IOError -> IO a

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | Construct an <a>IOError</a> value with a string describing the error.
--   The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a>
--   class raises a <a>userError</a>, thus:
--   
--   <pre>
--   instance Monad IO where
--     ...
--     fail s = ioError (userError s)
--   </pre>
userError :: String -> IOError

-- | The Haskell 2010 type for exceptions in the <a>IO</a> monad. Any I/O
--   operation may raise an <a>IOError</a> instead of returning a result.
--   For a more general type of exception, including also those that arise
--   in pure code, see <a>Exception</a>.
--   
--   In Haskell 2010, this is an opaque type.
type IOError = IOException

-- | <a>notElem</a> is the negation of <a>elem</a>.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => a -> Bool -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => a -> Bool -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => a -> [b] -> t a -> [b]

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words
--   with separating spaces.
--   
--   <pre>
--   &gt;&gt;&gt; unwords ["Lorem", "ipsum", "dolor"]
--   "Lorem ipsum dolor"
--   </pre>
unwords :: [String] -> String

-- | <a>words</a> breaks a string up into a list of words, which were
--   delimited by white space.
--   
--   <pre>
--   &gt;&gt;&gt; words "Lorem ipsum\ndolor"
--   ["Lorem","ipsum","dolor"]
--   </pre>
words :: String -> [String]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
--   
--   <pre>
--   &gt;&gt;&gt; unlines ["Hello", "World", "!"]
--   "Hello\nWorld\n!\n"
--   </pre>
unlines :: [String] -> String

-- | <a>lines</a> breaks a string up into a list of strings at newline
--   characters. The resulting strings do not contain newlines.
--   
--   Note that after splitting the string at newline characters, the last
--   part of the string is considered a line even if it doesn't end with a
--   newline. For example,
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "\n"
--   [""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n"
--   ["one"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\n\n"
--   ["one",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo"
--   ["one","two"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lines "one\ntwo\n"
--   ["one","two"]
--   </pre>
--   
--   Thus <tt><a>lines</a> s</tt> contains at least as many elements as
--   newlines in <tt>s</tt>.
lines :: String -> [String]

-- | The <a>read</a> function reads input from a string, which must be
--   completely consumed by the input process. <a>read</a> fails with an
--   <a>error</a> if the parse is unsuccessful, and it is therefore
--   discouraged from being used in real applications. Use <a>readMaybe</a>
--   or <a>readEither</a> for safe alternatives.
--   
--   <pre>
--   &gt;&gt;&gt; read "123" :: Int
--   123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--   </pre>
read :: Read a => String -> a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | The <a>lex</a> function reads a single lexeme from the input,
--   discarding initial white space, and returning the characters that
--   constitute the lexeme. If the input string contains only white space,
--   <a>lex</a> returns a single successful `lexeme' consisting of the
--   empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is
--   no legal lexeme at the beginning of the input string, <a>lex</a> fails
--   (i.e. returns <tt>[]</tt>).
--   
--   This lexer is not completely faithful to the Haskell lexical syntax in
--   the following respects:
--   
--   <ul>
--   <li>Qualified names are not handled properly</li>
--   <li>Octal and hexadecimal numerics are not recognized as a single
--   token</li>
--   <li>Comments are not treated properly</li>
--   </ul>
lex :: ReadS String

-- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses,
--   but surrounded with parentheses.
--   
--   <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt>
--   parses, but optionally surrounded with parentheses.
readParen :: () => Bool -> ReadS a -> ReadS a

-- | A parser for a type <tt>a</tt>, represented as a function that takes a
--   <a>String</a> and returns a list of possible parses as
--   <tt>(a,<a>String</a>)</tt> pairs.
--   
--   Note that this kind of backtracking parser is very inefficient;
--   reading a large structure may be quite slow (cf <a>ReadP</a>).
type ReadS a = String -> [(a, String)]

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <tt>$</tt>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <tt>$</tt> is function application, <a>&lt;$&gt;</a> is
--   function application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
--   <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
--   an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
--   <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <tt>even</tt> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => a -> b -> f a -> f b
infixl 4 <$>

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool

-- | utility function that surrounds the inner show function with
--   parentheses when the <a>Bool</a> parameter is <a>True</a>.
showParen :: Bool -> ShowS -> ShowS

-- | utility function converting a <a>String</a> to a show function that
--   simply prepends the string unchanged.
showString :: String -> ShowS

-- | utility function converting a <a>Char</a> to a show function that
--   simply prepends the character unchanged.
showChar :: Char -> ShowS

-- | equivalent to <a>showsPrec</a> with a precedence of 0.
shows :: Show a => a -> ShowS

-- | The <tt>shows</tt> functions return a function that prepends the
--   output <a>String</a> to an existing <a>String</a>. This allows
--   constant-time concatenation of results using function composition.
type ShowS = String -> String

-- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association
--   list.
lookup :: Eq a => a -> [(a, b)] -> Maybe b

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>,
--   returns a tuple where first element is longest prefix (possibly empty)
--   of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element
--   is the remainder of the list:
--   
--   <pre>
--   span (&lt; 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
--   span (&lt; 9) [1,2,3] == ([1,2,3],[])
--   span (&lt; 0) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs,
--   <a>dropWhile</a> p xs)</tt>
span :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: () => [a] -> [a]

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: () => a -> a -> a -> [a] -> [a]

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: () => a -> a -> a -> [a] -> [a]

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
--   n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
--   we have <a>Nothing</a>, we return the empty string instead of (for
--   example) "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: () => b -> a -> b -> Maybe a -> b

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: () => a -> b -> c -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: () => (a, b) -> c -> a -> b -> c

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: () => a -> a -> a

-- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt>
--   until <tt>p</tt> holds.
until :: () => a -> Bool -> a -> a -> a -> a

-- | Strict (call-by-value) application operator. It takes a function and
--   an argument, evaluates the argument to weak head normal form (WHNF),
--   then calls the function with that value.
($!) :: () => a -> b -> a -> b
infixr 0 $!

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: () => a -> b -> c -> b -> a -> c

-- | Function composition.
(.) :: () => b -> c -> a -> b -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: () => a -> b -> a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => a -> m b -> m a -> m b
infixr 1 =<<

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: () => [Char] -> a

-- | <a>error</a> stops execution and displays an error message.
error :: HasCallStack => [Char] -> a

-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "not"
not :: Bool -> Bool


module Clash.Tutorial


module Clash.Examples


-- | We simulate DDR signal by using <a>Signal</a>s which have exactly half
--   the period (or double the speed) of our normal <a>Signal</a>s.
--   
--   The primives in this module can be used to produce of consume DDR
--   signals.
--   
--   DDR signals are not meant to be used internally in a design, but only
--   to communicate with the outside world.
--   
--   In some cases hardware specific DDR IN registers can be infered by
--   synthesis tools from these generic primitives. But to be sure your
--   design will synthesize to dedicated hardware resources use the
--   functions from <a>Clash.Intel.DDR</a> or <a>Clash.Xilinx.DDR</a>.
module Clash.Explicit.DDR

-- | DDR input primitive
--   
--   Consumes a DDR input signal and produces a regular signal containing a
--   pair of values.
ddrIn :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast)) => Clock slow gated -> Reset slow synchronous -> (a, a, a) -> Signal fast a -> Signal slow (a, a)

-- | DDR output primitive
--   
--   Produces a DDR output signal from a normal signal of pairs of input.
ddrOut :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast)) => Clock slow gated -> Reset slow synchronous -> a -> Signal slow (a, a) -> Signal fast a
ddrIn# :: forall a slow fast n pFast gated synchronous. (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast)) => Clock slow gated -> Reset slow synchronous -> a -> a -> a -> Signal fast a -> Signal slow (a, a)
ddrOut# :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast)) => Clock slow gated -> Reset slow synchronous -> a -> Signal slow a -> Signal slow a -> Signal fast a


-- | DDR primitives for Intel FPGAs using ALTDDIO primitives.
--   
--   For general information about DDR primitives see
--   <a>Clash.Explicit.DDR</a>.
--   
--   Note that a synchronous reset is only available on certain devices,
--   see ALTDDIO userguide for the specifics:
--   https:/<i>www.altera.com</i>content<i>dam</i>altera-www<i>global</i>en_US<i>pdfs</i>literature<i>ug</i>ug_altddio.pdf
module Clash.Intel.DDR

-- | Intel specific variant of <a>ddrIn</a> implemented using the
--   ALTDDIO_IN IP core.
--   
--   Reset values are <tt>0</tt>
altddioIn :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast), KnownNat m) => SSymbol deviceFamily -> Clock slow gated -> Reset slow synchronous -> Signal fast (BitVector m) -> Signal slow (BitVector m, BitVector m)

-- | Intel specific variant of <a>ddrOut</a> implemented using the
--   ALTDDIO_OUT IP core.
--   
--   Reset value is <tt>0</tt>
altddioOut :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast), KnownNat m) => SSymbol deviceFamily -> Clock slow gated -> Reset slow synchronous -> Signal slow (BitVector m, BitVector m) -> Signal fast (BitVector m)


-- | PLL and other clock-related components for Xilinx FPGAs
module Clash.Xilinx.ClockGen

-- | A clock source that corresponds to the Xilinx PLL/MMCM component
--   created with the "Clock Wizard" with settings to provide a stable
--   <a>Clock</a> from a single free-running input
--   
--   Only works when configured with:
--   
--   <ul>
--   <li>1 reference clock</li>
--   <li>1 output clock</li>
--   <li>a reset port</li>
--   <li>a locked port</li>
--   </ul>
--   
--   You must use type applications to specify the output clock domain,
--   e.g.:
--   
--   <pre>
--   type Dom100MHz = Dom "A" 10000
--   
--   -- outputs a clock running at 100 MHz
--   clockWizard @<tt>Dom100MHz (SSymbol </tt>@"clkWizard50to100") clk50 rst
--   </pre>
clockWizard :: forall pllOut pllIn name. SSymbol name -> Clock pllIn  'Source -> Reset pllIn  'Asynchronous -> (Clock pllOut  'Source, Signal pllOut Bool)

-- | A clock source that corresponds to the Xilinx PLL/MMCM component
--   created with the "Clock Wizard", with settings to provide a stable
--   <a>Clock</a> from differential free-running inputs.
--   
--   Only works when configured with:
--   
--   <ul>
--   <li>1 differential reference pair</li>
--   <li>1 output clock</li>
--   <li>a reset port</li>
--   <li>a locked port</li>
--   </ul>
--   
--   You must use type applications to specify the output clock domain,
--   e.g.:
--   
--   <pre>
--   type Dom100MHz = Dom "A" 10000
--   
--   -- outputs a clock running at 100 MHz
--   clockWizardDifferential @<tt>Dom100MHz (SSymbol </tt>@"clkWizardD50to100") clk50N clk50P rst
--   </pre>
clockWizardDifferential :: forall pllOut pllIn name. SSymbol name -> Clock pllIn  'Source -> Clock pllIn  'Source -> Reset pllIn  'Asynchronous -> (Clock pllOut  'Source, Signal pllOut Bool)


-- | DDR primitives for Xilinx FPGAs
--   
--   For general information about DDR primitives see
--   <a>Clash.Explicit.DDR</a>.
--   
--   For more information about the Xilinx DDR primitives see: * Vivado
--   Design Suite 7 Series FPGA and Zynq-7000 All Programmable SoC
--   Libraries Guide, UG953 (v2017.2) June 7, 2016, p294-296,p404-406,
--   <a>https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_2/ug953-vivado-7series-libraries.pdf</a>
module Clash.Xilinx.DDR

-- | Xilinx specific variant of <a>ddrIn</a> implementend using the Xilinx
--   IDDR primitive.
--   
--   Reset values are <tt>0</tt>
iddr :: (HasCallStack, fast ~  'Dom n pFast, slow ~  'Dom n (2 * pFast), KnownNat m) => Clock slow gated -> Reset slow synchronous -> Signal fast (BitVector m) -> Signal slow ((BitVector m), (BitVector m))

-- | Xilinx specific variant of <a>ddrOut</a> implementend using the Xilinx
--   ODDR primitive.
--   
--   Reset value is <tt>0</tt>
oddr :: (slow ~  'Dom n (2 * pFast), fast ~  'Dom n pFast, KnownNat m) => Clock slow gated -> Reset slow synchronous -> Signal slow (BitVector m, BitVector m) -> Signal fast (BitVector m)
