set; remove; examples; tests;

.Rbuildignore

@@ -9,3 +9,6 @@
 ^README_files$
 ^doc$
 ^tmp$
+^README\.Rmd$
+^README-.*\.png$
+^CONDUCT\.md$

CONDUCT.md

@@ -0,0 +1,25 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who 
+contribute through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or
+imagery, derogatory comments or personal attacks, trolling, public or private harassment,
+insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this 
+Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 
+from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 
+opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the Contributor Covenant 
+(http:contributor-covenant.org), version 1.0.0, available at 
+http://contributor-covenant.org/version/1/0/0/

NAMESPACE

@@ -9,6 +9,9 @@ export(has_xattrs)
 export(is_bplist)
 export(list_xattrs)
 export(read_bplist)
+export(remove_xattr)
+export(rm_xattr)
+export(set_xattr)
 importFrom(Rcpp,sourceCpp)
 importFrom(magrittr,"%>%")
 importFrom(sys,exec_internal)

R/RcppExports.R

@@ -1,12 +1,21 @@
 # Generated by using Rcpp::compileAttributes() -> do not edit by hand
 # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 
+rcpp_set_xattr <- function(path, name, value, follow_symlinks = TRUE) {
+    .Call('_xattrs_rcpp_set_xattr', PACKAGE = 'xattrs', path, name, value, follow_symlinks)
+}
+
+rcpp_rm_xattr <- function(path, name, follow_symlinks = TRUE) {
+    .Call('_xattrs_rcpp_rm_xattr', PACKAGE = 'xattrs', path, name, follow_symlinks)
+}
+
 #' Test if a target path has xattrs
 #'
 #' @md
 #' @param path target path (file or dir); this is auto-expanded
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 has_xattrs <- function(path, follow_symlinks = TRUE) {
     .Call('_xattrs_has_xattrs', PACKAGE = 'xattrs', path, follow_symlinks)
 }
