Module spdx

Expand description

Constructs headers for SPDX licenses from the license crate.

Some licenses are effectively templates: certain tokens like <yyyy> or year are intended to be replaced with some user-defined value, like the copyright year in this case. These are represented by the LicenseTokens trait, with the replacement values needed to construct the final header text defined by LicenseTokens::TokenReplacementValues. If no tokens need to be replaced, NoTokens is available for that purpose.

Several common licenses have structs defined, with LicenseTokens already appropriately implemented (e.g. APACHE_2_0).

Most other licenses don’t need anything other than the copyright year and the copyright holder, or have nothing at all, and can be easily turned into headers with SpdxLicense, a type to define the tokens to replace (or NoTokens), and YearCopyrightOwnerValue.

If you find yourself needing a license that’s not already available easily with a struct in this module, see the examples below, and consider making a PR to add support.

§Examples

§Getting a header for the Apache 2.0 license:

// Copyright 2023 Google LLC.
// SPDX-License-Identifier: Apache-2.0
use std::path;
use file_header::license::spdx::*;

// Apache 2 has all relevant types already defined, and just needs year and name
let header = APACHE_2_0.build_header(YearCopyrightOwnerValue::new(2023, "Some copyright holder".to_string()));

// use normal header API to check or add

§Getting a header for an SPDX license with no tokens to replace

// Copyright 2023 Google LLC.
// SPDX-License-Identifier: Apache-2.0
use file_header::license::spdx::*;

let license = SpdxLicense::<NoTokens>::new(
   Box::new(license::licenses::Rpsl1_0),
   "Copyright (c) 1995-2002 RealNetworks, Inc. and/or its licensors".to_string(),
   10
);

let header = license.build_header(());

§Getting a header for an SPDX license type that uses the typical year & name

 // Copyright 2023 Google LLC.
 // SPDX-License-Identifier: Apache-2.0
 use file_header::license::spdx::*;

 // Replacement tokens used in LGPL2
 struct Lgpl2_0Tokens;

 impl LicenseTokens for Lgpl2_0Tokens {
    type TokenReplacementValues = YearCopyrightOwnerValue;

    fn replacement_pairs(replacements: Self::TokenReplacementValues) -> Vec<(&'static str, String)> {
        vec![
             ("year", replacements.year.to_string()),
             ("name of author", replacements.copyright_owner),
         ]
    }
 }

 let license = SpdxLicense::<Lgpl2_0Tokens>::new(
    Box::new(license::licenses::Lgpl2_0),
    "GNU Library General Public License as published by the Free Software Foundation; version 2.".to_string(),
    10
 );

 let header = license.build_header(YearCopyrightOwnerValue::new(2023, "Foo Inc.".to_string()));

§Getting a header for an unusual SPDX license

 // Copyright 2023 Google LLC.
 // SPDX-License-Identifier: Apache-2.0
 use file_header::license::spdx::*;

 /// Replacement values for `W3c20150513` license
 struct W3c20150513Values {
    name_of_software: String,
    distribution_uri: String,
    date_of_software: String,
 }

 impl W3c20150513Values   {
    fn new(name_of_software: String, distribution_uri: String, date_of_software: String,) -> Self {
        Self {
            name_of_software,
            distribution_uri,
            date_of_software
        }
    }
 }

 /// Tokens in the W3c20150513 license
 struct W3c20150513Tokens;

 impl LicenseTokens for W3c20150513Tokens {
    type TokenReplacementValues = W3c20150513Values;

    fn replacement_pairs(
        replacements: Self::TokenReplacementValues,
    ) -> Vec<(&'static str, String)> {
        vec![
            ("$name_of_software", replacements.name_of_software),
            ("$distribution_URI", replacements.distribution_uri),
            // yes, it really does use dashes just for this one
            ("$date-of-software", replacements.date_of_software),
        ]
    }
}

 let license = SpdxLicense::<W3c20150513Tokens>::new(
    Box::new(license::licenses::W3c20150513),
    "This work is distributed under the W3C® Software License".to_string(),
    10
 );

 let header = license.build_header(W3c20150513Values::new(
    "2023".to_string(),
    "https://example.com".to_string(),
    "Foo Inc.".to_string()));

Re-exports§

pub use license;

Structs§

APACHE_2_0: Apache 2.0 license
BSD_3: BSD 3-clause license
EPL_2_0: EPL 2.0 license
GPL_3_0_ONLY: GPL 3.0 license
MIT: MIT license
MPL_2_0: MPL 2.0 license
NoTokens: For licenses with no tokens to replace
SpdxLicense: Metadata around an SPDX license to enable constructing a Header.
YearCopyrightOwnerValue: Replacement values for licenses that use a year and copyright owner name.

Traits§

LicenseTokens: Tokens in license text to be replaced, e.g. yyyy which will be replaced with the copyright year.

Module spdxCopy item path