libghc-system-filepath-doc 0.4.13.4-6build2 / usr / share / doc / libghc-system-filepath-doc / html / system-filepath.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | High-level, byte-based file and directory path manipulations (deprecated)
--   
--   Please see:
--   <a>https://plus.google.com/+MichaelSnoyman/posts/Ft5hnPqpgEx</a>
@package system-filepath
@version 0.4.13.4


-- | High‐level, byte‐based file and directory path manipulations. You
--   probably want to import <a>Filesystem.Path.CurrentOS</a> instead,
--   since it handles detecting which rules to use in the current
--   compilation.
module Filesystem.Path
data FilePath

-- | A file path with no root, directory, or filename
empty :: FilePath

-- | <pre>
--   null p = (p == <a>empty</a>)
--   </pre>
null :: FilePath -> Bool

-- | Retrieves the <a>FilePath</a>’s root.
root :: FilePath -> FilePath

-- | Retrieves the <a>FilePath</a>’s directory. If the path is already a
--   directory, it is returned unchanged.
directory :: FilePath -> FilePath

-- | Retrieves the <a>FilePath</a>’s parent directory.
parent :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s filename component.
--   
--   <pre>
--   filename "foo/bar.txt" == "bar.txt"
--   </pre>
filename :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s directory name. This is only the <i>file
--   name</i> of the directory, not its full path.
--   
--   <pre>
--   dirname "foo/bar/baz.txt" == "bar"
--   dirname "/" == ""
--   </pre>
--   
--   Since: 0.4.1
dirname :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s basename component.
--   
--   <pre>
--   basename "foo/bar.txt" == "bar"
--   </pre>
basename :: FilePath -> FilePath

-- | Test whether a path is absolute.
absolute :: FilePath -> Bool

-- | Test whether a path is relative.
relative :: FilePath -> Bool

-- | Appends two <a>FilePath</a>s. If the second path is absolute, it is
--   returned unchanged.
append :: FilePath -> FilePath -> FilePath

-- | An alias for <a>append</a>.
(</>) :: FilePath -> FilePath -> FilePath

-- | A fold over <a>append</a>.
concat :: [FilePath] -> FilePath

-- | Find the greatest common prefix between a list of <a>FilePath</a>s.
commonPrefix :: [FilePath] -> FilePath

-- | Remove a prefix from a path.
--   
--   <pre>
--   <a>stripPrefix</a> "/foo/" "/foo/bar/baz.txt" == Just "bar/baz.txt"
--   <a>stripPrefix</a> "/foo/" "/bar/baz.txt" == Nothing
--   </pre>
--   
--   This function operates on logical prefixes, rather than by counting
--   characters. The prefix <tt>"/foo/bar/baz"</tt> is interpreted the path
--   <tt>("/foo/bar/", "baz")</tt>, and will be stripped accordingly:
--   
--   <pre>
--   <a>stripPrefix</a> "/foo/bar/baz" "/foo/bar/baz/qux" == Nothing
--   <a>stripPrefix</a> "/foo/bar/baz" "/foo/bar/baz.txt" == Just ".txt"
--   </pre>
--   
--   Since: 0.4.1
stripPrefix :: FilePath -> FilePath -> Maybe FilePath

-- | Remove intermediate <tt>"."</tt> and <tt>".."</tt> directories from a
--   path.
--   
--   <pre>
--   <a>collapse</a> "/foo/./bar" == "/foo/bar"
--   <a>collapse</a> "/foo/bar/../baz" == "/foo/baz"
--   <a>collapse</a> "/foo/../../bar" == "/bar"
--   <a>collapse</a> "./foo/bar" == "./foo/baz"
--   </pre>
--   
--   Note that if any of the elements are symbolic links, <a>collapse</a>
--   may change which file the path resolves to.
--   
--   Since: 0.2
collapse :: FilePath -> FilePath

-- | expand a FilePath into a list of the root name, directories, and file
--   name
--   
--   Since: 0.4.7
splitDirectories :: FilePath -> [FilePath]

-- | Get a <a>FilePath</a>’s last extension, or <a>Nothing</a> if it has no
--   extensions.
extension :: FilePath -> Maybe Text

-- | Get a <a>FilePath</a>’s full extension list.
extensions :: FilePath -> [Text]

-- | Get whether a <a>FilePath</a>’s last extension is the predicate.
hasExtension :: FilePath -> Text -> Bool

-- | Append an extension to the end of a <a>FilePath</a>.
addExtension :: FilePath -> Text -> FilePath

-- | An alias for <a>addExtension</a>.
(<.>) :: FilePath -> Text -> FilePath

-- | Remove a <a>FilePath</a>’s last extension.
dropExtension :: FilePath -> FilePath

-- | Replace a <a>FilePath</a>’s last extension.
replaceExtension :: FilePath -> Text -> FilePath

