001/*
002 * Copyright (C) 2022 - 2024, 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 org.apiguardian.api.API;
022import org.apiguardian.api.API.Status;
023
024/**
025 * Helpers to create new workspaces.
026 *
027 * @author Ashley Scopes
028 * @since 0.0.1
029 */
030@API(since = "0.0.1", status = Status.STABLE)
031public final class Workspaces extends UtilityClass {
032
033  private Workspaces() {
034    // Do nothing.
035  }
036
037  /**
038   * Create a new default workspace instance using the default path strategy.
039   *
040   * <p>This workspace must be closed after use. Ideally, you should use a try-with-resources
041   * to achieve this. Failing to do this will lead to resources being leaked and tests not being
042   * cleared up correctly.
043   *
044   * <p>The workspace can be passed to {@link JctCompiler#compile(Workspace)} to run the compiler
045   * across this workspace of code.
046   *
047   * <p>For example:
048   *
049   * <pre><code>
050   *   try (var workspace = Workspaces.newWorkspace()) {
051   *     workspace
052   *        .createSourcePathPackage()
053   *        .copyContentsFrom("src", "test", "resources", "test-data");
054   *
055   *     var compilation = someCompiler.compile(workspace);
056   *
057   *     assertThat(compilation).isSuccessful();
058   *   }
059   * </code></pre>
060   *
061   * @return the workspace.
062   */
063  public static Workspace newWorkspace() {
064    return newWorkspace(PathStrategy.defaultStrategy());
065  }
066
067  /**
068   * Create a new default workspace instance using the given path strategy.
069   *
070   * <p>This workspace must be closed after use. Ideally, you should use a try-with-resources
071   * to achieve this. Failing to do this will lead to resources being leaked and tests not being
072   * cleared up correctly.
073   *
074   * <p>The workspace can be passed to {@link JctCompiler#compile(Workspace)} to run the compiler
075   * across this workspace of code.
076   *
077   * <p>For example:
078   *
079   * <pre><code>
080   *   try (var workspace = Workspaces.newWorkspace(PathStrategy.TEMP_DIRECTORIES)) {
081   *     workspace
082   *        .createSourcePathPackage()
083   *        .copyContentsFrom("src", "test", "resources", "test-data");
084   *
085   *     var compilation = someCompiler.compile(workspace);
086   *
087   *     assertThat(compilation).isSuccessful();
088   *   }
089   * </code></pre>
090   *
091   * @param pathStrategy the path strategy to use.
092   * @return the workspace.
093   */
094  public static Workspace newWorkspace(PathStrategy pathStrategy) {
095    return new WorkspaceImpl(pathStrategy);
096  }
097}