Document and export analyze_license().

hornik · hornik · commit 2cbf0b70a551 · 2025-03-16T20:56:27.000Z
git-svn-id: https://svn.r-project.org/R/trunk@87983 00db46b3-68df-0310-9c12-caf00c1e9a41
diff --git a/src/library/base/R/namespace.R b/src/library/base/R/namespace.R
@@ -431,7 +431,7 @@ loadNamespace <- function (package, lib.loc = NULL,
         ## moved from library() in R 3.4.0
         checkLicense <- function(pkg, pkgInfo, pkgPath)
         {
-            L <- tools:::analyze_license(pkgInfo$DESCRIPTION["License"])
+            L <- tools::analyze_license(pkgInfo$DESCRIPTION["License"])
             if(!L$is_empty && !L$is_verified) {
                 site_file <-
                     path.expand(file.path(R.home("etc"), "licensed.site"))
diff --git a/src/library/tools/NAMESPACE b/src/library/tools/NAMESPACE
@@ -71,6 +71,8 @@ export("check_package_urls",
 
 export("R")
 
+export("analyze_license")
+
 exportPattern("^SIG.+")
 
 S3method("[", "check_details_changes")
diff --git a/src/library/tools/man/licensetools.Rd b/src/library/tools/man/licensetools.Rd
@@ -0,0 +1,59 @@
+% File src/library/tools/man/licensetools.Rd
+% Part of the R package, https://www.R-project.org
+% Copyright 2025 R Core Team
+% Distributed under GPL 2 or later
+
+\name{licensetools}
+\alias{analyze_license}
+\title{License Tools}
+\description{
+  Tools for computing on license specifications.
+}
+\usage{
+analyze_license(x)
+}
+\arguments{
+  \item{x}{a character string.}
+}
+\details{
+  R packages use the \samp{License} field in their \file{DESCRIPTION}
+  file to specify their license in a standardized form described in
+  section \sQuote{Licenses} of the \sQuote{Writing R Extensions} manual.
+  This uses alternatives of individual specifications
+  (\sQuote{components}) which can use version restrictions or give
+  pointers to \file{LICENSE} (or \file{LICENCE}) files either
+  restricting the base license or giving a full license.
+
+  Function \code{analyze_license()} checks if a given character string
+  provides such a standardized license spec (or something recognized as
+  a historic exception which can be transformed to a standardized spec).
+  If standardizable, it extracts the individual components and where
+  these give version ranges the corresponding expansions into components
+  with fixed versions.  It also indicates whether the license can be
+  verified to be FOSS
+  (\url{https://en.wikipedia.org/wiki/Free_and_open-source_software})
+  licenses.
+}
+\value{
+  a list with elements including
+  \item{is_canonical}{a logical indicating whether the given string 
+    is a standardized license spec.}
+  \item{is_standardizable}{a logical indicating whether the given string
+    is a standardized license spec, or can be transformed to one.}
+  \item{standardization}{a character string giving the standardized
+    license spec correponding to the given string if this is
+  standardizable.}
+  \item{components}{the components of the standardized license spec.}
+  \item{expansions}{the expansions of the components of the standardized
+    license spec.}
+  \item{is_verified}{a logical indicating whether the given string can
+    be verified to specify a FOSS license.}
+}
+\examples{
+## Examples from section 'Licenses' of 'Writing R Extensions':
+analyze_license("GPL-2")
+analyze_license("LGPL (>= 2.0, < 3) | Mozilla Public License")
+analyze_license("GPL-2 | file LICENCE")
+analyze_license("GPL (>= 2) | BSD_3_clause + file LICENSE")
+analyze_license("Artistic-2.0 | AGPL-3 + file LICENSE")
+}
diff --git a/tests/Examples/tools-Ex.Rout.save b/tests/Examples/tools-Ex.Rout.save
@@ -1,6 +1,6 @@
 
-R Under development (unstable) (2024-09-20 r87182) -- "Unsuffered Consequences"
-Copyright (C) 2024 The R Foundation for Statistical Computing
+R Under development (unstable) (2025-03-15 r87978) -- "Unsuffered Consequences"
+Copyright (C) 2025 The R Foundation for Statistical Computing
 Platform: x86_64-pc-linux-gnu
 
 R is free software and comes with ABSOLUTELY NO WARRANTY.
@@ -96,8 +96,8 @@ $status
 
 $stdout
  [1] ""                                                                                 
- [2] "R Under development (unstable) (2024-09-20 r87182) -- \"Unsuffered Consequences\""
- [3] "Copyright (C) 2024 The R Foundation for Statistical Computing"                    
+ [2] "R Under development (unstable) (2025-03-15 r87978) -- \"Unsuffered Consequences\""
+ [3] "Copyright (C) 2025 The R Foundation for Statistical Computing"                    
  [4] "Platform: x86_64-pc-linux-gnu"                                                    
  [5] ""                                                                                 
  [6] "R is free software and comes with ABSOLUTELY NO WARRANTY."                        
@@ -112,10 +112,10 @@ $stdout
 [15] "'help.start()' for an HTML browser interface to help."                            
 [16] "Type 'q()' to quit R."                                                            
 [17] ""                                                                                 
-[18] "> x <- readRDS(\"/tmp/RtmppU3jOk/runri1222936a0e6877\")"                          
+[18] "> x <- readRDS(\"/tmp/RtmpdMEyMD/runri27c6bb59ea22a0\")"                          
 [19] "> options(repos = x$repos)"                                                       
 [20] "> y <- tryCatch(list(do.call(x$fun, x$args, quote = TRUE)), error = identity)"    
-[21] "> saveRDS(y, \"/tmp/RtmppU3jOk/runro1222932d23e62e\")"                            
+[21] "> saveRDS(y, \"/tmp/RtmpdMEyMD/runro27c6bb1ae7e9dc\")"                            
 [22] "> "                                                                               
 
 $stderr
@@ -280,7 +280,7 @@ Error in assertWarning(ff()) :
 > bibstyle("unsorted", sortKeys = function(refs) seq_along(refs),
 +     fmtPrefix = function(paper) paste0("[", paper$.index, "]"),
 +        .init = TRUE)
-<environment: 0x55a55e43e3c0>
+<environment: 0x55cb7849ff00>
 > print(refs, .bibstyle = "unsorted")
 [1] R Core Team (2013). _R: A Language and Environment for Statistical
 Computing_. R Foundation for Statistical Computing, Vienna, Austria.
@@ -723,6 +723,231 @@ attr(,"match.length")
 > 
 > ### ** Examples
 > 
+> 
+> 
+> 
+> cleanEx()
+> nameEx("licensetools")
+> ### * licensetools
+> 
+> flush(stderr()); flush(stdout())
+> 
+> ### Name: licensetools
+> ### Title: License Tools
+> ### Aliases: analyze_license
+> 
+> ### ** Examples
+> 
+> ## Examples from section 'Licenses' of 'Writing R Extensions':
+> analyze_license("GPL-2")
+$is_empty
+[1] FALSE
+
+$is_canonical
+[1] TRUE
+
+$bad_components
+character(0)
+
+$is_standardizable
+[1] TRUE
+
+$is_verified
+[1] TRUE
+
+$standardization
+[1] "GPL-2"
+
+$components
+[1] "GPL-2"
+
+$expansions
+$expansions[[1]]
+[1] "GPL-2"
+
+
+$extensions
+NULL
+
+$pointers
+NULL
+
+$is_FOSS
+[1] TRUE
+
+$restricts_use
+[1] FALSE
+
+> analyze_license("LGPL (>= 2.0, < 3) | Mozilla Public License")
+$is_empty
+[1] FALSE
+
+$is_canonical
+[1] TRUE
+
+$bad_components
+character(0)
+
+$is_standardizable
+[1] TRUE
+
+$is_verified
+[1] TRUE
+
+$standardization
+[1] "LGPL (>= 2.0, < 3) | Mozilla Public License"
+
+$components
+[1] "LGPL (>= 2.0, < 3)"     "Mozilla Public License"
+
+$expansions
+$expansions[[1]]
+[1] "LGPL-2"   "LGPL-2.1"
+
+$expansions[[2]]
+[1] "MPL version 1.0" "MPL version 1.1" "MPL version 2.0"
+
+
+$extensions
+NULL
+
+$pointers
+NULL
+
+$is_FOSS
+[1] TRUE
+
+$restricts_use
+[1] FALSE
+
+> analyze_license("GPL-2 | file LICENCE")
+$is_empty
+[1] FALSE
+
+$is_canonical
+[1] TRUE
+
+$bad_components
+character(0)
+
+$is_standardizable
+[1] TRUE
+
+$is_verified
+[1] TRUE
+
+$standardization
+[1] "GPL-2 | file LICENCE"
+
+$components
+[1] "GPL-2"        "file LICENCE"
+
+$expansions
+$expansions[[1]]
+[1] "GPL-2"
+
+$expansions[[2]]
+[1] "file LICENCE"
+
+
+$extensions
+NULL
+
+$pointers
+[1] "LICENCE"
+
+$is_FOSS
+[1] TRUE
+
+$restricts_use
+[1] FALSE
+
+> analyze_license("GPL (>= 2) | BSD_3_clause + file LICENSE")
+$is_empty
+[1] FALSE
+
+$is_canonical
+[1] TRUE
+
+$bad_components
+character(0)
+
+$is_standardizable
+[1] TRUE
+
+$is_verified
+[1] TRUE
+
+$standardization
+[1] "GPL (>= 2) | BSD_3_clause + file LICENSE"
+
+$components
+[1] "GPL (>= 2)"                  "BSD_3_clause + file LICENSE"
+
+$expansions
+$expansions[[1]]
+[1] "GPL-2" "GPL-3"
+
+$expansions[[2]]
+[1] "BSD_3_clause + file LICENSE"
+
+
+$extensions
+                   components extensible
+1 BSD_3_clause + file LICENSE       TRUE
+
+$pointers
+[1] "LICENSE"
+
+$is_FOSS
+[1] TRUE
+
+$restricts_use
+[1] FALSE
+
+> analyze_license("Artistic-2.0 | AGPL-3 + file LICENSE")
+$is_empty
+[1] FALSE
+
+$is_canonical
+[1] TRUE
+
+$bad_components
+character(0)
+
+$is_standardizable
+[1] TRUE
+
+$is_verified
+[1] TRUE
+
+$standardization
+[1] "Artistic-2.0 | AGPL-3 + file LICENSE"
+
+$components
+[1] "Artistic-2.0"          "AGPL-3 + file LICENSE"
+
+$expansions
+$expansions[[1]]
+[1] "Artistic-2.0"
+
+$expansions[[2]]
+[1] "AGPL-3 + file LICENSE"
+
+
+$extensions
+             components extensible
+1 AGPL-3 + file LICENSE       TRUE
+
+$pointers
+[1] "LICENSE"
+
+$is_FOSS
+[1] TRUE
+
+$restricts_use
+[1] FALSE
+
 > 
 > 
 > 
@@ -1353,7 +1578,7 @@ needs Deep Thought
 > cleanEx()
 > options(digits = 7L)
 > base::cat("Time elapsed: ", proc.time() - base::get("ptime", pos = 'CheckExEnv'),"\n")
-Time elapsed:  0.333 0.016 0.729 0.293 0.082 
+Time elapsed:  0.389 0 0.763 0.293 0.075 
 > grDevices::dev.off()
 null device 
           1 

Original file line number	Diff line number	Diff line change
`@@ -431,7 +431,7 @@ loadNamespace <- function (package, lib.loc = NULL,`
`431`	`431`	`## moved from library() in R 3.4.0`
`432`	`432`	`checkLicense <- function(pkg, pkgInfo, pkgPath)`
`433`	`433`	`{`
`434`		`- L <- tools:::analyze_license(pkgInfo$DESCRIPTION["License"])`
	`434`	`+ L <- tools::analyze_license(pkgInfo$DESCRIPTION["License"])`
`435`	`435`	`if(!L$is_empty && !L$is_verified) {`
`436`	`436`	`site_file <-`
`437`	`437`	`path.expand(file.path(R.home("etc"), "licensed.site"))`