turtle
Shell programming, Haskell-style
Version on this page: | 1.6.1@rev:5 |
LTS Haskell 22.37: | 1.6.2@rev:3 |
Stackage Nightly 2024-10-06: | 1.6.2@rev:3 |
Latest on Hackage: | 1.6.2@rev:3 |
turtle-1.6.1@sha256:a7ce4da2e57c4ba6af76ff076b7297dc31bf28fe53191ab6cbd046e1c2bf84d2,5214
Module documentation for 1.6.1
turtle
is a reimplementation of the Unix command line environment
in Haskell so that you can use Haskell as both a shell and a scripting
language.
Features include:
Batteries included: Command an extended suite of predefined utilities
Interoperability: You can still run external shell commands
Portability: Works on Windows, OS X, and Linux
Exception safety: Safely acquire and release resources
Streaming: Transform or fold command output in constant space
Patterns: Use typed regular expressions that can parse structured values
Formatting: Type-safe
printf
-style text formattingModern: Supports
text
Read Turtle.Tutorial
for a detailed tutorial or Turtle.Prelude
for a
quick-start guide
turtle
is designed to be beginner-friendly, but as a result lacks certain
features, like tracing commands. If you feel comfortable using turtle
then you should also check out the Shelly
library which provides similar
functionality.
Changes
1.6.1.
- BUG FIX: Fix
turtle
to build on Windows - BUG FIX:
stripPrefix
andcommonPrefix
now correctly handle files with extensions- For example, before this fix
stripPrefix "./" "./foo.bar"
would returnJust "foo/.bar"
- For example, before this fix
1.6.0
- BREAKING CHANGE: Switch to the
FilePath
type frombase
instead ofsystem-filepath
- This is a breaking change for a couple of reasons:
- The
FilePath
type has changed, so the API is not backwards-compatible- The thing most likely to break is if you directly imported utilities
from the
system-filepath
orsystem-fileio
packages to operate onturtle
’sFilePath
s- If that happens, you should first check if the
Turtle
module exports a utility of the same name. If so, then switch to that - If there is no equivalent substitute from the
Turtle
module then you will have to change your code to use the closest equivalent utility from thefilepath
ordirectory
package - If you were previously using any of the
system-filepath
orsystem-fileio
utilities re-exported from theTurtle
module then those utilities will not break as they have been replaced with versions compatible with theFilePath
type frombase
- If that happens, you should first check if the
- The second thing most likely to break is any code that relies on
typeclasses since because if you defined any instances for the
FilePath
type exported byturtle
then those instances will now overlap with any instances defined for theString
type - The conversion utilities (e.g.
toText
,encodeString
) will still work, so code that used those conversion utilities should be less affected by this change
- The thing most likely to break is if you directly imported utilities
from the
- The behavior of the
collapse
utility is subtly differentcollapse
no longer interprets..
in paths- This new behavior is more correct in the presence of symlinks, so the change is (hopefully) an improvement to downstream code
- The
- The new API strives to match the old behavior as closely as possible
- … so this should (hopefully) not break too much code in practice
- With the exception of the
collapse
function the new API should be bug-for-bug compatible with the old API- Most of the surprising behavior inherited from the old API is around
how
.
and..
are handled in pathsparent ".." == "."
is an example of such surprising behavior
- Most of the surprising behavior inherited from the old API is around
how
- At some point in the future we may fix bugs in these utilities inherited
from
system-filepath
/system-fileio
, but no decision either way has been made, yet
- Some old utilities are marked
DEPRECATED
if their behavior exactly matches the behavior of an existing utility from thefilepath
ordirectory
package- These may be eventually removed at some point in the future or they remain in a deprecated state indefinitely. No decision either way has been made
- The
Turtle
module also re-exports any utility suggested by aDEPRECATED
pragma as a convenience
- Other utilities are not deprecated if the old behavior significantly departs
from any existing utility from the
filepath
ordirectory
package- For example, the behavior of the
filename
utility differs from the behavior ofSystem.FilePath.takeFileName
for filenames that begin with a.
, so we have to preserve the old behavior to avoid breaking downstream code - At some point in the future utilities like these may be deprecated in
favor of their closest analogs in the
filepath
/directory
packages or they may be supported indefinitely. No decision either way has been made
- For example, the behavior of the
- If you want to try to author code that is compatible with both the
pre-1.6 and post-1.6 API:
- If you add any instances to the
FilePath
type, import it qualified directly from thesystem-filepath
package and use it only for instances - Otherwise, don’t import anything else from the
system-filepath
/system-fileio
packages if you can help it. Instead, restrict yourself entirely to the utilities andFilePath
type exported by theTurtle
module - Use the conversion utilities (e.g.
encodeStrings
, even if they are not necessary post-1.6) - If that’s still not enough, use
CPP
and good luck!
- If you add any instances to the
- This is a breaking change for a couple of reasons:
1.5.25
- Build against latest version of
Win32
package
1.5.24
- Expose
Format
constructor
1.5.23
- Add
fromIO
utility - Build against GHC 9.0 / 9.2
1.5.22
- Add new
update
utility - Improve documentation for
limit
1.5.21
- Build against
optparse-applicative-0.16.0.0
1.5.20
- Build against
doctest-0.17
- Only depend on
semigroups
for GHC < 8.0
1.5.19
- Add pattern synonyms for
Size
1.5.18
- Fix space leak
1.5.17
- Add
optionsExt
: Extended version ofoptions
with header, footer, porgram-description and version information in--help
flag - Add
readlink
1.5.16
- Add
cptreeL
1.5.15
- Add
toLines
- Add
Turtle.Bytes.{fromUTF8,toUTF8}
- Add
Turtle.Bytes.{compress,decompress}
- Always expose a
MonadFail
instance, relying on thefail
package where needed. Related GHC 8.8 preparedness.
1.5.14
- Fix
cptree
to copy symlinks instead of descending into them - Build against newer versions of
Win32
package
1.5.13
- Fix
chmod
bug - Add
reduce
and re-export(<&>)
1.5.12
- Increase upper bound on
containers
1.5.11
- Don’t forward broken pipe exceptions when using
inproc
- Increase upper bound on
stm
- Tutorial improvements:
1.5.10
- Increase upper bound on
doctest
andcriterion
1.5.9
- Add
symlink
1.5.8
- Bug fix:
invert
no longer rejects inputs where a prefix matches the inverted pattern - Add lsdepth, findtree, cmin, and cmax
- Increase upper bound on
temporary
andfoldl
1.5.7
- Increase upper bound on
doctest
1.5.6
- Increase upper bound on
exceptions
1.5.5
- Increase upper bound on
criterion
1.5.4
- Increase upper bound on
exceptions
1.5.3
- Increase upper bound on
doctest
1.5.2
- Increase upper bound on
async
1.5.1
- GHC 8.4 support
- Re-export
encodeString
/decodeString
- Update tutorial to use
stack script
- Increase upper bounds on dependencies
1.5.0
- BREAKING CHANGE: Add
MonadCatch
instance forShell
- This requires a breaking change to the internal implementation of
Shell
- Most breaking changes can be fixed by replacing the
Shell
constructor with the newly added_Shell
utility for ease of migration - If you don’t use the
Shell
constructor then this change likely does not affect you
- This requires a breaking change to the internal implementation of
- Add
eprintf
1.4.5
- Add
grepText
,uniq
,nub
,sort
toTurtle.Prelude
- Increase upper bound on
unix-compat
1.4.4
- Fix small mistake in tutorial
1.4.3
- Increase upper bound on
doctest
1.4.2
- Add
sed{Prefix,Suffix,Entire}
andinplace{Prefix,Suffix,Entire}
1.4.1
- Increase upper bound on
doctest
1.4.0
- BREAKING CHANGE: Remove unnecessary
Maybe
from type ofsingle
- BREAKING CHANGE: Consolidate
searchable
andexecutable
stream{,WithErr}
now throws anExitCode
on failure
1.3.6
- Build against
ghc-8.2
- Relax upper bound on
optparse-applicative
andfoldl
1.3.5
- Increase upper bound on
foldl
1.3.4
- Bug fix:
cptree
now correctly copies files instead of creating directories of the same name - Increase upper bound on
criterion
1.3.3
- Bug fix: Change
textToLines
to behave likeData.Text.splitOn "\n"
instead ofData.Text.unlines
- This fixes weird behavior around handling empty strings.
splitOn
does the right thing, butunlines
does not. For example, this indirectly fixes a regression insed
, which would discard empty lines
- This fixes weird behavior around handling empty strings.
- Bug fix:
which
/whichAll
now behave correctly on Windows - Add new
cptree
/single
utilities - Documentation fixes
1.3.2
- Fix bugs in subprocess management
- Generalize type of
repr
to return any type that implementsIsString
- Add
optLine
,argLine
, andl
utilities to simplify working withLine
s
1.3.1
find
no longer follows symlinks- Increase upper bound on
directory
1.3
- BREAKING CHANGE: Several utilities now produce and consume
Line
s instead ofText
- The purpose of this change is to fix a very common source of confusion for new users about which utilities are line-aware
- Most of the impact on existing code is just changing the types by
replacing
Text
withLine
in the right places. The change at the term level should be small (based on the changes to the tutorial examples)
- BREAKING CHANGE:
Description
now wraps aDoc
instead ofText
- In the most common case where users use string literals this has no effect
- New
Turtle.Bytes
module that providesByteString
variations on subprocess runners - Fix
du
reporting incorrect sizes for directories - Add
pushd
,stat
,lstat
,which
,procStrictWithErr
,shellStrictWithErr
,onFiles
,header
,subcommandGroup
, andparallel
- Backport
need
to GHC 7.6.3 - Fix missing help text for option parsers
- Fix bugs in subprocess management
1.2.8
- Increase upper bound on
time
andtransformers
- Fix incorrect lower bound for
base
1.2.7
- Increase upper bound on
clock
dependency
1.2.6
- Generalize several types to use
MonadManaged
- Generalize type of
printf
to useMonadIO
- Add
system
, andcopymod
- Fix
rmtree
to more accurately match behavior ofrm -r
1.2.5
- Add
printf
,utc
,procs
, andshells
1.2.4
- Generalize type of
d
format specifier to format anyIntegral
type - Add
inprocWithErr
,inShellWithErr
,inplace
, andsz
1.2.3
- Add
subcommand
andtestpath
- Use line buffering for
Text
-based subprocesses
1.2.2
- Re-export
with
- Add
begins
,ends
,contains
,lowerBounded
,mktempfile
,nl
,paste
endless
,lsif
, andcut
- Fix subprocess management bugs
1.2.1
- Fix subprocess management bugs
1.2.0
- BREAKING CHANGE:
du
now returns aSize
instead of anInteger
- New
Turtle.Options
module that provides convenient utilities for options parsing - Add
hostname
,outhandle
,stderr
,cache
,countChars
,countWords
, andcountLines
- Fix subprocess management bugs
1.1.1
- Add
bounded
,upperBounded
,procStrict
,shellStrict
,arguments
- Add several
Permissions
-related commands - Generalize several types to
MonadIO
1.1.0
- BREAKING CHANGE: Remove
Floating
/Fractional
instances forPattern
andShell
- BREAKING CHANGE: Change behavior of
Num
instance forPattern
andShell
- Re-export
(&)
- Add
asciiCI
,(.||.)
,(.&&.)
,strict
1.0.2
- Add
fp
format specifier - Add
chars
/chars
high-efficiency parsing primitives - Fix bugs in path handling
1.0.1
- Generalize type of
die
- Fix doctest
1.0.0
- Initial release