001/*
002 * Copyright (C) 2022 - 2023, the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package io.github.ascopes.jct.workspaces;
017
018import io.github.ascopes.jct.compilers.JctCompiler;
019import io.github.ascopes.jct.utils.UtilityClass;
020import io.github.ascopes.jct.workspaces.impl.WorkspaceImpl;
021import java.util.Collection;
022import org.apiguardian.api.API;
023import org.apiguardian.api.API.Status;
024
025/**
026 * Helpers to create new workspaces.
027 *
028 * @author Ashley Scopes
029 * @since 0.0.1
030 */
031@API(since = "0.0.1", status = Status.STABLE)
032public final class Workspaces extends UtilityClass {
033
034  private Workspaces() {
035    // Do nothing.
036  }
037
038  /**
039   * Create a new default workspace instance using the default path strategy.
040   *
041   * <p>This workspace must be closed after use. Ideally, you should use a try-with-resources
042   * to achieve this. Failing to do this will lead to resources being leaked and tests not being
043   * cleared up correctly.
044   *
045   * <p>The workspace can be passed to {@link JctCompiler#compile(Workspace)} to run the compiler
046   * across this workspace of code.
047   *
048   * <p>For example:
049   *
050   * <pre><code>
051   *   try (var workspace = Workspaces.newWorkspace()) {
052   *     workspace
053   *        .createSourcePathPackage()
054   *        .copyContentsFrom("src", "test", "resources", "test-data");
055   *
056   *     var compilation = someCompiler.compile(workspace);
057   *
058   *     assertThat(compilation).isSuccessful();
059   *   }
060   * </code></pre>
061   *
062   * @return the workspace.
063   */
064  public static Workspace newWorkspace() {
065    return newWorkspace(PathStrategy.defaultStrategy());
066  }
067
068  /**
069   * Create a new default workspace instance using the given path strategy.
070   *
071   * <p>This workspace must be closed after use. Ideally, you should use a try-with-resources
072   * to achieve this. Failing to do this will lead to resources being leaked and tests not being
073   * cleared up correctly.
074   *
075   * <p>The workspace can be passed to {@link JctCompiler#compile(Workspace)} to run the compiler
076   * across this workspace of code.
077   *
078   * <p>For example:
079   *
080   * <pre><code>
081   *   try (var workspace = Workspaces.newWorkspace(PathStrategy.TEMP_DIRECTORIES)) {
082   *     workspace
083   *        .createSourcePathPackage()
084   *        .copyContentsFrom("src", "test", "resources", "test-data");
085   *
086   *     var compilation = someCompiler.compile(workspace);
087   *
088   *     assertThat(compilation).isSuccessful();
089   *   }
090   * </code></pre>
091   *
092   * @param pathStrategy the path strategy to use.
093   * @return the workspace.
094   */
095  public static Workspace newWorkspace(PathStrategy pathStrategy) {
096    return new WorkspaceImpl(pathStrategy);
097  }
098}