Object enhancements (#13)

- Allow setting an optional limit to the number of objects returned by the private `ms_object$get_paged_list()` method.
- The private `ms_object$init_list_objects()` method now has a `...` argument to allow passing extra parameters to class constructors.
- Add documentation on how to use `get_paged_list` and `init_list_objects`.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AzureGraph
 Title: Simple Interface to 'Microsoft Graph'
-Version: 1.2.0
+Version: 1.2.0.9000
 Authors@R: c(
     person("Hong", "Ooi", , "hongooi73@gmail.com", role = c("aut", "cre")),
     person("Microsoft", role="cph")

NEWS.md

@@ -1,3 +1,9 @@
+# AzureGraph 1.2.0.9000
+
+- Allow setting an optional limit to the number of objects returned by the private `ms_object$get_paged_list()` method.
+- The private `ms_object$init_list_objects()` method now has a `...` argument to allow passing extra parameters to class constructors.
+- Add documentation on how to use `get_paged_list` and `init_list_objects`.
+
 # AzureGraph 1.2.0
 
 - Internal refactoring to support future extensibility, including transferring some utility functions from AzureRMR to here.

R/format.R

@@ -13,7 +13,7 @@
 format_public_fields <- function(env, exclude=character(0))
 {
     objnames <- ls(env)
-    std_fields <- "token"
+    std_fields <- c("token")
     objnames <- setdiff(objnames, c(exclude, std_fields))
 
     maxwidth <- as.integer(0.8 * getOption("width"))

R/ms_object.R

@@ -7,7 +7,7 @@
 #' - `token`: The token used to authenticate with the Graph host.
 #' - `tenant`: The Azure Active Directory tenant for this object.
 #' - `type`: The type of object, in a human-readable format.
-#' - `properties`: The object properties.
+#' - `properties`: The object properties, as obtained from the Graph host.
 #' @section Methods:
 #' - `new(...)`: Initialize a new directory object. Do not call this directly; see 'Initialization' below.
 #' - `delete(confirm=TRUE)`: Delete an object. By default, ask for confirmation first.
@@ -15,6 +15,19 @@
 #' - `do_operation(...)`: Carry out an arbitrary operation on the object.
 #' - `sync_fields()`: Synchronise the R object with the data in Azure Active Directory.
 #'
+#' The following methods are private, and are intended for package authors extending AzureGraph to define their own objects.
+#' - `get_paged_list(lst, next_link_name, value_name, simplify, n)`: Used to process API calls that return lists of objects. Microsoft Graph returns lists in pages, with each page containing a subset of objects and a link to the next page. This method reconstructs the list, given the first page. Its arguments are:
+#'    - `lst`: Object containing the initial page of results, generally the result of a call to `do_operation`. Should be a list with names corresponding to the arguments `next_link_name` and `value_name`.
+#'    - `next_link_name`: The name of the component of `lst` containing the link to the next page. Defaults to `@odata.nextLink`.
+#'    - `value_name`: The name of the component of `lst` containing the first page of results. Defaults to `value`.
+#'    - `simplify`: Whether to turn the list of objects into a data frame. This is useful if the list is intended to be a rectangular data structure, eg a SharePoint list or OneDrive file listing. Note that the vctrs package must be installed to return a data frame, if the objects in the list can have varying structures (which will often be the case).
+#'    - `n`: Optionally, limit the list to this many objects.
+#' - `init_list_objects(lst, type_filter, default_generator, ...)`: `get_paged_list` returns a raw list, the result of parsing the JSON response from the Graph host. This method converts the list into actual R6 objects. Its arguments are:
+#'   - `lst`: The input list.
+#'   - `type_filter`: The possible types of objects that the list contains. The default is NULL.
+#'   - `default_generator`: An R6 class generator object to use, if `init_list_objects` is unable to detect the type of an object. It's recommended to change this from the default value of `ms_object`, if you know that all objects in the list will have the same class.
+#'   - `...`: Further arguments to pass to the generator's `initialize` method.
+#'
 #' @section Initialization:
 #' Objects of this class should not be created directly. Instead, create an object of the appropriate subclass.
 #'
@@ -99,30 +112,33 @@ private=list(
     # object type as it appears in REST API path
     api_type=NULL,
 
-    get_paged_list=function(lst, next_link_name="@odata.nextLink", value_name="value", simplify=FALSE)
+    get_paged_list=function(lst, next_link_name="@odata.nextLink", value_name="value", simplify=FALSE, n=Inf)
     {
-        bind_fn <- if(requireNamespace("vctrs"))
+        bind_fn <- if(requireNamespace("vctrs", quietly=TRUE))
             vctrs::vec_rbind
         else base::rbind
         res <- lst[[value_name]]
-        while(!is_empty(lst[[next_link_name]]))
+        if(n <= 0) n <- Inf
+        while(!is_empty(lst[[next_link_name]]) && length(res) < n)
         {
             lst <- call_graph_url(self$token, lst[[next_link_name]], simplify=simplify)
             res <- if(simplify)
-                bind_fn(res, lst[[value_name]])  # this assumes all objects have the exact same fields
+                bind_fn(res, lst[[value_name]])  # base::rbind assumes all objects have the exact same fields
             else c(res, lst[[value_name]])
         }
-        res
+        if(n < length(res))
+            res[seq_len(n)]
+        else res
     },
 
-    init_list_objects=function(lst, type_filter=NULL, default_generator=ms_object)
+    init_list_objects=function(lst, type_filter=NULL, default_generator=ms_object, ...)
     {
         lst <- lapply(lst, function(obj)
         {
             class_gen <- find_class_generator(obj, type_filter, default_generator)
             if(is.null(class_gen))
                 NULL
-            else class_gen$new(self$token, self$tenant, obj)
+            else class_gen$new(self$token, self$tenant, obj, ...)
         })
         lst[!sapply(lst, is.null)]
     }

man/graph_login.Rd

@@ -39,7 +39,7 @@ list_graph_logins()
 
 \item{aad_host}{Azure Active Directory host for authentication. Defaults to \verb{https://login.microsoftonline.com/}. Change this if you are using a government or private cloud.}
 
-\item{scopes}{The Microsoft Graph scopes (permissions) to obtain for this Graph login. Only for \code{version=2}.}
+\item{scopes}{The Microsoft Graph scopes (permissions) to obtain for this Graph login. For \code{create_graph_login}, this is used only for \code{version=2}. For \code{get_graph_login}, set this to NA to require an AAD v1.0 token.}
 
 \item{config_file}{Optionally, a JSON file containing any of the arguments listed above. Arguments supplied in this file take priority over those supplied on the command line. You can also use the output from the Azure CLI \verb{az ad sp create-for-rbac} command.}
 

man/ms_object.Rd

@@ -16,7 +16,7 @@ Base class representing a object in Microsoft Graph. All other Graph object clas
 \item \code{token}: The token used to authenticate with the Graph host.
 \item \code{tenant}: The Azure Active Directory tenant for this object.
 \item \code{type}: The type of object, in a human-readable format.
-\item \code{properties}: The object properties.
+\item \code{properties}: The object properties, as obtained from the Graph host.
 }
 }
 
@@ -29,6 +29,25 @@ Base class representing a object in Microsoft Graph. All other Graph object clas
 \item \code{do_operation(...)}: Carry out an arbitrary operation on the object.
 \item \code{sync_fields()}: Synchronise the R object with the data in Azure Active Directory.
 }
+
+The following methods are private, and are intended for package authors extending AzureGraph to define their own objects.
+\itemize{
+\item \code{get_paged_list(lst, next_link_name, value_name, simplify, n)}: Used to process API calls that return lists of objects. Microsoft Graph returns lists in pages, with each page containing a subset of objects and a link to the next page. This method reconstructs the list, given the first page. Its arguments are:
+\itemize{
+\item \code{lst}: Object containing the initial page of results, generally the result of a call to \code{do_operation}. Should be a list with names corresponding to the arguments \code{next_link_name} and \code{value_name}.
+\item \code{next_link_name}: The name of the component of \code{lst} containing the link to the next page. Defaults to \verb{@odata.nextLink}.
+\item \code{value_name}: The name of the component of \code{lst} containing the first page of results. Defaults to \code{value}.
+\item \code{simplify}: Whether to turn the list of objects into a data frame. This is useful if the list is intended to be a rectangular data structure, eg a SharePoint list or OneDrive file listing. Note that the vctrs package must be installed to return a data frame, if the objects in the list can have varying structures (which will often be the case).
+\item \code{n}: Optionally, limit the list to this many objects.
+}
+\item \code{init_list_objects(lst, type_filter, default_generator, ...)}: \code{get_paged_list} returns a raw list, the result of parsing the JSON response from the Graph host. This method converts the list into actual R6 objects. Its arguments are:
+\itemize{
+\item \code{lst}: The input list.
+\item \code{type_filter}: The possible types of objects that the list contains. The default is NULL.
+\item \code{default_generator}: An R6 class generator object to use, if \code{init_list_objects} is unable to detect the type of an object. It's recommended to change this from the default value of \code{ms_object}, if you know that all objects in the list will have the same class.
+\item \code{...}: Further arguments to pass to the generator's \code{initialize} method.
+}
+}
 }
 
 \section{Initialization}{