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


-- | Virtual Rubik's cube of arbitrary size.
--   
--   Provides virtual model of NxNxN Rubik's cube and console visualization
--   for 2x2x2, 3x3x3 ,4x4x4, and 5x5x5. Console visualization is choosen
--   in the interest of portability. Virtual cube can be constructed from
--   the state of a physical cube. Support for a two phase algorithm will
--   be given in a future release for cubes of size 3x3x3 to find the
--   smallest number of moves which solve the cube. The Rubik's cube
--   exhibits many non-trival aspects of group theory. The package comes
--   with an executable <a>hcube</a>. The command ./hcube 5 will create a
--   5x5x5 cube.
@package hcube
@version 0.1.0


module HCube.Data
newtype TestNumb
TestNumb :: Int -> TestNumb

-- | Integer type used in hcube.
type Numb = Int

-- | Physical size of cube. For example a value of 3 refers to original
--   3x3x3 Rubik's cube.
type Size = Numb

-- | Point is used in transformations of cubies in a two dimensional plane.
type Point = (Numb, Numb)

-- | Vector which orientation group matrices act on. Also used for
--   calculating new cubie positions.
type Vec = (Numb, Numb, Numb)
type Format = String

-- | String with each character representing a color of a physical cubie.
type ColorTag = String
type Projection = [(Numb, Side)]

-- | Type used to specify state of physical cube.
type CubeSurf = [(Side, [Color])]

-- | Matrices in hcube are constructed from column vectors. The third
--   vector is often chosen as the cross product of the first two such that
--   the determinate of the matrix is one.
data Matrix
Matrix :: Vec -> Vec -> Vec -> Matrix

-- | Used for simplistic processing of console commands.
data Command
Projection :: View -> Command
Operation :: [Rotation] -> Command
Undo :: Command
Help :: Command
Quit :: Command
NoCommand :: Command

-- | Left and right 3D view of cube.
data View
LeftV :: View
RightV :: View

-- | Used by Template to map logical structure of cube to display views.
data ViewAssociation
Sur :: (Numb, Side) -> ViewAssociation
Ide :: Numb -> ViewAssociation
Ori :: Numb -> ViewAssociation

-- | Defines a rotation of an arbitrary cube slice.
data Rotation
Rotation :: Slab -> Direction -> Numb -> Rotation
RotateCube :: Slab -> Direction -> Rotation

-- | Defines direction of slab movement.
data Direction
Clockwise :: Direction
Counter :: Direction
Twice :: Direction
NoDir :: Direction

-- | Defines an axis for slab movement.
data Slab
Layer :: Slab
HSlice :: Slab
VSlice :: Slab
NoSlab :: Slab

-- | Sides of a cube.
data Side
UpS :: Side
DownS :: Side
FrontS :: Side
BackS :: Side
LeftS :: Side
RightS :: Side
NoSide :: Side

-- | Represents the color of a cubie face.
data Color
White :: Color
Yellow :: Color
Orange :: Color
Red :: Color
Blue :: Color
Green :: Color
NoColor :: Color
data ActualCube
ActualCube :: Color -> Color -> Color -> Color -> Color -> Color -> ActualCube
up :: ActualCube -> Color
front :: ActualCube -> Color
down :: ActualCube -> Color
back :: ActualCube -> Color
left :: ActualCube -> Color
right :: ActualCube -> Color

-- | Represents the color white. Modify if the physical cube uses a
--   different coloring scheme
whiteC :: [Char]
yellowC :: [Char]
orangeC :: [Char]
redC :: [Char]
blueC :: [Char]
greenC :: [Char]
noC :: [Char]

-- | Gives inverse of a cube operation.
invOpp :: Rotation -> Rotation

-- | Reverses direction of rotation.
invDir :: Direction -> Direction

-- | Associates a side of a solved cube to a color.
sideToColor :: Side -> Color

-- | Inverse of sideToColor
colorToSide :: Color -> Side
instance Integral TestNumb
instance Enum TestNumb
instance Num TestNumb
instance Real TestNumb
instance Eq TestNumb
instance Ord TestNumb
instance Read TestNumb
instance Show TestNumb
instance Show Matrix
instance Show View
instance Read View
instance Eq View
instance Show Direction
instance Read Direction
instance Eq Direction
instance Show Slab
instance Read Slab
instance Eq Slab
instance Show Rotation
instance Read Rotation
instance Eq Rotation
instance Show Side
instance Read Side
instance Eq Side
instance Ord Side
instance Read Color
instance Eq Color
instance Show ActualCube
instance Read ActualCube
instance Eq ActualCube
instance Show Color

