Shikensu

๐Ÿš€

program : (Task -> Task) -> Path -> Program

Create a Shikensu Program.

This is basically a wrapper around list and perform. It creates a SimpleProgram for you, initialises the needed permissions, lists the given directory path, and finally performs the given task (sequence). It also prints errors to stderr or a success message to stdout.

The example below with the comments should help you understand the flow:

import FileSystem.Path as Path
import Shikensu
import Shikensu.Contrib as Shikensu
import Task

-- Our `Program` which references our `sequence` (more on that later)
-- and our relative directory path we want to list (empty path = current directory)
main =
    Shikensu.program sequence Path.empty

-- This is our `sequence`.
-- Here we receive a `Task` that contains the directory listing (aka. the compendium)
-- We essentially do two things with this listing:
-- (1) We manipulate it (these are the `Task.map` calls)
-- (2) Or we perform some IO operation (these are the `Task.andThen` calls)
       -> `read` reads the content of the files.
       -> `write` writes the manipulated in-memory representations of the files back to disk.
sequence task =
    task
        |> Task.map (Shikensu.withExtension "md")
        |> Task.andThen Shikensu.read
        |> Task.map (Shikensu.renderContent markdownRenderer) -- See `example` folder
        |> Task.andThen (Shikensu.write destinationPath)
programs : Array { path : Path, sequence : Task -> Task } -> Program

Provides a way to make multiple lists and operate on them.

Technically not multiple programs, but same idea as the program function, just with multiple lists.

Programs are performed sequentially.

import FileSystem.Path as Path
import Shikensu

Shikensu.programs
    [ { path = Path.fromPosixString "./posts"
      , sequence = Task.andThen Shikensu.read
      }
    , { path = Path.fromPosixString "./images"
      , sequence = Task.map (\bundle -> ...)
      }
    ]
type alias Program = Program {} {}

Alias for a Node program.

type alias Task = Task Error Bundle

Alias for the main Task type we'll be working with here.

list : Permission -> Path -> Task

The list function itself, unwrapped.

Recursively lists a directory and then gives you a Task containing a Bundle which in turns has an array of Definitions stored under the property named compendium.

This collection of Definitions is the main thing you'll be working with. The goal of this library is to scan a file tree, manipulate it and then optionally write it back to disk. This is done through these definitions.

import FileSystem.Path as Path
import Shikensu

Shikensu.perform
    -- To ignore, return `Cmd.none`
    { onSuccess = \env _ -> Stream.sendLine env.stdout "๐Ÿงช Sequence completed"
    , onError = \env err -> Stream.sendLine env.stderr ("๐Ÿšจ " ++ Error.toString err)
    }
    (\fsPermission ->
        Path.empty
            |> Shikensu.list fsPermission
            |> Task.map (Shikensu.withExtension "md")
    )
perform :
{ onSuccess : Environment -> a -> Task Error {}
, onError : Environment -> Error -> Task Never {}
}
-> (Permission -> Task Error a)
-> Program

A utility function that helps you create programs.

This function is also useful for when you want to write definitions to disk. Maybe you have a JSON file and you want to split it up in multiple files, that's something you can do with this function.

import FileSystem.Path as Path
import Shikensu

Shikensu.perform
    -- To ignore, return `Cmd.none`
    { onSuccess = \env _ -> Stream.sendLine env.stdout "๐Ÿงช Sequence completed"
    , onError = \env err -> Stream.sendLine env.stderr ("๐Ÿšจ " ++ Error.toString err)
    }
    (\fsPermission ->
        [ { baseName = "json-file-1"
          , content = Just jsonBytes
          , directoryPath = Path.fromPosixString "splitted"
          , extensionName = Just "json"
          , metadata = Dict.empty
          }
        ]
            |> Shikensu.bundle fsPermission
            |> Task.andThen (Shikensu.write CurrentDirectory)
    )

This uses Node.defineSimpleProgram and FileSystem.initialize underneath and then manages the Shikensu.Task value created by list or some other function.

See the list function above for an example using list.

IO

read : Bundle -> Task

Read the files in the given compendium/bundle, setting the content property in the definition.

write : Path -> Bundle -> Task

Write each definition to their respective location. The location will depend on the destination path.

๐Ÿ› ๏ธ

bundle : Permission -> Array Definition -> Bundle

A Task that bundles an array of definitions (compendium).

Use this to write a custom array of definitions to disk (there's an example in the perform function docs).