= polysemy-scoped-fs
:source-highlighter: highlight.js
:highlightjs-languages: haskell

This package provides well-typed (scoped) filesystem operation effects.
This is based on the idea and codes of https://www.tweag.io/blog/2022-01-05-polysemy-scoped/[Scoped Effect Resources for Polysemy] by Torsten Schmits.

== Example

We assume that the language extensions related to polysemy and polysemy-plugin are enabled.
cf. https://hackage.haskell.org/package/polysemy-1.7.1.0#readme

[source,haskell]
----
{-# LANGUAGE OverloadedStrings #-}

import qualified Polysemy.SequentialAccess as SA
import Polysemy (runFinal, embedToFinal, embed)
import Polysemy.Resource (resourceToIOFinal)
import Polysemy.Path
import Polysemy.FS.Scoped (scopedFile, AccessMode(RwAccess, ReadAccess))
import Polysemy.FS.Scoped.Text (rwAccessToIO, readAccessToIO)

writeFoobar :: IO ()
writeFoobar =
    runFinal $ embedToFinal $ resourceToIOFinal $ rwAccessToIO $ readAccessToIO $ do
        -- Open the file '/tmp/polysemy-scoped-fs-test' with read & write access mode.
        scopedFile @RwAccess [absfile|/tmp/polysemy-scoped-fs-test|] $ do
            SA.extend "This text will be deleted."
            SA.resize SA.NullSize -- Clear the file.
            SA.extend "foo" -- Append the text to the file.
            SA.extend "bar"
            SA.seek SA.TOF -- Seek to the top of the file.
            embed . print =<< SA.read SA.ToEnd

        -- Open the file with read only access mode.
        scopedFile @ReadAccess [absfile|/tmp/polysemy-scoped-fs-test|] $ do
            embed . print =<< SA.read SA.ToEnd

            -- SA.extend "baz"
            {-  We get the following type error *before runtime* ! :
                • Unhandled effect 'SA.Extend [Char]'
                Probable fix:
                    add an interpretation for 'SA.Extend [Char]'
                • In a stmt of a 'do' block: SA.extend "baz"
                In the third argument of ‘scopedFile’, namely
                    ‘do embed . print =<< SA.read SA.ToEnd
                        SA.extend "baz"’
                In a stmt of a 'do' block:
                    scopedFile
                    @ReadAccess
                    (Path.Internal.Path "/tmp/polysemy-scoped-fs-test" ::
                        Path Abs File)
                    do embed . print =<< SA.read SA.ToEnd
                        SA.extend "baz"
            -}

-- >>> writeFoobar
-- "foobar"
-- "foobar"
----

== License

This package is mainly licensed under 'AGPL-3.0-or-later'. However,
only the below files partially contain source codes that are licensed
under 'AGPL-3.0-or-later AND BSD-...'. Please see the header comments
in these files for the details. These files also include the copyright
notice, the conditions, and the disclaimer related to the BSD license.

* src/Polysemy/Scoped/Path.hs
* src/Polysemy/Scoped/Path/Internal.hs
* src/Polysemy/FS/Scoped/Internal.hs

=== Submission of Contributions

Unless You explicitly state otherwise, any Contribution intentionally
submitted for inclusion in the Work by You to the Licensor shall be
under the terms and conditions of AGPL-3.0-or-later, without any
additional terms or conditions; where Contribution, Work, You, and
Licensor are as defined in the Apache-2.0 license.