spec: clarify list += iterable

[alandonovan]

The spec says of x += y:

if x refers to a list, the statement does not allocate a new list but instead mutates the original list in place, similar to x.extend(y).

Python3 and go.starlark.net allow y to be an iterable, like x.extend(y), but java.starlark.net does not.

I propose the spec be clarified to say:

"""
However, if x refers to a list, the effect of the statement is equivalent to x.extend(y); that is, it does not create a new list but instead appends the elements of y, which must be an iterable sequence, in place to the original list.
"""
and the Java implementation be updated accordingly.

$ python3
>>> a = []
>>> a + {1: 2}
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate list (not "dict") to list
>>> a += {1: 2}
>>> a
[1]

$ starlark
Welcome to Starlark (go.starlark.net)
>>> a=[]
>>> a + {1: 2}
Traceback (most recent call last):
  <stdin>:1:3: in <expr>
Error: unknown binary op: list + dict
>>> a += {1: 2}
>>> a
[1]

$ bazel run src/main/java/net/starlark/java/cmd:starlark 
Welcome to Starlark (java.starlark.net)
>> a = []
>> a + {1: 2}
Traceback (most recent call last):
	File "<stdin>", line 1, column 3, in <toplevel>
Error: unsupported binary operation: list + dict
>> a += {1: 2}
Traceback (most recent call last):
	File "<stdin>", line 1, column 3, in <toplevel>
Error: unsupported binary operation: list + dict

[stepancheg]

A bit offtopic, but

• spec doesn't mention that extension types can override augmented assignment to be done in place, readers might assume that only list is special
• *= for list in current Starlark allocates a new list, but updates list in place in Python:

# java starlark
>> a = [1]
>> b = a
>> a *= 3
>> a
[1, 1, 1]
>> b
[1]

# python
>>> a = [1]
>>> b = a
>>> a *= 3
>>> a
[1, 1, 1]
>>> b
[1, 1, 1]