More documentation in Wml.hs

1 files changed, 81 insertions, 4 deletions

diff --git a/src/Rahm/Desktop/Keys/Wml.hs b/src/Rahm/Desktop/Keys/Wml.hs
index 4e63575..ae71e5f 100644
--- a/src/Rahm/Desktop/Keys/Wml.hs
+++ b/src/Rahm/Desktop/Keys/Wml.hs
@@ -339,30 +339,39 @@ readNextWorkspace =
     macros <- (lift . fromX) $ workspaceMacros <$> XS.get
 
     case (mask, sym, str) of
+      -- Escape kills the "readNextWorkspace" and returns nothing.
+      (_, e, _) | e == xK_Escape -> MaybeT $ return Nothing
+      -- Macros takes precedence over everything.
       (mask, keysym, _) | (Just macro) <- Map.lookup (mask, keysym) macros -> do
         fromMaybeTX $ workspaceForKeysT macro
-      (_, e, _) | e == xK_Escape -> MaybeT $ return Nothing
+
+      -- A single alphanumeric character is the atomic reference to a workspace.
       (_, _, [ch]) | isAlphaNum ch || ch == '*' -> return $ justWorkspace [ch]
+      -- to the non-visible workspace left of the next workspace.
       (_, _, "[") ->
         justWorkspace
           <$> ( lift1 (adjacentWorkspaceNotVisible prev)
                   =<< readNextWorkspaceName
               )
+      -- to the non-visible workspace right of the next workspace
       (_, _, "]") ->
         justWorkspace
           <$> ( lift1 (adjacentWorkspaceNotVisible next)
                   =<< readNextWorkspaceName
               )
+      -- To the left of the next workspace
       (_, _, "(") ->
         justWorkspace
           <$> ( lift1 (adjacentWorkspace prev)
                   =<< readNextWorkspaceName
               )
+      -- To the right of the next workspace
       (_, _, ")") ->
         justWorkspace
           <$> ( lift1 (adjacentWorkspace next)
                   =<< readNextWorkspaceName
               )
+      -- The workspace on the leftmost screen
       (_, _, "^") -> mapMaybeT fromX $
         MaybeT $
           withWindowSet $ \ws ->
@@ -371,16 +380,23 @@ readNextWorkspace =
                   ( justWorkspace . W.tag . W.workspace . snd
                   )
                   . head
-              ) (getHorizontallyOrderedScreens ws)
+              )
+                (getHorizontallyOrderedScreens ws)
+      -- The last workspace in history.
       (_, _, "'") -> fromMaybeTX $ justWorkspace . locationWorkspace <$> MaybeT lastLocation
+      -- The current workspace.
       (_, _, ".") -> mt $ justWorkspace <$> getCurrentWorkspace
+      -- The workspace on the rightmost screen
       (_, _, "$") -> MaybeT $
         fromX $
           withWindowSet $ \ws ->
             return $
               (fmap (justWorkspace . W.tag . W.workspace . snd) . last)
                 (getHorizontallyOrderedScreens ws)
+      -- Modify the next workspace as a "floating" workspace. (Windows sent to
+      -- it will float).
       (_, _, ":") -> floatWorkspace <$> readNextWorkspace
+      -- Workspace to the next screen to the right of the next workspace.
       (_, _, ",") -> do
         ws <- readNextWorkspace
         screens <-
@@ -391,6 +407,8 @@ readNextWorkspace =
         let (_, rest) = break ((== workspaceName ws) . Just) (screens ++ screens)
 
         justWorkspace <$> MaybeT (return $ head $ tail rest)
+
+      -- Workspace to the next screen to the left of the next workspace.
       (_, _, ";") -> do
         ws <- readNextWorkspace
         screens <-
@@ -401,8 +419,12 @@ readNextWorkspace =
         let (front, _) = break ((== workspaceName ws) . Just) (screens ++ screens)
 
         justWorkspace <$> MaybeT (return $ last front)
+
+      -- The workspace with the searched for window.
       (_, _, "/") -> fromMaybeTX $ do
         justWorkspace <$> ((MaybeT . workspaceWithWindow) =<< MaybeT ((head =<<) <$> askWindowId))
+
+      -- The workspace with the next read window on it.
       (_, _, "@") -> do
         loc <- readNextLocationSet
         MaybeT $
@@ -411,13 +433,20 @@ readNextWorkspace =
               win <- locationWindow =<< head loc
               winLocation <- W.findWindow ws win
               justWorkspaceWithPreferredWindow win . W.tag <$> W.getLocationWorkspace winLocation
+
+      -- The accompaning worksapce to the next read workspace.
       (_, _, "~") ->
         justWorkspace . accompaningWorkspace <$> readNextWorkspaceName
+      -- The accompaning workspace to the current workspace (equivalent to ~.)
       (_, _, " ") ->
         mt $
           justWorkspace . accompaningWorkspace <$> getCurrentWorkspace
+      -- The balck hole workspace
       (_, _, "_") -> return blackHoleWorkspace
