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":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/Version.java#L71-L107","documentation":"Version.parse in pkl-executor validates that an input string is a semantic version number using a VERSION regex. When the string does not match (and is not merely too large to fit), it throws IllegalArgumentException stating the value could not be parsed as a semantic version. The library throws this to reject malformed version strings early instead of failing later with confusing errors.","triggerScenarios":"Calling Version.parse(String) with a string that fails the VERSION regex: missing components (e.g. \"1.2\"), non-numeric parts, illegal pre-release/build metadata, or entirely non-version text like \"latest\" or a path.","commonSituations":"Hardcoded version constants with typos; interpolating an env var or property that is unset or holds a placeholder; passing a version range like \"1.x\" or \">=1.0.0\" where an exact version is expected; copying versions with stray whitespace or a leading 'v'.","solutions":["Fix the version string to a full semver form MAJOR.MINOR.PATCH with optional -prerelease/+build, e.g. \"1.2.3\".","Print/inspect the offending string; strip whitespace, a leading \"v\", or quotes before parsing.","If the value comes from config/env, add a default or fallback constant like \"0.0.0\" when unset.","If you only need comparison, parse with a lenient parser first and normalize the input before calling Version.parse."],"exampleFix":"// before\nVersion.parse(System.getenv(\"PKL_VERSION\")); // \"\" -> throws\n// after\nString v = System.getenv(\"PKL_VERSION\");\nVersion.parse(v == null || v.isBlank() ? \"0.27.1\" : v.trim().replaceFirst(\"^v\", \"\"));","handlingStrategy":"validation","validationCode":"private static final Pattern SEMVER = Pattern.compile(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(-[0-9A-Za-z.-]+)?(\\\\+[0-9A-Za-z.-]+)?$\");\nif (v == null || !SEMVER.matcher(v.trim().replaceFirst(\"^v\",\"\")).matches()) throw new IllegalArgumentException(\"Not a semver: \" + v);","typeGuard":"static boolean isSemVer(String s) { return s != null && Pattern.compile(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+([-.][0-9A-Za-z.-]+)*$\", 0).matcher(s.trim()).matches(); }","tryCatchPattern":"try { Version.parse(v); } catch (IllegalArgumentException e) { log.error(\"Bad version '{}': {}\", v, e.getMessage()); throw new ConfigException(\"pkl version must be semver\", e); }","preventionTips":["Store versions as semver constants in code, not free-form config","Normalize input: trim, strip leading 'v', before parsing","Add a startup validation step that parses all configured versions","Use java.util.regex to pre-validate user-supplied versions"],"tags":["java","parsing","semver","validation"],"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-14T11:17:12.474Z"}