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}