More advanced custom function tutorial

docs/guide/custom-functions.md

@@ -7,7 +7,7 @@ Expand the function library of your application, by adding custom functions.
 
 ## Add a custom function
 
-As an example, let's create a function that returns the number of letters in the word "HyperFormula".
+As an example, let's create a function that accepts a username as a string argument and returns a personalized greeting. 
 
 <iframe
   src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.2.x/custom-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"

src/ArraySize.ts

@@ -8,7 +8,7 @@ import {SimpleCellAddress} from './Cell'
 import {Config} from './Config'
 import {FunctionRegistry} from './interpreter/FunctionRegistry'
 import {InterpreterState} from './interpreter/InterpreterState'
-import {ArgumentTypes} from './interpreter/plugin/FunctionPlugin'
+import {FunctionArgumentType} from './interpreter/plugin/FunctionPlugin'
 import {Ast, AstNodeType, ProcedureAst} from './parser'
 
 export class ArraySize {
@@ -156,7 +156,7 @@ export class ArraySizePredictor {
     let maxWidth = 1
     let maxHeight = 1
     for (let i = 0; i < subChecks.length; i++) {
-      if (argumentDefinitions[i].argumentType !== ArgumentTypes.RANGE && argumentDefinitions[i].argumentType !== ArgumentTypes.ANY) {
+      if (argumentDefinitions[i].argumentType !== FunctionArgumentType.RANGE && argumentDefinitions[i].argumentType !== FunctionArgumentType.ANY) {
         maxHeight = Math.max(maxHeight, subChecks[i].height)
         maxWidth = Math.max(maxWidth, subChecks[i].width)
       }

src/index.ts

@@ -47,15 +47,17 @@ import {ExportedCellChange, ExportedChange, ExportedNamedExpressionChange} from
 import {HyperFormula} from './HyperFormula'
 import {RawTranslationPackage} from './i18n'
 import enGB from './i18n/languages/enGB'
-import {FunctionArgument, FunctionPlugin, FunctionPluginDefinition} from './interpreter'
+import {FunctionArgument, FunctionPlugin, FunctionPluginDefinition, FunctionArgumentType} from './interpreter'
 import {FormatInfo} from './interpreter/InterpreterValue'
 import * as plugins from './interpreter/plugin'
 import {SimpleRangeValue} from './interpreter/SimpleRangeValue'
 import {NamedExpression, NamedExpressionOptions} from './NamedExpressions'
 import {SerializedNamedExpression} from './Serialization'
 import {Sheet, SheetDimensions, Sheets} from './Sheet'
 
-/** @internal */
+/**
+ * Aggregate class for default export
+ */
 class HyperFormulaNS extends HyperFormula {
   public static HyperFormula = HyperFormula
   public static ErrorType = ErrorType
@@ -71,6 +73,7 @@ class HyperFormulaNS extends HyperFormula {
   public static ExpectedOneOfValuesError = ExpectedOneOfValuesError
   public static ExpectedValueOfTypeError = ExpectedValueOfTypeError
   public static FunctionPlugin = FunctionPlugin
+  public static FunctionArgumentType = FunctionArgumentType
   public static FunctionPluginValidationError = FunctionPluginValidationError
   public static InvalidAddressError = InvalidAddressError
   public static InvalidArgumentsError = InvalidArgumentsError
@@ -146,6 +149,7 @@ export {
   ExpectedOneOfValuesError,
   ExpectedValueOfTypeError,
   FunctionPlugin,
+  FunctionArgumentType,
   FunctionPluginValidationError,
   InvalidAddressError,
   InvalidArgumentsError,

src/interpreter/index.ts

@@ -9,7 +9,8 @@ import {
   FunctionMetadata,
   FunctionPlugin,
   FunctionPluginDefinition,
-  ImplementedFunctions
+  ImplementedFunctions,
+  FunctionArgumentType,
 } from './plugin/FunctionPlugin'
 
 export {
@@ -18,5 +19,6 @@ export {
   FunctionPlugin,
   ImplementedFunctions,
   FunctionMetadata,
-  FunctionTranslationsPackage
+  FunctionTranslationsPackage,
+  FunctionArgumentType,
 }

src/interpreter/plugin/AbsPlugin.ts

@@ -6,14 +6,14 @@
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 export class AbsPlugin extends FunctionPlugin implements FunctionPluginTypecheck<AbsPlugin> {
   public static implementedFunctions = {
     'ABS': {
       method: 'abs',
       parameters: [
-        {argumentType: ArgumentTypes.NUMBER}
+        {argumentType: FunctionArgumentType.NUMBER}
       ]
     },
   }

src/interpreter/plugin/ArrayPlugin.ts

@@ -11,7 +11,7 @@ import {coerceScalarToBoolean} from '../ArithmeticHelper'
 import {InterpreterState} from '../InterpreterState'
 import {InternalScalarValue, InterpreterValue} from '../InterpreterValue'
 import {SimpleRangeValue} from '../SimpleRangeValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 export class ArrayPlugin extends FunctionPlugin implements FunctionPluginTypecheck<ArrayPlugin> {
   public static implementedFunctions = {
@@ -20,16 +20,16 @@ export class ArrayPlugin extends FunctionPlugin implements FunctionPluginTypeche
       arraySizeMethod: 'arrayformulaArraySize',
       arrayFunction: true,
       parameters: [
-        {argumentType: ArgumentTypes.ANY}
+        {argumentType: FunctionArgumentType.ANY}
       ],
     },
     'ARRAY_CONSTRAIN': {
       method: 'arrayconstrain',
       arraySizeMethod: 'arrayconstrainArraySize',
       parameters: [
-        {argumentType: ArgumentTypes.RANGE},
-        {argumentType: ArgumentTypes.INTEGER, minValue: 1},
-        {argumentType: ArgumentTypes.INTEGER, minValue: 1},
+        {argumentType: FunctionArgumentType.RANGE},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 1},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 1},
       ],
       vectorizationForbidden: true,
     },
@@ -38,8 +38,8 @@ export class ArrayPlugin extends FunctionPlugin implements FunctionPluginTypeche
       arraySizeMethod: 'filterArraySize',
       arrayFunction: true,
       parameters: [
-        {argumentType: ArgumentTypes.RANGE},
-        {argumentType: ArgumentTypes.RANGE},
+        {argumentType: FunctionArgumentType.RANGE},
+        {argumentType: FunctionArgumentType.RANGE},
       ],
       repeatLastArgs: 1,
     }

src/interpreter/plugin/BitShiftPlugin.ts

@@ -8,7 +8,7 @@ import {ErrorMessage} from '../../error-message'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 const MAX_48BIT_INTEGER = 281474976710655
 const SHIFT_MIN_POSITIONS = -53
@@ -19,15 +19,15 @@ export class BitShiftPlugin extends FunctionPlugin implements FunctionPluginType
     'BITLSHIFT': {
       method: 'bitlshift',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
-        {argumentType: ArgumentTypes.INTEGER, minValue: SHIFT_MIN_POSITIONS, maxValue: SHIFT_MAX_POSITIONS},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: SHIFT_MIN_POSITIONS, maxValue: SHIFT_MAX_POSITIONS},
       ]
     },
     'BITRSHIFT': {
       method: 'bitrshift',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
-        {argumentType: ArgumentTypes.INTEGER, minValue: SHIFT_MIN_POSITIONS, maxValue: SHIFT_MAX_POSITIONS},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: SHIFT_MIN_POSITIONS, maxValue: SHIFT_MAX_POSITIONS},
       ]
     },
   }

src/interpreter/plugin/BitwiseLogicOperationsPlugin.ts

@@ -6,29 +6,29 @@
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 export class BitwiseLogicOperationsPlugin extends FunctionPlugin implements FunctionPluginTypecheck<BitwiseLogicOperationsPlugin> {
   public static implementedFunctions = {
     'BITAND': {
       method: 'bitand',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
       ]
     },
     'BITOR': {
       method: 'bitor',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
       ]
     },
     'BITXOR': {
       method: 'bitxor',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
-        {argumentType: ArgumentTypes.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 0},
       ]
     },
   }

