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 (ie. the focus), 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 Shikensu
import Shikensu.Contrib as Shikensu
import Shikensu.Focus exposing (Focus(..))
import Task

-- Our `Program` which references out `sequence` (more on that later)
-- and our `Focus`, the target directory we want to list.
main =
    Shikensu.program sequence CurrentDirectory

-- 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 destinationFocus)

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 Shikensu
import Shikensu.Focus exposing (Focus(..))

Shikensu.programs
    [ { focus = Relative (Path.directory [ "posts" ])
      , sequence = Task.andThen Shikensu.read
      }
    , { focus = Relative (Path.directory [ "images" ])
      , sequence = Task.map (\bundle -> ...)
      }
    ]

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 Shikensu
import Shikensu.Focus exposing (Focus(..))

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 ->
        CurrentDirectory
            |> Shikensu.list fsPermission
            |> Task.map (Shikensu.withExtension "md")
    )

⚠️ The given Focus will always be in the context of the environment of the resulting Gren binary that is being executed. So for example, say your pwd command returns ~/code/shikensu/, and your focus is Relative (Path.Directory [ "..", "example" ]). If you run ./binary/app the resulting path will be ~/code/example/.

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 Shikensu
import Shikensu.Focus exposing (Focus(..))

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.directory [ "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.

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

Write each definition to their respective location. The location will depend on the focus and the environment it was run in.

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).

This is basically a small wrapper around currentWorkingDirectory that makes a Bundle.

Get the absolute directory path of the current working directory.