From 11474f48e1fcd9e27f6dda8aeda1d0568c26d8d4 Mon Sep 17 00:00:00 2001 From: ivanbrennan Date: Sun, 5 Mar 2023 17:47:18 -0500 Subject: [PATCH 1/4] doc: XMonad.Layout.Inspect Describe and document usage. --- XMonad/Layout/Inspect.hs | 56 +++++++++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/XMonad/Layout/Inspect.hs b/XMonad/Layout/Inspect.hs index 4950834aa6..18b93eb8f0 100644 --- a/XMonad/Layout/Inspect.hs +++ b/XMonad/Layout/Inspect.hs @@ -8,6 +8,7 @@ -- | -- Module : XMonad.Layout.Inspect +-- Description : Inspect layout data. -- Copyright : (c) 2020 Tomáš Janoušek -- License : BSD3 -- @@ -15,8 +16,9 @@ -- Stability : experimental -- Portability : unknown -- --- TODO --- +-- Inspect a workspace's layout data. Useful for accessing data contained in +-- layout modifiers. + module XMonad.Layout.Inspect ( -- * Usage -- $usage @@ -36,23 +38,58 @@ import XMonad import qualified XMonad.StackSet as W -- $usage +-- This module provides a way for layout authors to make workspace layout data +-- accessible to end-users. +-- +-- Best explained by example, suppose you've written a layout modifier: +-- +-- > newtype Foo a = Foo String deriving (Read, Show) +-- > instance LayoutModifier Foo a +-- > foo :: LayoutClass l a => String -> l a -> ModifiedLayout Foo l a +-- > foo = ModifiedLayout . Foo +-- +-- To allow users to inspect the string contained in a given workspace's layout, +-- first import this module: +-- +-- > import XMonad.Layout.Inspect +-- +-- Then define instances for 'InspectResult' and 'InspectLayout', and implement +-- getFoo in terms of 'inspectWorkspace': +-- +-- > data GetFoo = GetFoo +-- > type instance InspectResult GetFoo = Alt Maybe String +-- > +-- > instance InspectLayout GetFoo Foo a where +-- > inspectLayout GetFoo (Foo s) = pure s +-- > +-- > getFoo :: (LayoutClass l Window, InspectLayout GetFoo l Window) +-- > => l Window -> WindowSpace -> Maybe String +-- > getFoo l = getAlt . inspectWorkspace l GetFoo +-- +-- An end-user can then call getFoo by passing it the appropriate layout and a +-- given workspace: -- --- TODO: help for users +-- > xFoo :: WindowSpace -> X () +-- > xFoo wsp = do +-- > l <- asks (layoutHook . config) +-- > case getFoo l wsp of +-- > Nothing -> pure () +-- > Just s -> xmessage s --- | TODO +-- | Inspect the layout of the currently focused workspace. inspectCurrent :: (LayoutClass l Window, InspectLayout i l Window) => l Window -> i -> X (InspectResult i) inspectCurrent l i = gets (inspectWorkspace l i . w) where w = W.workspace . W.current . windowset --- | TODO +-- | Inspect the layout of the workspace with a specified tag. inspectTag :: (LayoutClass l Window, InspectLayout i l Window) => l Window -> i -> WorkspaceId -> X (Maybe (InspectResult i)) inspectTag l i t = gets (fmap (inspectWorkspace l i) . mw) where mw = find ((t==) . W.tag) . W.workspaces . windowset --- | TODO +-- | Inspect the layout of a specified workspace. inspectWorkspace :: (LayoutClass l Window, InspectLayout i l Window) => l Window -> i -> WindowSpace -> InspectResult i inspectWorkspace l i = inspectLayout i . asLayout l . W.layout @@ -69,7 +106,12 @@ cast' x | Just HRefl <- ta `eqTypeRep` tb = x type family InspectResult i --- | TODO: for layout/modifier authors +-- | A typeclass defining 'inspectLayout' over monoidal @InspectResult@ types. +-- An overlappable instance provides sensible default behavior, returning +-- 'mempty'. (Specific @InspectResult@ instances may override this by defining +-- their own instance of 'InspectLayout'.) Additionally, an instance is provided +-- for layouts using 'Choose', provided that all the layouts in the 'Choose' are +-- capable of being inspected. class Monoid (InspectResult i) => InspectLayout i l a where inspectLayout :: i -> l a -> InspectResult i From 95a7ca7b966823a8d8af04ff910f78440c06cb06 Mon Sep 17 00:00:00 2001 From: ivanbrennan Date: Mon, 6 Mar 2023 14:05:55 -0500 Subject: [PATCH 2/4] fix(doc): layout arg Attempting to read the layoutHook from config produces a layout wrapped in the Layout existential, so it seems the only way to correctly inspect a layout is by using the same value that was passed to the XConfig constructor, or by recreating an identical value. Otherwise, the type cast fails and we fallback to the OVERLAPPABLE instance for InspectLayout, returning Nothing. --- XMonad/Layout/Inspect.hs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/XMonad/Layout/Inspect.hs b/XMonad/Layout/Inspect.hs index 18b93eb8f0..222f118b22 100644 --- a/XMonad/Layout/Inspect.hs +++ b/XMonad/Layout/Inspect.hs @@ -69,10 +69,13 @@ import qualified XMonad.StackSet as W -- An end-user can then call getFoo by passing it the appropriate layout and a -- given workspace: -- +-- > myLayoutHook = ... +-- > +-- > main = xmonad $ def { layoutHook = myLayoutHook, ... +-- > -- > xFoo :: WindowSpace -> X () -- > xFoo wsp = do --- > l <- asks (layoutHook . config) --- > case getFoo l wsp of +-- > case getFoo myLayoutHook wsp of -- > Nothing -> pure () -- > Just s -> xmessage s From 0fb8b4201245b7429f521a721114d5968e9b3737 Mon Sep 17 00:00:00 2001 From: ivanbrennan Date: Mon, 6 Mar 2023 15:59:51 -0500 Subject: [PATCH 3/4] doc: s/data/state/ Emphasize the fact that we're trying to access runtime state, as opposed to static data. --- XMonad/Layout/Inspect.hs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/XMonad/Layout/Inspect.hs b/XMonad/Layout/Inspect.hs index 222f118b22..99dbabaa17 100644 --- a/XMonad/Layout/Inspect.hs +++ b/XMonad/Layout/Inspect.hs @@ -8,7 +8,7 @@ -- | -- Module : XMonad.Layout.Inspect --- Description : Inspect layout data. +-- Description : Inspect layout state. -- Copyright : (c) 2020 Tomáš Janoušek -- License : BSD3 -- @@ -16,7 +16,7 @@ -- Stability : experimental -- Portability : unknown -- --- Inspect a workspace's layout data. Useful for accessing data contained in +-- Inspect a workspace's layout state. Useful for accessing state contained in -- layout modifiers. module XMonad.Layout.Inspect ( @@ -38,7 +38,7 @@ import XMonad import qualified XMonad.StackSet as W -- $usage --- This module provides a way for layout authors to make workspace layout data +-- This module provides a way for layout authors to make workspace layout state -- accessible to end-users. -- -- Best explained by example, suppose you've written a layout modifier: From 95706c1d4595ec1d8c9c03cdc94d1b15af8c2b5b Mon Sep 17 00:00:00 2001 From: ivanbrennan Date: Mon, 6 Mar 2023 16:04:38 -0500 Subject: [PATCH 4/4] doc: move instance documentation to the instance Also, omit the Choose documentation, since the type signature pretty much says it all. --- XMonad/Layout/Inspect.hs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/XMonad/Layout/Inspect.hs b/XMonad/Layout/Inspect.hs index 99dbabaa17..439262584f 100644 --- a/XMonad/Layout/Inspect.hs +++ b/XMonad/Layout/Inspect.hs @@ -110,14 +110,12 @@ cast' x | Just HRefl <- ta `eqTypeRep` tb = x type family InspectResult i -- | A typeclass defining 'inspectLayout' over monoidal @InspectResult@ types. --- An overlappable instance provides sensible default behavior, returning --- 'mempty'. (Specific @InspectResult@ instances may override this by defining --- their own instance of 'InspectLayout'.) Additionally, an instance is provided --- for layouts using 'Choose', provided that all the layouts in the 'Choose' are --- capable of being inspected. class Monoid (InspectResult i) => InspectLayout i l a where inspectLayout :: i -> l a -> InspectResult i +-- | An overlappable instance provides sensible default behavior, returning +-- 'mempty'. Specific @InspectResult@ instances may override this by defining +-- their own instance of 'InspectLayout'. instance {-# OVERLAPPABLE #-} Monoid (InspectResult i) => InspectLayout i l a where inspectLayout _ _ = mempty