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


-- | Manipulate patterns in cellular automata, create and parse RLE files
--   
--   This package contains a Pattern type for working with 2-dimensional
--   2-state cellular automata. It also has functions for creating and
--   parsing RLE files. RLE is a textual representation of CA patterns used
--   in applications such as Golly and LifeViewer.
@package ca-patterns
@version 0.1.0.0


-- | The functions in this module allow you to create, transform, and
--   combine CA patterns.
module Data.CA.Pattern

-- | The state of a cell.
data Cell
Dead :: Cell
Alive :: Cell
isDead :: Cell -> Bool
isAlive :: Cell -> Bool

-- | A pattern in a 2-dimensional 2-state cellular automaton.
data Pattern

-- | Get the state of one of the cells in a pattern. <tt>lookup 0 0</tt>
--   returns the cell in the upper-left corner. If the row or column number
--   is out of range, this function will return <a>Dead</a>.
lookup :: Int -> Int -> Pattern -> Cell

-- | Generate a pattern from a function.
generate :: Int -> Int -> (Int -> Int -> Cell) -> Pattern
height :: Pattern -> Int
width :: Pattern -> Int

-- | Get the height and width of a pattern.
dimensions :: Pattern -> (Int, Int)

-- | Test if a pattern is valid, i.e. rectangular. Some of the functions in
--   this module only behave properly on rectangular patterns.
valid :: Pattern -> Bool

-- | Convert a vector of rows into a pattern, assuming the rows are all the
--   same length.
fromRectVector :: Vector (Vector Cell) -> Pattern

-- | Convert a vector of rows into a pattern. If the rows are not all the
--   same length, they will padded with dead cells until the pattern is
--   rectangular.
fromVector :: Vector (Vector Cell) -> Pattern

-- | Convert a pattern into a vector of rows.
toVector :: Pattern -> Vector (Vector Cell)

-- | Convert a list of rows into a pattern, assuming the rows are all the
--   same length.
fromRectList :: [[Cell]] -> Pattern

-- | Convert a list of rows into a pattern. If the rows are not all the
--   same length, they will padded with dead cells until the pattern is
--   rectangular.
fromList :: [[Cell]] -> Pattern

-- | Convert a pattern into a list of rows.
toList :: Pattern -> [[Cell]]

-- | Convert a pattern into text. For example, <tt>toText '.' 'Z'</tt> will
--   replace each dead cell with a <tt>.</tt> and each live cell with a
--   <tt>Z</tt>.
toText :: Char -> Char -> Pattern -> Text

-- | Convert a pattern into a string.
toString :: Char -> Char -> Pattern -> String

-- | Remove rows of dead cells from the top of a pattern.
trimTop :: Pattern -> Pattern

-- | Remove rows of dead cells from the bottom of a pattern.
trimBottom :: Pattern -> Pattern

-- | Remove columns of dead cells from the left side of a pattern.
trimLeft :: Pattern -> Pattern

-- | You get the idea.
trimRight :: Pattern -> Pattern

-- | A composition of <a>trimTop</a>, <a>trimBottom</a>, <a>trimLeft</a>,
--   and <a>trimRight</a>. Removes as many dead cells from the pattern as
--   possible while keeping it rectangular.
trim :: Pattern -> Pattern

-- | Force a pattern to have the given height by removing rows from the
--   bottom or by adding rows of dead cells.
setHeight :: Int -> Pattern -> Pattern

-- | Force a pattern to have the given width by remove columns from the
--   right or by adding columns of dead cells.
setWidth :: Int -> Pattern -> Pattern

-- | Set the height and width of a pattern.
setDimensions :: Int -> Int -> Pattern -> Pattern

-- | Reflect horizontally, switching the left and the right.
reflectX :: Pattern -> Pattern

-- | Reflect vertically, switching the top and the bottom.
reflectY :: Pattern -> Pattern

-- | Rotate counterclockwise by a quarter turn.
rotateL :: Pattern -> Pattern

-- | Rotate clockwise by a quarter turn.
rotateR :: Pattern -> Pattern

-- | Combine two patterns given a vertical and horizontal offset, which
--   describe the displacement of the second pattern relative to the first
--   one.
combine :: Int -> Int -> Pattern -> Pattern -> Pattern
instance GHC.Show.Show Data.CA.Pattern.Cell
instance GHC.Classes.Ord Data.CA.Pattern.Cell
instance GHC.Classes.Eq Data.CA.Pattern.Cell

module Data.CA.List

-- | A list of every possible h by w pattern. This function is necessarily
--   exponential in both arguments, so it's only practical if the
--   dimensions are very small.
withDimensions :: Int -> Int -> [Pattern]

-- | Combine two patterns in multiple ways. Useful for creating a list of
--   spaceship / still life collisions.
--   
--   See <a>combine</a>.
combinations :: (Int, Int) -> (Int, Int) -> Pattern -> Pattern -> [Pattern]


-- | The RLE (run length encoded) format is a common way of representing
--   patterns in life-like cellular automata. RLE files consist of three
--   sections:
--   
--   <ol>
--   <li>Zero or more comment lines beginning with <tt>#</tt></li>
--   <li>A header of the form <tt>x = [width], y = [height], rule =
--   [rule]</tt>. <tt>[width]</tt> and <tt>[height]</tt> are natural
--   numbers, and <tt>[rule]</tt> is the rule the pattern is meant to be
--   run in, such as <tt>B36/S23</tt>. The "rule" field is optional.</li>
--   <li>The content of the pattern. <tt>b</tt> represents a dead cell,
--   <tt>o</tt> represents a live cell, and <tt>$</tt> denotes the end of a
--   row. A run of identical characters can be abbreviated with a number,
--   e.g. <tt>4o</tt> is short for <tt>oooo</tt> (hence the name "run
--   length encoded"). This section must be terminated by a <tt>!</tt>
--   character.</li>
--   </ol>
--   
--   A glider in the Game of Life could be represented like so:
--   
--   <pre>
--   #N glider
--   x = 3, y = 3, rule = B3/S23
--   3o$2bo$bo!
--   </pre>
--   
--   See this <a>LifeWiki article</a> for more information.
module Text.RLE

-- | A string representing a cellular automaton, such as <tt>"B36/S23"</tt>
--   or <tt>"B3/S2-i34q"</tt>.
type Rule = String

-- | Parse an RLE file, returning a <a>Rule</a> (if it exists) and a
--   <a>Pattern</a>. The argument can be <a>String</a>, <tt>Text</tt>, or
--   any other type with a <a>Stream</a> instance.
--   
--   This parser is fairly liberal. Whitespace is allowed everywhere except
--   in the middle of a number or rulestring, and there need not be a
--   newline after the header. Also, text after the final <tt>!</tt>
--   character is ignored.
parse :: Stream s Identity Char => s -> Maybe (Maybe Rule, Pattern)

-- | Convert a <a>Pattern</a> into an RLE. If the first argument is
--   <a>Nothing</a>, the generated RLE will have no "rule" field in its
--   header.
make :: (Semigroup s, IsString s) => Maybe Rule -> Pattern -> s

-- | Convert a list of patterns into RLEs and print them. Example:
--   
--   <pre>
--   import qualified Text.RLE as RLE
--   import Data.CA.List (withDimensions)
--   main = RLE.printAll (Just "B3/S23") (withDimensions 4 4)
--   </pre>
--   
--   The program above will print the RLE of every possible pattern
--   contained in a 4 by 4 square. This data can then be piped into another
--   program such as apgsearch.
printAll :: Maybe Rule -> [Pattern] -> IO ()
instance GHC.Classes.Eq Text.RLE.RunType