Mixing name/value pair syntax

In a Matlab seminar a few years ago, I asked why function calls that mix old style and new style name/value pair syntax would only work in a certain order. Specifically, the old style pairs must come first in the argument list. When the order is reversed, an error is thrown as illustrated below.

testFunc('A',10, B=20)

    A: 10
    B: 20

testFunc(B=20, 'A',10)

Unsupported use of the '=' operator. To compare values for equality, use '=='. To pass name-value arguments using the name=value format, provide these arguments after all other inputs.

A MathWorker at the seminar told me that this was by design, but there was no time for him to elaborate. Can anyone think why this would have been a deliberate design choice?

function testFunc(opts)
arguments
   opts.A=1;
   opts.B=2;
end

disp(opts)

end

[Rik]

The only thing I can come up with is the risk of typos, but I don't see how requiring this order would affect that.

If you supply these options with varargin they will result in a cellstr (with string if you use Name=Value). I don't see why that would affect this at all, but maybe it is related? Would the order change anything?

Unrelatedly: I think it is neat you can keep the output of a previous run, even if your edit-and-rerun results in a syntax error.

testFunc('A',10, B=20)

    {'A'}    {[10]}    {["B"]}    {[20]}

testFunc(B=20,'A',10)

Unsupported use of the '=' operator. To compare values for equality, use '=='. To pass name-value arguments using the name=value format, provide these arguments after all other inputs.

function testFunc(varargin)
disp(varargin)
end

[dpb]

I "know nutink!" really, but I have presumed it would be owing to keeping the internal parser less complicated if it can make the assumption that paired/named arguments are last.

[Matt J]

Just as follow-up, one arguably negative consequence of this is that only old-style name/value pairings can be overriden programmatically using comma-separated list expansion, e.g.,

override={'B',10};

testFunc('B', 20 , override{:}) %Successful override

    A: 1
    B: 10

testFunc(B=20 , override{:}) %Forbidden

Unsupported use of the '=' operator. To compare values for equality, use '=='. To pass name-value arguments using the name=value format, provide these arguments after all other inputs.

function testFunc(opts)
arguments
   opts.A=1;
   opts.B=2;
end

 disp(opts)

end

[dpb]

As a follow-up to my earlier, there are usages buried in MATLAB internal functions that rely on the convention as well, optional arguments in the input list are located by finding the location of the first name that matches one of the allowable options and then split off from there to the end of the list and checked for being an even number for starters.

Changing the convention would require a major amount of rework.

[Rik]

