001/*
002 * JDrupes Builder
003 * Copyright (C) 2026 Michael N. Lipp
004 * 
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.builder.api;
020
021import java.nio.file.Path;
022import java.util.stream.Stream;
023
024/// The representation of a tree of [InputResource]s. Each [InputResource]
025/// in the tree is identified by a path relative to the root of the tree.
026///
027/// Implementations of this interface must provide a [ResourceFactory]
028/// that supports the invocation of [ResourceFactory#create] with
029/// the following arguments
030///
031/// * The backing [InputResource] for the [InputTree]
032/// * [String]\[\] an array of ant-style path patterns
033///
034/// Implementations of the jdbld API must at least support the creation
035/// of an [InputTree] from a [ZipFile].
036/// 
037/// Implementations of this interface must ensure that the content
038/// of the input tree is not evaluated before a consuming operation
039/// is performed on the [Stream] returned by [#paths] or [#entries].
040///
041/// @param <T> the contained type
042///
043public interface InputTree<T extends InputResource> extends Resources<T> {
044
045    /// An Entry in the tree.
046    ///
047    /// @param <T> the generic type
048    /// @param path the path
049    /// @param resource the resource
050    ///
051    public record Entry<T extends InputResource>(Path path, T resource) {
052    }
053
054    /// Add a ant-style path pattern to exclude from the tree.
055    ///
056    /// @param pattern the pattern
057    /// @return the file tree
058    ///
059    InputTree<T> exclude(String pattern);
060
061    /// Returns the relative paths of the entries in this tree.
062    ///
063    /// @return the stream
064    ///
065    Stream<Path> paths();
066
067    /// Returns the paths of the files in this file tree relative to
068    /// its root.
069    ///
070    /// @return the stream
071    ///
072    Stream<Entry<T>> entries();
073
074    /// Creates a new input file tree from the given backing input resources.
075    ///
076    /// @param backing the source
077    /// @param patterns the patterns. If no patterns are given, the
078    /// default pattern "**" is used
079    /// @return the file tree
080    ///
081    @SuppressWarnings({ "PMD.UseDiamondOperator", "PMD.ShortMethodName" })
082    static InputTree<InputResource> of(InputResource backing,
083            String... patterns) {
084        return ResourceFactory.create(
085            new ResourceType<InputTree<InputResource>>() {}, null, backing,
086            (Object) patterns);
087    }
088}