Add documentation and cleanup

Author: VeryMilkyJoe

plugins/hls-cabal-plugin/src/Ide/Plugin/Cabal.hs

@@ -287,7 +287,6 @@ completion _ide _ complParams = do
     | Just ctx <- context = do
         let completer = contextToCompleter ctx
         completions <- completer completionContext
-        -- genPkgDesc <- readGenericPackageDescription silent fp
         pure $ J.List $ makeCompletionItems completions
     | otherwise = pure $ J.List []
    where

plugins/hls-cabal-plugin/src/Ide/Plugin/Cabal/Completions.hs

@@ -18,6 +18,7 @@ import           Distribution.CabalSpecVersion   (CabalSpecVersion (CabalSpecV2_
                                                   showCabalSpecVersion)
 import           Distribution.Compat.Lens        ((^.))
 import           Ide.Plugin.Cabal.LicenseSuggest (licenseNames)
+import qualified Language.LSP.Types              as Compls (CompletionItem (..))
 import qualified Language.LSP.Types              as J
 import qualified Language.LSP.Types.Lens         as JL
 import qualified Language.LSP.VFS                as VFS
@@ -44,16 +45,17 @@ data CabalCompletionItem = CabalCompletionItem
 
 {- | The context a cursor can be in within a cabal file,
   we can be in stanzas or the top level,
-  and additionally we can be in a context where we have already written a keyword
-  but no value for it yet
+  and additionally we can be in a context where we have already
+  written a keyword but no value for it yet
 -}
 type Context = (LevelContext, KeyWordContext)
 
 -- | Context inside a cabal file, used to decide which keywords to suggest
 data LevelContext
   = -- | Top level context in a cabal file such as 'author'
     TopLevel
-  | -- | Nested context in a cabal file, such as 'library', which has nested keywords, specific to the stanza
+  | -- | Nested context in a cabal file, such as 'library',
+    -- which has nested keywords, specific to the stanza
     Stanza T.Text
   deriving (Eq, Show, Read)
 
@@ -62,7 +64,7 @@ data LevelContext
 -}
 data KeyWordContext
   = -- | Key word context, where a keyword
-    -- occurs right before the current position
+    -- occurs right before the current position,
     -- with no value associated to it
     KeyWord T.Text
   | -- | Keyword context where no keyword occurs
@@ -113,9 +115,10 @@ contextToCompleter (Stanza s, KeyWord kw) =
       Nothing -> noopCompleter
       Just l  -> l
 