+      -- The alternate workspace
       (_, _, "-") -> return alternateWorkspace
+      -- If the next two read workspaces are equal, go to the third workspace
+      -- otherwise go to the fourth workspace.
       (_, _, "=") -> do
         ws1 <- readNextWorkspace
         ws2 <- readNextWorkspace
@@ -429,6 +458,9 @@ readNextWorkspace =
           if workspaceName ws1 == workspaceName ws2
             then ws3
             else ws4
+
+      -- If the next read location set is not empty, go to the next read
+      -- workspace, otherwise go to the next-next read workspace.
       (_, _, "?") -> do
         l1 <- readNextLocationSet
 
@@ -449,40 +481,74 @@ readNextLocationSet :: (KeyFeeder m) => MaybeT m [Location]
 readNextLocationSet =
   readNextKey $ \mask sym str ->
     case (mask, sym, str) of
+      -- Escape returns nothing and aborts reading the next location.
       (_, e, _) | e == xK_Escape -> MaybeT $ return Nothing
+
+      -- A character is the base-case. Refers to a collection of windows.
       (_, _, [ch]) | isAlpha ch -> mt $ getMarkedLocations [ch]
+
+      -- Goes to the most recent location in history.
       (_, _, "0") -> (: []) <$> MaybeT (fromX getMostRecentLocationInHistory)
+
+      -- A Digit goes to the past history.
       (_, _, [ch])
         | isDigit ch ->
           (: []) <$> MaybeT (fromX $ pastHistory (ord ch - 0x30))
+
+      -- The current window.
       (_, _, ".") -> (: []) <$> mt getCurrentLocation
+
+      -- The window on the far-left of the screens.
       (_, _, "^") -> (: []) <$> fromMaybeTX farLeftWindow
+
+      -- The windows on the far-right of the screens.
       (_, _, "$") -> (: []) <$> fromMaybeTX farRightWindow
+
+      -- The next location in history.
       (_, _, "\"") -> (: []) <$> MaybeT (fromX nextLocation)
+
+      -- The previous location in history.
       (_, _, "'") -> (: []) <$> MaybeT (fromX lastLocation)
+
+      -- All visible windows.
       (_, _, "*") -> mt $ do
-        -- All visible windows.
         wins <-
           withWindowSet $
             return . concatMap (W.integrate' . W.stack . W.workspace) . W.screens
 
         catMaybes <$> mapM (runMaybeT . windowLocation) wins
+
+      -- The last referenced windows.
       (_, _, "-") ->
         fromMaybeTX $
           mapM windowLocation =<< lift getAlternateWindows
+
+      -- Search for the windows.
       (_, _, "/") ->
         fromMaybeTX $
           mapM windowLocation =<< MaybeT askWindowId
+
+      -- All windows.
       (_, _, "%") -> fromMaybeTX $ do
         ret <- mapM windowLocation =<< lift (withWindowSet (return . sortOn Down . W.allWindows))
         lift $ logs Info "allWindows %s" (intercalate "\n" (map show ret))
         return ret
+
+      -- Windows in a workspace
       (_, _, s)
         | s == "\t" || s == "@" || s == "\n" ->
           (mt . windowsInWorkspace) =<< readNextWorkspaceName
+
+      -- The first window in the next window set.
       (_, _, "!") -> (: []) <$> joinMaybe (head <$> readNextLocationSet)
+
+      -- The windows except the first in a window set.
       (_, _, ",") -> tail <$> readNextLocationSet
+
+      -- The next window set, but reversed
       (_, _, "~") -> reverse <$> readNextLocationSet
+
+      -- All the floating windows
       (_, _, ":") ->
         mt $
           withWindowSet $
@@ -490,24 +556,35 @@ readNextLocationSet =
               . mapM (runMaybeT . windowLocation)
               . Map.keys
               . W.floating
+
+      -- If the next read window set is not empty, then this location
+      -- otherwise the next read location.
       (_, _, "?") -> do
         l1 <- readNextLocationSet
         l2 <- readNextLocationSet
         return $ if null l1 then l2 else l1
+
+      -- The next window set unioned with the next location set
       (_, _, "|") -> do
         l1 <- readNextLocationSet
         l2 <- readNextLocationSet
         return (l1 ++ l2)
+
+      -- Empty window set.
       (_, _, "_") -> return []
+
+      -- The next location set differenced with the next-next location set
       (_, _, "\\") -> do
         l1 <- readNextLocationSet
         l2 <- readNextLocationSet
         return $ filter (not . flip elem l2) l1
+
+      -- The next location set intersected with the next-next location set
       (_, _, "&") -> do
-        -- intersection
         l1 <- readNextLocationSet
         l2 <- readNextLocationSet
         return $ filter (`elem` l2) l1
+
       (mask, keysym, _) -> do
         macro <- (MaybeT . fromX) (Map.lookup (mask, keysym) . windowsetMacros <$> XS.get)
         lift $ fromX $ logs Info "Executing Macro: %s" (show macro)