More advanced custom function tutorial #1108

sequba · 2022-11-23T09:30:47Z

Context

Updated demo as a PR in demos repo. Works in CodeSandbox (sandbox support for the unit tests works).

Update the custom-functions demo to create a simple function that:
- accepts a string argument
- returns a string
Add another example of a more complex custom function that:
- performs a mathematical operation on numbers
- accepts a range argument
- validates the argument
- returns an array (see export ArraySize from hyperformula #843)
- validates the argument
- is testable (there is an example of a unit test)
And:
- update the custom-functions guide to describe the updated demo
- rename ArgumentTypes interface to FunctionArgumentType and export it for typescript users

How did you test your changes?

Types of changes

Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
New feature or improvement (a non-breaking change that adds functionality)
Bug fix (a non-breaking change that fixes an issue)
Additional language file, or a change to an existing language file (translations)
Change to the documentation

Related issues:

Fixes #779

Checklist:

My change is compliant with the OpenDocument standard.
My change is compatible with Microsoft Excel.
My change is compatible with Google Sheets.
My code follows the code style of this project.
I described my changes in the CHANGELOG.md file.
My changes require a documentation update.
My changes require a migration guide.

github-actions · 2022-11-23T09:32:48Z

Performance comparison of head (`318d094`) vs base (`aa3f7c0`)

                                     testName |  base |  head |  change
-----------------------------------------------------------------------
                                      Sheet A | 458.1 | 462.8 |  +1.03%
                                      Sheet B |   201 | 203.9 |  +1.44%
                                      Sheet T | 242.5 |   243 |  +0.21%
                                Column ranges | 554.2 | 565.1 |  +1.97%
Sheet A:  change value, add/remove row/column |    36 |    32 | -11.11%
 Sheet B: change value, add/remove row/column |   314 |   325 |  +3.50%
                   Column ranges - add column |   212 |   246 | +16.04%
                Column ranges - without batch |   614 |   721 | +17.43%
                        Column ranges - batch |   139 |   154 | +10.79%

…om-functions.spec.ts

src/index.ts

…ew demo (GREET)

warpech

The page is already good, but with large amounts of text it is easy to add a large amount of comments!

src/interpreter/plugin/FunctionPlugin.ts

docs/guide/custom-functions.md

…edoc documentation is generated for it

…sn guide

src/ArrayValue.ts

…tions guide

…ntions guide

warpech

Partial review

docs/guide/custom-functions.md

warpech

Partial review pt. 2

docs/guide/custom-functions.md

warpech · 2022-12-16T12:11:05Z

docs/guide/custom-functions.md

+      state,
+      this.metadata('DOUBLE_RANGE'),
+      (range) => {
+        const resultArray = //...


Is it on purpose that the body of the function is omitted?

Yes, this snippet demonstrates usage of SimpleRangeValue to return an array

But it does not demonstrate that fully, because the body of the function is missing. I think that a snippet is valuable only if it contains working code.

For one, the fully working example added in handsontable/hyperformula-demos#14 uses internalScalarValueToNumber, which is not explained here.

In my opinion it would unnecessarily increase the complexity of the guide. A reader can see the fully working example in the demo section if interested in the details.

warpech

I think that this is the final review from me. I realize that my comments are "yak shaving", but they come from trying to put the guide in practice. My full journey is documented as commits in https://github.com/handsontable/hyperformula-demos/tree/feature/issue-779-recreation-from-guide-in-typescript

Please decide which of these comments must be applied immediately and which can be postponed after the release.

warpech · 2022-12-19T23:21:04Z

docs/guide/custom-functions.md

+
+In a more advanced example, we'll create a custom function `DOUBLE_RANGE` that takes a range of numbers and returns the range of the same size with all the numbers doubled.
+
+### Accept a range argument


I'm lost, because the guide so far presented just one argument type: STRING. Now, it jumps to RANGE, without answering some questions that popped up in my head:

It is not clear, why only STRING and RANGE types are presented in the guide. Are other types (NUMBER, BOOLEAN, SCALAR, NOERROR, INTEGER, COMPLEX, ANY) more like STRING or more like RANGE or yet totally different?

When should I use RANGE type?

I checked the popularity of all argument types in src. Here are the results:

NUMBER - 377

RANGE - 63

STRING- 46

ANY - 33

NOERROR - 30

COMPLEX - 25

INTEGER - 27

BOOLEAN - 22

SCALAR - 21

So all of them are useful for some types of functions. It would be good to write a sentence about each of them, and why is RANGE special among them.

You're right. Elaborating more on various argument types would be helpful to a developer of the custom functions. I'll create a follow-up task to do that.

warpech · 2022-12-19T23:24:33Z

docs/guide/custom-functions.md

+      state,
+      this.metadata('DOUBLE_RANGE'),
+      (range) => {
+        const resultArray = //...


But it does not demonstrate that fully, because the body of the function is missing. I think that a snippet is valuable only if it contains working code.

For one, the fully working example added in handsontable/hyperformula-demos#14 uses internalScalarValueToNumber, which is not explained here.

docs/guide/custom-functions.md

warpech · 2022-12-19T23:41:38Z

docs/guide/custom-functions.md

+      this.metadata('DOUBLE_RANGE'),
+      (range) => {
+        const resultArray = //...
+        return SimpleRangeValue.onlyValues(resultArray);


Some of our built-in functions return SimpleRangeValue.onlyNumbers and SimpleRangeValue.onlyRanges. Might I need them? What's the difference between them and SimpleRangeValue.onlyValues?

It's a valid question. I'll create a follow-up task to elaborate on that.

warpech · 2022-12-19T23:47:35Z

docs/guide/custom-functions.md

+
+### Validate the arguments and return an error
+
+To handle invalid inputs, the custom function should return an instance of the [`CellError` class](../api/classes/cellerror.md) with the relevant [error type](types-of-errors.md).


This sentence contradicts with what was said earlier:

To benefit from HyperFormula's automatic validations, wrap your method in the built-in runFunction() method, which: (...) Validates arguments passed to your function against your argument validation options.

Can you give more details about what do I need to validate that is not done by runFunction?

I'll create a follow-up task to elaborate on that.

docs/guide/custom-functions.md

…rty in the custom functions guide

codecov · 2022-12-20T19:17:37Z

Codecov Report

Merging #1108 (318d094) into develop (aa3f7c0) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop    #1108   +/-   ##
========================================
  Coverage    95.82%   95.82%           
========================================
  Files          162      162           
  Lines        14091    14097    +6     
  Branches      3004     3004           
========================================
+ Hits         13503    13509    +6     
  Misses         588      588

Impacted Files	Coverage Δ
src/Lookup/AdvancedFind.ts	`96.15% <ø> (ø)`
src/Lookup/ColumnBinarySearch.ts	`100.00% <ø> (ø)`
src/Lookup/RowSearchStrategy.ts	`100.00% <ø> (ø)`
src/Lookup/SearchStrategy.ts	`100.00% <ø> (ø)`
src/interpreter/CriterionFunctionCompute.ts	`98.94% <ø> (ø)`
src/interpreter/InterpreterValue.ts	`100.00% <ø> (ø)`
src/ArraySize.ts	`95.41% <100.00%> (ø)`
src/ArrayValue.ts	`81.17% <100.00%> (ø)`
src/Cell.ts	`92.45% <100.00%> (ø)`
src/ContentChanges.ts	`100.00% <100.00%> (ø)`
... and 51 more

Start writing a custom function example for GREET()

2889c31

Export FunctionArgumentType enum

0f4bcdf

sequba mentioned this pull request Nov 23, 2022

Update custom functions demo handsontable/hyperformula-demos#14

Merged

sequba added 2 commits November 23, 2022 12:40

Move custom function tests from square-plugin-example.spec.ts to cust…

7b3c860

…om-functions.spec.ts

Add unit tests for custom functions implemented with runFunction

6d0af2e

sequba linked an issue Nov 24, 2022 that may be closed by this pull request

Docs: add a more advanced custom function tutorial #779

Closed

5 tasks

sequba commented Nov 24, 2022

View reviewed changes

src/index.ts Show resolved Hide resolved

sequba and others added 5 commits November 24, 2022 19:05

WIP

70c1b49

Update the code snippets in the custom functions guide to match the n…

9e67e69

…ew demo (GREET)

Add info about unit tests to the custom functions guide

9e3dbb3

Merge branch 'develop' into feature/issue-779

0f25ddf

Rewrite custom function options section in custom functions guide

82d0e8b

warpech requested changes Dec 7, 2022

View reviewed changes

sequba added 6 commits December 10, 2022 17:27

Export ArraySize class

fbc1ca9

Update custom-functions guide after changes in the demo

60c0ce5

Structural changes in the custom-functions guide

01144a9

Move SimpleRangeValue from ./src/interpreter to ./src so that the typ…

f1615da

…edoc documentation is generated for it

Describe DOUBLE_RANGE function in the custom-functions guide

8d4fca3

Use ArraySize in the example of arraySizeMethod in the custom-functio…

6b5992d

…sn guide

sequba commented Dec 13, 2022

View reviewed changes

src/ArrayValue.ts Show resolved Hide resolved

sequba added 7 commits December 13, 2022 16:38

Add changelog entry

ee375f7

Add the description for the arraySizeMethod option

0ab7465

Rephrase a few sentences in the custom-functions guide

b9c6868

Improve the description of returnNumberType option in the custom-func…

fb5e5aa

…tions guide

Add default values to the custom function options description

befa807

Add possible values to the argumentType description in the custom-fuc…

4f62223

…ntions guide

Reduce content duplication on custom function name translations

ea0f41b

sequba requested a review from warpech December 14, 2022 11:59

Minor improvements to custom-functions guide

682f5d5

sequba and others added 3 commits December 14, 2022 20:01

Merge branch 'develop' into feature/issue-779

3fa9d33

grammarly fixes

bfbb0f0

Reformat table

56fe511

sequba requested a review from adamu-handsontable December 15, 2022 11:20

Improve the description of the vectorization feature

32556e4

warpech requested changes Dec 16, 2022

View reviewed changes

docs/guide/custom-functions.md Outdated Show resolved Hide resolved

docs/guide/custom-functions.md Show resolved Hide resolved

warpech requested changes Dec 16, 2022

View reviewed changes

sequba requested a review from warpech December 16, 2022 14:40

warpech requested changes Dec 20, 2022

View reviewed changes

sequba and others added 5 commits December 20, 2022 16:54

Merge branch 'develop' into feature/issue-779

a6b1e57

code review fixes

aef856b

Change translations object to be standalone instead of a static prope…

f629630

…rty in the custom functions guide

Use FunctionArgumentType enum in custom functions guide

efe66ef

Fix typo

318d094

sequba mentioned this pull request Dec 20, 2022

Custom functions guide improvements #1123

Closed

5 tasks

sequba merged commit 1696cbc into develop Dec 20, 2022

sequba deleted the feature/issue-779 branch December 20, 2022 19:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

More advanced custom function tutorial #1108

More advanced custom function tutorial #1108

sequba commented Nov 23, 2022 •

edited

Loading

github-actions bot commented Nov 23, 2022 •

edited

Loading

warpech left a comment

warpech left a comment

warpech left a comment

warpech Dec 16, 2022

sequba Dec 16, 2022

warpech Dec 19, 2022

sequba Dec 20, 2022

warpech left a comment

warpech Dec 19, 2022

sequba Dec 20, 2022

sequba Dec 20, 2022

warpech Dec 19, 2022

warpech Dec 19, 2022

sequba Dec 20, 2022

sequba Dec 20, 2022

warpech Dec 19, 2022

sequba Dec 20, 2022

sequba Dec 20, 2022

codecov bot commented Dec 20, 2022


		In a more advanced example, we'll create a custom function `DOUBLE_RANGE` that takes a range of numbers and returns the range of the same size with all the numbers doubled.

		### Accept a range argument


		### Validate the arguments and return an error

		To handle invalid inputs, the custom function should return an instance of the [`CellError` class](../api/classes/cellerror.md) with the relevant [error type](types-of-errors.md).

More advanced custom function tutorial #1108

More advanced custom function tutorial #1108

Conversation

sequba commented Nov 23, 2022 • edited Loading

Context

How did you test your changes?

Types of changes

Related issues:

Checklist:

github-actions bot commented Nov 23, 2022 • edited Loading

Performance comparison of head (318d094) vs base (aa3f7c0)

warpech left a comment

Choose a reason for hiding this comment

warpech left a comment

Choose a reason for hiding this comment

warpech left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

warpech left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Dec 20, 2022

Codecov Report

sequba commented Nov 23, 2022 •

edited

Loading

github-actions bot commented Nov 23, 2022 •

edited

Loading

Performance comparison of head (`318d094`) vs base (`aa3f7c0`)