@@ -17,6 +26,7 @@ has_xattrs <- function(path, follow_symlinks = TRUE) {
 #' @param path target path (file or dir); this is auto-expanded
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 list_xattrs <- function(path, follow_symlinks = TRUE) {
     .Call('_xattrs_list_xattrs', PACKAGE = 'xattrs', path, follow_symlinks)
 }
@@ -29,6 +39,7 @@ list_xattrs <- function(path, follow_symlinks = TRUE) {
 #' @param name xattr name to retrieve
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 get_xattr <- function(path, name, follow_symlinks = TRUE) {
     .Call('_xattrs_get_xattr', PACKAGE = 'xattrs', path, name, follow_symlinks)
 }
@@ -40,6 +51,7 @@ get_xattr <- function(path, name, follow_symlinks = TRUE) {
 #' @param name xattr name to retrieve
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 get_xattr_raw <- function(path, name, follow_symlinks = TRUE) {
     .Call('_xattrs_get_xattr_raw', PACKAGE = 'xattrs', path, name, follow_symlinks)
 }
@@ -51,6 +63,7 @@ get_xattr_raw <- function(path, name, follow_symlinks = TRUE) {
 #' @param name xattr name to retrieve
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 get_xattr_size <- function(path, name, follow_symlinks = TRUE) {
     .Call('_xattrs_get_xattr_size', PACKAGE = 'xattrs', path, name, follow_symlinks)
 }

R/df.R

@@ -4,6 +4,7 @@
 #' @param path path target path (file or dir); this is auto-expanded
 #' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 #' @export
+#' @example inst/examples/ex1.R
 get_xattr_df <- function(path, follow_symlinks = TRUE) {
 
   xattr_list <- rcpp_get_xattr_df(path, follow_symlinks)

R/rm.R

@@ -0,0 +1,22 @@
+#' Remove an extended attribute
+#'
+#' @md
+#' @param path target path (file or dir); this is auto-expanded
+#' @param name xattr name to retrieve
+#' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
+#' @export
+#' @example inst/examples/ex1.R
+rm_xattr <- function(path, name, follow_symlinks=TRUE) {
+
+  path <- path.expand(path)
+  if (!file.exists(path)) stop("File not found.", call.=FALSE)
+
+  ret <- rcpp_rm_xattr(path, name, follow_symlinks)
+
+  if (ret > 0) warning(sprintf("Error %s while removing attribute.", ret))
+
+}
+
+#' @rdname rm_xattr
+#' @export
+remove_xattr <- rm_xattr

R/set.R

@@ -0,0 +1,23 @@
+#' Set or modify an extended attribute
+#'
+#' @md
+#' @param path target path (file or dir); this is auto-expanded
+#' @param name xattr name to retrieve
+#' @param value raw vector of value to set
+#' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
+#' @export
+#' @example inst/examples/ex1.R
+set_xattr <- function(path, name, value, follow_symlinks=TRUE) {
+
+  value <- value[1]
+
+  path <- path.expand(path)
+  if (!file.exists(path)) stop("File not found.", call.=FALSE)
+
+  if (is.character(value)) value <- charToRaw(value)
+
+  ret <- rcpp_set_xattr(path, name, value, follow_symlinks)
+
+  if (ret > 0) warning(sprintf("Error %s while setting attribute.", ret))
+
+}

R/xattrs-package.R

@@ -12,4 +12,5 @@
 #' @importFrom xml2 read_xml as_list
 #' @importFrom sys exec_internal
 #' @importFrom Rcpp sourceCpp
+#' @example inst/examples/ex1.R
 NULL

README.Rmd

@@ -1,8 +1,15 @@
 ---
-output: rmarkdown::github_document
-editor_options: 
-  chunk_output_type: console
+output: github_document
 ---
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, echo = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "##",
+  fig.path = "README-"
+)
+```
 
 # xattrs
 
@@ -12,12 +19,6 @@ Work With Filesystem Object Extended Attributes
 
 Filesystem path target extended attributes store extra, customizable, small bits of info. For example, author name, file character encoding, short comments, security status, etc. Methods are provided to list, extract and work with these attributes.
 
-## TODO
-
-- Set xattrs
-- Modify xattrs
-- Remove xattrs
-
 ## NOTE
 
 I don't think this will work on Windows.
@@ -133,4 +134,50 @@ filter(xdf, name == "com.apple.metadata:kMDItemWhereFroms") %>%
   mutate(converted = map(converted, ~flatten_chr(.x$plist$array$string))) %>% 
   unnest() %>% 
   mutate(converted = urltools::domain(converted)) # you don't rly need to see the full URLs for this example
-```
+```
+
+### Full Suite
+
+```{r}
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+```
+
+## Code of Conduct
+
+Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.

README.md

@@ -1,4 +1,6 @@
 
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
 # xattrs
 
 Work With Filesystem Object Extended Attributes
@@ -10,12 +12,6 @@ small bits of info. For example, author name, file character encoding,
 short comments, security status, etc. Methods are provided to list,
 extract and work with these attributes.
 
-## TODO
-
-  - Set xattrs
-  - Modify xattrs
-  - Remove xattrs
-
 ## NOTE
 
 I don’t think this will work on Windows.
@@ -48,10 +44,9 @@ library(tidyverse)
 
 # current verison
 packageVersion("xattrs")
+## [1] '0.1.0'
 ```
 
-    ## [1] '0.1.0'
-
 ### Basic Operation
 
 Extended attributes seem to get stripped when R builds pkgs so until I
@@ -63,49 +58,41 @@ directory listing.
 sample_file <- "~/Downloads/Elementary-Lunch-Menu.pdf"
 
 list_xattrs(sample_file)
-```
-
-    ## [1] "com.apple.metadata:kMDItemWhereFroms" "com.apple.quarantine"
+## [1] "com.apple.metadata:kMDItemWhereFroms" "com.apple.quarantine"
 
-``` r
 get_xattr_size(sample_file, "com.apple.metadata:kMDItemWhereFroms")
+## [1] 177
 ```
 
-    ## [1] 177
-
 Extended attributes can be *anything* so it makes alot of sense to work
-with the contents as a raw
-    vector:
+with the contents as a raw vector:
 
 ``` r
 get_xattr_raw(sample_file, "com.apple.metadata:kMDItemWhereFroms")
+##   [1] 62 70 6c 69 73 74 30 30 a2 01 02 5f 10 53 68 74 74 70 3a 2f 2f 77 77 77 2e 6d 73 61 64 36 30 2e 6f 72 67 2f 77 70
+##  [39] 2d 63 6f 6e 74 65 6e 74 2f 75 70 6c 6f 61 64 73 2f 32 30 31 37 2f 30 31 2f 45 6c 65 6d 65 6e 74 61 72 79 2d 46 65
+##  [77] 62 72 75 61 72 79 2d 4c 75 6e 63 68 2d 4d 65 6e 75 2e 70 64 66 5f 10 2a 68 74 74 70 3a 2f 2f 77 77 77 2e 6d 73 61
+## [115] 64 36 30 2e 6f 72 67 2f 62 6c 6f 67 2f 66 65 62 72 75 61 72 79 2d 6d 65 6e 75 73 2f 08 0b 61 00 00 00 00 00 00 01
+## [153] 01 00 00 00 00 00 00 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 8e
 ```
 
-    ##   [1] 62 70 6c 69 73 74 30 30 a2 01 02 5f 10 53 68 74 74 70 3a 2f 2f 77 77 77 2e 6d 73 61 64 36 30 2e 6f 72 67 2f 77 70
-    ##  [39] 2d 63 6f 6e 74 65 6e 74 2f 75 70 6c 6f 61 64 73 2f 32 30 31 37 2f 30 31 2f 45 6c 65 6d 65 6e 74 61 72 79 2d 46 65
-    ##  [77] 62 72 75 61 72 79 2d 4c 75 6e 63 68 2d 4d 65 6e 75 2e 70 64 66 5f 10 2a 68 74 74 70 3a 2f 2f 77 77 77 2e 6d 73 61
-    ## [115] 64 36 30 2e 6f 72 67 2f 62 6c 6f 67 2f 66 65 62 72 75 61 72 79 2d 6d 65 6e 75 73 2f 08 0b 61 00 00 00 00 00 00 01
-    ## [153] 01 00 00 00 00 00 00 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 8e
-
 There is a “string” version of the function, but it may return “nothing”
 if there are embedded NULLs or other breaking characters in the
 contents:
 
 ``` r
 get_xattr(sample_file, "com.apple.metadata:kMDItemWhereFroms")
+## [1] "bplist00\xa2\001\002_\020Shttp://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf_\020*http://www.msad60.org/blog/february-menus/\b\va"
 ```
 
-    ## [1] "bplist00\xa2\001\002_\020Shttp://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf_\020*http://www.msad60.org/blog/february-menus/\b\va"
-
 You are really better off doing this if you really want a raw string
 conversion:
 
 ``` r
 readBin(get_xattr_raw(sample_file, "com.apple.metadata:kMDItemWhereFroms"), "character")
+## [1] "bplist00\xa2\001\002_\020Shttp://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf_\020*http://www.msad60.org/blog/february-menus/\b\va"
 ```
 
-    ## [1] "bplist00\xa2\001\002_\020Shttp://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf_\020*http://www.msad60.org/blog/february-menus/\b\va"
-
 More often than not (on macOS) extended attributes are “binary property
 lists” (or “binary plist” for short). You can test to see if the
 returned raw vector is likely a binary
@@ -113,10 +100,9 @@ plist:
 
 ``` r
 is_bplist(get_xattr_raw(sample_file, "com.apple.metadata:kMDItemWhereFroms"))
+## [1] TRUE
 ```
 
-    ## [1] TRUE
-
 If it is, you can get the data out of it. For now, this makes a system
 call to `plutil` on macOS and `plistutil` on other systems. You’ll be
 given a hint on how to install `plistutil` if it’s not
@@ -124,50 +110,47 @@ found.
 
 ``` r
 read_bplist(get_xattr_raw(sample_file, "com.apple.metadata:kMDItemWhereFroms"))
+## $plist
+## $plist$array
+## $plist$array$string
+## $plist$array$string[[1]]
+## [1] "http://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf"
+## 
+## 
+## $plist$array$string
+## $plist$array$string[[1]]
+## [1] "http://www.msad60.org/blog/february-menus/"
+## 
+## 
+## 
+## attr(,"version")
+## [1] "1.0"
 ```
 
-    ## $plist
-    ## $plist$array
-    ## $plist$array$string
-    ## $plist$array$string[[1]]
-    ## [1] "http://www.msad60.org/wp-content/uploads/2017/01/Elementary-February-Lunch-Menu.pdf"
-    ## 
-    ## 
-    ## $plist$array$string
-    ## $plist$array$string[[1]]
-    ## [1] "http://www.msad60.org/blog/february-menus/"
-    ## 
-    ## 
-    ## 
-    ## attr(,"version")
-    ## [1] "1.0"
-
 This is R, so you should really consider doing this instead of any of
 the above \#rectanglesrule:
 
 ``` r
 get_xattr_df(sample_file)
+## # A tibble: 2 x 3
+##   name                                  size contents   
+##   <chr>                                <dbl> <list>     
+## 1 com.apple.metadata:kMDItemWhereFroms  177. <raw [177]>
+## 2 com.apple.quarantine                   68. <raw [68]>
 ```
 
-    ## # A tibble: 2 x 3
-    ##   name                                  size contents   
-    ##   <chr>                                <dbl> <list>     
-    ## 1 com.apple.metadata:kMDItemWhereFroms  177. <raw [177]>
-    ## 2 com.apple.quarantine                   68. <raw [68]>
-
 you can live dangerously even with data frames, tho:
 
 ``` r
 get_xattr_df(sample_file) %>% 
   mutate(txt = map_chr(contents, readBin, "character")) # potentially "dangerous"
+## # A tibble: 2 x 4
+##   name                                  size contents    txt                                                           
+##   <chr>                                <dbl> <list>      <chr>                                                         
+## 1 com.apple.metadata:kMDItemWhereFroms  177. <raw [177]> "bplist00\xa2\x01\x02_\x10Shttp://www.msad60.org/wp-content/u…
+## 2 com.apple.quarantine                   68. <raw [68]>  0083;5891d3e4;Google Chrome.app;FF4E968A-9E06-4C79-B4CA-C6A31…
 ```
 
-    ## # A tibble: 2 x 4
-    ##   name                                  size contents    txt                                                           
-    ##   <chr>                                <dbl> <list>      <chr>                                                         
-    ## 1 com.apple.metadata:kMDItemWhereFroms  177. <raw [177]> "bplist00\xa2\x01\x02_\x10Shttp://www.msad60.org/wp-content/u…
-    ## 2 com.apple.quarantine                   68. <raw [68]>  0083;5891d3e4;Google Chrome.app;FF4E968A-9E06-4C79-B4CA-C6A31…
-
 ### Extended Example
 
 We can process a whole directory of files to see what extended
@@ -179,16 +162,15 @@ fils <- list.files("~/Downloads", full.names = TRUE)
 xdf <- map_df(set_names(fils, fils), get_xattr_df, .id="path")
 
 count(xdf, name, sort=TRUE) 
+## # A tibble: 4 x 2
+##   name                                         n
+##   <chr>                                    <int>
+## 1 com.apple.quarantine                        28
+## 2 com.apple.metadata:kMDItemWhereFroms        23
+## 3 com.apple.metadata:_kMDItemUserTags          8
+## 4 com.apple.metadata:kMDItemDownloadedDate     1
 ```
 
-    ## # A tibble: 4 x 2
-    ##   name                                         n
-    ##   <chr>                                    <int>
-    ## 1 com.apple.quarantine                        28
-    ## 2 com.apple.metadata:kMDItemWhereFroms        23
-    ## 3 com.apple.metadata:_kMDItemUserTags          8
-    ## 4 com.apple.metadata:kMDItemDownloadedDate     1
-
 And we can work with `com.apple.metadata:kMDItemWhereFroms` binary plist
 data in bulk:
 
@@ -200,19 +182,82 @@ filter(xdf, name == "com.apple.metadata:kMDItemWhereFroms") %>%
   mutate(converted = map(converted, ~flatten_chr(.x$plist$array$string))) %>% 
   unnest() %>% 
   mutate(converted = urltools::domain(converted)) # you don't rly need to see the full URLs for this example
+## # A tibble: 23 x 2
+##     size converted                                                       
+##    <dbl> <chr>                                                           
+##  1  143. eprint.ncl.ac.uk                                                
+##  2  117. files.slack.com                                                 
+##  3  592. irma.nps.gov                                                    
+##  4  110. apps.start.umd.edu                                              
+##  5 1510. aws-athena-query-results-181646978271-us-east-1.s3.amazonaws.com
+##  6  145. www.eac.gov                                                     
+##  7  177. www.msad60.org                                                  
+##  8  185. www.telerik.com                                                 
+##  9  152. www.gess-inc.com                                                
+## 10  134. files.slack.com                                                 
+## # ... with 13 more rows
 ```
 
-    ## # A tibble: 23 x 2
-    ##     size converted                                                       
-    ##    <dbl> <chr>                                                           
-    ##  1  143. eprint.ncl.ac.uk                                                
-    ##  2  117. files.slack.com                                                 
-    ##  3  592. irma.nps.gov                                                    
-    ##  4  110. apps.start.umd.edu                                              
-    ##  5 1510. aws-athena-query-results-181646978271-us-east-1.s3.amazonaws.com
-    ##  6  145. www.eac.gov                                                     
-    ##  7  177. www.msad60.org                                                  
-    ##  8  185. www.telerik.com                                                 
-    ##  9  152. www.gess-inc.com                                                
-    ## 10  134. files.slack.com                                                 
-    ## # ... with 13 more rows
+### Full Suite
+
+``` r
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+## [1] FALSE
+get_xattr(tf, "is.rud.setting")
+## character(0)
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+## [1] "first attribut"
+get_xattr_size(tf, "is.rud.setting.a")
+## [1] 14
+
+# shld be TRUE
+has_xattrs(tf)
+## [1] TRUE
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+## [1] "second attribute"
+get_xattr_size(tf, "is.rud.setting.b")
+## [1] 16
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+## [1] "first attribute"
+get_xattr_size(tf, "is.rud.setting.a")
+## [1] 15
+
+# see all the attributes
+list_xattrs(tf)
+## [1] "is.rud.setting.a" "is.rud.setting.b"
+
+# data frame vs individual functions
+get_xattr_df(tf)
+## # A tibble: 2 x 3
+##   name              size contents  
+##   <chr>            <dbl> <list>    
+## 1 is.rud.setting.a   15. <raw [15]>
+## 2 is.rud.setting.b   16. <raw [16]>
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+## character(0)
+
+# cleanup
+unlink(tf)
+```
+
+## Code of Conduct
+
+Please note that this project is released with a [Contributor Code of
+Conduct](CONDUCT.md). By participating in this project you agree to
+abide by its terms.

inst/examples/ex1.R

@@ -0,0 +1,38 @@
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+

man/get_xattr.Rd

@@ -19,3 +19,43 @@ Retrieve the contents of the named xattr
 \note{
 You should really use \code{\link[=get_xattr_raw]{get_xattr_raw()}}
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/get_xattr_df.Rd

@@ -14,3 +14,43 @@ get_xattr_df(path, follow_symlinks = TRUE)
 \description{
 Retrieve a data frame of xattr names, sizes and (raw) contents for a target path
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/get_xattr_raw.Rd

@@ -16,3 +16,43 @@ get_xattr_raw(path, name, follow_symlinks = TRUE)
 \description{
 Retrieve the (raw) contents of the named xattr
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/get_xattr_size.Rd

@@ -16,3 +16,43 @@ get_xattr_size(path, name, follow_symlinks = TRUE)
 \description{
 Retrieve the size (bytes) of the named xattr
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/has_xattrs.Rd

@@ -14,3 +14,43 @@ has_xattrs(path, follow_symlinks = TRUE)
 \description{
 Test if a target path has xattrs
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/list_xattrs.Rd

@@ -14,3 +14,43 @@ list_xattrs(path, follow_symlinks = TRUE)
 \description{
 List extended attribute names of a target path
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/rm_xattr.Rd

@@ -0,0 +1,61 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/rm.R
+\name{rm_xattr}
+\alias{rm_xattr}
+\alias{remove_xattr}
+\title{Remove an extended attribute}
+\usage{
+rm_xattr(path, name, follow_symlinks = TRUE)
+
+remove_xattr(path, name, follow_symlinks = TRUE)
+}
+\arguments{
+\item{path}{target path (file or dir); this is auto-expanded}
+
+\item{name}{xattr name to retrieve}
+
+\item{follow_symlinks}{if \code{FALSE} get xattr of the symlink vs the target it references}
+}
+\description{
+Remove an extended attribute
+}
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/set_xattr.Rd

@@ -0,0 +1,60 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/set.R
+\name{set_xattr}
+\alias{set_xattr}
+\title{Set or modify an extended attribute}
+\usage{
+set_xattr(path, name, value, follow_symlinks = TRUE)
+}
+\arguments{
+\item{path}{target path (file or dir); this is auto-expanded}
+
+\item{name}{xattr name to retrieve}
+
+\item{value}{raw vector of value to set}
+
+\item{follow_symlinks}{if \code{FALSE} get xattr of the symlink vs the target it references}
+}
+\description{
+Set or modify an extended attribute
+}
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}

man/xattrs.Rd

@@ -10,6 +10,46 @@ Filesystem path target extended attributes store extra, customizable, small bits
 info. For example, author name, file character encoding, short comments, security
 status, etc. Methods are provided to list, extract and work with these attributes.
 }
+\examples{
+# Create a temp file for the example
+tf <- tempfile(fileext = ".csv")
+write.csv(mtcars, tf)
+
+# has attributes? (shld be FALSE)
+has_xattrs(tf)
+get_xattr(tf, "is.rud.setting")
+
+# set an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribut")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# shld be TRUE
+has_xattrs(tf)
+
+set_xattr(tf, "is.rud.setting.b", "second attribute")
+get_xattr(tf, "is.rud.setting.b")
+get_xattr_size(tf, "is.rud.setting.b")
+
+# overwrite an attribute
+set_xattr(tf, "is.rud.setting.a", "first attribute")
+get_xattr(tf, "is.rud.setting.a")
+get_xattr_size(tf, "is.rud.setting.a")
+
+# see all the attributes
+list_xattrs(tf)
+
+# data frame vs individual functions
+get_xattr_df(tf)
+
+# remove attribute
+rm_xattr(tf, "is.rud.setting")
+get_xattr(tf, "is.rud.setting")
+
+# cleanup
+unlink(tf)
+
+}
 \author{
 Bob Rudis (bob@rud.is)
 }

src/RcppExports.cpp

@@ -5,6 +5,33 @@
 
 using namespace Rcpp;
 
+// rcpp_set_xattr
+int rcpp_set_xattr(std::string path, std::string name, RawVector value, bool follow_symlinks);
+RcppExport SEXP _xattrs_rcpp_set_xattr(SEXP pathSEXP, SEXP nameSEXP, SEXP valueSEXP, SEXP follow_symlinksSEXP) {
+BEGIN_RCPP
+    Rcpp::RObject rcpp_result_gen;
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< std::string >::type path(pathSEXP);
+    Rcpp::traits::input_parameter< std::string >::type name(nameSEXP);
+    Rcpp::traits::input_parameter< RawVector >::type value(valueSEXP);
+    Rcpp::traits::input_parameter< bool >::type follow_symlinks(follow_symlinksSEXP);
+    rcpp_result_gen = Rcpp::wrap(rcpp_set_xattr(path, name, value, follow_symlinks));
+    return rcpp_result_gen;
+END_RCPP
+}
+// rcpp_rm_xattr
+int rcpp_rm_xattr(std::string path, std::string name, bool follow_symlinks);
+RcppExport SEXP _xattrs_rcpp_rm_xattr(SEXP pathSEXP, SEXP nameSEXP, SEXP follow_symlinksSEXP) {
+BEGIN_RCPP
+    Rcpp::RObject rcpp_result_gen;
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< std::string >::type path(pathSEXP);
+    Rcpp::traits::input_parameter< std::string >::type name(nameSEXP);
+    Rcpp::traits::input_parameter< bool >::type follow_symlinks(follow_symlinksSEXP);
+    rcpp_result_gen = Rcpp::wrap(rcpp_rm_xattr(path, name, follow_symlinks));
+    return rcpp_result_gen;
+END_RCPP
+}
 // has_xattrs
 bool has_xattrs(const std::string path, bool follow_symlinks);
 RcppExport SEXP _xattrs_has_xattrs(SEXP pathSEXP, SEXP follow_symlinksSEXP) {
@@ -82,6 +109,8 @@ END_RCPP
 }
 
 static const R_CallMethodDef CallEntries[] = {
+    {"_xattrs_rcpp_set_xattr", (DL_FUNC) &_xattrs_rcpp_set_xattr, 4},
+    {"_xattrs_rcpp_rm_xattr", (DL_FUNC) &_xattrs_rcpp_rm_xattr, 3},
     {"_xattrs_has_xattrs", (DL_FUNC) &_xattrs_has_xattrs, 2},
     {"_xattrs_list_xattrs", (DL_FUNC) &_xattrs_list_xattrs, 2},
     {"_xattrs_get_xattr", (DL_FUNC) &_xattrs_get_xattr, 3},

src/xattrs-main.cpp

@@ -1,12 +1,11 @@
 #include <Rcpp.h>
 #include <algorithm>
+#include <sys/stat.h>
 
 #include "extattr.h"
 
 using namespace Rcpp;
 
-// NOTE TO SELF
-
 inline RawVector getxattr_raw(const std::string path, const std::string &name, int options=0) {
 
   ssize_t size = getxattrsize(path, name, options);
@@ -29,12 +28,37 @@ inline RawVector getxattr_raw(const std::string path, const std::string &name, i
 
 }
 
+inline int setxattr_raw(const std::string path, const std::string &name, RawVector value, int options=0) {
+#if defined(__APPLE__) && defined(__MACH__)
+	return setxattr(path.c_str(), name.c_str(), value.begin(), value.size(), 0, options);
+#endif
+#if defined(__FreeBSD__)
+	return extattr_set_file(path.c_str(), EXTATTR_NAMESPACE_USER, name.c_str(), value.begin(), value.size());
+#endif
+}
+
+// [[Rcpp::export]]
+int rcpp_set_xattr(std::string path, std::string name, RawVector value, bool follow_symlinks=true) {
+  int options = 0;
+  if (!follow_symlinks) options = XATTR_NOFOLLOW;
+  return(setxattr_raw(path, name, value, options));
+}
+
+
+// [[Rcpp::export]]
+int rcpp_rm_xattr(std::string path, std::string name, bool follow_symlinks=true) {
+  int options = 0;
+  if (!follow_symlinks) options = XATTR_NOFOLLOW;
+  return(removexattr(path, name, options));
+}
+
 //' Test if a target path has xattrs
 //'
 //' @md
 //' @param path target path (file or dir); this is auto-expanded
 //' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 //' @export
+//' @example inst/examples/ex1.R
 // [[Rcpp::export]]
 bool has_xattrs(const std::string path, bool follow_symlinks=true) {
   std::string full_path = std::string(R_ExpandFileName(path.c_str()));
@@ -49,6 +73,7 @@ bool has_xattrs(const std::string path, bool follow_symlinks=true) {
 //' @param path target path (file or dir); this is auto-expanded
 //' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 //' @export
+//' @example inst/examples/ex1.R
 // [[Rcpp::export]]
 CharacterVector list_xattrs(const std::string path, bool follow_symlinks=true) {
   std::string full_path = std::string(R_ExpandFileName(path.c_str()));
@@ -68,6 +93,7 @@ CharacterVector list_xattrs(const std::string path, bool follow_symlinks=true) {
 //' @param name xattr name to retrieve
 //' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 //' @export
+//' @example inst/examples/ex1.R
 // [[Rcpp::export]]
 CharacterVector get_xattr(const std::string path, std::string name, bool follow_symlinks=true) {
   std::string full_path = std::string(R_ExpandFileName(path.c_str()));
@@ -87,6 +113,7 @@ CharacterVector get_xattr(const std::string path, std::string name, bool follow_
 //' @param name xattr name to retrieve
 //' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 //' @export
+//' @example inst/examples/ex1.R
 // [[Rcpp::export]]
 RawVector get_xattr_raw(const std::string path, std::string name, bool follow_symlinks=true) {
   std::string full_path = std::string(R_ExpandFileName(path.c_str()));
@@ -106,6 +133,7 @@ RawVector get_xattr_raw(const std::string path, std::string name, bool follow_sy
 //' @param name xattr name to retrieve
 //' @param follow_symlinks if `FALSE` get xattr of the symlink vs the target it references
 //' @export
+//' @example inst/examples/ex1.R
 // [[Rcpp::export]]
 ssize_t get_xattr_size(const std::string path, std::string name, bool follow_symlinks=true) {
   std::string full_path = std::string(R_ExpandFileName(path.c_str()));

tests/testthat/test-xattrs.R

@@ -1,6 +1,34 @@
-context("minimal package functionality")
+context("Get / set / check / read / list / size xattrs ops work")
 test_that("we can do something", {
 
-  #expect_that(some_function(), is_a("data.frame"))
+  tf <- tempfile(fileext = ".csv")
+  write.csv(mtcars, tf)
+
+  expect_false(has_xattrs(tf))
+  expect_identical(get_xattr(tf, "is.rud.setting"), character(0))
+
+  set_xattr(tf, "is.rud.setting.a", "first attribut")
+
+  expect_equal(get_xattr(tf, "is.rud.setting.a"), "first attribut")
+  expect_equal(get_xattr_size(tf, "is.rud.setting.a"), 14)
+
+  expect_true(has_xattrs(tf))
+
+  set_xattr(tf, "is.rud.setting.b", "second attribute")
+  expect_equal(get_xattr(tf, "is.rud.setting.b"), "second attribute")
+  expect_equal(get_xattr_size(tf, "is.rud.setting.b"), 16)
+
+  set_xattr(tf, "is.rud.setting.a", "first attribute")
+  expect_equal(get_xattr(tf, "is.rud.setting.a"), "first attribute")
+  expect_equal(get_xattr_size(tf, "is.rud.setting.a"), 15)
+
+  expect_equal(length(list_xattrs(tf)), 2)
+
+  expect_equal(nrow(get_xattr_df(tf)), 2)
+
+  rm_xattr(tf, "is.rud.setting")
+  expect_equal(get_xattr(tf, "is.rud.setting"), character(0))
+
+  unlink(tf)
 
 })