[GR-4809] Need a mechanism to provide help for FastR builtins.

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/base/BasePackage.java

@@ -94,6 +94,8 @@ import com.oracle.truffle.r.nodes.builtin.fastr.FastRContext;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRContextFactory;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRDebug;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRDebugNodeGen;
+import com.oracle.truffle.r.nodes.builtin.fastr.FastRHelp;
+import com.oracle.truffle.r.nodes.builtin.fastr.FastRHelpNodeGen;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRIdentity;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRIdentityNodeGen;
 import com.oracle.truffle.r.nodes.builtin.fastr.FastRInspect;
@@ -408,6 +410,7 @@ public class BasePackage extends RBuiltinPackage {
         add(FastrDqrls.class, FastrDqrlsNodeGen::create);
         add(FastRDebug.class, FastRDebugNodeGen::create);
         add(FastRSetBreakpoint.class, FastRSetBreakpointNodeGen::create);
+        add(FastRHelp.class, FastRHelpNodeGen::create);
         add(FastRIdentity.class, FastRIdentityNodeGen::create);
         add(FastRTry.class, FastRTryNodeGen::create);
         add(FastRInspect.class, FastRInspectNodeGen::create);

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/FastRHelp.java

+/*
+ * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.r.nodes.builtin.fastr;
+
+import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
+import static com.oracle.truffle.r.runtime.builtins.RBehavior.COMPLEX;
+import static com.oracle.truffle.r.runtime.builtins.RBuiltinKind.PRIMITIVE;
+
+import com.oracle.truffle.api.dsl.Specialization;
+import static com.oracle.truffle.r.nodes.builtin.CastBuilder.Predef.singleElement;
+import static com.oracle.truffle.r.nodes.builtin.CastBuilder.Predef.stringValue;
+import com.oracle.truffle.r.nodes.builtin.RBuiltinNode;
+import com.oracle.truffle.r.runtime.RError;
+import static com.oracle.truffle.r.runtime.RVisibility.ON;
+import com.oracle.truffle.r.runtime.builtins.RBuiltin;
+import com.oracle.truffle.r.runtime.data.RNull;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+
+@RBuiltin(name = ".fastr.interop.getHelpRd", visibility = ON, kind = PRIMITIVE, parameterNames = {"builtinName"}, behavior = COMPLEX)
+public abstract class FastRHelp extends RBuiltinNode.Arg1 {
+
+    static {
+        Casts casts = new Casts(FastRHelp.class);
+        casts.arg("builtinName").mustBe(stringValue()).asStringVector().mustBe(singleElement()).findFirst();
+    }
+
+    @Specialization()
+    @TruffleBoundary
+    public Object isExternal(String builtinName) {
+        InputStream in = getClass().getResourceAsStream("/com/oracle/truffle/r/nodes/builtin/fastr/Rd/" + builtinName + ".Rd");
+        if (in != null) {
+            try (BufferedReader r = new BufferedReader(new InputStreamReader(in))) {
+                StringBuilder sb = new StringBuilder();
+                String line;
+                while ((line = r.readLine()) != null) {
+                    sb.append(line).append("\n");
+                }
+                return sb.toString();
+            } catch (IOException ex) {
+                RError.warning(this, RError.Message.GENERIC, "problems while reading " + builtinName + ".Rd", ex.getMessage());
+            }
+        }
+        return RNull.instance;
+    }
+
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.external.byte.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.external.byte}
+\alias{as.external.byte}
+\title{Marks a R value to be converted to byte when passed over to a foreign language.}
+\usage{
+as.external.byte(value)
+}
+\arguments{
+\item{value}{a R value which can be converted to byte}
+}
+\value{
+An interop byte value. Error in case the given value can't be converted to a byte.
+}
+\description{
+Marks a R value to be converted to byte when passed over to a foreign language.
+}
+\examples{
+as.external.byte(123)
+}
+\seealso{
+\code{\link{as.external.char}}, \code{\link{as.external.float}}, \code{\link{as.external.long}}, \code{\link{as.external.short}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.external.char.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.external.char}
+\alias{as.external.char}
+\title{Marks a R value to be converted to char when passed over to a foreign language.}
+\usage{
+as.external.char(value)
+}
+\arguments{
+\item{value}{a R value which can be converted to char}
+}
+\value{
+An interop char value. Error in case the given value can't be converted to a char.
+}
+\description{
+Marks a R value to be converted to char when passed over to a foreign language.
+}
+\examples{
+as.external.char('a')
+}
+\seealso{
+\code{\link{as.external.byte}}, \code{\link{as.external.float}}, \code{\link{as.external.long}}, \code{\link{as.external.short}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.external.float.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.external.float}
+\alias{as.external.float}
+\title{Marks a R value to be converted to float when passed over to a foreign language.}
+\usage{
+as.external.float(value)
+}
+\arguments{
+\item{value}{a R value which can be converted to float}
+}
+\value{
+An interop float value. Error in case the given value can't be converted to a float.
+}
+\description{
+Marks a R value to be converted to float when passed over to a foreign language.
+}
+\examples{
+as.external.float(1.1)
+}
+\seealso{
+\code{\link{as.external.byte}}, \code{\link{as.external.char}}, \code{\link{as.external.long}}, \code{\link{as.external.short}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.external.long.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.external.long}
+\alias{as.external.long}
+\title{Marks a R value to be converted to long when passed over to a foreign language.}
+\usage{
+as.external.long(value)
+}
+\arguments{
+\item{value}{a R value which can be converted to long}
+}
+\value{
+An interop long value. Error in case the given value can't be converted to a long.
+}
+\description{
+Marks a R value to be converted to long when passed over to a foreign language.
+}
+\examples{
+as.external.long(123)
+}
+\seealso{
+\code{\link{as.external.byte}}, \code{\link{as.external.char}}, \code{\link{as.external.float}}, \code{\link{as.external.short}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.external.short.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.external.short}
+\alias{as.external.short}
+\title{Marks a R value to be converted to short when passed over to a foreign language.}
+\usage{
+as.external.short(value)
+}
+\arguments{
+\item{value}{a R value which can be converted to short}
+}
+\value{
+An interop short value. Error in case the given value can't be converted to a short.
+}
+\description{
+Marks a R value to be converted to short when passed over to a foreign language.
+}
+\examples{
+as.external.short(123)
+}
+\seealso{
+\code{\link{as.external.byte}}, \code{\link{as.external.char}}, \code{\link{as.external.short}}, \code{\link{as.external.long}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/as.java.array.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{as.java.array}
+\alias{as.java.array}
+\title{Converts a R vector or list to a java array.}
+\usage{
+as.java.array(x, className)
+}
+\arguments{
+\item{x}{a vector or list}
+
+\item{className}{Optional. Determines the java array component type.}
+}
+\value{
+An external object representing a java array. Error in case the array could not be created.
+}
+\description{
+Converts a R vector or list to a java array.
+}
+\examples{
+as.java.array(c(1, 2, 3), 'java.lang.Double')
+}
+\seealso{
+\code{\link{new.java.array}}, \code{\link{is.external.array}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/is.external.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{is.external}
+\alias{is.external}
+\title{Determines whether the given object is an external object or not.}
+\usage{
+is.external(obj)
+}
+\arguments{
+\item{obj}{an external object}
+}
+\value{
+TRUE in case the given value is executable, otherwise FALSE.
+}
+\description{
+Determines whether the given object is an external object or not.
+}
+\examples{
+javaClass <- new.java.class('java.util.ArrayList')
+is.external(javaClass)
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/is.external.array.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{is.external.array}
+\alias{is.external.array}
+\title{Determines whether the given external object has a size. If an external object has a size, it is expected it represents an array-like structure.
+Note that even if an e.g. java ArrayList has a "size", the returned value still would be false, because it will be recognised as an array-like structure.}
+\usage{
+is.external.array(obj)
+}
+\arguments{
+\item{obj}{an external object}
+}
+\value{
+TRUE in case the given value is an array-like structure, otherwise FALSE.
+}
+\description{
+Determines whether the given external object has a size. If an external object has a size, it is expected it represents an array-like structure.
+Note that even if an e.g. java ArrayList has a "size", the returned value still would be false, because it will be recognised as an array-like structure.
+}
+\examples{
+javaClass <- new.java.class('java.util.ArrayList')
+is.external.array(javaClass)
+}
+\seealso{
+\code{\link{new.java.array}}, \code{\link{as.java.array}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/is.external.executable.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{is.external.executable}
+\alias{is.external.executable}
+\title{Determines whether the passed external object can be executed.}
+\usage{
+is.external.executable(value)
+}
+\arguments{
+\item{value}{an external object}
+}
+\value{
+TRUE in case the given value is executable, otherwise FALSE.
+}
+\description{
+Determines whether the passed external object can be executed.
+}
+\examples{
+javaClass <- new.java.class('java.util.Collections')
+is.external.executable(javaClass$addAll())
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/is.external.null.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{is.external.null}
+\alias{is.external.null}
+\title{Determines whether the given object (external object, or not) represents a Null value.}
+\usage{
+is.external.null(value)
+}
+\arguments{
+\item{value}{an external object}
+}
+\value{
+TRUE in case the given value is Null, otherwise FALSE.
+}
+\description{
+Determines whether the given object (external object, or not) represents a Null value.
+}
+\examples{
+javaClass <- new.java.class('java.util.Collections')
+is.external.null(javaClass)
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/java.addToClasspath.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{java.addToClasspath}
+\alias{java.addToClasspath}
+\title{Adds a class path entry to the class path.}
+\usage{
+java.addToClasspath(value, silent = FALSE)
+}
+\arguments{
+\item{value}{character vector. The class path entry or entries to be added to the FastR interop class path.}
+
+\item{silent}{logical, default FALSE. Determines whether errors should be reported or not.}
+}
+\description{
+Adds a class path entry to the class path.
+}
+\examples{
+java.addClasspathEntry('/foo/bar.jar')
+}
+\seealso{
+\code{\link{new.java.class}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/java.class.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{java.class}
+\alias{java.class}
+\title{Returns the fully qualified class name for the given external object representing a java class.}
+\usage{
+java.class(class)
+}
+\arguments{
+\item{class}{an external object representing a java class.}
+}
+\value{
+fully qualified class name if the given value is an external object representing a java class.
+}
+\description{
+Returns the fully qualified class name for the given external object representing a java class.
+}
+\examples{
+javaClass <- new.java.class('java.util.ArrayList')
+javaObject <- new.external(javaClass)
+java.class(javaObject)
+}
+\seealso{
+\code{\link{new.external}}, \code{\link{new.java.class}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/new.external.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{new.external}
+\alias{new.external}
+\title{Creates a new external object from the given class.}
+\usage{
+new.external(class)
+}
+\arguments{
+\item{class}{an external object representing a class}
+}
+\value{
+An external object created from the given class. Error in case the object could not be created.
+}
+\description{
+Creates a new external object from the given class.
+}
+\examples{
+javaClass <- new.java.class('java.util.ArrayList')
+new.external(javaClass)
+}
+\seealso{
+\code{\link{java.class}}, \code{\link{new.java.class}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/new.java.array.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{new.java.array}
+\alias{new.java.array}
+\title{Creates a new java array given by the class name and length or dimensions.}
+\usage{
+new.java.array(class, dim)
+}
+\arguments{
+\item{class}{a fully qualified class name}
+
+\item{dim}{the array length or dimensions}
+}
+\value{
+An external object representing a java array. Error in case the array could not be created.
+}
+\description{
+Creates a new java array given by the class name and length or dimensions.
+}
+\examples{
+new.java.array('java.lang.Double', 10)
+new.java.array('java.lang.Double', c(2, 3))
+}
+\seealso{
+\code{\link{as.java.array}}, \code{\link{is.external.array}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/fastr/Rd/new.java.class.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fastrInteropt.R
+\name{new.java.class}
+\alias{new.java.class}
+\title{Creates a java class given by the fully qualified java class name. The class must be available on FastR`s interop classpath.}
+\usage{
+new.java.class(class, silent = FALSE)
+}
+\arguments{
+\item{class}{a fully qualified java class name}
+
+\item{silent}{logical, default FALSE. Determines whether errors should be reported or not.}
+}
+\value{
+An external object representing a java class. Otherwise either NULL if silent is set to TRUE, or error in case the class name could not be determined.
+}
+\description{
+Creates a java class given by the fully qualified java class name. The class must be available on FastR`s interop classpath.
+}
+\examples{
+new.java.class('java.util.ArrayList')
+}
+\seealso{
+\code{\link{java.addClasspathEntry}}, \code{\link{new.external}}, \code{\link{java.class}}
+}

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/utils/R/utils_overrides.R

@@ -32,3 +32,74 @@ setBreakpoint <- function (srcfile, line, nameonly = TRUE, envir = parent.frame(
 }
 
 }), asNamespace("utils"))
+
+eval(expression({
+help <- function (topic, package = NULL, lib.loc = NULL, verbose = getOption("verbose"), try.all.packages = getOption("help.try.all.packages"), help_type = getOption("help_type")) {
+    types <- c("text", "html", "pdf")
+    if (!missing(package))
+        if (is.name(y <- substitute(package)))
+            package <- as.character(y)
+    if (missing(topic)) {
+        if (!is.null(package)) {
+            help_type <- if (!length(help_type))
+                "text"
+                else match.arg(tolower(help_type), types)
+            if (interactive() && help_type == "html") {
+                port <- tools::startDynamicHelp(NA)
+                if (port <= 0L)
+                  return(library(help = package, lib.loc = lib.loc, character.only = TRUE))
+                browser <- if (.Platform$GUI == "AQUA") {
+                  get("aqua.browser", envir = as.environment("tools:RGUI"))
+                }
+                else getOption("browser")
+                browseURL(paste0("http://127.0.0.1:", port, "/library/", package, "/html/00Index.html"), browser)
+                return(invisible())
+            }
+            else return(library(help = package, lib.loc = lib.loc, character.only = TRUE))
+        }
+        if (!is.null(lib.loc))
+            return(library(lib.loc = lib.loc))
+        topic <- "help"
+        package <- "utils"
+        lib.loc <- .Library
+    }
+    ischar <- tryCatch(is.character(topic) && length(topic) == 1L, error = identity)
+    if (inherits(ischar, "error"))
+        ischar <- FALSE
+    if (!ischar) {
+        reserved <- c("TRUE", "FALSE", "NULL", "Inf", "NaN", "NA", "NA_integer_", "NA_real_", "NA_complex_", "NA_character_")
+        stopic <- deparse(substitute(topic))
+        if (!is.name(substitute(topic)) && !stopic %in% reserved)
+            stop("'topic' should be a name, length-one character vector or reserved word")
+        topic <- stopic
+    }
+    # Fastr >>>>
+    fastrHelpRd <- .fastr.interop.getHelpRd(topic)
+    if (!is.null(fastrHelpRd)) {
+        fastrHelpRd <- tools::parse_Rd(textConnection(fastrHelpRd))
+        cat("==== R Help on ‘", topic, "’ ====\n", sep = "")
+        return(tools::Rd2txt(fastrHelpRd))
+    }
+    # Fastr <<<<
+    help_type <- if (!length(help_type))
+        "text"
+        else match.arg(tolower(help_type), types)
+    paths <- index.search(topic, find.package(if (is.null(package))
+        loadedNamespaces()
+        else package, lib.loc, verbose = verbose))
+    tried_all_packages <- FALSE
+    if (!length(paths) && is.logical(try.all.packages) && !is.na(try.all.packages) && try.all.packages && is.null(package) && is.null(lib.loc)) {
+        for (lib in .libPaths()) {
+            packages <- .packages(TRUE, lib)
+            packages <- packages[is.na(match(packages, .packages()))]
+            paths <- c(paths, index.search(topic, file.path(lib, packages)))
+        }
+        paths <- paths[nzchar(paths)]
+        tried_all_packages <- TRUE
+    }
+    paths <- unique(paths)
+    attributes(paths) <- list(call = match.call(), topic = topic, tried_all_packages = tried_all_packages, type = help_type)
+    class(paths) <- "help_files_with_topic"
+    paths
+}
+}), asNamespace("utils"))
\ No newline at end of file