Merge branch 'dev'

Author: Andreas Blätte

.github/workflows/R-CMD-check.yaml

@@ -6,7 +6,7 @@ on:
       - main
       - master
       - dev
-      - win
+      - pcre2
   pull_request:
     branches:
       - main

DESCRIPTION

@@ -1,14 +1,14 @@
 Package: RcppCWB
 Type: Package
 Title: 'Rcpp' Bindings for the 'Corpus Workbench' ('CWB')
-Version: 0.5.5
-Date: 2023-01-24
+Version: 0.6.0
+Date: 2023-03-21
 Author: Andreas Blaette [aut, cre],
   Bernard Desgraupes [aut],
   Sylvain Loiseau [aut],
   Oliver Christ [ctb],
   Bruno Maximilian Schulze [ctb],
-  Stefanie Evert [ctb],
+  Stephanie Evert [ctb],
   Arne Fitschen [ctb],
   Jeroen Ooms [ctb],
   Marius Bertram [ctb],
@@ -19,7 +19,7 @@ Authors@R: c(
   person("Sylvain", "Loiseau", role = "aut"),
   person("Oliver", "Christ", role = "ctb"),
   person("Bruno Maximilian", "Schulze", role = "ctb"),
-  person("Stefanie", "Evert", role = "ctb"),
+  person("Stephanie", "Evert", role = "ctb"),
   person("Arne", "Fitschen", role = "ctb"),
   person("Jeroen", "Ooms", role = "ctb"),
   person("Marius", "Bertram", role = "ctb"),
@@ -29,7 +29,7 @@ Maintainer: Andreas Blaette <andreas.blaette@uni-due.de>
 Description: 'Rcpp' Bindings for the C code of the 'Corpus Workbench' ('CWB'), an indexing and query 
   engine to efficiently analyze large corpora (<https://cwb.sourceforge.io>). 'RcppCWB' is licensed
   under the GNU GPL-3, in line with the GPL-3 license of the 'CWB' (<https://www.r-project.org/Licenses/GPL-3>).
-  The 'CWB' relies on 'pcre' (BSD license, see <http://www.pcre.org/licence.txt>)
+  The 'CWB' relies on 'pcre2' (BSD license, see <http://www.pcre.org/licence.txt>)
   and 'GLib' (LGPL license, see <https://www.gnu.org/licenses/lgpl-3.0.en.html>).
   See the file LICENSE.note for further information. The package includes modified code of the
   'rcqp' package (GPL-2, see <https://cran.r-project.org/package=rcqp>). The original work of the authors
@@ -40,7 +40,7 @@ License: GPL-3
 Encoding: UTF-8
 Copyright: For the copyrights for the 'Corpus Workbench' (CWB) and acknowledgement of authorship, see file COPYRIGHTS.
 NeedsCompilation: yes
-SystemRequirements: GNU make, pcre (>= 7 < 10), GLib (>= 2.0.0). On Windows, no prior installations are necessary,
+SystemRequirements: GNU make, pcre2 (>= 10.00), GLib (>= 2.0.0). On Windows, no prior installations are necessary,
   as pre-built (i.e. cross-compiled) binaries of required libraries are downloaded from a GitHub repository 
   (<https://github.com/PolMine/libcl>) during installation. On macOS, static libraries of Glib are downloaded
   (<https://github.com/PolMine/libglib>) if Glib is not present.
@@ -49,12 +49,14 @@ Imports:
     fs
 Suggests:
     knitr,
-    testthat
+    testthat,
+    rmarkdown
 LinkingTo: Rcpp
 Biarch: true
+VignetteBuilder: knitr
 URL: https://github.com/PolMine/RcppCWB
 BugReports: https://github.com/PolMine/RcppCWB/issues
-RoxygenNote: 7.2.2
+RoxygenNote: 7.2.3
 Roxygen: list(markdown = TRUE)
 Collate:
   'RcppCWB_package.R'

NEWS.md

@@ -1,3 +1,16 @@
+# RcppCWB 0.5.5.9001-.9003
+
+* Rcpp wrappers for Corpus Library (CL) functions are exposed directly and  
+can be used in C++ functions imported using `Rcpp::sourceCpp()` or
+`Rcpp::cppFunction()`.
+* Dependency PCRE has been updated to PCRE2 #68.
+* The README suggested to install the development version of RcppCWB using the 
+snippet `devtools::install_github("PolMine/RcppCWB")`. The missing `ref = "dev"`
+has been inserted.
+* `cwb_encode()` crashed if arguments `data_dir` and `vrt_dir` include a tilde.
+Tilde expansion is now applied to these arguments to avoid this #73.
+* A new vignette explains how to write C++ inline functions.
+
 # RcppCWB 0.5.5
 
 * C++ code replaces `sprintf()` with `snprintf()` to address security issue.

R/RcppExports.R

@@ -41,32 +41,60 @@
     .Call(`_RcppCWB_cwb_version`)
 }
 
-.p_attr_default <- function() {
+#' Get default p-attribute
+#' 
+#' Usually the default p-attribute will be "word". Use this function to avoid
+#' a hard-coded solution. Extracts the default attribute defined in the CWB
+#' source code.
+#' 
+#' @rdname p_attr_default
+#' @return A length-one `character` vector.
+#' @export
+p_attr_default <- function() {
     .Call(`_RcppCWB_p_attr_default`)
 }
 
-.s_attr <- function(corpus, s_attribute, registry) {
-    .Call(`_RcppCWB__s_attr`, corpus, s_attribute, registry)
+#' @param corpus ID of a CWB corpus (length-one `character` vector).
+#' @param s_attribute A structural attribute (length-one `character` vector).
+#' @param registry Registry directory.
+#' @rdname cl_rework
+#' @export
+s_attr <- function(corpus, s_attribute, registry) {
+    .Call(`_RcppCWB_s_attr`, corpus, s_attribute, registry)
 }
 
-.p_attr <- function(corpus, p_attribute, registry) {
-    .Call(`_RcppCWB__p_attr`, corpus, p_attribute, registry)
+#' @param p_attribute A positional attribute (length-one `character` vector).
+#' @rdname cl_rework
+#' @export
+p_attr <- function(corpus, p_attribute, registry) {
+    .Call(`_RcppCWB_p_attr`, corpus, p_attribute, registry)
 }
 
-.cl_attribute_size <- function(corpus, attribute, attribute_type, registry) {
-    .Call(`_RcppCWB__cl_attribute_size`, corpus, attribute, attribute_type, registry)
+#' @param attribute Either a positional, or a structural attribute.
+#' @param attribute_type Either "p" (positional attribute) or "s" (structural attribute).
+#' @rdname cl_functions
+attribute_size <- function(corpus, attribute, attribute_type, registry) {
+    .Call(`_RcppCWB_attribute_size`, corpus, attribute, attribute_type, registry)
 }
 
-.p_attr_size <- function(p_attr) {
-    .Call(`_RcppCWB__p_attr_size`, p_attr)
+#' @param p_attr A `externalptr` referencing a p-attribute.
+#' @rdname cl_rework
+#' @export
+p_attr_size <- function(p_attr) {
+    .Call(`_RcppCWB_p_attr_size`, p_attr)
 }
 
-.s_attr_size <- function(s_attr) {
-    .Call(`_RcppCWB__s_attr_size`, s_attr)
+#' @param s_attr A `externalptr` referencing a p-attribute.
+#' @rdname cl_rework
+#' @export
+s_attr_size <- function(s_attr) {
+    .Call(`_RcppCWB_s_attr_size`, s_attr)
 }
 
-.p_attr_lexicon_size <- function(p_attr) {
-    .Call(`_RcppCWB__lexicon_size`, p_attr)
+#' @rdname cl_rework
+#' @export
+p_attr_lexicon_size <- function(p_attr) {
+    .Call(`_RcppCWB_p_attr_lexicon_size`, p_attr)
 }
 
 .cl_lexicon_size <- function(corpus, p_attribute, registry) {
@@ -77,92 +105,132 @@
     .Call(`_RcppCWB__cl_cpos2struc`, corpus, s_attribute, cpos, registry)
 }
 
-.cpos_to_struc <- function(s_attr, cpos) {
-    .Call(`_RcppCWB__cpos_to_struc`, s_attr, cpos)
+#' @param cpos An `integer` vector of corpus positions.
+#' @rdname cl_rework
+#' @export
+cpos_to_struc <- function(s_attr, cpos) {
+    .Call(`_RcppCWB_cpos_to_struc`, s_attr, cpos)
 }
 
-.cl_cpos2str <- function(corpus, p_attribute, registry, cpos) {
-    .Call(`_RcppCWB__cl_cpos2str`, corpus, p_attribute, registry, cpos)
+#' Rcpp wrappers for CWB Corpus Library functions
+#' 
+#' @param corpus The ID of a CWB corpus.
+#' @param p_attribute A positional attribute.
+#' @param registry Path to the corpus registry.
+#' @param cpos An integer vector of corpus positions.
+#' @rdname cl_functions
+cpos2str <- function(corpus, p_attribute, registry, cpos) {
+    .Call(`_RcppCWB_cpos2str`, corpus, p_attribute, registry, cpos)
 }
 
-.cpos_to_str <- function(p_attr, cpos) {
-    .Call(`_RcppCWB__cpos_to_str`, p_attr, cpos)
+#' @rdname cl_rework
+#' @export
+cpos_to_str <- function(p_attr, cpos) {
+    .Call(`_RcppCWB_cpos_to_str`, p_attr, cpos)
 }
 
-.cl_cpos2id <- function(corpus, p_attribute, registry, cpos) {
-    .Call(`_RcppCWB__cl_cpos2id`, corpus, p_attribute, registry, cpos)
+#' @rdname cl_functions
+cpos2id <- function(corpus, p_attribute, registry, cpos) {
+    .Call(`_RcppCWB_cpos2id`, corpus, p_attribute, registry, cpos)
 }
 
-.cpos_to_id <- function(p_attr, cpos) {
-    .Call(`_RcppCWB__cpos_to_id`, p_attr, cpos)
+#' @rdname cl_rework
+#' @export
+cpos_to_id <- function(p_attr, cpos) {
+    .Call(`_RcppCWB_cpos_to_id`, p_attr, cpos)
 }
 
-.cl_struc2cpos <- function(corpus, s_attribute, registry, struc) {
-    .Call(`_RcppCWB__cl_struc2cpos`, corpus, s_attribute, registry, struc)
+#' @param s_attribute A structural attribute.
+#' @param struc An integer value with struc.
+#' @rdname cl_functions
+struc2cpos <- function(corpus, s_attribute, registry, struc) {
+    .Call(`_RcppCWB_struc2cpos`, corpus, s_attribute, registry, struc)
 }
 
-.struc_to_cpos <- function(s_attr, struc) {
-    .Call(`_RcppCWB__struc_to_cpos`, s_attr, struc)
+#' @param struc A length-one `integer` vector with a struc.
+#' @rdname cl_rework
+#' @export
+struc_to_cpos <- function(s_attr, struc) {
+    .Call(`_RcppCWB_struc_to_cpos`, s_attr, struc)
 }
 
-.cl_id2str <- function(corpus, p_attribute, registry, id) {
-    .Call(`_RcppCWB__cl_id2str`, corpus, p_attribute, registry, id)
+#' @param id An `integer` vector with token ids.
+#' @rdname cl_functions
+id2str <- function(corpus, p_attribute, registry, id) {
+    .Call(`_RcppCWB_id2str`, corpus, p_attribute, registry, id)
 }
 
 .cl_struc2str <- function(corpus, s_attribute, struc, registry) {
     .Call(`_RcppCWB__cl_struc2str`, corpus, s_attribute, struc, registry)
 }
 
-.struc_to_str <- function(s_attr, struc) {
-    .Call(`_RcppCWB__struc_to_str`, s_attr, struc)
+#' @rdname cl_rework
+#' @export
+struc_to_str <- function(s_attr, struc) {
+    .Call(`_RcppCWB_struc_to_str`, s_attr, struc)
 }
 
 .cl_regex2id <- function(corpus, p_attribute, regex, registry) {
     .Call(`_RcppCWB__cl_regex2id`, corpus, p_attribute, regex, registry)
 }
 
-.regex_to_id <- function(p_attr, regex) {
-    .Call(`_RcppCWB__regex_to_id`, p_attr, regex)
+#' @param regex A regular expression.
+#' @rdname cl_rework
+#' @export
+regex_to_id <- function(p_attr, regex) {
+    .Call(`_RcppCWB_regex_to_id`, p_attr, regex)
 }
 
 .cl_str2id <- function(corpus, p_attribute, str, registry) {
     .Call(`_RcppCWB__cl_str2id`, corpus, p_attribute, str, registry)
 }
 
-.str_to_id <- function(p_attr, str) {
-    .Call(`_RcppCWB__str_to_id`, p_attr, str)
+#' @param str A `character` vector.
+#' @rdname cl_rework
+#' @export
+str_to_id <- function(p_attr, str) {
+    .Call(`_RcppCWB_str_to_id`, p_attr, str)
 }
 
 .cl_id2freq <- function(corpus, p_attribute, id, registry) {
     .Call(`_RcppCWB__cl_id2freq`, corpus, p_attribute, id, registry)
 }
 
-.id_to_freq <- function(p_attr, id) {
-    .Call(`_RcppCWB__id_to_freq`, p_attr, id)
+#' @param id An `integer` vector with token ids.
+#' @rdname cl_rework
+#' @export
+id_to_freq <- function(p_attr, id) {
+    .Call(`_RcppCWB_id_to_freq`, p_attr, id)
 }
 
 .cl_id2cpos <- function(corpus, p_attribute, id, registry) {
     .Call(`_RcppCWB__cl_id2cpos`, corpus, p_attribute, id, registry)
 }
 
-.id_to_cpos <- function(p_attr, id) {
-    .Call(`_RcppCWB__id_to_cpos`, p_attr, id)
+#' @rdname cl_rework
+#' @export
+id_to_cpos <- function(p_attr, id) {
+    .Call(`_RcppCWB_id_to_cpos`, p_attr, id)
 }
 
 .cl_cpos2lbound <- function(corpus, s_attribute, cpos, registry) {
     .Call(`_RcppCWB__cl_cpos2lbound`, corpus, s_attribute, cpos, registry)
 }
 
-.cpos_to_lbound <- function(s_attr, cpos) {
-    .Call(`_RcppCWB__cpos_to_lbound`, s_attr, cpos)
+#' @rdname cl_rework
+#' @export
+cpos_to_lbound <- function(s_attr, cpos) {
+    .Call(`_RcppCWB_cpos_to_lbound`, s_attr, cpos)
 }
 
 .cl_cpos2rbound <- function(corpus, s_attribute, cpos, registry) {
     .Call(`_RcppCWB__cl_cpos2rbound`, corpus, s_attribute, cpos, registry)
 }
 
-.cpos_to_rbound <- function(s_attr, cpos) {
-    .Call(`_RcppCWB__cpos_to_rbound`, s_attr, cpos)
+#' @rdname cl_rework
+#' @export
+cpos_to_rbound <- function(s_attr, cpos) {
+    .Call(`_RcppCWB_cpos_to_rbound`, s_attr, cpos)
 }
 
 .cl_find_corpus <- function(corpus, registry) {