github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/parser/equ.md (about)

     1  # `=` (arithmetic evaluation)
     2  
     3  > Evaluate a mathematical function (deprecated)
     4  
     5  ## Description
     6  
     7  `=` evaluates a mathematical function and returns it's output
     8  
     9  **This is a deprecated feature. Please refer to [`expr`](expr.md) instead.**
    10  
    11  ## Usage
    12  
    13  ```
    14  <stdin> -> = evaluation -> <stdout>
    15  
    16  = evaluation -> <stdout>
    17  ```
    18  
    19  ## Examples
    20  
    21  As a method:
    22  
    23  ```
    24  » let age=18
    25  » $age -> = < 21
    26  true
    27  
    28  » $age -> = < 21 -> if { out "Under 21" } else { out "Over 21" }
    29  Under 21
    30  ```
    31  
    32  As a function:
    33  
    34  ```
    35  » let age=18
    36  » = age < 21
    37  true
    38  
    39  » = age < 21 -> if { out "Under 21" } else { out "Over 21" }
    40  Under 21
    41  ```
    42  
    43  Inlining as a function:
    44  
    45  ```
    46  » let age=18
    47  » if { = age < 21 } then { out "Under 21" } else { out "Over 21" }
    48  Under 21
    49  ```
    50  
    51  ## Detail
    52  
    53  ### Variables
    54  
    55  There are two ways you can use variables with the math functions. Either by
    56  string interpolation like you would normally with any other function, or
    57  directly by name.
    58  
    59  String interpolation:
    60  
    61  ```
    62  » set abc=123
    63  » = $abc==123
    64  true
    65  ```
    66  
    67  Directly by name:
    68  
    69  ```
    70  » set abc=123
    71  » = abc==123
    72  false
    73  ```
    74  
    75  To understand the difference between the two, you must first understand how
    76  string interpolation works; which is where the parser tokenised the parameters
    77  like so
    78  
    79  ```
    80  command line: = $abc==123
    81  token 1: command (name: "=")
    82  token 2: parameter 1, string (content: "")
    83  token 3: parameter 1, variable (name: "abc")
    84  token 4: parameter 1, string (content: "==123")
    85  ```
    86  
    87  Then when the command line gets executed, the parameters are compiled on demand
    88  similarly to this crude pseudo-code
    89  
    90  ```
    91  command: "="
    92  parameters 1: concatenate("", GetValue(abc), "==123")
    93  output: "=" "123==123"
    94  ```
    95  
    96  Thus the actual command getting run is literally `123==123` due to the variable
    97  being replace **before** the command executes.
    98  
    99  Whereas when you call the variable by name it's up to `=` or `let` to do the
   100  variable substitution.
   101  
   102  ```
   103  command line: = abc==123
   104  token 1: command (name: "=")
   105  token 2: parameter 1, string (content: "abc==123")
   106  ```
   107  
   108  ```
   109  command: "="
   110  parameters 1: concatenate("abc==123")
   111  output: "=" "abc==123"
   112  ```
   113  
   114  The main advantage (or disadvantage, depending on your perspective) of using
   115  variables this way is that their data-type is preserved.
   116  
   117  ```
   118  » set str abc=123
   119  » = abc==123
   120  false
   121  
   122  » set int abc=123
   123  » = abc==123
   124  true
   125  ```
   126  
   127  Unfortunately is one of the biggest areas in Murex where you'd need to be
   128  careful. The simple addition or omission of the dollar prefix, `$`, can change
   129  the behavior of `=` and `let`.
   130  
   131  ### Strings
   132  
   133  Because the usual Murex tools for encapsulating a string (`"`, `'` and `()`)
   134  are interpreted by the shell language parser, it means we need a new token for
   135  handling strings inside `=` and `let`. This is where backtick comes to our
   136  rescue.
   137  
   138  ```
   139  » set str abc=123
   140  » = abc==`123`
   141  true
   142  ```
   143  
   144  Please be mindful that if you use string interpolation then you will need to
   145  instruct `=` and `let` that your field is a string
   146  
   147  ```
   148  » set str abc=123
   149  » = `$abc`==`123`
   150  true
   151  ```
   152  
   153  ### Best practice recommendation
   154  
   155  As you can see from the sections above, string interpolation offers us some
   156  conveniences when comparing variables of differing data-types, such as a `str`
   157  type with a number (eg `num` or `int`). However it makes for less readable code
   158  when just comparing strings. Thus the recommendation is to avoid using string
   159  interpolation except only where it really makes sense (ie use it sparingly).
   160  
   161  ### Non-boolean logic
   162  
   163  Thus far the examples given have been focused on comparisons however `=` and
   164  `let` supports all the usual arithmetic operators:
   165  
   166  ```
   167  » = 10+10
   168  20
   169  
   170  » = 10/10
   171  1
   172  
   173  » = (4 * (3 + 2))
   174  20
   175  
   176  » = `foo`+`bar`
   177  foobar
   178  ```
   179  
   180  ### Read more
   181  
   182  Murex uses the [govaluate package](https://github.com/Knetic/govaluate). More information can be found in it's manual.
   183  
   184  ## Synonyms
   185  
   186  * `=`
   187  
   188  
   189  ## See Also
   190  
   191  * [Reserved Variables](../user-guide/reserved-vars.md):
   192    Special variables reserved by Murex
   193  * [Variable and Config Scoping](../user-guide/scoping.md):
   194    How scoping works within Murex
   195  * [`%(Brace Quote)`](../parser/brace-quote.md):
   196    Initiates or terminates a string (variables expanded)
   197  * [`[ Index ]`](../parser/item-index.md):
   198    Outputs an element from an array, map or table
   199  * [`[[ Element ]]`](../parser/element.md):
   200    Outputs an element from a nested structure
   201  * [`export`](../commands/export.md):
   202    Define an environmental variable and set it's value
   203  * [`expr`](../commands/expr.md):
   204    Expressions: mathematical, string comparisons, logical operators
   205  * [`global`](../commands/global.md):
   206    Define a global variable and set it's value
   207  * [`global`](../commands/global.md):
   208    Define a global variable and set it's value
   209  * [`if`](../commands/if.md):
   210    Conditional statement to execute different blocks of code depending on the result of the condition
   211  * [`let`](../commands/let.md):
   212    Evaluate a mathematical function and assign to variable (deprecated)
   213  * [`set`](../commands/set.md):
   214    Define a local variable and set it's value
   215  
   216  <hr/>
   217  
   218  This document was generated from [builtins/core/typemgmt/math_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/typemgmt/math_doc.yaml).