How to program a F::argx message?

Question

How useful is it to program a user-built function in a package to produce a red warning message F::argx if you give the wrong number of arguments to that function? How do I do this?

Answer 1

The large addendum on handling multiple messages as built-ins do has been moved to a separate post; please see the link below for advanced message handling options.

• How to check the style and number of arguments like the built-in functions?

---

Macro package function SetArgumentCount

In recent versions there is an undocumented function Macros`SetArgumentCount that specifically automates creation of a definition for an argument Message. Examples:

Macros`SetArgumentCount[foo, 2]

foo[1]
foo[1, 2, 3]

foo::argr: foo called with 1 argument; 2 arguments are expected.

foo::argrx: foo called with 3 arguments; 2 arguments are expected.

Macros`SetArgumentCount[foo, {2, 4}]

foo[1]
foo[1, 2, 3, 4, 5]

foo::argbu: foo called with 1 argument; between 2 and 4 arguments are expected. >>

foo::argb: foo called with 5 arguments; between 2 and 4 arguments are expected. >>

(Returned input intentionally omitted.)

---

Available messages

The message ::argx is one of the general messages intended for use with any function. These have the special property of being called for any symbol used (placed left of ::):

Message[foo::"argx", "foo", 2, 3]

foo::argx: foo called with 2 arguments; 1 argument is expected. >>

Use Messages[General] to see a list of these messages.

Synax highlighting

SyntaxInformation can be used to create the red syntax highlighting present in many built-in functions. For a full description please see:

• Syntax highlighting for your own functions

Basic usage

You may have noticed that the method shown in R.M's answer doesn't produce behavior that exactly matches internal functions such as Plot, which echo bad input:

Plot[1, 2, 3, 4]

Plot::nonopt: Options expected (instead of 4) beyond position 2 in Plot[1,2,3,4]. An option must be a rule or a list of rules. >>

Plot[1, 2, 3, 4]

To get this you behavior you can generate the Message as a side-effect, as in Condition:

ClearAll@f
SyntaxInformation[f] = {"ArgumentsPattern" -> {_}};
f[1] := True
f[_] := False
f[x___] /; Message[f::argx, "f", Length@{x}] := Null

Now:

f[1, 2, 3]

f::argx: f called with 3 arguments; 1 argument is expected. >>

f[1, 2, 3]

The final no-match rule can also be written:

x_f /; Message[f::argx, "f", Length @ Unevaluated @ x] := Null

Answer 2

As acl points out, this post shows you how to setup error highlighting for invalid number of arguments. Coming to the actual error messages used, there are three built-in messages attached to General, that can be used for your own functions as well. These are argx, argrx and argt:

General::argx
(* "`1` called with `2` arguments; 1 argument is expected." *)

General::argrx
(* "`1` called with `2` arguments; `3` arguments are expected." *)

General::argt
(* "`1` called with `2` arguments; `3` or `4` arguments are expected." *)

You can attach these messages to your own functions (any message defined for General can be used for any other symbol) like in the following example (shown only for argx):

ClearAll@f
SyntaxInformation[f] = {"ArgumentsPattern" -> {_}};
f[1] := True
f[_] := False
f[_, x__] := Message[f::argx, "f", Length@{x} + 1]

Answer 3

There's a nice internal method for this that has existed since at least 10.4: System`Private`ArgumentsWithRules.

You can use it to define a nicely handled function like so:

f[args___] :=
 With[
  {
   a =
    System`Private`ArgumentsWithRules[
     f[args](*function with args to gather from*), 
     {
      0(*min length*),
      1(*max length*)
      }, 
     Hold(*head to wrap on the lists*)
     ]
   },
  yourFunctionBody /; Length[a] > 0
  ]

f[1, 2]

f::argt: f called with 2 arguments; 0 or 1 arguments are expected.

f[1, 2]

Even better, if f has Options this detects it:

Options[f] = {"a" -> "b"};
f[1, 2]

f::nonopt: Options expected (instead of 2) beyond position 1 in f[1,2]. An option must be a rule or a list of rules.

f[1, 2]

This makes it useful extension on ArgumentCountQ:

ArgumentCountQ[f, 3, 1, 2]

f::argt: f called with 3 arguments; 1 or 2 arguments are expected.

False

Answer 4

Thats what I learned.
To see if my function has just 2 arguments, not 1 argument and no more the 2 arguments I did these steps:
Define the warnings

General::twoplus = "f called with to much arguments, 2 argument expected.";  
General::twominus = "f called with 1 argument, 2 arguments expected.";  
f[_, _, x__] := Message[f::twoplus, "f", Length@{x} + 1]  
f[x__] := Message[f::twominus, "f", Length@{x} + 1]  

Define the function

f[x_, y_] := x + y + 1;  

Call the function

f[1]  
f::twominus: f called with 1 argument, 2 arguments expected.  

f[1, 2]  
4  

f[1, 2, 3]  
f::twoplus: f called with to much arguments, 2 argument expected.