lice-comb.matching — com.github.pmonks/lice-comb 2.0.160-RC1

The core matching functionality within lice-comb. Matching is provided for three categories of input, and uses a different process for each:

1. License names
2. License uris
3. License texts

Each matching fn has two variants:

1. A 'simple' version that returns a set of SPDX expressions (Strings)
2. An 'info' version that returns an 'expressions-info map'

An expressions-info map has this structure:

• key: an SPDX expression (String), which may be a single SPDX license identifier)
• value: a sequence of 'expression-info' maps

Each lice-comb expression-info map has this structure:

• :id (String, optional): The SPDX identifier within the expression that this info map refers to.
• :type (either :declared or :concluded, mandatory): Whether this identifier was unambiguously declared within the input or was instead concluded by lice-comb (see SPDX specification for more detail on the definition of these two terms).
• :confidence (one of: :high, :medium, :low, only provided when :type = :concluded): Indicates the approximate confidence lice-comb has in its conclusions for this particular SPDX identifier.
• :strategy (a keyword, mandatory): The strategy lice-comb used to determine this particular SPDX identifier. See the source for lice-comb.utils for an up-to-date list of all possible values.
• :source (a sequence of Strings): The list of sources used to arrive at this SPDX identifier, starting from the most general (the input) to the most specific (the smallest subset of the input that was used to make this determination).

id->name clj

(id->name id)

Returns the human readable name of the given license or exception identifier; either the official SPDX license or exception name or, if the id is a lice-comb specific LicenseRef, a lice-comb specific name. Returns the id verbatim if unable to determine a name. Returns nil if the id is blank.

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.

Note: this method has a substantial performance cost.

name->expressions clj

(name->expressions name)

Attempts to determine the SPDX license expression(s) (a set of Strings) from the given 'license name' (a String), or nil if there aren't any. This involves:

1. Determining whether the name is a valid SPDX license expression, and if so normalising (see clj-spdx's spdx.expressions/normalise fn) and returning it
2. Checking if the name is actually a URI, and if so performing URL matching on it (as per url->ids)
3. attempting to construct one or more SPDX license expressions from the name

name->expressions-info clj

(name->expressions-info name)

Returns a lice-comb expressions-info map for the given 'license name' (a String), or nil if there isn't one. This involves:

1. Determining whether the name is a valid SPDX license expression, and if so normalising it (see clj-spdx's spdx.expressions/normalise fn)
2. Checking if the name is actually a URI, and if so performing URL matching on it (as per url->ids-info)
3. attempting to construct one or more SPDX license expressions from the name

The keys in the maps are the detected SPDX license and exception identifiers, and each value contains information about how that identifiers was determined.

proprietary-commercial? clj

(proprietary-commercial? id)

Is the given id lice-comb's custom 'proprietary / commercial' LicenseRef?

public-domain? clj

(public-domain? id)

Is the given id lice-comb's custom 'public domain' LicenseRef?

text->ids clj

(text->ids text)

Returns a set of SPDX expressions (Strings) for the given license text (a String, Reader, InputStream, or something that is accepted by clojure.java.io/reader - File, URL, URI, Socket, etc.), or nil if no expressions were found.

Notes:

• this function implements the SPDX matching guidelines (via clj-spdx). See https://spdx.github.io/spdx-spec/v2.3/license-matching-guidelines-and-templates/
• the caller is expected to open & close a Reader or InputStream passed to this function (e.g. using clojure.core/with-open)
• you cannot pass a String representation of a filename to this method - you should pass filenames through clojure.java.io/file (or similar) first

text->ids-info clj

(text->ids-info text)

Returns an expressions-info map for the given license text (a String, Reader, InputStream, or something that is accepted by clojure.java.io/reader - File, URL, URI, Socket, etc.), or nil if no expressions were found.

Notes:

• this function implements the SPDX matching guidelines (via clj-spdx). See https://spdx.github.io/spdx-spec/v2.3/license-matching-guidelines-and-templates/
• the caller is expected to open & close a Reader or InputStream passed to this function (e.g. using clojure.core/with-open)
• you cannot pass a String representation of a filename to this method - you should pass filenames through clojure.java.io/file (or similar) first

unlisted? clj

(unlisted? id)

Is the given id a lice-comb custom 'unlisted' LicenseRef?

uri->ids clj

(uri->ids uri)

Returns the SPDX license and/or exception identifiers (a set of Strings) for the given uri, or nil if there aren't any. It does this via two steps:

1. Seeing if the given URI is in the license or exception list, and returning the ids of the associated licenses and/or exceptions if so
2. Attempting to retrieve the plain text content of the given URI and performing full SPDX license matching on the result if there was one

Notes on step 1:

1. this does not perform exact matching; rather it simplifies URIs in various ways to avoid irrelevant differences, including performing a case-insensitive comparison, ignoring protocol differences (http vs https), ignoring extensions representing MIME types (.txt vs .html, etc.), etc. See lice-comb.impl.utils/simplify-uri for exact details.
2. URIs in the SPDX license and exception lists are not unique - the same URI may represent multiple licenses and/or exceptions.

uri->ids-info clj

(uri->ids-info uri)

Returns an exceptions-info map for the given license uri (a String, URL, or URI).

Notes:

• This is done

Returns the SPDX license and/or exception identifiers (a map) for the given uri, or nil if there aren't any. It does this via two steps:

1. Seeing if the given URI is in the license or exception list, and returning the ids of the associated licenses and/or exceptions if so
2. Attempting to retrieve the plain text content of the given URI and performing full SPDX license matching on the result if there was one

Notes on step 1:

1. this does not perform exact matching; rather it simplifies URIs in various ways to avoid irrelevant differences, including performing a case-insensitive comparison, ignoring protocol differences (http vs https), ignoring extensions representing MIME types (.txt vs .html, etc.), etc. See lice-comb.impl.utils/simplify-uri for exact details.
2. URIs in the SPDX license and exception lists are not unique - the same URI may represent multiple licenses and/or exceptions.

The keys in the maps are the detected SPDX license and exception identifiers, and each value contains information about how that identifiers was determined.