Function Repository Resource:

# FailWhenUndefined

Append a definition rule to a symbol so that it will fail when given undefined arguments

Contributed by: Richard Hennigan (Wolfram Research)
 ResourceFunction["FailWhenUndefined"][f] appends a rule to the definition of f so that it will return a Failure object rather than remain unevaluated for undefined arguments. ResourceFunction["FailWhenUndefined"][f,handler] applies handler to the generated Failure object at the time of failure. ResourceFunction["FailWhenUndefined"][f,handler,type] specifies which set of values to modify for f.

## Details and Options

The default value for handler is Identity.
The default value for type is DownValues.
The value for type can be one of the following:
 OwnValues definitions of the form f:=… DownValues definitions of the form f[…]:=… SubValues definitions of the form f[…][…]:=… {SubValues,n} definitions of the form f[…]…[…]:=… n equivalent to {SubValues,n}
ResourceFunction["FailWhenUndefined"] accepts the option "Message" which specifies whether a message should be issued at the time of failure.

## Examples

### Basic Examples (2)

Define a function so that it fails when given undefined arguments:

 In[1]:=

Check the definition:

 In[2]:=
 Out[2]=

Defined behavior:

 In[3]:=
 Out[3]=

Undefined behavior:

 In[4]:=
 Out[4]=
 In[5]:=
 Out[5]=

Specify a function to apply to the failure object at the time of failure:

 In[6]:=
 Out[7]=

Defined behavior:

 In[8]:=
 Out[8]=

Undefined behavior:

 In[9]:=
 Out[9]=

### Scope (4)

Catch undefined SubValues:

 In[10]:=

This allows undefined operator forms:

 In[11]:=
 Out[11]=
 In[12]:=
 Out[12]=

Undefined behavior is caught when applying the operator form:

 In[13]:=
 Out[13]=
 In[14]:=
 Out[14]=

Specify the number of SubValues positions:

 In[15]:=
 In[16]:=
 Out[16]=
 In[17]:=
 Out[17]=

Fail for undefined OwnValues:

 In[18]:=

Defined behavior:

 In[19]:=
 Out[13]=
 In[20]:=
 Out[21]=

Undefined behavior:

 In[22]:=
 Out[23]=

Use an integer as shorthand for {SubValues,n}:

 In[24]:=
 Out[25]=

### Options (1)

#### Message (1)

Do not issue a message when failing:

 In[26]:=
 In[27]:=
 Out[27]=
 In[28]:=
 Out[28]=

### Properties and Relations (3)

One level of SubValues is equivalent to DownValues:

 In[29]:=
 Out[30]=

Zero levels of SubValues is equivalent to OwnValues:

 In[31]:=
 Out[32]=

FailWhenUndefined always appends definitions so that it will not rewrite existing ones:

 In[33]:=
 In[34]:=
 Out[34]=

In this case, the definition created by FailWhenUndefined is unreachable:

 In[35]:=
 Out[35]=

### Possible Issues (4)

Definitions created by FailWhenUndefined may be overwritten by other definitions, so it should be used after all other definitions have been created for a symbol in order to avoid unexpected results:

 In[36]:=
 In[37]:=
 Out[37]=

Always apply FailWhenUndefined last:

 In[38]:=
 In[39]:=
 Out[39]=

FailWhenUndefined defines a message for the given symbol:

 In[40]:=
 In[41]:=
 Out[41]=
 In[42]:=
 Out[42]=

If the "undefined" message tag already exists for the given symbol, FailWhenUndefined will be used instead:

 In[43]:=
 In[44]:=
 Out[44]=

The original message is unmodified:

 In[45]:=
 Out[45]=

Repeated applications of FailWhenUndefined will add unreachable definition rules:

 In[46]:=
 In[47]:=
 Out[47]=

## Version History

• 1.0.0 – 04 March 2022