-- 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>. Refer to the README file for details.
@package hcube
@version 0.1.1


module HCube.Data

-- | 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 [safe] Show Matrix
instance [safe] Show View
instance [safe] Read View
instance [safe] Eq View
instance [safe] Show Direction
instance [safe] Read Direction
instance [safe] Eq Direction
instance [safe] Show Slab
instance [safe] Read Slab
instance [safe] Eq Slab
instance [safe] Show Rotation
instance [safe] Read Rotation
instance [safe] Eq Rotation
instance [safe] Show Side
instance [safe] Read Side
instance [safe] Eq Side
instance [safe] Ord Side
instance [safe] Read Color
instance [safe] Eq Color
instance [safe] Show ActualCube
instance [safe] Read ActualCube
instance [safe] Eq ActualCube
instance [safe] Show Color


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

-- | Returns square root of argument if argument is a perfect square.
squareRoot :: Int -> Maybe Int

-- | 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 [safe] Show Orient
instance [safe] Read Orient
instance [safe] Eq Orient
instance [safe] Group Orient
instance [safe] 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 [safe] Show Cube
instance [safe] Read Cube
instance [safe] Eq Cube
instance [safe] Show Rubik
instance [safe] Read Rubik
instance [safe] 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 ()


-- | 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 :: CubeSurf -> Rubik
fromPhysical :: FilePath -> IO 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 ()