Cleanup and doc updates

Author: harendra-kumar

README.md

@@ -1,12 +1,12 @@
 # Streamly Coreutils
 
 This repository provides Haskell functions that reimplement common
-GNU `coreutils` commands, leveraging the `streamly` library for
+GNU `coreutils` commands, utilizing the `streamly` library for
 efficient, streaming data processing where applicable. The goal is to
 offer a functional and highly performant alternative to traditional
 shell commands within Haskell applications, enabling complex data
-transformations and system interactions using a pure functional
-paradigm. Where applicable, these implementations are designed to be
+transformations, system programming and scripting using a pure functional
+paradigm. Where applicable, the implementation is designed to be
 highly concurrent, for example, the `ls` equivalent can list directory
 contents concurrently for improved performance.
 
@@ -15,11 +15,16 @@ contents concurrently for improved performance.
 Currently, this library provides implementations for the
 following coreutils-inspired as well as some additional commands:
 
-* Filesystem: `cp`, `rm`, `mv`, `ln`, `readlink`, `test`, `stat`, `touch`
-* Directories: `ls`, `dirname`, `mkdir`, `cd`, `pwd`, `home` and others
+* Dir traversal: `ls`, `cp -r`, `rm -r`
+* Dir modify: `touch`, `ln`, `cp`, `mkdir`, `rm`, `mv`
+* File stat: `test`, `stat`, `touch`
+* File read/write: `cp`
+* Symlink read: `readlink`
+* Processes: `cd`, `pwd`, `sleep`
+* Environment: `home`
 * Text Processing: `cut`, `tail`
-* Processes: `sleep`
-* Shell: `which`, executing shell commands with streaming
+* Shell: streaming composition of shell commands
+* Paths: `dirname`, `which`
 
 ## Important API Notice
 

src/Streamly/Coreutils.hs

@@ -7,12 +7,10 @@
 -- Portability : GHC
 --
 module Streamly.Coreutils
-    ( module Streamly.Coreutils.Uniq
-    , module Streamly.Coreutils.Cp
+    ( module Streamly.Coreutils.Cp
     , module Streamly.Coreutils.FileTest
     )
 where
 
-import Streamly.Coreutils.Uniq
 import Streamly.Coreutils.Cp
 import Streamly.Coreutils.FileTest

src/Streamly/Coreutils/Cut.hs

@@ -9,7 +9,9 @@
 -- Functionality equivalent to the @cut@ command.
 
 module Streamly.Coreutils.Cut
-    ( foldIndicesBy
+    ( foldIndicesBy -- XXX rename to cut
+
+    -- * Deprecated
     , decodeLatin1
     , readLines
     , splitByWord8
@@ -41,7 +43,9 @@ decodeLatin1 arr =
         & Stream.toList
         & runIdentity
 
--- XXX this should go in unicode text file reading module - Unicode.FileIO?
+-- XXX this should go in unicode text file reading module - Unicode.FileIO or
+-- cat coreutil? Redirection ">" can have its own "pipeTo" or "redirectTo"
+-- function.
 -- e.g. readUtf8, writeUtf8, readLines, readWords, readWordsBy, readDSV,
 -- readDSVSeq
 
@@ -119,9 +123,12 @@ filterIndices :: Monad m =>
     [Int] -> Stream m a -> Stream m a
 filterIndices xs = filterByMask (Stream.fromList (makeIndexMask xs))
 
--- | Split the lines in a file using the given separator and then fold the
--- selected indices (indices start from 0) in each line using the supplied
--- fold.
+-- XXX Rename to "cut" using "CutOptions". fold, indices can be part of
+-- CutOptions with defaults.
+
+-- | @foldIndicesBy fold indices separator file@. Split the lines in a file
+-- using the given separator and then fold the selected indices (indices start
+-- from 0) in each line using the supplied fold.
 --
 -- For example to generate an array of the selected indices for each line:
 --

src/Streamly/Coreutils/FileTest.hs

@@ -116,7 +116,7 @@ module Streamly.Coreutils.FileTest
     --
     -- On POSIX systems, this checks the standard Unix permission bits.
     --
-    -- On Windows, only one or two predicates make sense:
+    -- On Windows, only select few predicates make sense:
     --
     -- * 'hasOwnerWrite' - returns false if the file is marked read only via attributes.
     -- * 'hasOwnerExec' - returns true based on the file extension: @.bat@, @.cmd@,
@@ -150,9 +150,9 @@ module Streamly.Coreutils.FileTest
 
     -- *** Mode based access
     -- | These APIs perform only the file permission mode checks, actual
-    -- readability, writability or executability may depend many other factors
+    -- readability, writability or executability may depend on many other factors
     -- like filesystem mount permissions, access control lists (ACLs) etc. For
-    -- deeper checks see: 'isReadable', 'isWritable', 'isExecutable'.
+    -- more comprehensive checks see: 'isReadable', 'isWritable', 'isExecutable'.
     --
     , isReadableByMode
     , isWritableByMode
@@ -209,6 +209,8 @@ module Streamly.Coreutils.FileTest
     --
     -- >>> let _ = modifiedWithin (days 1 + hours 5 + minutes 10 + seconds 20)
 
+    -- XXX These can be moved to the streamly time module.
+
     -- *** Time units
     , seconds
     , minutes

src/Streamly/Coreutils/Touch.hs

@@ -14,8 +14,8 @@ module Streamly.Coreutils.Touch
 
     -- * Options
     , Touch
-    , create
-    , followLinks
+    , create -- XXX rename for conflicts
+    , followLinks -- XXX this is a common option in multiple commands
     )
 where
 

streamly-coreutils.cabal

@@ -1,7 +1,7 @@
 cabal-version:       2.4
 name:                streamly-coreutils
 version:             0.1.0
-synopsis:            GNU Coreutils like API for Streamly
+synopsis:            GNU Coreutils like API for Haskell
 description:
    Streaming Haskell implementations of GNU coreutils, built on
    Streamly.  Provides familiar, composable, high-performance,
@@ -171,17 +171,6 @@ library
 -- Test suites
 -------------------------------------------------------------------------------
 
--- test-suite coreutils-test
---   import: compile-options
---   type: exitcode-stdio-1.0
---   main-is: Main.hs
---   hs-source-dirs: test
---   build-depends:
---       streamly-coreutils
---     , streamly-core
---     , base              >= 4.8   && < 5
---   default-language: Haskell2010
-
 test-suite Streamly.Coreutils.Rm
   import: compile-options
   type: exitcode-stdio-1.0