That doesn't make sense to me. I must admit I don't know how this interacts with the arguments block (which I don't personally use), but with varargin the Name=Value syntax is forwarded as a cellstr. To me that means your suggested protected case shouldn't be affected. Can you perhaps explain what I'm missing?

[Matt J]

Changing the convention would require a major amount of rework.

I don't see how. The only difference between new-style and old style pair parsing is that now an '=' sign becomes a possible delimiter of the input arguments, in addtition to commas. It should be easy to preconvert the argument list from new style to old style and do whatever it is you used to do. I can code that right now:

convert(" B=20, 'A',10 ")

ans = "'B' , 20 ,  'A' , 10  "

function strOldStyle=convert(strNewStyle)

 [str,m]=strsplit(strNewStyle,["=",","]);
 
 idx=(m=="=");
 
 m(idx)=",";
 
 str(idx)="'"+ strtrim(str(idx))+"'";
 
 strOldStyle = strjoin([str;m,""]);
 

end

[dpb]

It's not the delimiter, it's the order that classical must all go first.

[Matt J]

But we're trying to understand why that is necessary, right? Why is it necessary when you can easily pre-map any argument list to the classical syntax?

[dpb]

There are just a lot of places to go make the adjustment, though. Conceptually, it could be kludged that way, but MATLAB has a lot of functions to deal with. Unless there might be some super high-level way to intercept every call, I suppose. But that would seem to add quite a bit of overhead.

[Matt J]

Isn't there a centralized parser that handles the syntax analysis of an mfile? Why would that be split?

[Rik]

Isn't there a single parser that looks for syntax errors? Why would the naive approach of making the Name=Value syntax work the same as {:} cause any issues anywhere? And why there be a requirement for Name=Value to be last either way?

Only partially on topic: I think the monstrosity below shows how poorly I understand what is happening.

tryme(A=10)

A = "A"

B = 10

function tryme(A,B)
arguments
   A=1;
   B=2;
end
A
B
end

[Matt J]

I think the monstrosity below shows how poorly I understand what is happening.

Nothing monstrous there. As you noted earlier, the A=10 syntax gets converted to a comma-separated pair {"A",10} and so the call is equivalent to,

args={"A",10};

tryme(args{:})

I might have expected,

 args = {'A',10}

so that's a little strange.

Answer 1

[Steven Lord]

Suppose I show you this call. How would you as a human interpret it, and how would MATLAB interpret it (were it syntactically legal)?

myfun(A="B", "C", D="E", "F")

As a human, I would say the intent for some of the arguments was pretty clear: the parameter named A should take on value "B" and the parameter named D should take on value "E". The intent of arguments "C" and "F" is less clear; perhaps those should be interpreted as the first and second positional arguments in the call?

As MATLAB, if we allowed this, that would be the same call as:

myfun("A", "B", "C", "D", "E", "F")

or

myfun(A = "B", C = "D", E = "F")

where parameters named A, C, and E will take on values "B", "D", and "F" respectively.

By requiring name=value arguments to come at the end of the signature, we avoid having to deal with this potential ambiguity or this one:

myfun(A = "B", C = "D", "E", "F") % Are E and F positional or name-value?

[Steven Lord]

Would users be surprised when they ran this:

myfun(A = "B", "C", D = "E", "F")

and options C and E were set but option D was not? Note that this is not something where the author of myfun would be the one surprised; this is something where users of myfun could be surprised.

[Matt J]

They would be surprised, but isn't it their own damn fault for not properly pairing their arguments? The same hazard existes even when the old name-value pair syntax is/was being used.

[Rik]

With the old syntax the risk is even greater, which is why people tend to use ellipses (...) to keep everything straight in long lists of arguments.

I also honestly don't the reason.

Designing a parses to trigger understandable errors is an art. You need to put yourself in the mind of a bad/novice user. In this case the most probable error would be that C doesn't exist as a parameter.

Answer 2

[John D'Errico]

I have at least a couple of reasons why, which is why I will pose this as an answer. Knowing exactly which deliberations were made is not possible, since none of us were on the committee which made them. And if anyone reading this was there, they would have an NDA involved. But I think I can put myself into their heads...

First, the property-value pair syntax (sorry, I've always called them property-values pairs instead of name-value pairs, so my head and fingers just think that way when I write) has been around pretty much forever in MATLAB. They cannot simply decide it is going away, as far too much user code relies on it. And X=10 would not even be a properly formed argument to pass into a function. Far better to have parser code that would convert it on the fly into a property-value pair.

At the same time, it is far cleaner to write (AND read) X = 10, instead of 'X',10. The readability aspect may even be the more important in the eyes of the user. I believe TMW has gotten many requests for the new style. So they very much wanted to introduce the newer form.

But what happens in MATLAB when you use these various syntaxes?

function testfun(varargin)
  varargin
end

testfun(12,'X',10,A = pi)

varargin = 1×5 cell array
    {[12]}    {'X'}    {[10]}    {["A"]}    {[3.1416]}

As you can see, the parser saw the new form at the end of the input string, and on the fly converted it into a corresponding property-value pair. Then it assumes testfun will be able to process the property-value pairs.

So what happens is the parser looks at the arguments, and once it sees something of the form A = pi, it just grabs everything that follows and re-formats it into corresponding pairs of arguments. No tests are needed at that point, just fly, and if something "bad" was done, then let it generate an error code. Tests take time. Complex code that needs to make decisions is slow, harder to write, more prone to bugs, etc.

Now matter what though, the parser will still need to accept the property-value pair coding style, as that is too deeply part of MATLAB, and the code users have written and used for so many years.

Now I need to put on my committee hat. I need to choose a design spec that will be most easily written. I don't want complicated code in the parser. And it needs to be fast. I don't want it to need to make deliberations on a possibly long string of inputs, one at a time, as that will be considerably slower. I don't want it to need to insert a pair of arguments into a slot in a cell array, where before there was room for only one argument. Again, that will make the code slower. And it needs to be easily read by the user too, as code where the input arguments to a function can flip randomly back and forth between coding styles is hard on the eyes, and hard to debug too.

They made a choice, one that I could accept were I on that committee. In the end, I would bet the most important of the possible factors was the one about parser speed, which also would considerably improve the simplicity of the code they would need to write.

Was there only one dominant reason for this design choice? I think there rarely is. It was certainly a choice made by a committee, where they had to weigh the various factors they would see. But simplicity and speed of code will almost always be at the head of any design decision made about the MATLAB parser. Honestly, I don't even think there was that much need for deliberation in the matter.

[Matt J]

As I told @dpb, though, I have trouble seeing why the parsing gets substantially slower just because you now have two possible argument delimiters ('=' and ',') instead of just one. They're already parsing two delimiters in some form now. Why does the order matter?