-{- | Takes info about the current cursor position, information
-  about the handled cabal file and a set of possible keywords
-  and creates completion suggestions that fit the current input from the given list
+{- | Takes info about the current cursor position,
+  the handled cabal file and a set of possible keywords
+  and creates completion suggestions that fit the current input
+  from the given list
 -}
 makeCompletionItems :: [CabalCompletionItem] -> [J.CompletionItem]
 makeCompletionItems l = map buildCompletion l
@@ -139,15 +142,18 @@ getContext pos ls =
           kwContext <- getKeyWordContext pos ls m
           pure (Stanza s, kwContext)
  where
-  lvlContext = if pos ^. JL.character == 0 then TopLevel else findCurrentLevel (getPreviousLines pos ls)
+  lvlContext =
+    if pos ^. JL.character == 0
+      then TopLevel
+      else currentLevel (previousLines pos ls)
 
 -- ----------------------------------------------------------------
 -- Helper Functions
 -- ----------------------------------------------------------------
 
-{- | Takes a position, a list of lines (representing a file) and a map of keywords as keys
-  and returns a keyword context if there is a keyword from the map before the current position
-  in the given line list
+{- | Takes a position, a list of lines (representing a file)
+  and a map of keywords and returns a keyword context if the
+  previously written keyword matches one in the map
 -}
 getKeyWordContext :: Position -> [T.Text] -> Map T.Text a -> Maybe KeyWordContext
 getKeyWordContext pos ls keywords = do
@@ -157,42 +163,58 @@ getKeyWordContext pos ls keywords = do
       let (whiteSpaces, lastLine) = T.span (== ' ') lastLine'
       let keywordIndentation = T.length whiteSpaces
       let cursorIndentation = fromIntegral (pos ^. JL.character)
-      -- in order to be in a keyword context the cursor needs to be indented more than the keyword
+      -- in order to be in a keyword context the cursor needs
+      -- to be indented more than the keyword
       if cursorIndentation > keywordIndentation
-        then -- if the last thing written was a keyword without a value
+        then
+        -- if the last thing written was a keyword without a value
         case List.find (`T.isPrefixOf` lastLine) (Map.keys keywords) of
           Nothing -> Just None
           Just kw -> Just $ KeyWord kw
         else Just None
  where
   lastNonEmptyLineM = do
     cur <- currentLineM
-    List.find (not . T.null . T.stripEnd) $ cur : getPreviousLines pos ls
+    List.find (not . T.null . T.stripEnd) $ cur : previousLines pos ls
   currentLineM = ls Extra.!? (fromIntegral $ pos ^. JL.line)
 
 {- | Parse the given set of lines (starting before current cursor position
   up to the start of the file) to find the nearest stanza declaration,
-  if none is found we are in the top level
+  if none is found we are in the top level context
 -}
-findCurrentLevel :: [T.Text] -> LevelContext
-findCurrentLevel [] = TopLevel
-findCurrentLevel (cur : xs)
+currentLevel :: [T.Text] -> LevelContext
+currentLevel [] = TopLevel
+currentLevel (cur : xs)
   | Just s <- stanza = Stanza s
-  | otherwise = findCurrentLevel xs
+  | otherwise = currentLevel xs
  where
   stanza = List.find (`T.isPrefixOf` cur) (Map.keys stanzaKeywordMap)
 
+{- | Returns a CabalCompletionItem with the given starting position
+  and text to be inserted,
+  where the displayed text is the same as the inserted text
+-}
+makeSimpleCabalCompletionItem :: Range -> T.Text -> CabalCompletionItem
+makeSimpleCabalCompletionItem r txt = CabalCompletionItem txt Nothing r
+
+{- | Returns a CabalCompletionItem with the given starting position,
+  text to be inserted and text to be displayed in the completion suggestion
+-}
+makeCabalCompletionItem :: Range -> T.Text -> T.Text -> CabalCompletionItem
+makeCabalCompletionItem r insertTxt displayTxt =
+    CabalCompletionItem insertTxt (Just displayTxt) r
+
 {- | Get all lines before the given cursor position in the given file
-  and reverse them in order to traverse backwards starting from the current position
+  and reverse their order to traverse backwards starting from the current position
 -}
-getPreviousLines :: Position -> [T.Text] -> [T.Text]
-getPreviousLines pos ls = reverse $ take (fromIntegral currentLine) ls
+previousLines :: Position -> [T.Text] -> [T.Text]
+previousLines pos ls = reverse $ take (fromIntegral currentLine) ls
  where
   currentLine = pos ^. JL.line
 
 {- | Takes information about the current file's file path,
   the current cursor position in the file
-  and its contents and builds a CabalCompletionItem
+  and its contents; and builds a CabalCompletionItem
   with the prefix up to that cursor position,
   checks whether a suffix needs to be completed,
   and calculates the range in the document in which to complete
@@ -207,56 +229,54 @@ getFilePathCompletionContext dir prefixInfo =
     }
  where
   completionEnd = VFS.cursorPos prefixInfo
-  completionStart = Position (_line completionEnd) (_character completionEnd - (fromIntegral $ T.length filepathPrefix))
-  filepathPrefix = T.takeWhileEnd (not . (`elem` stopConditionChars)) prevLineText
-  (prevLineText, endLineText) = T.splitAt cursorColumn $ VFS.fullLine prefixInfo
-  suffix = if (apostropheOrSpaceSeparator == '\"') && even (T.count "\"" endLineText) then "\"" else ""
+  completionStart =
+    Position
+      (_line completionEnd)
+      (_character completionEnd - (fromIntegral $ T.length filepathPrefix))
+  filepathPrefix = T.takeWhileEnd (not . (`elem` stopConditionChars)) beforeCursorText
+  (beforeCursorText, afterCursorText) = T.splitAt cursorColumn $ VFS.fullLine prefixInfo
+  suffix =
+    if apostropheOrSpaceSeparator == '\"' && even (T.count "\"" afterCursorText)
+      then "\""
+      else ""
+  apostropheOrSpaceSeparator =
+    if odd $ T.count "\"" beforeCursorText
+      then '\"'
+      else ' '
   cursorColumn = fromIntegral $ VFS.cursorPos prefixInfo ^. JL.character
   -- if the filepath is inside apostrophes, we parse until the apostrophe,
-  -- otherwise space is a separator
-  apostropheOrSpaceSeparator = if odd $ T.count "\"" prevLineText then '\"' else ' '
+  -- otherwise we parse until a space occurs
   stopConditionChars = apostropheOrSpaceSeparator : [',']
 
 buildCompletion :: CabalCompletionItem -> J.CompletionItem
 buildCompletion completionItem =
   J.CompletionItem
-    toDisplay
-    (Just J.CiKeyword)
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    Nothing
-    (Just $ J.CompletionEditText (J.TextEdit (itemRange completionItem) $ itemInsert completionItem))
-    Nothing
-    Nothing
-    Nothing
-    Nothing
+  {
+    Compls._label = toDisplay,
+    Compls._kind = Just J.CiKeyword,
+    Compls._tags = Nothing,
+    Compls._detail = Nothing,
+    Compls._documentation = Nothing,
+    Compls._deprecated = Nothing,
+    Compls._preselect = Nothing,
+    Compls._sortText = Nothing,
+    Compls._filterText = Nothing,
+    Compls._insertText = Nothing,
+    Compls._insertTextFormat = Nothing,
+    Compls._insertTextMode = Nothing,
+    Compls._textEdit = Just $ J.CompletionEditText (J.TextEdit (itemRange completionItem) $ itemInsert completionItem),
+    Compls._additionalTextEdits = Nothing,
+    Compls._commitCharacters = Nothing,
+    Compls._command = Nothing,
+    Compls._xdata = Nothing
+  }
  where
   toDisplay = fromMaybe (itemInsert completionItem) (itemDisplay completionItem)
 
 -- ----------------------------------------------------------------
--- Completor API
+-- Completer API
 -- ----------------------------------------------------------------
 
-{- | Returns a CabalCompletionItem with the given starting position
-  and text to be inserted where the displayed text is the same as the inserted text
-  after the inserted text
--}
-makeSimpleCabalCompletionItem :: Range -> T.Text -> CabalCompletionItem
-makeSimpleCabalCompletionItem r txt = CabalCompletionItem txt Nothing r
-
-{- | Returns a CabalCompletionItem with the given starting position,
-  text to be inserted and text to be displayed in the completion suggestion
--}
-makeCabalCompletionItem :: Range -> T.Text -> T.Text -> CabalCompletionItem
-makeCabalCompletionItem r insertTxt displayTxt = CabalCompletionItem insertTxt (Just displayTxt) r
-
 {- | Completer to be used when no completion suggestions
   are implemented for the field
 -}
@@ -272,9 +292,8 @@ constantCompleter completions ctxInfo = do
   let range = completionRange ctxInfo
   pure $ map (makeSimpleCabalCompletionItem range . Fuzzy.original) scored
 
-
 {- | Completer to be used when a file path can be
-  completed for the field, takes the file path of the directory to start from,
+  completed for a field, takes the file path of the directory to start from,
   completes file paths as well as directories
 -}
 filePathCompleter :: Completer
@@ -290,9 +309,9 @@ filePathCompleter ctx = do
         fullFilePath <- makeFullFilePath suffix compl complInfo
         pure $ makeCabalCompletionItem (completionRange ctx) fullFilePath fullFilePath
     )
-  where 
+  where
     -- | Takes a suffix, a completed path and a pathCompletionInfo and
-    --   generates the whole filepath including the already written prefix 
+    --   generates the whole filepath including the already written prefix
     --   and the suffix in case the completed path is a filepath
     makeFullFilePath :: T.Text -> T.Text -> PathCompletionInfo -> IO T.Text
     makeFullFilePath suffix' completion' complInfo = do
@@ -301,30 +320,6 @@ filePathCompleter ctx = do
       let fullPath = if isFilePath then fullPath' ++ T.unpack suffix' else fullPath'
       pure $ T.pack fullPath
 
-{- | Takes a path completion info and returns the list of files 
-     in the directory the path completion info describes
--}
-listFileCompletions :: PathCompletionInfo -> IO [FilePath]
-listFileCompletions complInfo = do
-  try (evaluate =<< listDirectory (mkCompletionDirectory complInfo)) >>= \case
-    Right dirs -> do
-      fixedDirs <- mapM
-        (\d -> do
-            isDir <- doesDirectoryExist $ mkDirFromCWD complInfo d
-            pure $ if isDir then Posix.addTrailingPathSeparator d else d
-        )
-        dirs
-      pure fixedDirs
-    Left (_::IOError) -> pure []
-
-{- | Returns a list of all directories in the directory 
-     described by path completion info
--}
-listDirectoryCompletions :: PathCompletionInfo -> IO [FilePath]
-listDirectoryCompletions complInfo = do
-  filepaths <- listFileCompletions complInfo
-  filterM (doesDirectoryExist . mkDirFromCWD complInfo) filepaths
-
 {- | Completer to be used when a directory can be completed for the field,
   takes the file path of the directory to start from,
   only completes directories
@@ -342,13 +337,36 @@ directoryCompleter ctx = do
         pure $ makeCabalCompletionItem (completionRange ctx) fullDirPath fullDirPath
     )
   where
-    -- | Takes a directory and PathCompletionInfo and 
+    -- | Takes a directory and PathCompletionInfo and
     --   returns the whole path including the prefix that was already written
     makeFullDirPath :: T.Text -> PathCompletionInfo -> IO T.Text
     makeFullDirPath completion' complInfo = do
       let fullPath =  prefixPathInfo complInfo Posix.</> T.unpack completion'
       pure $ T.pack fullPath
 
+{- | Takes a path completion info and returns the list of files
+  in the directory the path completion info describes
+-}
+listFileCompletions :: PathCompletionInfo -> IO [FilePath]
+listFileCompletions complInfo = do
+  try (evaluate =<< listDirectory (mkCompletionDirectory complInfo)) >>= \case
+    Right dirs -> do
+      fixedDirs <- mapM
+        (\d -> do
+            isDir <- doesDirectoryExist $ mkDirFromCWD complInfo d
+            pure $ if isDir then Posix.addTrailingPathSeparator d else d
+        )
+        dirs
+      pure fixedDirs
+    Left (_::IOError) -> pure []
+
+{- | Returns a list of all (and only) directories in the
+  directory described by path completion info
+-}
+listDirectoryCompletions :: PathCompletionInfo -> IO [FilePath]
+listDirectoryCompletions complInfo = do
+  filepaths <- listFileCompletions complInfo
+  filterM (doesDirectoryExist . mkDirFromCWD complInfo) filepaths
 
 pathCompletionInfoFromCompletionContext :: CabalCompletionContext -> PathCompletionInfo
 pathCompletionInfoFromCompletionContext ctx = PathCompletionInfo
@@ -360,14 +378,23 @@ pathCompletionInfoFromCompletionContext ctx = PathCompletionInfo
     dirNamePrefix = T.pack $ Posix.takeFileName prefix
     fp = Posix.takeDirectory $ completionCabalFilePath ctx
 
-{- | Returns 
+{- | Returns the directory, the currently handled cabal file is in,
+  we let System.FilePath handle the separator syntax since this is used
+  to query filepaths from the system
 -}
 mkCompletionDirectory :: PathCompletionInfo -> FilePath
-mkCompletionDirectory complInfo = FP.addTrailingPathSeparator $ cabalFilePathInfo complInfo FP.</> (FP.normalise $ prefixPathInfo complInfo)
+mkCompletionDirectory complInfo =
+  FP.addTrailingPathSeparator
+    $ cabalFilePathInfo complInfo FP.</> (FP.normalise $ prefixPathInfo complInfo)
 
+{- | Returns the complete filepath for the given filepath,
+  since cabal files only use posix syntax, and this is used for completions
+  we use posix separators here
+-}
 mkDirFromCWD :: PathCompletionInfo -> FilePath -> FilePath
 mkDirFromCWD complInfo fp = Posix.addTrailingPathSeparator $ mkCompletionDirectory complInfo Posix.</> Posix.normalise fp
 
+-- | Information used to query and build file path/directory completions
 data PathCompletionInfo = PathCompletionInfo
   { prefixLeftOver    :: T.Text
   -- ^ partly written start of next part of path
@@ -389,10 +416,8 @@ cabalVersionKeyword =
     constantCompleter $
       map (T.pack . showCabalSpecVersion) [CabalSpecV2_2 .. maxBound]
 
--- todo: we could add file path completion for file path fields
---       we could add descriptions of field values and then show them when inside the field's context
-
 -- | Top level keywords of a cabal file
+-- TODO: we could add descriptions of field values and then show them when inside the field's context
 cabalKeywords :: Map T.Text Completer
 cabalKeywords =
   Map.fromList