src/interpreter/plugin/BooleanPlugin.ts

@@ -8,7 +8,7 @@ import {ErrorMessage} from '../../error-message'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InternalNoErrorScalarValue, InternalScalarValue, InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 /**
  * Interpreter plugin containing boolean functions
@@ -26,69 +26,69 @@ export class BooleanPlugin extends FunctionPlugin implements FunctionPluginTypec
     'IF': {
       method: 'conditionalIf',
       parameters: [
-        {argumentType: ArgumentTypes.BOOLEAN},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
-        {argumentType: ArgumentTypes.SCALAR, defaultValue: false, passSubtype: true},
+        {argumentType: FunctionArgumentType.BOOLEAN},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, defaultValue: false, passSubtype: true},
       ],
     },
     'AND': {
       method: 'and',
       parameters: [
-        {argumentType: ArgumentTypes.BOOLEAN},
+        {argumentType: FunctionArgumentType.BOOLEAN},
       ],
       repeatLastArgs: 1,
       expandRanges: true,
     },
     'OR': {
       method: 'or',
       parameters: [
-        {argumentType: ArgumentTypes.BOOLEAN},
+        {argumentType: FunctionArgumentType.BOOLEAN},
       ],
       repeatLastArgs: 1,
       expandRanges: true,
     },
     'XOR': {
       method: 'xor',
       parameters: [
-        {argumentType: ArgumentTypes.BOOLEAN},
+        {argumentType: FunctionArgumentType.BOOLEAN},
       ],
       repeatLastArgs: 1,
       expandRanges: true,
     },
     'NOT': {
       method: 'not',
       parameters: [
-        {argumentType: ArgumentTypes.BOOLEAN},
+        {argumentType: FunctionArgumentType.BOOLEAN},
       ]
     },
     'SWITCH': {
       method: 'switch',
       parameters: [
-        {argumentType: ArgumentTypes.NOERROR},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.NOERROR},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
       ],
       repeatLastArgs: 1,
     },
     'IFERROR': {
       method: 'iferror',
       parameters: [
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
       ]
     },
     'IFNA': {
       method: 'ifna',
       parameters: [
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
       ]
     },
     'CHOOSE': {
       method: 'choose',
       parameters: [
-        {argumentType: ArgumentTypes.INTEGER, minValue: 1},
-        {argumentType: ArgumentTypes.SCALAR, passSubtype: true},
+        {argumentType: FunctionArgumentType.INTEGER, minValue: 1},
+        {argumentType: FunctionArgumentType.SCALAR, passSubtype: true},
       ],
       repeatLastArgs: 1,
     },

src/interpreter/plugin/CharPlugin.ts

@@ -8,20 +8,20 @@ import {ErrorMessage} from '../../error-message'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 export class CharPlugin extends FunctionPlugin implements FunctionPluginTypecheck<CharPlugin> {
   public static implementedFunctions = {
     'CHAR': {
       method: 'char',
       parameters: [
-        {argumentType: ArgumentTypes.NUMBER}
+        {argumentType: FunctionArgumentType.NUMBER}
       ],
     },
     'UNICHAR': {
       method: 'unichar',
       parameters: [
-        {argumentType: ArgumentTypes.NUMBER}
+        {argumentType: FunctionArgumentType.NUMBER}
       ],
     },
   }

src/interpreter/plugin/CodePlugin.ts

@@ -8,20 +8,20 @@ import {ErrorMessage} from '../../error-message'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
 import {InterpreterValue} from '../InterpreterValue'
-import {ArgumentTypes, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
+import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck} from './FunctionPlugin'
 
 export class CodePlugin extends FunctionPlugin implements FunctionPluginTypecheck<CodePlugin> {
   public static implementedFunctions = {
     'CODE': {
       method: 'code',
       parameters: [
-        {argumentType: ArgumentTypes.STRING}
+        {argumentType: FunctionArgumentType.STRING}
       ]
     },
     'UNICODE': {
       method: 'unicode',
       parameters: [
-        {argumentType: ArgumentTypes.STRING}
+        {argumentType: FunctionArgumentType.STRING}
       ]
     },
   }