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