spdx.expressions
SPDX license expression functionality. This functionality is bespoke (it is
not provided by Spdx-Java-Library).
init!
(init!)
Initialises this namespace upon first call (and does nothing on subsequent
calls), returning nil. Consumers of this namespace are not required to call
this fn, as initialisation will occur implicitly anyway; it is provided to
allow explicit control of the cost of initialisation to callers who need it.
normalise
(normalise s)
(normalise s opts)
Normalises an SPDX expression, by running it through parse then unparse.
Returns nil if `s` is nil or is not a valid SPDX expression.
`opts` are as for parse
parse
(parse s)
(parse s {:keys [normalise-gpl-ids? case-sensitive-operators?], :or {normalise-gpl-ids? true, case-sensitive-operators? false}, :as opts})
Attempt to parse `s` (a String) as an SPDX license expression, returning a
data structure representing the parse tree, or nil if it cannot be parsed.
The optional `opts` map has these keys:
* `normalise-gpl-ids?` (boolean, default true) - controls whether
deprecated 'historical oddity' GPL family ids in the expression are
normalised to their non-deprecated replacements as part of the parsing
process.
* `case-sensitive-operators?` (boolean, default false) - controls whether
operators in expressions (AND, OR, WITH) are case-sensitive
(spec-compliant, but strict) or not (non-spec-compliant, lenient).
Notes:
* The parser always normalises SPDX ids to their canonical case
e.g. aPAcHe-2.0 -> Apache-2.0
* The parser always removes redundant grouping
e.g. (((((Apache-2.0)))))) -> Apache-2.0
* The parser synthesises grouping when needed to make SPDX license
expressions' precedence rules explicit (see
https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/#d45-order-of-precedence-and-parentheses)
* The default options result in parsing that is more lenient than the SPDX
specification and that is therefore not strictly spec compliant. You can
enable strictly compliant parsing by setting `normalise-gpl-ids?` to `false`
and `case-sensitive-operators?` to `true`.
Examples (assuming default options):
"Apache-2.0"
-> {:license-id "Apache-2.0"}
"Apache-2.0+"
-> {:license-id "Apache-2.0" :or-later? true}
"GPL-2.0+"
-> {:license-id "GPL-2.0-or-later"}
"GPL-2.0 WITH Classpath-exception-2.0"
-> {:license-id "GPL-2.0-only"
:license-exception-id "Classpath-exception-2.0"}
"CDDL-1.1 or (GPL-2.0+ with Classpath-exception-2.0)"
-> [:or
{:license-id "CDDL-1.1"}
{:license-id "GPL-2.0-or-later"
:license-exception-id "Classpath-exception-2.0"}]
"DocumentRef-foo:LicenseRef-bar")
-> {:document-ref "foo"
:license-ref "bar"}
See SPDX Specification Annex D for more details on SPDX license expressions:
https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/
parse-with-info
(parse-with-info s)
(parse-with-info s {:keys [normalise-gpl-ids? case-sensitive-operators?], :or {normalise-gpl-ids? true, case-sensitive-operators? false}})
unparse
(unparse parse-result)
Turns a valid `parse-result` (i.e. obtained from `parse`) back into a
canonicalised SPDX expression (a String). Results are undefined for invalid
parse trees. Returns nil if `parse-result` is nil.
Canonicalisation involves:
* Converting all SPDX listed identifiers to their official case
* Upper casing all operators
* Removing redundant grouping (parens)
* Adding grouping (parens) to make precedence rules explicit
* (with default options) Normalising deprecated 'historical oddity' GPL family
ids to their non-deprecated replacements
valid?
(valid? s)
(valid? s {:keys [case-sensitive-operators?], :or {case-sensitive-operators? false}})
Is `s` (a String) a valid SPDX license expression?
Note: if you intend to parse `s` if it's valid, it's more efficient to call
parse directly and check for a nil result instead of calling this method
first (doing so avoids double parsing).
The optional `opts` map has these keys:
* `case-sensitive-operators?` (boolean, default false) - controls whether
operators in expressions (AND, OR, WITH) are case-sensitive
(spec-compliant, but strict) or not (non-spec-compliant, lenient).