search

OpenRefine / openrefine.org

Source website for openrefine.org
https://openrefine.org
Other
133 stars 119 forks source link

Documentation of GREL operators is lacking #289

Closed jquartel closed 6 months ago

jquartel commented 7 months ago

Although the functionality of operators in GREL is quite intuitive, there is some overloading and special functionality that is not documented in an easy way to find. For example, the overloading of the + operator for string concatenation is only mentioned in the 'Basics' section, while the != (not equal to) operator is not mentioned at all. The special behaviour of the / operator for ints is nicely mentioned at the top of the Math functions section, but the % (integer modulus) operator gets no mention (though it does work - I use it a lot!). It would be great if there were either a separate section on operators, or else that all operators are described in each object type section i.e. at the top of each of 'String functions', and 'Math Functions' (there are no overloaded operators for array types, sadly, so no need for a mention in that section). I'm not aware of any operators that work for Date objects (presumably == and != work, but it might be logical to assume the relational operators like < and > work for these and someone might look to the documentation to find out.

aayushk9 commented 7 months ago

Hello @jquartel I've noticed the gaps in GREL operators documentation. I'm happy to work on improving it. Will focus on adding missing details for operators in relevant sections. Thanks for opening the issue

aayushk9 commented 7 months ago

@jquartel Should we include only the operators mentioned earlier or entire list of operators present in GREL?

jquartel commented 7 months ago

I don't think there are (currently) very many are there?

ostephens commented 7 months ago

I think we should document all the available operators

aayushk9 commented 7 months ago

I agree that including the entire list would be helpful for users to have a complete reference. I will raise a pull request soon.

tfmorris commented 7 months ago

Note that there is a pending PR which changes the behavior of some operators. https://github.com/OpenRefine/OpenRefine/pull/6342

aayushk9 commented 7 months ago

Got it! Will include changes from the PR.

aayushk9 commented 7 months ago

Are there any operators in GREL beyond arithmetic, relational, logical, string manipulation, list operations and type conversion operators?

deckerrj commented 7 months ago

The only other odd item I know of is that PI is a literal in GREL, which means the PI binding is half-useless since the parser will compile out any instance of the string literal PI into the number literal using Math.PI.

ostephens commented 7 months ago

@aayushk9 Some of the operators you mention are already documented I believe. We should avoid duplicating text if possible - so if you are listing operators that are already documented please just link to the existing documentation. (although when I said "all operators" I wasn't thinking of logical, list operations and type conversion which I believe are all already documented)

aayushk9 commented 7 months ago

@ostephens Sure, I'll link the mentioned operators to existing docs and add the missing ones. Thanks for the feedback!

aayushk9 commented 7 months ago

I have made the necessary changes, but what should I do about the modifications mentioned in this PR OpenRefine/OpenRefine#6342 as it has not been merged yet?

aayushk9 commented 7 months ago

@ostephens @jquartel I have raised a PR . Do let me know if I have to make any changes!