-- | Append many extensions to the end of a <a>FilePath</a>.
addExtensions :: FilePath -> [Text] -> FilePath

-- | Remove all extensions from a <a>FilePath</a>.
dropExtensions :: FilePath -> FilePath

-- | Remove all extensions from a <a>FilePath</a>, and replace them with a
--   new list.
replaceExtensions :: FilePath -> [Text] -> FilePath

-- | <pre>
--   splitExtension p = (<a>dropExtension</a> p, <a>extension</a> p)
--   </pre>
splitExtension :: FilePath -> (FilePath, Maybe Text)

-- | <pre>
--   splitExtensions p = (<a>dropExtensions</a> p, <a>extensions</a> p)
--   </pre>
splitExtensions :: FilePath -> (FilePath, [Text])
instance GHC.Base.Monoid Filesystem.Path.Internal.FilePath


module Filesystem.Path.Rules

-- | The type of <tt>platformFormat</tt> for <a>Rules</a> is conditionally
--   selected at compilation time. As such it is only intended for direct
--   use with external OS functions and code that expects
--   <tt>platformFormat</tt> to be stable across platforms may fail to
--   subsequently compile on a differing platform.
--   
--   For example: on Windows or OSX <tt>platformFormat</tt> will be
--   <a>Text</a>, and on Linux it will be <a>ByteString</a>.
--   
--   If portability is a concern, restrict usage to functions which do not
--   expose <tt>platformFormat</tt> directly.
data Rules platformFormat

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
posix :: Rules ByteString

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
--   
--   This is a variant of <a>posix</a> for use with GHC 7.2, which tries to
--   decode file paths in its IO computations.
--   
--   Since: 0.3.3 / 0.4.2
posix_ghc702 :: Rules ByteString

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
--   
--   This is a variant of <a>posix</a> for use with GHC 7.4 or later, which
--   tries to decode file paths in its IO computations.
--   
--   Since: 0.3.7 / 0.4.6
posix_ghc704 :: Rules ByteString

-- | Windows and DOS
windows :: Rules Text

-- | Darwin and Mac OS X.
--   
--   This is almost identical to <a>posix</a>, but with a native path type
--   of <a>Text</a> rather than <a>ByteString</a>.
--   
--   Since: 0.3.4 / 0.4.3
darwin :: Rules Text

-- | Darwin and Mac OS X.
--   
--   This is a variant of <a>darwin</a> for use with GHC 7.2 or later,
--   which tries to decode file paths in its IO computations.
--   
--   Since: 0.3.4 / 0.4.3
darwin_ghc702 :: Rules Text

-- | Attempt to convert a <a>FilePath</a> to human‐readable text.
--   
--   If the path is decoded successfully, the result is a <a>Right</a>
--   containing the decoded text. Successfully decoded text can be
--   converted back to the original path using <a>fromText</a>.
--   
--   If the path cannot be decoded, the result is a <a>Left</a> containing
--   an approximation of the original path. If displayed to the user, this
--   value should be accompanied by some warning that the path has an
--   invalid encoding. Approximated text cannot be converted back to the
--   original path.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to display file paths with an unusual
--   or obscure encoding, use <a>encode</a> and then decode them manually.
--   
--   Since: 0.2
toText :: Rules platformFormat -> FilePath -> Either Text Text

-- | Convert human‐readable text into a <a>FilePath</a>.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to create file paths with an unusual
--   or obscure encoding, encode them manually and then use <a>decode</a>.
--   
--   Since: 0.2
fromText :: Rules platformFormat -> Text -> FilePath

-- | Convert a <a>FilePath</a> to a platform‐specific format, suitable for
--   use with external OS functions.
--   
--   Note: The type of <tt>platformTextFormat</tt> can change depending
--   upon the underlying compilation platform. Consider using <a>toText</a>
--   or <a>encodeString</a> instead. See <a>Rules</a> for more information.
--   
--   Since: 0.3
encode :: Rules platformFormat -> FilePath -> platformFormat

-- | Convert a <a>FilePath</a> from a platform‐specific format, suitable
--   for use with external OS functions.
--   
--   Note: The type of <tt>platformTextFormat</tt> can change depending
--   upon the underlying compilation platform. Consider using
--   <a>fromText</a> or <a>decodeString</a> instead. See <a>Rules</a> for
--   more information.
--   
--   Since: 0.3
decode :: Rules platformFormat -> platformFormat -> FilePath

-- | Attempt to convert a <a>FilePath</a> to a string suitable for use with
--   functions in <tt>System.IO</tt>. The contents of this string are
--   platform‐dependent, and are not guaranteed to be human‐readable. For
--   converting <a>FilePath</a>s to a human‐readable format, use
--   <a>toText</a>.
--   
--   Since: 0.3.1
encodeString :: Rules platformFormat -> FilePath -> String

