os-string-compat

Note on Hackage

I haven't been able to get Stack/Cabal to generate versions of the documentation that properly link to entities from other packages on Hackage. Unfortunately, this means that you won't see documentation for functions that are just included directly from other packages, and you won't see links to their source code. To (partially) get around this, I ran Haddock while Stack was using an older version of filepath so that there would be more visible definitions. Hopefully this will improve the documentation.

If you want proper documentation of functions (and types), I recommend just checking out os-string, since it shouldn't have that problem.

This may be because I'm trying to compile the documentation on Windows. I might try at some point to auto-generate the docs with GitHub Actions... once I understand how to do that.

Note on macOS

This package may not work with older versions of GHC on macOS; when testing GHC 8.10.1 on macOS on GitHub Actions, it failed to install GHC. This seens to be because ARM support for mac wasn't added until GHC 8.10.4 (and improved thereafter). To reflect this, macOS is tested on the oldest version of GHC that still successfully installs on GitHub.

Currently, the oldest version of GHC that is able to compile this package on macOS is 9.2.8.

Intro and Purpose

This is a compatibility layer over os-string and (older versions of) filepath. Notably, in versions 1.4.100 <= v < 1.5 of filepath, the newtype OsString was defined in the filepath package itself. However, you can import these versions of filepath alongside os-string, which also defines a newtype OsString. In fact, in versions 1.4.200 onwards of filepath it recommends importing OsString via os-string instead of via filepath.

The problem is, you can't use functions from os-string on OsStrings from filepath. This may not seem like a problem at first, but os-string adds a lot of functions for working directly on OsStrings. This isn't a problem if you have a version of filepath that's newer than 1.5, but some packages require that filepath be older than 1.5. If you're writing a package that depends on such a package, you can't use any of the new functions from os-string directly.

Fortunately, in both os-string and older versions of filepath, OsString is ultimately just a newtype over ShortByteString¹, so you can coerce between the two definitions of OsString². That's what this package does: it exposes new versions of functions from os-string that are just coerced to work on OsString/OsPath from 1.4.100+.

Note that this package works for both pre-1.5 versions of filepath and post-1.5 versions of filepath. On newer versions, it just re-exports the functions³ from os-string, since filepath 1.5+ depends on os-string. Therefore, you can import os-string-compat instead of os-string and you can use the functions regardless of which version of filepath you have. If you're writing a library, you may want to depend on os-string-compat instead of os-string, since it'll enable you to put more lenient bounds on filepath.

Usage

Stack

If this package still isn't available on Hackage (i.e. if the link https://hackage.haskell.org/package/os-string-compat doesn't lead to a valid package), you'll have to import this package by adding it to your stack.yaml file. You'll also have to do this if you want to use an exact revision of the package. e.g.

extra-deps:
- git: https://github.com/Anteproperispomenon/os-string-compat
  commit: 3ea425f103d2f14e3f9f7f713eb4291fee5b38a4 # keep this up-to-date

If this package is available on Hackage, you may still have to add it to the extra-deps field in stack.yaml, but you won't have to give an exact commit. You can just say e.g.

extra-deps:
- os-string-compat-1.0.0

Cabal

If this package has been added to Hackage, you should be able to run cabal update and then add os-string-compat >= 1.0.0 to the build-depends field in your <package_name>.cabal file.

If it still isn't available on Hackage, then you'll have to add it to your cabal.project file. I haven't used this feature myself, but it'll probably be something like this:

packages: .

source-repository-package
    type: git
    location: https://github.com/Anteproperispomenon/os-string-compat
    tag: 3ea425f103d2f14e3f9f7f713eb4291fee5b38a4

(See cabal docs for more info)

Using the Modules

After that, instead of importing System.OsString etc, you import System.OsString.Compat etc... That is, you use the same module name, but add .Compat to the end. Note that this package doesn't include compatibility modules for System.OsString.Data.ByteString.Short or System.OsString.Data.ByteString.Short.Word16, since you can just import them directly without needing to worry about compatibility with filepath; when they were included in filepath, they were known as "System.OsPath.Data.ByteString.Short" etc..., so their module names won't clash.

To-Do

Possibly add more versions of GHC to GitHub Actions workflows. Also look into how to use GitHub Actions to automate building documentation/packages for Hackage. Also, figure out how to cache dependencies for the Stack workflow.

Footnotes