module HCube.Common
getLine2 :: IO [Char]
twoPagesOnOne :: String -> [String] -> [String]
fourPagesOnOne :: String -> [String] -> [String]
padR :: Int -> String -> String
padL :: Int -> String -> String
prShow :: Show a => Int -> a -> String
plShow :: Show a => Int -> a -> String


-- | Common utility functions, simple linear algebra.
module HCube.Utility

-- | Multiple a matrix on the left side of a vector.
(|*|) :: Matrix -> Vec -> Vec

-- | Multiple two matrices.
(|**|) :: Matrix -> Matrix -> Matrix

-- | Multiple a matrix by a scalar.
multMatrix :: Numb -> Matrix -> Matrix

-- | The cofactor of a matrix.
cofactors :: Matrix -> Matrix

-- | Transpose of a matrix.
transposeM :: Matrix -> Matrix

-- | Inverse of a matrix.
inverse :: Matrix -> Matrix

-- | Display a matrix.
showM :: Matrix -> String
doM :: Monad m => (a -> Bool) -> (a -> m a) -> a -> m a
(~>) :: Monad m => m a -> (a -> b -> m b) -> b -> m b
(~|) :: Monad m => (a -> m b) -> a -> m a
(<*) :: Monad m => m a -> m b -> m a
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]
listToMaybe :: [a] -> Maybe a

-- | A safe form of read.
maybeRead :: String -> Maybe Int

-- | Applies a function on the domain of Side x Side.
spanFaces :: (Enum a, Num a, Ord b) => (Side -> Side -> b) -> [(a, b)]

-- | List of the sides.
sides :: [Side]

-- | List of the vectors.
vecs :: [Vec]

-- | Multiple a vector by a scalar.
multVec :: Numb -> Vec -> Vec

-- | Convert a function with two vector arguments to one accepting a list
--   of vectors.
mapVec :: (Vec -> Vec -> a) -> [Vec] -> a

-- | The determinate of a matrix.
det :: Matrix -> Int

-- | Calculate the determinate of a matrix constructed by three column
--   vectors.
vecDet :: Vec -> Vec -> Vec -> Int

-- | Multiple a matrix by a scalar.
matrixMult :: Matrix -> Int -> Matrix

-- | The cross product of two vectors.
cross :: Vec -> Vec -> Vec

-- | Vector multipled by scalar -1.
minus :: Vec -> Vec

-- | Vectors we are interested in only have one non zero component.
vcomp :: Vec -> Int

-- | Position of non-zero vector component.
vpos :: Vec -> Int

-- | The dot product of two vectors.
dot :: Vec -> Vec -> Numb
gateMinus :: Numb -> Vec -> Vec
modMinus :: Numb -> Numb -> Vec -> Vec
modNot :: Numb -> Numb -> Numb


-- | Orientation group is used to represent orientation of cubies, and cube
--   as a whole.
module HCube.OrientGroup

-- | Logical extension of Monoid to a group.
class Monoid a => Group a
inv :: Group a => a -> a

-- | Representation of Cubie orientation.
data Orient
Orient :: [Vec] -> Orient

-- | Constructs an element of the orientation group from the name.
cons :: Char -> Orient

-- | Maps an element of the orientation group to a matrix. Orient
--   tranformation matrix is determined by specifing, (1,0,0) goes to v1
--   and (0,1,0) goes to v2.
to :: Orient -> Matrix

-- | Gives the name of an element of the orientation group.
eid :: Orient -> Char

-- | Two vector representation of orientation.
getVec :: Orient -> [Vec]

-- | Inverse of sideToVec.
vecToSide :: Vec -> Side

-- | Associates a side to a vector.
sideToVec :: Side -> Vec

-- | Raw number is an intermediate step in associating two vectors to an
--   orientation. The orientation number 1 corresponds to an orientation of
--   ''a'' and so on.
rawToOrientNumber :: Numb -> Numb

-- | Inverse of rawToOrientNumber
orientNumberToRaw :: Numb -> Numb

-- | Converts the orientation to the raw orientation number.
rawOrientNum :: Orient -> Numb

-- | Maps a function of orientation over orient domain.
spanDomain :: (Enum a, Num a, Ord b) => (Orient -> b) -> [(a, b)]

-- | Inverse of colorToVec.
vecToColor :: Vec -> Color

-- | Gives the color of the side identified by the vector, in a solved
--   state.
colorToVec :: Color -> Vec

-- | List of names for elements of the orientation group.
orientChrDomain :: [Char]
instance Show Orient
instance Read Orient
instance Eq Orient
instance Group Orient
instance Monoid Orient


