spdx.expressions — com.github.pmonks/clj-spdx 1.0.152

SPDX license expression functionality. This functionality is bespoke (it is not provided by Spdx-Java-Library).

extract-ids clj

(extract-ids parse-result)

(extract-ids parse-result
             {:keys [include-or-later?] :or {include-or-later? false} :as opts})

Extract all SPDX ids (as a set of strings) from the given parse-result.

The optional opts map has these keys:

• include-or-later? (boolean, default false) - controls whether the output includes the 'or later' indicator ('+') after license ids that have that designation in the parse tree.

init! clj

(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 clj

(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 clj

(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 clj

(parse-with-info s)

(parse-with-info s
                 {:keys [normalise-gpl-ids? case-sensitive-operators?]
                  :or {normalise-gpl-ids? true
                       case-sensitive-operators? false}})

As for parse, but returns an instaparse parse error info if parsing fails, instead of nil. See https://github.com/Engelberg/instaparse#parse-errors

opts are as for parse

unparse clj

(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? clj

(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).