diff --git a/pkl-core/src/main/java/org/pkl/core/Member.java b/pkl-core/src/main/java/org/pkl/core/Member.java index 45b1e398..3e33a799 100644 --- a/pkl-core/src/main/java/org/pkl/core/Member.java +++ b/pkl-core/src/main/java/org/pkl/core/Member.java @@ -98,6 +98,12 @@ public abstract class Member implements Serializable { return simpleName; } + /** + * The source location of a {@link Member}. + * + * @param startLine the first line of the member + * @param endLine the last line of the member + */ public record SourceLocation(int startLine, int endLine) implements Serializable { @Serial private static final long serialVersionUID = 0L; diff --git a/pkl-core/src/main/java/org/pkl/core/Platform.java b/pkl-core/src/main/java/org/pkl/core/Platform.java index f1cd450c..385cabee 100644 --- a/pkl-core/src/main/java/org/pkl/core/Platform.java +++ b/pkl-core/src/main/java/org/pkl/core/Platform.java @@ -22,6 +22,12 @@ import org.graalvm.home.Version; /** * Information about the Pkl release that the current program runs on. This class is the Java * equivalent of standard library module {@code pkl.platform}. + * + * @param language the language implementation of this platform + * @param runtime the language runtime of this platform + * @param virtualMachine the virtual machine of this platform + * @param operatingSystem the operating system of this platform + * @param processor the processor of this platform */ public record Platform( Language language, @@ -68,31 +74,31 @@ public record Platform( /** * The language runtime of a platform. * - * @param name the name of this language runtime. - * @param version the version of this language runtime. + * @param name the name of this language runtime + * @param version the version of this language runtime */ public record Runtime(String name, String version) {} /** * The virtual machine of a platform. * - * @param name the name of this virtual machine. - * @param version the version of this virtual machine. + * @param name the name of this virtual machine + * @param version the version of this virtual machine */ public record VirtualMachine(String name, String version) {} /** * The operating system of a platform. * - * @param name the name of this operating system. - * @param version the version of this operating system. + * @param name the name of this operating system + * @param version the version of this operating system */ public record OperatingSystem(String name, String version) {} /** * The processor of a platform. * - * @param architecture the instruction set architecture of this processor. + * @param architecture the instruction set architecture of this processor */ public record Processor(String architecture) {} } diff --git a/pkl-core/src/main/java/org/pkl/core/Release.java b/pkl-core/src/main/java/org/pkl/core/Release.java index 78ac20d1..cc77c015 100644 --- a/pkl-core/src/main/java/org/pkl/core/Release.java +++ b/pkl-core/src/main/java/org/pkl/core/Release.java @@ -19,15 +19,31 @@ import com.oracle.truffle.api.TruffleOptions; import java.io.IOException; import java.util.LinkedHashSet; import java.util.List; -import java.util.Objects; import java.util.Properties; import java.util.Set; /** * Information about the Pkl release that the current program runs on. This class is the Java * equivalent of standard library module {@code pkl.release}. + * + * @param version the version of this release + * @param os the operating system (name and version) this release is running on + * @param flavor the flavor of this release (native, or Java and JVM version) + * @param versionInfo the output of {@code pkl --version} for this release + * @param commitId the Git commit ID of this release + * @param sourceCode the source code of this release + * @param documentation the documentation of this release + * @param standardLibrary the standard library of this release */ -public final class Release { +public record Release( + Version version, + String os, + String flavor, + String versionInfo, + String commitId, + SourceCode sourceCode, + Documentation documentation, + StandardLibrary standardLibrary) { private static final String SOURCE_CODE_HOMEPAGE = "https://github.com/apple/pkl/"; private static final String DOCUMENTATION_HOMEPAGE = "https://pkl-lang.org/main/"; @@ -72,98 +88,17 @@ public final class Release { new StandardLibrary(stdlibModules)); } - private final Version version; - private final String os; - private final String flavor; - private final String versionInfo; - private final String commitId; - private final SourceCode sourceCode; - private final Documentation documentation; - private final StandardLibrary standardLibrary; - - /** Constructs a release. */ - public Release( - Version version, - String os, - String flavor, - String versionInfo, - String commitId, - SourceCode sourceCode, - Documentation documentation, - StandardLibrary standardLibrary) { - this.version = version; - this.os = os; - this.flavor = flavor; - this.versionInfo = versionInfo; - this.commitId = commitId; - this.sourceCode = sourceCode; - this.documentation = documentation; - this.standardLibrary = standardLibrary; - } - /** The Pkl release that the current program runs on. */ public static Release current() { return CURRENT; } - /** The version of this release. */ - public Version version() { - return version; - } - - /** The operating system (name and version) this release is running on. */ - public String os() { - return os; - } - - /** The flavor of this release (native, or Java and JVM version). */ - public String flavor() { - return flavor; - } - - /** The output of {@code pkl --version} for this release. */ - public String versionInfo() { - return versionInfo; - } - - /** The Git commit ID of this release. */ - public String commitId() { - return commitId; - } - - /** The source code of this release. */ - public SourceCode sourceCode() { - return sourceCode; - } - - /** The documentation of this release. */ - public Documentation documentation() { - return documentation; - } - - /** The standard library of this release. */ - public StandardLibrary standardLibrary() { - return standardLibrary; - } - - @Override - public boolean equals(Object obj) { - if (this == obj) return true; - if (!(obj instanceof Release other)) return false; - return version.equals(other.version) - && versionInfo.equals(other.versionInfo) - && commitId.equals(other.commitId) - && sourceCode.equals(other.sourceCode) - && documentation.equals(other.documentation) - && standardLibrary.equals(other.standardLibrary); - } - - @Override - public int hashCode() { - return Objects.hash(version, versionInfo, commitId, sourceCode, documentation, standardLibrary); - } - - /** The source code of a Pkl release. */ + /** + * The source code of a Pkl release. + * + * @param homepage the homepage of this source code + * @param version the version of this source code + */ public record SourceCode(String homepage, String version) { /** * @deprecated As of 0.28.0, replaced by {@link #version()}. @@ -181,8 +116,16 @@ public final class Release { return homepage + "blob/" + version + "/" + path; } - /** The source code scheme for the stdlib module. */ + /** + * @deprecated As of 0.28.0, replaced by {@link #sourceCodeUrlScheme()}. + */ + @Deprecated(forRemoval = true) public String getSourceCodeUrlScheme() { + return sourceCodeUrlScheme(); + } + + /** Returns the source code scheme for the stdlib module. */ + public String sourceCodeUrlScheme() { return homepage + "blob/" + version + "/stdlib%{path}#L%{line}-L%{endLine}"; } } @@ -190,7 +133,7 @@ public final class Release { /** * The documentation of a Pkl release. * - * @param homepage the homepage of this documentation. + * @param homepage the homepage of this documentation */ public record Documentation(String homepage) {} @@ -198,7 +141,7 @@ public final class Release { * The standard library of a Pkl release. * * @since 0.21.0 - * @param modules the modules of this standard library. + * @param modules the modules of this standard library */ public record StandardLibrary(Set modules) {} } diff --git a/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt b/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt index fd32925f..41ce50ff 100644 --- a/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt +++ b/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt @@ -49,7 +49,7 @@ class CliDocGenerator(private val options: CliDocGeneratorOptions) : CliCommand( sourceCodeUrlScheme = if (options.isTestMode) "https://github.com/apple/pkl/blob/0.24.0/stdlib%{path}#L%{line}-L%{endLine}" - else Release.current().sourceCode().sourceCodeUrlScheme, + else Release.current().sourceCode().sourceCodeUrlScheme(), documentation = if (options.isTestMode) URI("https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/") else diff --git a/pkl-doc/src/main/kotlin/org/pkl/doc/DocScope.kt b/pkl-doc/src/main/kotlin/org/pkl/doc/DocScope.kt index c100fc09..a99ae9ab 100644 --- a/pkl-doc/src/main/kotlin/org/pkl/doc/DocScope.kt +++ b/pkl-doc/src/main/kotlin/org/pkl/doc/DocScope.kt @@ -210,7 +210,7 @@ internal class SiteScope( val path = "/stdlib/${name.substring(4)}.pkl" Release.current() .sourceCode() - .sourceCodeUrlScheme + .sourceCodeUrlScheme() .replaceSourceCodePlaceholders(path, sourceLocation) .toUri() }