Directories

Directories - the NonEmptyDtry and Dtry monads

A nonempty directory of Ts (NonEmptyDtry{T}) is essentially a tree whose leaves hold values of type T. Each value is addressed by the path from the root node to the respective leaf, given by a list of Symbols, see DtryPath.

The monad unit sends a value of type T to a tree consisting only of a leaf holding the value.

The monad multiplication flattens a directory of directories of Ts into a directory of Ts by grafting the trees stored at the leaves directly onto their respective parent nodes.

A (possibly empty) directory of Ts (Dtry{T}) is either empty or it is a nonempty directory of Ts. The Dtry monad is hence obtained by composing the NonEmptyDtry monad with the 'Maybe monad'. The composition of the monads relies on a distributive law. Since subdirectories (subtrees) of a directory cannot be empty, the distributive law filters out any empty directories at the leaves, as they cannot be grafted onto their parent nodes.

This module implements directories as an immutable data structure. Subdirectories are stored in lexicographic order to ensure that two directories with the same set of paths (namespace) and the same associated values are equal.

The implementation supports simple access of subdirectories and values, pretty-printing, iteration, mapping, filtering, merging, etc.

The concrete subtypes of AbstractDtry are NonEmptyDtry and Dtry.

A Dtry{T} is either empty or it wraps a NonEmptyDtry of Ts.

Dtry(value::T) -> Dtry{T}

Construct a directory, which contains just a single value (monad unit).

Dtry(pairs::Vararg{Pair{Symbol,Dtry{T}}}) -> Dtry{T}

Construct a directory of Ts from a number of pairs of names and subdirectories. Empty subdirectories are filtered out.

Dtry{T}()

Construct an empty directory of Ts.

Abstract supertype for exceptions that may be thrown when accessing directories. Concrete subtypes are DtryBranchError (branch with a given name does not exist) and DtryLeafError (given directory is not a leaf).

DtryBranchError(dtry::AbstractDtry, name::Symbol)

The given directory has no direct subdirectory with the given name.

DtryLeafError(dtry::AbstractDtry)

The given directory is not a leaf holding a value.

A DtryPath is a linked list of Symbols representing a path in a directory, see also ■.

DtryPath(names::Vararg{Symbol})

Construct a DtryPath from a series of names.

Example

julia> DtryPath(:foo, :bar) == ■.foo.bar
true

A NonEmptyDtry{T} either contains a single value of type T or it has at least one non-empty subdirectory of Ts.

NonEmptyDtry(value::T) -> NonEmptyDtry{T}

Construct a non-empty directory, which contains just a single value (monad unit).

NonEmptyDtry(pairs::Vararg{Pair{Symbol,NonEmptyDtry{T}}}) -> NonEmptyDtry{T}

Construct a non-empty directory of Ts from a number of pairs of names and non-empty subdirectories.

DtryPath representing the root node of a directory. With that, ■.foo represents the path to a subdirectory named foo.

*(p1::DtryPath, p2::DtryPath) -> DtryPath

Concatenate two DtryPaths.

Example

julia> ■.foo * ■.bar == ■.foo.bar
true

zip(dtry1::NonEmptyDtry{T1}, dtry2::NonEmptyDtry{T2}) -> NonEmptyDtry{Tuple{T1,T2}}
zip(dtry1::Dtry{T1}, dtry2::Dtry{T2}) -> Dtry{Tuple{T1,T2}}

Given a directory of T1s and a directory of T2s with the same tree structure, as well as a function f : T1 × T2 -> X, produce a directory of Tuple{T1,T2}s, where the value at path p is given by (dtry1[p], dtry2[p]).

all(p, dtry::Dtry{T}) -> Bool

Returns true if predicate p : T -> Bool returns true for all values of the directory.

all(p, dtry::NonEmptyDtry{T}) -> Bool

Returns true if predicate p : T -> Bool returns true for all values of the directory.

collect(dtry::AbstractDtry{T}) -> Vector{T}

Collect values from a directory.

filter(f, dtry::AbstractDtry{T}) -> Dtry{T}

Given a function f : T -> Bool and a (nonempty) directory of Ts, produce a new directory of Ts by keeping the entry at path p only if f(dtry[p]) == true.

foreach(f, dtry::Dtry{T}) -> Nothing

Call function f on each Pair{DtryPath,T}.

foreach(f, dtry::NonEmptyDtry{T}) -> Nothing

Call function f on each Pair{DtryPath,T}.

get(dtry::Dtry, path::DtryPath, default)

If path refers to a value within dtry, returns the value. Otherwise, returns default.

get(dtry::NonEmptyDtry, path::DtryPath, default)

If path refers to a value within dtry, returns the value. Otherwise, returns default.

getindex(dtry::Dtry{T}, path::DtryPath) -> T

If path refers to a value within dtry, returns the value. Otherwise, throws a DtryAccessError.

getindex(dtry::Dtry{T}) -> T

If dtry isa leaf, dtry[] returns its value. Otherwise, throws a DtryLeafError

getindex(dtry::NonEmptyDtry{T}) -> T

If dtry isa leaf, dtry[] returns its value. Otherwise, throws a DtryLeafError

getindex(dtry::NonEmptyDtry{T}, path::DtryPath) -> T

If path refers to a value within dtry, returns the value. Otherwise, throws a DtryAccessError.

isempty(dtry::AbstractDtry) -> Bool

Returns true if the given directory is empty.

length(path::DtryPath) -> Int

Returns the length of the DtryPath (linked list of Symbols).

Example

julia> length(■.foo.bar) == 2
true

length(dtry::Dtry) -> Int

Returns the number of values (leaves) in the given directory.

length(dtry::NonEmptyDtry) -> Int

Returns the number of values (leaves) in the given directory.

