# Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

Convert symbols in an expression into formal symbols

Contributed by:
Paco Jain (Wolfram Research)

ResourceFunction["FormalizeSymbols"][ converts all symbols in | |

ResourceFunction["FormalizeSymbols"][ returns the rules that would be used for replacement in ResourceFunction["FormalizeSymbols"][ |

Formal symbols like a are standard Wolfram Language symbols that can not be assigned values. Using formal symbols prevents symbolic expression from unintentionally using values from the local environment.

Symbols are replaced with their formal counterparts when possible (and when doing so will not cause collisions between different symbols). If no formal counterpart exists, the symbol is not replaced unless the option setting "ExtraReplacements"→True is used. In that case, a random formal symbol not already used will be chosen as the replacement symbol.

ResourceFunction["FormalizeSymbols"] accepts the following options:

"EvaluateOnce" | False | whether to allow symbols with OwnValues to evaluate exactly once |

"ExcludeInputSymbols | {} | a list of symbols to exclude from the left-hand side of replacement rules |

"ExcludeTargetSymbols" | {} | a list of symbols to exclude from the right-hand side of replacement rules |

"ExtraReplacements" | False | whether to replace symbols that lack a direct formal counterpart |

"ReplacementContexts" | Automatic | a list of contexts whose symbols are to be replaced (or All) |

"Verbose" | False | whether to print a message when non-standard replacments are made |

ResourceFunction["FormalizeSymbols"] has the HoldFirst attribute to prevent evaluation of defined symbols in *expr* prior to replacement. However, in the special case that ResourceFunction["FormalizeSymbols"] is called directly on a bare symbol having an ownvalue, with the setting "EvaluateOnce"→True, the argument is allowed to evaluate exactly once to allow for intermediate variable assignment (see the second Properties and Relations example).

By default, ResourceFunction["FormalizeSymbols"] only replaces symbols in the current context, as given by $Context (typically having value "Global`"). To replace symbols from other contexts, use the option "ReplacementContexts".

Replaced symbols will always be in the System` context in the output regardless of the context in which they began.

Convert symbols to their formal counterparts:

In[1]:= |

Out[1]= |

FormalizeSymbols works on Latin, Greek and other symbols for which there exists a formal version in the Wolfram Language:

In[2]:= |

Out[2]= |

In[3]:= |

Out[3]= |

FormalizeSymbols works on both uppercase and lowercase letters:

In[4]:= |

Out[4]= |

FormalizeSymbols[*expr*,"Rules"] returns the rules that would be used for replacement in formalizing an expression:

In[5]:= |

Out[5]= |

By default, FormalizeSymbols does not affect symbols with multi-character symbol names:

In[6]:= |

Out[6]= |

To replace multi-character symbols as well, use the setting "ExtraReplacements"→True:

In[7]:= |

Out[7]= |

By default, FormalizeSymbols only affects symbols in the current context (here "Global`"). To allow replacement of symbols in other contexts, use the option "ReplacementContexts":

In[8]:= |

Out[8]= |

In[9]:= |

Out[9]= |

In the special case that FormalizeSymbols is directly called on a bare symbol having an own value, its argument can be allowed to evaluate exactly once using the option setting "EvaluateOnce"→True, as in the following case:

In[10]:= |

Out[12]= |

Without this top-level evaluation, the above inputs would result in x:

In[13]:= |

Out[13]= |

With "EvaluateOnce"→True, evaluation does not proceed beyond top-level:

In[14]:= |

Out[17]= |

Contrast this result with using Evaluate, which triggers full evaluation:

In[18]:= |

Out[18]= |

To exclude a given set of symbols from being replaced, use the option "ExcludeInputSymbols". Compare:

In[19]:= |

Out[19]= |

In[20]:= |

Out[20]= |

To exclude a given set of formal symbols as possible replacement characters, use the option "ExcludeTargetSymbols". Compare:

In[21]:= |

Out[21]= |

In[22]:= |

Out[22]= |

By default, FormalizeSymbols does not replace symbols that lack a direct formal equivalent:

In[23]:= |

Out[23]= |

To replace all symbols, regardless of name, use the setting "ExtraReplacements"→True:

In[24]:= |

Out[24]= |

The default setting of "ReplacementContexts"→Automatic replaces only symbols in $Context (here Global`):

In[25]:= |

Out[25]= |

The "ReplacementContexts" option can be set to a list of contexts for which symbols should be formalized:

In[26]:= |

Out[26]= |

With the setting "ReplacementContexts"→All, symbols in any context other than System` are replaced:

In[27]:= |

Out[27]= |

FormalizeSymbols automatically avoids symbol collisions:

In[28]:= |

Out[28]= |

With the option setting "Verbose"→True a warning is issued about potential collisions:

In[29]:= |

Out[29]= |

FormalizeSymbols has the HoldFirst attribute to prevent (with default option settings) evaluation of defined symbols prior to replacement:

In[32]:= |

Out[33]= |

For the special case of pure symbols having OwnValues, pure HoldFirst behavior can be overridden using the "EvaluateOnce" option:

In[34]:= |

Out[35]= |

In[36]:= |

Out[36]= |

Contrast this result with using Evaluate, which triggers full evaluation:

In[37]:= |

Out[37]= |

Symbols within the System` context are never replaced. In particular, this includes Pi, N, C, D, E, I, K, and O

In[38]:= |

Out[38]= |

In[39]:= |

Out[39]= |

In[40]:= |

Out[40]= |

This work is licensed under a Creative Commons Attribution 4.0 International License