-- | Attempt to parse a <a>FilePath</a> from a string suitable for use with
--   functions in <tt>System.IO</tt>. Do not use this function for parsing
--   human‐readable paths, as the character set decoding is
--   platform‐dependent. For converting human‐readable text to a
--   <a>FilePath</a>, use <a>fromText</a>.
--   
--   Since: 0.3.1
decodeString :: Rules platformFormat -> String -> FilePath

-- | Check if a <a>FilePath</a> is valid; it must not contain any illegal
--   characters, and must have a root appropriate to the current
--   <a>Rules</a>.
valid :: Rules platformFormat -> FilePath -> Bool

-- | Split a search path, such as <tt>$PATH</tt> or <tt>$PYTHONPATH</tt>,
--   into a list of <a>FilePath</a>s.
--   
--   Note: The type of <tt>platformTextFormat</tt> can change depending
--   upon the underlying compilation platform. Consider using
--   <a>splitSearchPathString</a> instead. See <a>Rules</a> for more
--   information.
splitSearchPath :: Rules platformFormat -> platformFormat -> [FilePath]

-- | splitSearchPathString is like <a>splitSearchPath</a>, but takes a
--   string encoded in the format used by <tt>System.IO</tt>.
splitSearchPathString :: Rules platformFormat -> String -> [FilePath]


-- | Re‐exports contents of <a>Filesystem.Path.Rules</a>, defaulting to the
--   current OS’s rules when needed.
--   
--   Also enables <a>Show</a> and <a>IsString</a> instances for
--   <a>FilePath</a>.
module Filesystem.Path.CurrentOS
currentOS :: Rules platformTextFormat

-- | Attempt to convert a <a>FilePath</a> to human‐readable text.
--   
--   If the path is decoded successfully, the result is a <a>Right</a>
--   containing the decoded text. Successfully decoded text can be
--   converted back to the original path using <a>fromText</a>.
--   
--   If the path cannot be decoded, the result is a <a>Left</a> containing
--   an approximation of the original path. If displayed to the user, this
--   value should be accompanied by some warning that the path has an
--   invalid encoding. Approximated text cannot be converted back to the
--   original path.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to display file paths with an unusual
--   or obscure encoding, use <a>encode</a> and then decode them manually.
--   
--   Since: 0.2
toText :: FilePath -> Either Text Text

-- | Convert human‐readable text into a <a>FilePath</a>.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to create file paths with an unusual
--   or obscure encoding, encode them manually and then use <a>decode</a>.
--   
--   Since: 0.2
fromText :: Text -> FilePath

-- | Convert a <a>FilePath</a> to a platform‐specific format, suitable for
--   use with external OS functions.
--   
--   Note: The type <tt>platformTextFormat</tt> can change depending upon
--   the underlying compilation platform. Consider using <a>toText</a> or
--   <a>encodeString</a> instead. See <a>Rules</a> for more information.
--   
--   Since: 0.3
encode :: FilePath -> platformTextFormat

-- | Convert a <a>FilePath</a> from a platform‐specific format, suitable
--   for use with external OS functions.
--   
--   Note: The type <tt>platformTextFormat</tt> can change depending upon
--   the underlying compilation platform. Consider using <a>fromText</a> or
--   <a>decodeString</a> instead. See <a>Rules</a> for more information.
--   
--   Since: 0.3
decode :: platformTextFormat -> FilePath

-- | Attempt to convert a <a>FilePath</a> to a string suitable for use with
--   functions in <tt>System.IO</tt>. The contents of this string are
--   platform‐dependent, and are not guaranteed to be human‐readable. For
--   converting <a>FilePath</a>s to a human‐readable format, use
--   <a>toText</a>.
--   
--   Since: 0.3.1
encodeString :: FilePath -> String

-- | Attempt to parse a <a>FilePath</a> from a string suitable for use with
--   functions in <tt>System.IO</tt>. Do not use this function for parsing
--   human‐readable paths, as the character set decoding is
--   platform‐dependent. For converting human‐readable text to a
--   <a>FilePath</a>, use <a>fromText</a>.
--   
--   Since: 0.3.1
decodeString :: String -> FilePath

-- | Check if a <a>FilePath</a> is valid; it must not contain any illegal
--   characters, and must have a root appropriate to the current
--   <a>Rules</a>.
valid :: FilePath -> Bool

-- | Split a search path, such as <tt>$PATH</tt> or <tt>$PYTHONPATH</tt>,
--   into a list of <a>FilePath</a>s.
splitSearchPath :: platformTextFormat -> [FilePath]

-- | splitSearchPathString is like <a>splitSearchPath</a>, but takes a
--   string encoded in the format used by <tt>System.IO</tt>.
splitSearchPathString :: String -> [FilePath]
instance Data.String.IsString Filesystem.Path.Internal.FilePath
instance GHC.Show.Show Filesystem.Path.Internal.FilePath