-- | Exposes virtual cube functionality.
module HCube.Lib

-- | Vitrual Rubik's cube.
data Rubik
Rubik :: Size -> [Cube] -> [Cube] -> [Cube] -> [Cube] -> Bool -> View -> [Rotation] -> Rubik
n :: Rubik -> Size
crn :: Rubik -> [Cube]
edg :: Rubik -> [Cube]
cnt :: Rubik -> [Cube]
hid :: Rubik -> [Cube]
loop :: Rubik -> Bool
view :: Rubik -> View
his :: Rubik -> [Rotation]

-- | Individual cube of Rubik's cube, known as a Cubie.
data Cube
Cube :: Vec -> Orient -> Numb -> Cube
pos :: Cube -> Vec
ori :: Cube -> Orient
cid :: Cube -> Numb

-- | Converts a pseudo-vector representation to a cube id.
posToId :: Size -> Vec -> Numb

-- | Converts a cube id to a pseudo-vector representation.
getPos :: Size -> Numb -> Vec

-- | Converts from a surface view of cube to a cubie view of cube.
consCubeInfo :: Int -> CubeSurf -> [(Int, ActualCube, ColorTag)]

-- | CubeSurf representing a solved cube.
solvedSurf :: Int -> CubeSurf

-- | Maps a face id defined with respect to a side, to the cube id.
cubeIdsOfFace :: Int -> Side -> [Int]

-- | Generates a tuple of cube ids corresponding to (corners, edges,
--   centers, hidden cubies).
cubeTypes :: Size -> ([Int], [Int], [Int], [Int])

-- | Creates a virtual cube in solved state
initCube :: Size -> Rubik

-- | Color of cube id on a face is returned. This function is important for
--   rendering.
getFaceColor :: Rubik -> (Numb, Side) -> String

-- | Returns the cubie at a given position.
getCubeFromPos :: Rubik -> Numb -> Cube

-- | Performs a cube operation on virtual cube. Conceptually this
--   corresponds to multiplying the cube state by an appropriate element of
--   the permutation group. However a vector approach is used here.
doCubeOps :: [Rotation] -> Rubik -> Rubik

-- | Loads cube from a file.
loadCube :: Size -> FilePath -> IO Rubik

-- | Saves cube to a file.
saveCube :: FilePath -> Rubik -> IO ()
instance Show Cube
instance Read Cube
instance Eq Cube
instance Show Rubik
instance Read Rubik
instance Eq Rubik


-- | Generation of permutation representation of cube.
module HCube.Permutation

-- | Map a cube operation to an element of the permutation group.
genPerm :: Size -> (Rubik -> [Cube]) -> Rotation -> Permutation Numb


-- | Console visualization of virtual cube.
module HCube.Template
render :: Rubik -> IO Rubik


-- | Test invariants of hcube.
module HCube.Test
runTests :: IO ()
instance Arbitrary TestNumb


-- | Provides functions for re-constructing internal data representation of
--   virtual cube from a physical cube.
module HCube.Cons

-- | Constructs a virtual cube from a physical cube using CubeSurf.
realToVirtual :: Size -> CubeSurf -> Rubik

-- | Constructs the orientaion of a cubie from the color of two of its
--   faces.
consOrient :: (Side, Color) -> (Side, Color) -> Orient


-- | Module for generating tables exhibiting internals of hcube. See the
--   design directory for output generated by these functions.
module HCube.Theory

-- | Show mapping of cube face to vector and color.
displayColors :: IO ()

-- | Two vectors are required to uniquely determine cube orientation.
--   Orientation is defined as an operation from identity orientation.
--   Right face goes to face represented by vector 1. Back gace goes to
--   face represented by vector 2.
displayOrientVecMapping :: IO ()

-- | Cube orientation can be viewed as a transformation of faces from
--   identity position.
displayOrientTransforms :: IO ()

-- | Matrix representation of oriention group. Right handed coordinate
--   system implies determinate must be one.
displayOrientMatrices :: IO ()

-- | Shows how colors on a cubie are mapped to orientation.
displayColorToOrient :: IO ()

-- | Displays inverses for orientation group.
displayOrientI :: IO ()

-- | Displays multiplication table for orientation group.
displayOrientP :: IO ()

-- | Displays how coloring of cubie is used to determine cube id of cube.
--   Cube id represents position of cubie in solved configuration.
displayColorTags :: Size -> IO ()

-- | Displays mapping of face id to cube id. Face ids are useful when
--   specifing the state of a physical cube.
displayFaceIds :: Size -> IO ()