Throws {@link IllegalArgumentException} if the given string could not be parsed as a\n * semantic version number or is too large to fit into a {@link Version}.\n */\n public static Version parse(String version) {\n var result = parseOrNull(version);\n if (result != null) return result;\n\n if (VERSION.matcher(version).matches()) {\n throw new IllegalArgumentException(\n String.format(\"`%s` is too large to fit into a Version.\", version));\n }\n\n throw new IllegalArgumentException(\n String.format(\"`%s` could not be parsed as a semantic version number.\", version));\n }\n\n /**\n * Parses the given string as a semantic version number.\n *\n *
Returns {@code null} if the given string could not be parsed as a semantic version number or\n * is too large to fit into a {@link Version}.\n */\n public static @Nullable Version parseOrNull(String version) {\n var matcher = VERSION.matcher(version);\n if (!matcher.matches()) return null;\n\n try {\n return new Version(\n Integer.parseInt(matcher.group(1)),\n Integer.parseInt(matcher.group(2)),\n Integer.parseInt(matcher.group(3)),","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/Version.java#L70-L106","documentation":"Version.parse throws this IllegalArgumentException when the input neither parses as a Version nor even matches the VERSION regex, i.e. it is not a well-formed semantic version string at all. The fallback branch after the 'too large' check produces this message.","triggerScenarios":"Version.parse with strings like \"abc\", \"1.2\", \"v1.2.3\", \"1.2.3-beta.1+meta\" if unsupported, or empty/whitespace input that fails the semver pattern.","commonSituations":"Reading versions from CLI args, env vars, or config files with typos or a leading 'v'; legacy version strings like \"1.2\"; locale-formatted versions like \"1,2,3\".","solutions":["Pass a full semantic version string: MAJOR.MINOR.PATCH (e.g. \"1.2.3\").","Strip prefixes like \"v\" and trim whitespace before parsing.","Use Version.parseOrNull and branch on null to handle invalid input gracefully instead of throwing."],"exampleFix":"// before\nVersion v = Version.parse(\"v1.2\"); // throws\n// after\nVersion v = Version.parse(\"1.2.0\");","handlingStrategy":"validation","validationCode":"Pattern SEMVER = Pattern.compile(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(-[0-9A-Za-z.-]+)?$\");\nif (!SEMVER.matcher(input).matches()) {\n throw new IllegalArgumentException(\"expected MAJOR.MINOR.PATCH, got: \" + input);\n}","typeGuard":"Version safeParse(String s) { var v = Version.parseOrNull(s); return v; /* null when malformed */ }","tryCatchPattern":"try {\n return Version.parse(input);\n} catch (IllegalArgumentException e) {\n throw new IllegalArgumentException(\"`\" + input + \"` is not a valid semver (expected e.g. 1.2.3)\", e);\n}","preventionTips":["Trim whitespace and strip a leading 'v' before parsing.","Validate version strings with a semver regex at the boundary (CLI/env/config).","Prefer parseOrNull over parse when invalid input is expected to be possible."],"tags":["versioning","parsing","pkl","format"],"backgroundTag":"invalid-argument-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}