File operations with folders in path

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gitlabr
 Title: Access to the 'Gitlab' API
-Version: 2.0.0.9000
+Version: 2.1.0
 Authors@R: c(
     person("Jirka", "Lewandowski", , "jirka.lewandowski@wzb.eu", role = "aut"),
     person("Sébastien", "Rochette", , "sebastien@thinkr.fr", role = c("aut", "cre"),
@@ -39,4 +39,4 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.2
+RoxygenNote: 7.2.1

NAMESPACE

@@ -41,10 +41,13 @@ export(gl_create_branch)
 export(gl_create_issue)
 export(gl_create_merge_request)
 export(gl_delete_branch)
+export(gl_delete_file)
+export(gl_delete_group)
 export(gl_delete_issue)
 export(gl_delete_merge_request)
 export(gl_delete_project)
 export(gl_edit_commit_comment)
+export(gl_edit_group)
 export(gl_edit_issue)
 export(gl_edit_issue_comment)
 export(gl_edit_merge_request)
@@ -56,20 +59,25 @@ export(gl_get_commit_comments)
 export(gl_get_commits)
 export(gl_get_diff)
 export(gl_get_file)
+export(gl_get_group_id)
 export(gl_get_issue)
 export(gl_get_issue_comments)
 export(gl_get_project)
 export(gl_get_project_id)
 export(gl_get_projects)
+export(gl_group_req)
 export(gl_jobs)
 export(gl_latest_build_artifact)
 export(gl_list_branches)
 export(gl_list_files)
 export(gl_list_group_projects)
+export(gl_list_groups)
 export(gl_list_issues)
 export(gl_list_merge_requests)
 export(gl_list_projects)
+export(gl_list_sub_groups)
 export(gl_list_user_projects)
+export(gl_new_group)
 export(gl_new_issue)
 export(gl_new_project)
 export(gl_pipelines)

NEWS.md

@@ -1,3 +1,5 @@
+# gitlabr 2.1.0
+
 # gitlabr 2.0.0.9000
 
 New

R/files.R

@@ -18,8 +18,6 @@
 #' gl_repository(project = <<your-project-id>>)
 #' # _All contributors
 #' gl_repository(project = <<your-project-id>>, "contributors")
-#' # _List files
-#' gl_list_files(project = <<your-project-id>>)
 #' # _Get content of one file
 #' gl_get_file(project = <<your-project-id>>, file_path = "README.md")
 #' # _Test if file exists
@@ -29,11 +27,25 @@ gl_repository <- function(project, req = c("tree"), ref = get_main(), ...) {
   gitlab(gl_proj_req(project, c("repository", req), ...), ref = ref, ...)
 }
 
-#' @rdname gl_repository
+
+#' List of files in a folder
+#' 
+#' @param project name or id of project (not repository!)
+#' @param path path of the folder
+#' @param ref name of ref (commit branch or tag) 
+#' @param ... passed on to [gitlab()] API call
 #' @importFrom purrr partial
 #' @export
-gl_list_files <- function(project, ref = get_main(), ...) {
-  gitlab(gl_proj_req(project, c("repository", "tree"), ...), ref = ref, ...)
+#' @examples \dontrun{
+#' # Set GitLab connection for examples
+#' set_gitlab_connection(
+#'  gitlab_url = "https://gitlab.com",
+#'  private_token = Sys.getenv("GITLAB_COM_TOKEN"))
+#' 
+#' gl_list_files(project = <<your-project-id>>, path = <<path-to-folder>>)
+#' }
+gl_list_files <- function(project, path = "", ref = get_main(), ...) {
+  gitlab(gl_proj_req(project, c("repository", "tree"), ...), path = path, ref = ref, ...)
 }
 
 #' For `gl_file_exists` dots are passed on to [gl_list_files()] and GitLab API call
@@ -49,7 +61,7 @@ gl_file_exists <- function(project, file_path, ref, ...) {
     iff(dirname(file_path) != ".", c, path = dirname(file_path)) %>%
     iffn(project_missing, c, project = project) %>%
     pipe_into("args", do.call, what = gl_list_files) %>%
-    dplyr::filter(name == basename(file_path)) %>%
+    dplyr::filter( {if (nrow(.) > 0) name else ""} == basename(file_path)) %>%
     { nrow(.) > 0 }
 }
 
@@ -77,7 +89,7 @@ gl_get_file <- function(project,
                   ...)
   } else {
     gl_repository(project = project,
-                  req = c("files", file_path),
+                  req = c("files", utils::URLencode(file_path, reserved = TRUE)),
                   ref = ref,
                   verb = httr::GET,
                   ...)
@@ -126,7 +138,7 @@ gl_push_file <- function(project,
 
   exists <- gl_file_exists(project = project, file_path, ref = branch, ...)
   if (!exists || overwrite) {
-    gitlab(req = gl_proj_req(project = project, c("repository", "files", file_path), ...),
+    gitlab(req = gl_proj_req(project = project, c("repository", "files", utils::URLencode(file_path, reserved = TRUE)), ...),
            branch_name = branch,  ## This is legacy for API v3 use and will be ignored by API v4
            branch = branch,
            content = content,
@@ -140,6 +152,7 @@ gl_push_file <- function(project,
 }
 
 #' @rdname onefile
+#' @export
 gl_delete_file <- function(project,
                          file_path,
                          commit_message,
@@ -148,7 +161,7 @@ gl_delete_file <- function(project,
 
   exists <- gl_file_exists(project = project, file_path, ref = branch, ...)
   if (exists) {
-    gitlab(req = gl_proj_req(project = project, c("repository", "files", file_path), ...),
+    gitlab(req = gl_proj_req(project = project, c("repository", "files", utils::URLencode(file_path, reserved = TRUE)), ...),
            branch_name = branch,  ## This is legacy for API v3 use and will be ignored by API v4
            branch = branch,
            commit_message = commit_message,

R/globals.R

@@ -3,6 +3,6 @@
 ## cf. https://stackoverflow.com/questions/9439256/how-can-i-handle-r-cmd-check-no-visible-binding-for-global-variable-notes-when
 globalVariables(c("name", "id", "iid", "rel", ".",  ## general
                   "gitlabr_0_7_renaming", "old_name", "new_name", ## update_code
-                  "matches_name", "matches_path", "matches_path_with_namespace", "path", "path_with_namespace", ## get_project_id
+                  "matches_name", "matches_path", "matches_path_with_namespace", "path", "full_path", "matches_full_path", "path_with_namespace", ## get_project_id
                   "StopReporter" ## for NSE in use_gitlab_ci
 ))

R/groups.R

@@ -0,0 +1,153 @@
+#' List groups information
+#' 
+#' @param ... passed on to [gitlab()]
+#' @export
+#' @return tibble of each group with corresponding information
+#' 
+#' @examples \dontrun{
+#' set_gitlab_connection(
+#'   gitlab_url = "https://gitlab.com", 
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
+#' # List all groups
+#' gl_get_groups(max_page = 1)
+#' # List sub-groups of a group
+#' gl_list_sub_groups(group_id = "<<group-id>>", max_page = 1)
+#' }
+gl_list_groups <- function(...) {
+  gitlabr::gitlab("groups", ...)
+}
+
+#' @param group_id id of the group to list group from
+#' @export
+#' @rdname gl_list_groups
+gl_list_sub_groups <- function(group_id, ...) {
+  gitlab(c("groups", group_id, "subgroups"), ...)
+}
+
+#' Create a group specific request
+#' 
+#' Prefixes the request location with "groups/:id/subgroups" and automatically
+#' translates group names into ids
+#' 
+#' @param group group name or id
+#' @param ... passed on to [gl_get_group_id()]
+#' @export
+#' @return A vector of character to be used as request for functions involving groups
+#' @examples 
+#' \dontrun{
+#' gl_group_req("test_group"<<your-group-id>>)
+#' }
+gl_group_req <- function(group, ...) {
+  if (missing(group) || is.null(group)) {
+    return(c("groups"))
+  } else {
+    return(c("groups", to_group_id(group, ...)))
+  }
+}
+
+#' Get a group id by name
+#' 
+#' @param group_name group name
+#' @param ... passed on to [gitlab()]
+#' @importFrom dplyr mutate filter
+#' 
+#' @details 
+#' Number of pages searched is limited to (per_page =) 20 * (max_page =) 10 by default.
+#' If the `group_name` is an old group lost in a big repository (position > 200), 
+#' `gl_get_group_id()` may not find the group id.
+#' 
+#' @export
+#' @return Integer. ID of the group if found.
+#' @examples
+#' \dontrun{
+#' gl_get_group_id("<<your-group-name>>")
+#' }
+gl_get_group_id <- function(group_name, ...) {
+
+  matching <- gitlab(req = "groups", ...) %>%
+    mutate(matches_name = name == group_name,
+           matches_path = path == group_name,
+           matches_full_path = full_path == group_name) %>%
+    filter(matches_full_path |
+             (sum(matches_full_path) == 0L &
+                matches_path | matches_name))
+
+  if (nrow(matching) == 0) {
+    stop("There was no matching 'id' with your group name. ",
+         "Either it does not exist, or most probably, ", 
+         "it is not available in the first groups available to you. ",
+         "The name-matching is limited to the first pages of groups accessible. ",
+         "Please use directly the 'id' of your group.")
+  } else if (nrow(matching) > 1) {
+    warning(paste(c("Multiple groups with given name or path found,",
+                    "please use explicit name with namespace:",
+                    matching$path_with_namespace,
+                    paste("Picking", matching[1,"path_with_namespace"], "as default")),
+                  collapse = "\n"))
+  }
+
+  matching[1,"id"] %>%
+    as.integer()
+}
+
+to_group_id <- function(x, ...) {
+  if (!is.na(suppressWarnings(as.numeric(x))) | is.numeric(x)) {
+    as.numeric(x)
+  } else {
+    gl_get_group_id(x, ...)
+  }
+}
+
+
+#' Manage groups
+#' @param path to the new group
+#' @param name of the new group
+#' @param ... passed on to [gitlab()] API call for "Create group"
+#' @export
+#' @return A tibble with the group information. `gl_delete_group()` returns an empty tibble.
+#' @details 
+#' You can use extra parameters as proposed in the GitLab API.
+#' 
+#' @examples \dontrun{
+#' set_gitlab_connection(
+#'   gitlab_url = "https://gitlab.com", 
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
+#' # Create new group
+#' gl_new_group(name = "mygroup")
+#' # Edit existing group
+#' gl_edit_group(group = "<<your-group-id>>", default_branch = "main")
+#' # Delete group
+#' gl_delete_group(group = "<<your-group-id>>")
+#' }
+gl_new_group <- function(name,
+                         path,
+                         ...) {
+    gitlab(req = "groups", 
+           path = path,
+           name = name,
+           verb = httr::POST,
+           ...)
+}
+
+#' @param group The ID or URL-encoded path of the group.
+#' @rdname gl_new_group
+#' @export
+gl_edit_group <- function(group,
+                          ...) {
+
+  gitlab(req = c("groups", to_group_id(group)), 
+         verb = httr::PUT,
+         ...)
+
+}
+
+#' @rdname gl_new_group
+#' @export
+gl_delete_group <- function(group) {
+
+  gitlab(req = c("groups", to_group_id(group)),
+         verb = httr::DELETE)
+}
+