OsUtil build path/file improvements

[Nathan Cheshire]

I think a builder pattern would improve readability of these:

File myFile = new OsUtil.FileBuilder("src").add("components").add("something.java").getAsFile();

We could also have addFirst, addLast, addAtIndex, and some other fun utility functions.

[Nathan Cheshire]

/**
 * A builder for resources such as Paths, Files, and directories.
 */
public final class ResourceBuilder {
    /**
     * The linked list holding the path pargs.
     */
    private final LinkedList<String> pathParts;

    /**
     * Constructs a new resource builder.
     *
     * @param firstPathPart the first part of the path to build
     */
    public ResourceBuilder(String firstPathPart) {
        Preconditions.checkNotNull(firstPathPart);
        Preconditions.checkArgument(!firstPathPart.isEmpty());

        pathParts = new LinkedList<>();
        pathParts.add(firstPathPart);
    }

    /**
     * Adds the provided path part to the end of the path parts list.
     *
     * @param pathPart the path part to add
     */
    public ResourceBuilder add(String pathPart) {
        Preconditions.checkNotNull(pathPart);
        Preconditions.checkArgument(!pathPart.isEmpty());

        pathParts.add(pathPart);
    }

    /**
     * Adds the provided path parts to the end of the path parts list.
     * Note: the order of the list is maintained as the parts are added to the internal parts list.
     *
     * @param parts the parts to add sequentially
     */
    public ResourceBuilder add(List<String> parts) {
        Preconditions.checkNotNull(parts);

        pathParts.addAll(parts);
    }

    /**
     * Adds the provided part to the beginning.
     *
     * @param pathPart the part to add
     */
    public ResourceBuilder addFirst(String pathPart) {
        Preconditions.checkNotNull(pathPart);

        pathParts.addFirst(pathPart);
    }

    /**
     * Adds the provided path parts to the start of the path parts list.
     * Note: the order of the list is maintained as the parts are added to the interal parts list.
     *
     * @param parts the parts to add sequentially
     */
    public ResourceBuilder addFirst(List<String> parts) {
        Preconditions.checkNotNull(pathParts);

        ImmutableList<String> defensiveParts = ImmutableList.copyOf(parts);

        for (int i = defensiveParts.size() - 1 ; i >= 0 ; i--) {
            pathParts.addFirst(defensiveParts.get(i));
        }
    }

    /**
     * Constructs and returns a resource path using the provided paths.
     *
     * @return a resource path using the provided paths
     */
    public String getPath() {
        return constructFormattedPath();
    }

    /**
    * Constructs and returns a new file object using the provided paths.
    *
    * @return a new file object using the provided paths
    */
    public File getFile() {
        File ret = new File(constructFormattedPath());
        Preconditions.checkArgument(ret.isFile());
        return ret;
    }

    /**
     * Constructs and returns a new directory object using the provided paths.
     *
     * @return a new directory object using the provided paths
     */
    public File getDirectory() {
        File ret = new File(constructFormattedPath());
        Preconditions.checkArgument(ret.isDirectory());
        return ret;
    }

    /**
     * Constructs and returned a formatted path using the current state of the parts list.
     *
     * @return a formatted path using the provided path parts
     */
    private String constructFormattedPath() {
        StringBuilder ret = new StringBuilder();
        pathParts.forEach(part -> {
            ret.add(parts.replaceAll("^/+", "").replaceAll("/+$", ""));
        })
        return ret.toString();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int hashCode() {
        return pathParts.hashCode();
    }

     /**
     * {@inheritDoc}
     */
    @Override
    public String toString() {
        return "ResourceBuilder{pathParts=" + pathParts + "}";
    }

     /**
     * {@inheritDoc}
     */
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        } else if (!(o instanceof ResourceBuilder)) {
            return false;
        }

        ResoruceBuilder other = (ResoruceBuilder) o ;
        return pathParts.equals(other.pathParts);
    }
}