core/org.eclipse.statet.rj.services.core/src/org/eclipse/statet/rj/services/FunctionCall.java - statet/org.eclipse.statet-rj - Git at Google

 /*=============================================================================#
  # Copyright (c) 2009, 2018 Stephan Wahlbrink and others.
  #
  # This program and the accompanying materials are made available under the
  # terms of the Eclipse Public License 2.0 which is available at
  # https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
  # which is available at https://www.apache.org/licenses/LICENSE-2.0.
  #
  # SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  #
  # Contributors:
  #     Stephan Wahlbrink <sw@wahlbrink.eu> - initial API and implementation
  #=============================================================================*/

 package org.eclipse.statet.rj.services;

 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IProgressMonitor;

 import org.eclipse.statet.jcommons.lang.NonNullByDefault;
 import org.eclipse.statet.jcommons.lang.Nullable;

 import org.eclipse.statet.rj.data.RObject;
 import org.eclipse.statet.rj.data.RStore;


 /**
  * A function call provides a comfortable way to build and execute
  * R function call.
  *
  * <p>A function call builder for a given function can be created by
  * {@link RService#createFunctionCall(String)}.</p>
  *
  * <p>The builder mainly provides methods to add arguments and to
  * finally evaluate the resulting function call in R.</p>
  *
  * <p>Arguments are added by the <code>#add...()</code> methods. The
  * order they are added is exactly the order they are send to R. There
  * are add methods for a symbol referring to data existing in R,
  * for given R data objects and for single data values which are
  * transformed automatically from java primitives into R data objects.
  * All methods are available in a variant with and without a parameter
  * for the R argument name. An unnamed argument can be specified by
  * using the variant without the argument name parameter or by specifying
  * the name as <code>null</code>.</p>
  *
  * <p>The common guidelines in {@link RService} (like concurrency) are effective
  * for all evaluation methods in this interface.</p>
  */
 @NonNullByDefault
 public interface FunctionCall {


 	/**
 	 * Adds an argument with the given R expression as value.
 	 *
 	 * <p>The expression is parsed and lazily evaluated as known from function calls in R source
 	 * code.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param expression a single valid expression
 	 * @return a reference to this object
 	 *
 	 * @see #addChar(String, String) to add a string/character value directly
 	 */
 	FunctionCall add(@Nullable String arg, String expression);

 	/**
 	 * Adds a unnamed argument with the given R expression as value.
 	 *
 	 * <p>The expression is parsed and lazily evaluated as known from function calls in R source
 	 * code.</p>
 	 *
 	 * @param expression a single valid expression
 	 * @return a reference to this object
 	 *
 	 * @see #addChar(String) to add a string/character value directly
 	 */
 	FunctionCall add(String expression);

 	/**
 	 * Adds a argument with the given R data object as value.
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param data an R data object
 	 * @return a reference to this object
 	 */
 	FunctionCall add(@Nullable String arg, RObject data);

 	/**
 	 * Adds an unnamed argument with the given R data object as value.
 	 *
 	 * @param arg the name of the argument
 	 * @param data an R data object
 	 * @return a reference to this object
 	 */
 	FunctionCall add(RObject data);


 	/**
 	 * Adds an argument with the given boolean/logical as value.
 	 *
 	 * <p>The Java boolean value is transformed into an R data object
 	 * of type {@link RStore#LOGICAL logical}.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param logical the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addLogi(@Nullable String arg, boolean logical);

 	/**
 	 * Adds an unnamed argument with the given boolean/logical as value.
 	 *
 	 * <p>The Java boolean value is transformed into an R data object
 	 * of type {@link RStore#LOGICAL logical}.</p>
 	 *
 	 * @param logical the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addLogi(boolean logical);

 	/**
 	 * Adds an argument with the given integer as value.
 	 *
 	 * <p>The Java integer value is transformed into an R data object
 	 * of type {@link RStore#INTEGER integer}.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param integer the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addInt(@Nullable String arg, int integer);

 	/**
 	 * Adds an unnamed argument with the given integer as value.
 	 *
 	 * <p>The Java integer value is transformed into an R data object
 	 * of type {@link RStore#INTEGER integer}.</p>
 	 *
 	 * @param integer the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addInt(int integer);

 	/**
 	 * Adds an argument with the given double/numeric as value.
 	 *
 	 * <p>The Java double value is transformed into an R data object
 	 * of type {@link RStore#NUMERIC numeric}, also called real.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param numeric the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addNum(@Nullable String arg, double numeric);

 	/**
 	 * Adds an unnamed argument with the given double/numeric as value.
 	 *
 	 * <p>The Java double value is transformed into an R data object
 	 * of type {@link RStore#NUMERIC numeric}, also called real.</p>
 	 *
 	 * @param arg the name of the argument
 	 * @param numeric the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addNum(double numeric);

 	/**
 	 * Adds an argument with the given string/character as value.
 	 *
 	 * <p>The Java String value is transformed into an R data object
 	 * of type {@link RStore#CHARACTER character}.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param character the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addCplx(@Nullable String arg, double real, double imaginary);

 	/**
 	 * Adds an unnamed argument with the given string/character as value.
 	 *
 	 * <p>The Java String value is transformed into an R data object
 	 * of type {@link RStore#CHARACTER character}.</p>
 	 *
 	 * @param character the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addCplx(double real, double imaginary);

 	/**
 	 * Adds an argument with the given string/character as value.
 	 *
 	 * <p>The Java String value is transformed into an R data object
 	 * of type {@link RStore#CHARACTER character}.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @param character the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addChar(@Nullable String arg, String character);

 	/**
 	 * Adds an unnamed argument with the given string/character as value.
 	 *
 	 * <p>The Java String value is transformed into an R data object
 	 * of type {@link RStore#CHARACTER character}.</p>
 	 *
 	 * @param character the value of the argument
 	 * @return a reference to this object
 	 */
 	FunctionCall addChar(String character);

 	/**
 	 * Adds an argument with the given NULL as value.
 	 *
 	 * <p>The Java String value is transformed into an R data
 	 * {@link RObject#NULL NULL} object.</p>
 	 *
 	 * @param arg the name of the argument or <code>null</code> for unnamed
 	 * @return a reference to this object
 	 */
 	FunctionCall addNull(@Nullable String arg);

 	/**
 	 * Adds an unnamed argument with the given NULL as value.
 	 *
 	 * <p>The Java String value is transformed into an R data
 	 * {@link RObject#NULL NULL} object.</p>
 	 *
 	 * @return a reference to this object
 	 */
 	FunctionCall addNull();


 	/**
 	 * Performs the evaluation of this function call in R without returning a value.
 	 * The method returns after the evaluation is finished.
 	 *
 	 * <p>The evaluation is performed in the global environment of R.</p>
 	 *
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback.
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 */
 	void evalVoid(IProgressMonitor monitor) throws CoreException;

 	/**
 	 * Performs the evaluation of this function call in R without returning a value.
 	 * The method returns after the evaluation is finished.
 	 *
 	 * <p>This method allows advanced configuration for the evaluation.</p>
 	 *
 	 * @param envir the environment where to perform the evaluation; specified by an reference
 	 *     or language object, or <code>null</code> for the global environment
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback.
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 *
 	 * @since de.walware.rj.services 2.1
 	 */
 	void evalVoid(@Nullable RObject envir,
 			IProgressMonitor monitor) throws CoreException;

 	/**
 	 * Performs the evaluation of the this function call in R and returns its value as R data object.
 	 * The method returns after the evaluation is finished.
 	 *
 	 * <p>This is a short version of {@link #evalData(String, int, int, IProgressMonitor)}
 	 * sufficient for most purpose. The returned R data objects are created by the default factory
 	 * with no limit in the object tree depth.</p>
 	 *
 	 * <p>The evaluation is performed in the global environment of R.</p>
 	 *
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback
 	 * @return the evaluated value as R data object
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 */
 	RObject evalData(IProgressMonitor monitor) throws CoreException;

 	/**
 	 * Performs the evaluation of the this function call in R and returns its value as R data object.
 	 * The method returns after the evaluation is finished.
 	 *
 	 * <p>This method allows advanced configuration for the returned R data object.</p>
 	 *
 	 * <p>The evaluation is performed in the global environment of R.</p>
 	 *
 	 * @param factoryId the id of the factory to use when creating the RObject in this VM.
 	 * @param options 0
 	 * @param depth object tree depth for the created return value
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback
 	 * @return the evaluated value as R data object
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 */
 	RObject evalData(@Nullable String factoryId, int options, int depth,
 			IProgressMonitor monitor) throws CoreException;

 	/**
 	 * Performs the evaluation of the this function call in R and returns its value as R data object.
 	 * The method returns after the evaluation is finished.
 	 *
 	 * <p>This method allows advanced configuration for the evaluation and the returned R data
 	 * object.</p>
 	 *
 	 * @param envir the environment where to perform the evaluation; specified by an reference
 	 *     or language object, or <code>null</code> for the global environment
 	 * @param factoryId the id of the factory to use when creating the RObject in this VM.
 	 * @param options 0
 	 * @param depth object tree depth for the created return value
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback
 	 * @return the evaluated value as R data object
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 *
 	 * @since de.walware.rj.services 2.1
 	 */
 	RObject evalData(@Nullable RObject envir,
 			@Nullable String factoryId, int options, int depth,
 			IProgressMonitor monitor) throws CoreException;

 	/**
 	 * Performs the evaluation of the this function call in R and assign its return value to
 	 * the specified expression.
 	 *
 	 * <p>The target have to be a valid target expression for a R <code>&lt;-</code> assignment
 	 * operation.  A single symbol like <code>x</code> or <code>`x-y`</code>, a path in an object
 	 * tree like <code>xlist$item1</code> or <code>xobj@slotName</code> is valid as well as
 	 * special function calls which supports assignments like <code>dim(x)</code>.</p>
 	 *
 	 * <p>The evaluation and assignment is performed in the global environment of R.</p>
 	 *
 	 * @param target a single valid expression to assign the result to
 	 * @param monitor a progress monitor to catch cancellation and provide progress feedback
 	 * @throws CoreException if the operation was canceled or failed; the status
 	 *     of the exception contains detail about the cause
 	 *
 	 * @since de.walware.rj.services 2.0
 	 */
 	void evalAssign(String target,
 			IProgressMonitor monitor) throws CoreException;

 }
	/*=============================================================================#
	# Copyright (c) 2009, 2018 Stephan Wahlbrink and others.
	#
	# This program and the accompanying materials are made available under the
	# terms of the Eclipse Public License 2.0 which is available at
	# https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
	# which is available at https://www.apache.org/licenses/LICENSE-2.0.
	#
	# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
	#
	# Contributors:
	# Stephan Wahlbrink <sw@wahlbrink.eu> - initial API and implementation
	#=============================================================================*/

	package org.eclipse.statet.rj.services;

	import org.eclipse.core.runtime.CoreException;
	import org.eclipse.core.runtime.IProgressMonitor;

	import org.eclipse.statet.jcommons.lang.NonNullByDefault;
	import org.eclipse.statet.jcommons.lang.Nullable;

	import org.eclipse.statet.rj.data.RObject;
	import org.eclipse.statet.rj.data.RStore;


	/**
	* A function call provides a comfortable way to build and execute
	* R function call.
	*
	* <p>A function call builder for a given function can be created by
	* {@link RService#createFunctionCall(String)}.</p>
	*
	* <p>The builder mainly provides methods to add arguments and to
	* finally evaluate the resulting function call in R.</p>
	*
	* <p>Arguments are added by the <code>#add...()</code> methods. The
	* order they are added is exactly the order they are send to R. There
	* are add methods for a symbol referring to data existing in R,
	* for given R data objects and for single data values which are
	* transformed automatically from java primitives into R data objects.
	* All methods are available in a variant with and without a parameter
	* for the R argument name. An unnamed argument can be specified by
	* using the variant without the argument name parameter or by specifying
	* the name as <code>null</code>.</p>
	*
	* <p>The common guidelines in {@link RService} (like concurrency) are effective
	* for all evaluation methods in this interface.</p>
	*/
	@NonNullByDefault
	public interface FunctionCall {


	/**
	* Adds an argument with the given R expression as value.
	*
	* <p>The expression is parsed and lazily evaluated as known from function calls in R source
	* code.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param expression a single valid expression
	* @return a reference to this object
	*
	* @see #addChar(String, String) to add a string/character value directly
	*/
	FunctionCall add(@Nullable String arg, String expression);

	/**
	* Adds a unnamed argument with the given R expression as value.
	*
	* <p>The expression is parsed and lazily evaluated as known from function calls in R source
	* code.</p>
	*
	* @param expression a single valid expression
	* @return a reference to this object
	*
	* @see #addChar(String) to add a string/character value directly
	*/
	FunctionCall add(String expression);

	/**
	* Adds a argument with the given R data object as value.
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param data an R data object
	* @return a reference to this object
	*/
	FunctionCall add(@Nullable String arg, RObject data);

	/**
	* Adds an unnamed argument with the given R data object as value.
	*
	* @param arg the name of the argument
	* @param data an R data object
	* @return a reference to this object
	*/
	FunctionCall add(RObject data);


	/**
	* Adds an argument with the given boolean/logical as value.
	*
	* <p>The Java boolean value is transformed into an R data object
	* of type {@link RStore#LOGICAL logical}.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param logical the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addLogi(@Nullable String arg, boolean logical);

	/**
	* Adds an unnamed argument with the given boolean/logical as value.
	*
	* <p>The Java boolean value is transformed into an R data object
	* of type {@link RStore#LOGICAL logical}.</p>
	*
	* @param logical the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addLogi(boolean logical);

	/**
	* Adds an argument with the given integer as value.
	*
	* <p>The Java integer value is transformed into an R data object
	* of type {@link RStore#INTEGER integer}.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param integer the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addInt(@Nullable String arg, int integer);

	/**
	* Adds an unnamed argument with the given integer as value.
	*
	* <p>The Java integer value is transformed into an R data object
	* of type {@link RStore#INTEGER integer}.</p>
	*
	* @param integer the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addInt(int integer);

	/**
	* Adds an argument with the given double/numeric as value.
	*
	* <p>The Java double value is transformed into an R data object
	* of type {@link RStore#NUMERIC numeric}, also called real.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param numeric the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addNum(@Nullable String arg, double numeric);

	/**
	* Adds an unnamed argument with the given double/numeric as value.
	*
	* <p>The Java double value is transformed into an R data object
	* of type {@link RStore#NUMERIC numeric}, also called real.</p>
	*
	* @param arg the name of the argument
	* @param numeric the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addNum(double numeric);

	/**
	* Adds an argument with the given string/character as value.
	*
	* <p>The Java String value is transformed into an R data object
	* of type {@link RStore#CHARACTER character}.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param character the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addCplx(@Nullable String arg, double real, double imaginary);

	/**
	* Adds an unnamed argument with the given string/character as value.
	*
	* <p>The Java String value is transformed into an R data object
	* of type {@link RStore#CHARACTER character}.</p>
	*
	* @param character the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addCplx(double real, double imaginary);

	/**
	* Adds an argument with the given string/character as value.
	*
	* <p>The Java String value is transformed into an R data object
	* of type {@link RStore#CHARACTER character}.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @param character the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addChar(@Nullable String arg, String character);

	/**
	* Adds an unnamed argument with the given string/character as value.
	*
	* <p>The Java String value is transformed into an R data object
	* of type {@link RStore#CHARACTER character}.</p>
	*
	* @param character the value of the argument
	* @return a reference to this object
	*/
	FunctionCall addChar(String character);

	/**
	* Adds an argument with the given NULL as value.
	*
	* <p>The Java String value is transformed into an R data
	* {@link RObject#NULL NULL} object.</p>
	*
	* @param arg the name of the argument or <code>null</code> for unnamed
	* @return a reference to this object
	*/
	FunctionCall addNull(@Nullable String arg);

	/**
	* Adds an unnamed argument with the given NULL as value.
	*
	* <p>The Java String value is transformed into an R data
	* {@link RObject#NULL NULL} object.</p>
	*
	* @return a reference to this object
	*/
	FunctionCall addNull();


	/**
	* Performs the evaluation of this function call in R without returning a value.
	* The method returns after the evaluation is finished.
	*
	* <p>The evaluation is performed in the global environment of R.</p>
	*
	* @param monitor a progress monitor to catch cancellation and provide progress feedback.
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*/
	void evalVoid(IProgressMonitor monitor) throws CoreException;

	/**
	* Performs the evaluation of this function call in R without returning a value.
	* The method returns after the evaluation is finished.
	*
	* <p>This method allows advanced configuration for the evaluation.</p>
	*
	* @param envir the environment where to perform the evaluation; specified by an reference
	* or language object, or <code>null</code> for the global environment
	* @param monitor a progress monitor to catch cancellation and provide progress feedback.
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*
	* @since de.walware.rj.services 2.1
	*/
	void evalVoid(@Nullable RObject envir,
	IProgressMonitor monitor) throws CoreException;

	/**
	* Performs the evaluation of the this function call in R and returns its value as R data object.
	* The method returns after the evaluation is finished.
	*
	* <p>This is a short version of {@link #evalData(String, int, int, IProgressMonitor)}
	* sufficient for most purpose. The returned R data objects are created by the default factory
	* with no limit in the object tree depth.</p>
	*
	* <p>The evaluation is performed in the global environment of R.</p>
	*
	* @param monitor a progress monitor to catch cancellation and provide progress feedback
	* @return the evaluated value as R data object
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*/
	RObject evalData(IProgressMonitor monitor) throws CoreException;

	/**
	* Performs the evaluation of the this function call in R and returns its value as R data object.
	* The method returns after the evaluation is finished.
	*
	* <p>This method allows advanced configuration for the returned R data object.</p>
	*
	* <p>The evaluation is performed in the global environment of R.</p>
	*
	* @param factoryId the id of the factory to use when creating the RObject in this VM.
	* @param options 0
	* @param depth object tree depth for the created return value
	* @param monitor a progress monitor to catch cancellation and provide progress feedback
	* @return the evaluated value as R data object
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*/
	RObject evalData(@Nullable String factoryId, int options, int depth,
	IProgressMonitor monitor) throws CoreException;

	/**
	* Performs the evaluation of the this function call in R and returns its value as R data object.
	* The method returns after the evaluation is finished.
	*
	* <p>This method allows advanced configuration for the evaluation and the returned R data
	* object.</p>
	*
	* @param envir the environment where to perform the evaluation; specified by an reference
	* or language object, or <code>null</code> for the global environment
	* @param factoryId the id of the factory to use when creating the RObject in this VM.
	* @param options 0
	* @param depth object tree depth for the created return value
	* @param monitor a progress monitor to catch cancellation and provide progress feedback
	* @return the evaluated value as R data object
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*
	* @since de.walware.rj.services 2.1
	*/
	RObject evalData(@Nullable RObject envir,
	@Nullable String factoryId, int options, int depth,
	IProgressMonitor monitor) throws CoreException;

	/**
	* Performs the evaluation of the this function call in R and assign its return value to
	* the specified expression.
	*
	* <p>The target have to be a valid target expression for a R <code><-</code> assignment
	* operation. A single symbol like <code>x</code> or <code>`x-y`</code>, a path in an object
	* tree like <code>xlist$item1</code> or <code>xobj@slotName</code> is valid as well as
	* special function calls which supports assignments like <code>dim(x)</code>.</p>
	*
	* <p>The evaluation and assignment is performed in the global environment of R.</p>
	*
	* @param target a single valid expression to assign the result to
	* @param monitor a progress monitor to catch cancellation and provide progress feedback
	* @throws CoreException if the operation was canceled or failed; the status
	* of the exception contains detail about the cause
	*
	* @since de.walware.rj.services 2.0
	*/
	void evalAssign(String target,
	IProgressMonitor monitor) throws CoreException;

	}