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