map(f, dtry::NonEmptyDtry{T}) -> NonEmptyDtry{X}
map(f, dtry::Dtry{T}) -> Dtry{X}

Make a new directory of Xs with the same tree structure as dtry, where the value at path p is given by f(dtry[p])::X. The return type X of f is inferred.

map(f, dtry::Dtry{T}, X::Type) -> Dtry{X}

Make a new directory of Xs with the same tree structure as dtry, where the value at path p is given by f(dtry[p])::X.

map(f, dtry::NonEmptyDtry{T}, X::Type) -> NonEmptyDtry{X}

Make a new nonempty directory of Xs with the same tree structure as dtry, where the value at path p is given by f(dtry[p])::X.

mapreduce(f, op, dtry::Dtry{T}, default)

Transforms each value contained in the given directory using the function f : T -> X and reduces the results using the binary operation op : X × X -> X. For an empty directory, returns default.

mapreduce(f, op, dtry::NonEmptyDtry{T})

Transforms each value contained in the given directory using the function f : T -> X and reduces the results using the binary operation op : X × X -> X.

merge(dtry1::NonEmptyDtry{T}, dtry2::NonEmptyDtry{T}) -> NonEmptyDtry{T}
merge(dtry1::Dtry{T}, dtry2::Dtry{T}) -> Dtry{T}

Merge two directories, given that their namespaces are disjoint, i.e. the union of their namespaces is prefix-free.

filtermap(f, dtry::AbstractDtry{T}, X::Type) -> Dtry{X}

Make a new directory of Xs from a (nonempty) directory of Ts based on a function f : T -> Union{Some{X},Nothing}. When f returns nothing, the respective entry is filtered out.

filtermapwithpath(f, dtry::AbstractDtry{T}, X::Type) -> Dtry{X}

Make a new directory of Xs from a (nonempty) directory of Ts based on a function f : DtryPath × T -> Union{Some{X},Nothing}. When f returns nothing, the respective entry is filtered out.

foreachpath(f, dtry::Dtry) -> Nothing

Call function f on each path::DtryPath.

foreachpath(f, dtry::NonEmptyDtry) -> Nothing

Call function f on each path::DtryPath.

foreachvalue(f, dtry::Dtry{T}) -> Nothing

Call function f on each value::T.

foreachvalue(f, dtry::NonEmptyDtry{T}) -> Nothing

Call function f on each value::T.

haspath(dtry::Dtry, path::DtryPath) -> Bool

Returns true if the given directory contains a leaf/value at the given path.

haspath(dtry::NonEmptyDtry, path::DtryPath) -> Bool

Returns true if the given directory contains a leaf/value at the given path.

hasprefix(dtry::Dtry, prefix::DtryPath) -> Bool

Returns true if the given directory has a (complete) path (to a leaf/value), which starts with the given prefix (or incomplete path).

hasprefix(dtry::NonEmptyDtry, prefix::DtryPath) -> Bool

Returns true if the given directory has a (complete) path (to a leaf/value), which starts with the given prefix (or incomplete path).

mapwithpath(f, dtry::Dtry{T}, X::Type) -> Dtry{X}

Make a new directory of Xs with the same tree structure as dtry, where the value at path p is given by f((p, dtry[p]))::X.

mapwithpath(f, dtry::NonEmptyDtry{T}, X::Type) -> NonEmptyDtry{X}

Make a new directory of Xs with the same tree structure as dtry, where the value at path p is given by f((p, dtry[p]))::X.

print_dtry(io::IO, dtry::Dtry{T}; prefix::String, print_value=nothing)

Write a pretty-printed representation of the given directory to io. As an optional keyword argument, a function print_value(io::IO, value::T; prefix::String) can be used to pretty-print the values. Whenever the output of print_value spans more than one line, prefix is prepended to the extra lines. To print a directory of directories, let print_values=print_dtry.

print_dtry_repr(io::IO, dtry::Dtry{T})

Write a round-trippable code representation of the given directory to io.

zipmap(f, dtry1::Dtry{T1}, dtry2::Dtry{T2}, X::Type) -> Dtry{X}

Given a directory of T1s and a directory of T2s with the same tree structure, as well as a function f : T1 × T2 -> X, produce a new directory of Xs, where the value at path p is given by f(dtry1[p], dtry2[p]).

zipmap(f, dtry1::NonEmptyDtry{T1}, dtry2::NonEmptyDtry{T2}, X::Type) -> NonEmptyDtry{X}

Given a nonempty directory of T1s and a nonempty directory of T2s with the same tree structure, as well as a function f : T1 × T2 -> X, produce a new nonempty directory of Xs, where the value at path p is given by f(dtry1[p], dtry2[p]).

zipmapwithpath(f, dtry1::Dtry{T1}, dtry2::Dtry{T2}, X::Type) -> Dtry{X}

Given a directory of T1s and a directory of T2s with the same tree structure, as well as a function f : DtryPath × T1 × T2 -> X, produce a new directory of Xs, where the value at path p is given by f(p, dtry1[p], dtry2[p]).

zipmapwithpath(f, dtry1::NonEmptyDtry{T1}, dtry2::NonEmptyDtry{T2}, X::Type) -> NonEmptyDtry{X}

Given a directory of T1s and a directory of T2s with the same tree structure, as well as a function f : DtryPath × T1 × T2 -> X, produce a new directory of Xs, where the value at path p is given by f(p, dtry1[p], dtry2[p]).

flatten(dtry::NonEmptyDtry{NonEmptyDtry{T}}) -> Dtry{T}

Flattens a nonempty directory of nonempty directories (monad multiplication).

flatten(dtry::Dtry{Dtry{T}}) -> Dtry{T}

Flattens a directory of directories (monad multiplication).