diff --git a/NAMESPACE b/NAMESPACE index 3c63ade..45a9f91 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -6,7 +6,6 @@ export(exec_flowr) export(exec_node_command) export(get_default_node_base_dir) export(install_flowr) -export(install_node) export(request_file_analysis) export(request_repl) export(request_slice) diff --git a/R/connect.R b/R/connect.R index 40ad1da..5b9f645 100644 --- a/R/connect.R +++ b/R/connect.R @@ -2,6 +2,10 @@ #' Connects to a running flowR server at the given host and port #' +#' @param host The host to connect to. By default, this is "localhost". +#' @param port The port to connect to. By default, this is 1042. +#' @param blocking Whether to use blocking mode for the connection. +#' #' @seealso [send_request()] #' @seealso [disconnect()] #' @@ -17,6 +21,9 @@ connect <- function(host = "localhost", port = 1042, blocking = TRUE) { #' Sends a JSON request to the running flowR server, if connected #' +#' @param connection The connection to use when sending the request. +#' @param command The command to send, as a named list representing the key-value pairs to set in the JSON request. +#' #' @seealso [connect()] #' @seealso [disconnect()] #' @@ -36,6 +43,8 @@ send_request <- function(connection, command) { #' Closes an active connection to a flowR server, if connected #' +#' @param connection The connection to close. +#' #' @seealso [connect()] #' @seealso [send_request()] #' diff --git a/R/node.R b/R/node.R index d1dd5c6..93e16b7 100644 --- a/R/node.R +++ b/R/node.R @@ -1,7 +1,11 @@ -# TODO this is still undocumented :( - -#' @export -install_node <- function(node_ver, verbose = FALSE, node_base_dir = get_default_node_base_dir()) { +#' Installs the given version of Node.js on the local system in the given directory. +#' +#' @param node_ver The versino of Node to install +#' @param verbose Whether to print out information about the commands being executed. +#' @param base_dir The base directory to install Node in. By default, this uses the package's installation directory through [get_default_node_base_dir()]. +#' +#' #' @export +install_node <- function(node_ver, verbose = FALSE, base_dir = get_default_node_base_dir()) { os <- get_os() arch <- switch(Sys.info()[["machine"]], "x86-64" = "x64", @@ -12,20 +16,20 @@ install_node <- function(node_ver, verbose = FALSE, node_base_dir = get_default_ ) if (verbose) { - print(paste0("Installing node ", node_ver, " in ", node_base_dir)) + print(paste0("Installing node ", node_ver, " in ", base_dir)) } - if (dir.exists(node_base_dir)) { - unlink(node_base_dir, recursive = TRUE) + if (dir.exists(base_dir)) { + unlink(base_dir, recursive = TRUE) if (verbose) { print("Removing old node installation") } } - dir.create(node_base_dir) + dir.create(base_dir) # url example: https://nodejs.org/dist/v22.5.1/node-v22.5.1-win-x86.zip file_type <- if (os == "win") "zip" else "tar.gz" - node_archive_dest <- file.path(node_base_dir, paste0("node.", file_type)) + node_archive_dest <- file.path(base_dir, paste0("node.", file_type)) node_file_name <- sprintf("node-v%s-%s-%s", node_ver, os, arch) utils::download.file(sprintf("https://nodejs.org/dist/v%s/%s.%s", node_ver, node_file_name, file_type), node_archive_dest) if (verbose) { @@ -33,22 +37,38 @@ install_node <- function(node_ver, verbose = FALSE, node_base_dir = get_default_ } if (file_type == "zip") { - utils::unzip(node_archive_dest, exdir = node_base_dir) + utils::unzip(node_archive_dest, exdir = base_dir) } else { - utils::untar(node_archive_dest, exdir = node_base_dir) + utils::untar(node_archive_dest, exdir = base_dir) } unlink(node_archive_dest) if (verbose) { - print(paste0("Extracted node archive to ", file.path(node_base_dir, node_file_name))) + print(paste0("Extracted node archive to ", file.path(base_dir, node_file_name))) } } +#' Installs the given version of flowR on the local system in the given directory. +#' This function expects Node to have been installed using [install_node()] prior. +#' +#' @param flowr_ver The version of flowR to install. +#' @param verbose Whether to print out information about the commands being executed. +#' @param base_dir The base directory that Node was installed in, and where flowR should be installed. By default, this uses the package's installation directory through [get_default_node_base_dir()]. +#' @return The return value of the [exec_node_command()] call. +#' #' @export install_flowr <- function(flowr_ver, verbose = FALSE, base_dir = get_default_node_base_dir()) { exec_node_command("npm", paste0("install -g @eagleoutice/flowr@", flowr_ver), verbose, base_dir) } +#' Executes a local version of the flowR CLI with the given arguments in the given directory. +#' This function expects Node and flowR to have been installed using [install_node()] and [install_flowr()] prior. +#' +#' @param args The arguments to pass to the flowR CLI, as a character. +#' @param verbose Whether to print out information about the commands being executed. +#' @param base_dir The base directory that Node and flowR were installed in. By default, this uses the package's installation directory through [get_default_node_base_dir()]. +#' @return The return value of the [exec_node_command()] call. +#' #' @export exec_flowr <- function(args, verbose = FALSE, base_dir = get_default_node_base_dir()) { # we installed flowr globally (see above) in the scope of our local node installation, so we can find it here @@ -56,30 +76,44 @@ exec_flowr <- function(args, verbose = FALSE, base_dir = get_default_node_base_d exec_node_command("node", paste(flowr_path, args), verbose, base_dir) } +#' Executes the given Node subcommand in the given arguments in the given directory. +#' This function expects Node to have been installed using [install_node()]. +#' +#' @param app The node subcommand to run, which can be one of "node", "npm", or "npx". +#' @param args The arguments to pass to the Node command, as a character. +#' @param verbose Whether to print out information about the commands being executed. +#' @param base_dir The base directory that Node was installed in. By default, this uses the package's installation directory through [get_default_node_base_dir()]. +#' @return The return value of the system2 call. +#' #' @export -exec_node_command <- function(app, args, verbose = FALSE, base_dir = get_default_node_base_dir()) { +exec_node_command <- function(app = c("node", "npm", "npx"), args, verbose = FALSE, base_dir = get_default_node_base_dir()) { # linux/mac have binaries in the bin subdirectory, windows has node.exe and npm/npx.cmd in the root, bleh path <- if (get_os() == "win") paste0(app, if (app == "node") ".exe" else ".cmd") else file.path("bin", app) cmd <- file.path(get_node_exe_dir(base_dir), path) if (verbose) { print(paste0("Executing ", cmd, " ", paste0(args, collapse = " "))) } - system2(cmd, args) + return(system2(cmd, args)) } +#' Returns the default node base directory to use when installing Node, which is the directory that the package with the given name is installed in. +#' +#' @param pkg_dir_name The name of the package to find the installation directory of. By default, this is "flowr", the name of this package. +#' @return The default base directory to use when installing Node. +#' #' @export -get_default_node_base_dir <- function(addin_dir_name = "flowradapter") { +get_default_node_base_dir <- function(pkg_dir_name = "flowr") { # we find the directory to install node into by finding the directory that # the currently running instance of the package is (likely) installed in. # this may seem like a terrible solution but it's the best one i could come up with :( for (path in .libPaths()) { for (dir in list.dirs(path, full.names = FALSE, recursive = FALSE)) { - if (dir == addin_dir_name) { + if (dir == pkg_dir_name) { return(file.path(path, dir, "_node")) } } } - stop(paste0("Could not find ", addin_dir_name, " directory in any libPaths")) + stop(paste0("Could not find ", pkg_dir_name, " directory in any libPaths")) } get_node_exe_dir <- function(base_dir) { diff --git a/R/slice.R b/R/slice.R index 489c3d7..8d4b02d 100644 --- a/R/slice.R +++ b/R/slice.R @@ -7,7 +7,7 @@ #' @param id The id of the request #' @return A list containing the id and the response #' -#' @seealso [initiate_file_analysis()] +#' @seealso [request_file_analysis()] #' @seealso [connect()] #' #' @export diff --git a/R/visit.R b/R/visit.R index 74baa7e..c795352 100644 --- a/R/visit.R +++ b/R/visit.R @@ -14,7 +14,7 @@ visit_nodes <- function(nodes, callback) { #' Visits the given node and all of their children, invoking the callback for each visited node #' -#' @param nodes The node to visit +#' @param node The node to visit #' @param callback The callback function to invoke for each node #' #' @export diff --git a/man/connect.Rd b/man/connect.Rd index de821d4..fdeb1c9 100644 --- a/man/connect.Rd +++ b/man/connect.Rd @@ -6,6 +6,13 @@ \usage{ connect(host = "localhost", port = 1042, blocking = TRUE) } +\arguments{ +\item{host}{The host to connect to. By default, this is "localhost".} + +\item{port}{The port to connect to. By default, this is 1042.} + +\item{blocking}{Whether to use blocking mode for the connection.} +} \description{ Connects to a running flowR server at the given host and port } diff --git a/man/disconnect.Rd b/man/disconnect.Rd index 7b58f2d..6c5ba60 100644 --- a/man/disconnect.Rd +++ b/man/disconnect.Rd @@ -6,6 +6,9 @@ \usage{ disconnect(connection) } +\arguments{ +\item{connection}{The connection to close.} +} \description{ Closes an active connection to a flowR server, if connected } diff --git a/man/exec_flowr.Rd b/man/exec_flowr.Rd new file mode 100644 index 0000000..2674155 --- /dev/null +++ b/man/exec_flowr.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/node.R +\name{exec_flowr} +\alias{exec_flowr} +\title{Executes a local version of the flowR CLI with the given arguments in the given directory. +This function expects Node and flowR to have been installed using \code{\link[=install_node]{install_node()}} and \code{\link[=install_flowr]{install_flowr()}} prior.} +\usage{ +exec_flowr(args, verbose = FALSE, base_dir = get_default_node_base_dir()) +} +\arguments{ +\item{args}{The arguments to pass to the flowR CLI, as a character.} + +\item{verbose}{Whether to print out information about the commands being executed.} + +\item{base_dir}{The base directory that Node and flowR were installed in. By default, this uses the package's installation directory through \code{\link[=get_default_node_base_dir]{get_default_node_base_dir()}}.} +} +\value{ +The return value of the \code{\link[=exec_node_command]{exec_node_command()}} call. +} +\description{ +Executes a local version of the flowR CLI with the given arguments in the given directory. +This function expects Node and flowR to have been installed using \code{\link[=install_node]{install_node()}} and \code{\link[=install_flowr]{install_flowr()}} prior. +} diff --git a/man/exec_node_command.Rd b/man/exec_node_command.Rd new file mode 100644 index 0000000..f16fa20 --- /dev/null +++ b/man/exec_node_command.Rd @@ -0,0 +1,30 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/node.R +\name{exec_node_command} +\alias{exec_node_command} +\title{Executes the given Node subcommand in the given arguments in the given directory. +This function expects Node to have been installed using \code{\link[=install_node]{install_node()}}.} +\usage{ +exec_node_command( + app = c("node", "npm", "npx"), + args, + verbose = FALSE, + base_dir = get_default_node_base_dir() +) +} +\arguments{ +\item{app}{The node subcommand to run, which can be one of "node", "npm", or "npx".} + +\item{args}{The arguments to pass to the Node command, as a character.} + +\item{verbose}{Whether to print out information about the commands being executed.} + +\item{base_dir}{The base directory that Node was installed in. By default, this uses the package's installation directory through \code{\link[=get_default_node_base_dir]{get_default_node_base_dir()}}.} +} +\value{ +The return value of the system2 call. +} +\description{ +Executes the given Node subcommand in the given arguments in the given directory. +This function expects Node to have been installed using \code{\link[=install_node]{install_node()}}. +} diff --git a/man/get_default_node_base_dir.Rd b/man/get_default_node_base_dir.Rd new file mode 100644 index 0000000..07339ea --- /dev/null +++ b/man/get_default_node_base_dir.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/node.R +\name{get_default_node_base_dir} +\alias{get_default_node_base_dir} +\title{Returns the default node base directory to use when installing Node, which is the directory that the package with the given name is installed in.} +\usage{ +get_default_node_base_dir(pkg_dir_name = "flowr") +} +\arguments{ +\item{pkg_dir_name}{The name of the package to find the installation directory of. By default, this is "flowr", the name of this package.} +} +\value{ +The default base directory to use when installing Node. +} +\description{ +Returns the default node base directory to use when installing Node, which is the directory that the package with the given name is installed in. +} diff --git a/man/install_flowr.Rd b/man/install_flowr.Rd new file mode 100644 index 0000000..bcc9140 --- /dev/null +++ b/man/install_flowr.Rd @@ -0,0 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/node.R +\name{install_flowr} +\alias{install_flowr} +\title{Installs the given version of flowR on the local system in the given directory. +This function expects Node to have been installed using \code{\link[=install_node]{install_node()}} prior.} +\usage{ +install_flowr( + flowr_ver, + verbose = FALSE, + base_dir = get_default_node_base_dir() +) +} +\arguments{ +\item{flowr_ver}{The version of flowR to install.} + +\item{verbose}{Whether to print out information about the commands being executed.} + +\item{base_dir}{The base directory that Node was installed in, and where flowR should be installed. By default, this uses the package's installation directory through \code{\link[=get_default_node_base_dir]{get_default_node_base_dir()}}.} +} +\value{ +The return value of the \code{\link[=exec_node_command]{exec_node_command()}} call. +} +\description{ +Installs the given version of flowR on the local system in the given directory. +This function expects Node to have been installed using \code{\link[=install_node]{install_node()}} prior. +} diff --git a/man/install_node.Rd b/man/install_node.Rd new file mode 100644 index 0000000..379f745 --- /dev/null +++ b/man/install_node.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/node.R +\name{install_node} +\alias{install_node} +\title{Installs the given version of Node.js on the local system in the given directory.} +\usage{ +install_node(node_ver, verbose = FALSE, base_dir = get_default_node_base_dir()) +} +\arguments{ +\item{node_ver}{The versino of Node to install} + +\item{verbose}{Whether to print out information about the commands being executed.} + +\item{base_dir}{The base directory to install Node in. By default, this uses the package's installation directory through \code{\link[=get_default_node_base_dir]{get_default_node_base_dir()}}. + +#' @export} +} +\description{ +Installs the given version of Node.js on the local system in the given directory. +} diff --git a/man/request_slice.Rd b/man/request_slice.Rd index 697ee07..a729da4 100644 --- a/man/request_slice.Rd +++ b/man/request_slice.Rd @@ -23,7 +23,7 @@ A list containing the id and the response Sends a \href{https://github.com/flowr-analysis/flowr/wiki/Interface#the-slice-request}{"request-slice"} request } \seealso{ -\code{\link[=initiate_file_analysis]{initiate_file_analysis()}} +\code{\link[=request_file_analysis]{request_file_analysis()}} \code{\link[=connect]{connect()}} } diff --git a/man/send_request.Rd b/man/send_request.Rd index 614ad1b..89d3764 100644 --- a/man/send_request.Rd +++ b/man/send_request.Rd @@ -6,6 +6,11 @@ \usage{ send_request(connection, command) } +\arguments{ +\item{connection}{The connection to use when sending the request.} + +\item{command}{The command to send, as a named list representing the key-value pairs to set in the JSON request.} +} \description{ Sends a JSON request to the running flowR server, if connected } diff --git a/man/visit_node.Rd b/man/visit_node.Rd index 4d016de..d99094f 100644 --- a/man/visit_node.Rd +++ b/man/visit_node.Rd @@ -7,9 +7,9 @@ visit_node(node, callback) } \arguments{ -\item{callback}{The callback function to invoke for each node} +\item{node}{The node to visit} -\item{nodes}{The node to visit} +\item{callback}{The callback function to invoke for each node} } \description{ Visits the given node and all of their children, invoking the callback for each visited node