1# Starlark in Go: Language definition
2
3Starlark is a dialect of Python intended for use as a configuration
4language. A Starlark interpreter is typically embedded within a larger
5application, and this application may define additional
6domain-specific functions and data types beyond those provided by the
7core language. For example, Starlark is embedded within (and was
8originally developed for) the [Bazel build tool](https://bazel.build),
9and [Bazel's build language](https://docs.bazel.build/versions/main/skylark/language.html) is based on Starlark.
10
11This document describes the Go implementation of Starlark
12at go.starlark.net/starlark.
13The language it defines is similar but not identical to
14[the Java-based implementation](https://github.com/bazelbuild/bazel/blob/master/src/main/java/net/starlark/java/eval/Starlark.java)
15used by Bazel.
16We identify places where their behaviors differ, and an
17[appendix](#dialect-differences) provides a summary of those
18differences.
19We plan to converge both implementations on a single specification.
20
21This document is maintained by Alan Donovan <adonovan@google.com>.
22It was influenced by the Python specification,
23Copyright 1990–2017, Python Software Foundation,
24and the Go specification, Copyright 2009–2017, The Go Authors.
25
26Starlark was designed and implemented in Java by Laurent Le Brun,
27Dmitry Lomov, Jon Brandvin, and Damien Martin-Guillerez, standing on
28the shoulders of the Python community.
29The Go implementation was written by Alan Donovan and Jay Conrod;
30its scanner was derived from one written by Russ Cox.
31
32## Overview
33
34Starlark is an untyped dynamic language with high-level data types,
35first-class functions with lexical scope, and automatic memory
36management or _garbage collection_.
37
38Starlark is strongly influenced by Python, and is almost a subset of
39that language. In particular, its data types and syntax for
40statements and expressions will be very familiar to any Python
41programmer.
42However, Starlark is intended not for writing applications but for
43expressing configuration: its programs are short-lived and have no
44external side effects and their main result is structured data or side
45effects on the host application.
46As a result, Starlark has no need for classes, exceptions, reflection,
47concurrency, and other such features of Python.
48
49Starlark execution is _deterministic_: all functions and operators
50in the core language produce the same execution each time the program
51is run; there are no sources of random numbers, clocks, or unspecified
52iterators. This makes Starlark suitable for use in applications where
53reproducibility is paramount, such as build tools.
54
55## Contents
56
57<!-- WTF? No automatic TOC? -->
58
59 * [Overview](#overview)
60 * [Contents](#contents)
61 * [Lexical elements](#lexical-elements)
62 * [Data types](#data-types)
63 * [None](#none)
64 * [Booleans](#booleans)
65 * [Integers](#integers)
66 * [Floating-point numbers](#floating-point-numbers)
67 * [Strings](#strings)
68 * [Lists](#lists)
69 * [Tuples](#tuples)
70 * [Dictionaries](#dictionaries)
71 * [Sets](#sets)
72 * [Functions](#functions)
73 * [Built-in functions](#built-in-functions)
74 * [Name binding and variables](#name-binding-and-variables)
75 * [Value concepts](#value-concepts)
76 * [Identity and mutation](#identity-and-mutation)
77 * [Freezing a value](#freezing-a-value)
78 * [Hashing](#hashing)
79 * [Sequence types](#sequence-types)
80 * [Indexing](#indexing)
81 * [Expressions](#expressions)
82 * [Identifiers](#identifiers)
83 * [Literals](#literals)
84 * [Parenthesized expressions](#parenthesized-expressions)
85 * [Dictionary expressions](#dictionary-expressions)
86 * [List expressions](#list-expressions)
87 * [Unary operators](#unary-operators)
88 * [Binary operators](#binary-operators)
89 * [Conditional expressions](#conditional-expressions)
90 * [Comprehensions](#comprehensions)
91 * [Function and method calls](#function-and-method-calls)
92 * [Dot expressions](#dot-expressions)
93 * [Index expressions](#index-expressions)
94 * [Slice expressions](#slice-expressions)
95 * [Lambda expressions](#lambda-expressions)
96 * [Statements](#statements)
97 * [Pass statements](#pass-statements)
98 * [Assignments](#assignments)
99 * [Augmented assignments](#augmented-assignments)
100 * [Function definitions](#function-definitions)
101 * [Return statements](#return-statements)
102 * [Expression statements](#expression-statements)
103 * [If statements](#if-statements)
104 * [For loops](#for-loops)
105 * [Break and Continue](#break-and-continue)
106 * [Load statements](#load-statements)
107 * [Module execution](#module-execution)
108 * [Built-in constants and functions](#built-in-constants-and-functions)
109 * [None](#none)
110 * [True and False](#true-and-false)
111 * [any](#any)
112 * [all](#all)
113 * [bool](#bool)
114 * [chr](#chr)
115 * [dict](#dict)
116 * [dir](#dir)
117 * [enumerate](#enumerate)
118 * [fail](#fail)
119 * [float](#float)
120 * [getattr](#getattr)
121 * [hasattr](#hasattr)
122 * [hash](#hash)
123 * [int](#int)
124 * [len](#len)
125 * [list](#list)
126 * [max](#max)
127 * [min](#min)
128 * [ord](#ord)
129 * [print](#print)
130 * [range](#range)
131 * [repr](#repr)
132 * [reversed](#reversed)
133 * [set](#set)
134 * [sorted](#sorted)
135 * [str](#str)
136 * [tuple](#tuple)
137 * [type](#type)
138 * [zip](#zip)
139 * [Built-in methods](#built-in-methods)
140 * [dict·clear](#dict·clear)
141 * [dict·get](#dict·get)
142 * [dict·items](#dict·items)
143 * [dict·keys](#dict·keys)
144 * [dict·pop](#dict·pop)
145 * [dict·popitem](#dict·popitem)
146 * [dict·setdefault](#dict·setdefault)
147 * [dict·update](#dict·update)
148 * [dict·values](#dict·values)
149 * [list·append](#list·append)
150 * [list·clear](#list·clear)
151 * [list·extend](#list·extend)
152 * [list·index](#list·index)
153 * [list·insert](#list·insert)
154 * [list·pop](#list·pop)
155 * [list·remove](#list·remove)
156 * [set·union](#set·union)
157 * [string·capitalize](#string·capitalize)
158 * [string·codepoint_ords](#string·codepoint_ords)
159 * [string·codepoints](#string·codepoints)
160 * [string·count](#string·count)
161 * [string·elem_ords](#string·elem_ords)
162 * [string·elems](#string·elems)
163 * [string·endswith](#string·endswith)
164 * [string·find](#string·find)
165 * [string·format](#string·format)
166 * [string·index](#string·index)
167 * [string·isalnum](#string·isalnum)
168 * [string·isalpha](#string·isalpha)
169 * [string·isdigit](#string·isdigit)
170 * [string·islower](#string·islower)
171 * [string·isspace](#string·isspace)
172 * [string·istitle](#string·istitle)
173 * [string·isupper](#string·isupper)
174 * [string·join](#string·join)
175 * [string·lower](#string·lower)
176 * [string·lstrip](#string·lstrip)
177 * [string·partition](#string·partition)
178 * [string·removeprefix](#string·removeprefix)
179 * [string·removesuffix](#string·removesuffix)
180 * [string·replace](#string·replace)
181 * [string·rfind](#string·rfind)
182 * [string·rindex](#string·rindex)
183 * [string·rpartition](#string·rpartition)
184 * [string·rsplit](#string·rsplit)
185 * [string·rstrip](#string·rstrip)
186 * [string·split](#string·split)
187 * [string·splitlines](#string·splitlines)
188 * [string·startswith](#string·startswith)
189 * [string·strip](#string·strip)
190 * [string·title](#string·title)
191 * [string·upper](#string·upper)
192 * [Dialect differences](#dialect-differences)
193
194
195## Lexical elements
196
197A Starlark program consists of one or more modules.
198Each module is defined by a single UTF-8-encoded text file.
199
200A complete grammar of Starlark can be found in [grammar.txt](../syntax/grammar.txt).
201That grammar is presented piecemeal throughout this document
202in boxes such as this one, which explains the notation:
203
204```grammar {.good}
205Grammar notation
206
207- lowercase and 'quoted' items are lexical tokens.
208- Capitalized names denote grammar productions.
209- (...) implies grouping.
210- x | y means either x or y.
211- [x] means x is optional.
212- {x} means x is repeated zero or more times.
213- The end of each declaration is marked with a period.
214```
215
216The contents of a Starlark file are broken into a sequence of tokens of
217five kinds: white space, punctuation, keywords, identifiers, and literals.
218Each token is formed from the longest sequence of characters that
219would form a valid token of each kind.
220
221```grammar {.good}
222File = {Statement | newline} eof .
223```
224
225*White space* consists of spaces (U+0020), tabs (U+0009), carriage
226returns (U+000D), and newlines (U+000A). Within a line, white space
227has no effect other than to delimit the previous token, but newlines,
228and spaces at the start of a line, are significant tokens.
229
230*Comments*: A hash character (`#`) appearing outside of a string
231literal marks the start of a comment; the comment extends to the end
232of the line, not including the newline character.
233Comments are treated like other white space.
234
235*Punctuation*: The following punctuation characters or sequences of
236characters are tokens:
237
238```text
239+ - * / // % =
240+= -= *= /= //= %= == !=
241^ < > << >> & |
242^= <= >= <<= >>= &= |=
243. , ; : ~ **
244( ) [ ] { }
245```
246
247*Keywords*: The following tokens are keywords and may not be used as
248identifiers:
249
250```text
251and elif in or
252break else lambda pass
253continue for load return
254def if not while
255```
256
257The tokens below also may not be used as identifiers although they do not
258appear in the grammar; they are reserved as possible future keywords:
259
260<!-- and to remain a syntactic subset of Python -->
261
262```text
263as finally nonlocal
264assert from raise
265class global try
266del import with
267except is yield
268```
269
270<b>Implementation note:</b>
271The Go implementation permits `assert` to be used as an identifier,
272and this feature is widely used in its tests.
273
274*Identifiers*: an identifier is a sequence of Unicode letters, decimal
275 digits, and underscores (`_`), not starting with a digit.
276Identifiers are used as names for values.
277
278Examples:
279
280```text
281None True len
282x index starts_with arg0
283```
284
285*Literals*: literals are tokens that denote specific values. Starlark
286has string, integer, and floating-point literals.
287
288```text
2890 # int
290123 # decimal int
2910x7f # hexadecimal int
2920o755 # octal int
2930b1011 # binary int
294
2950.0 0. .0 # float
2961e10 1e+10 1e-10
2971.1e10 1.1e+10 1.1e-10
298
299"hello" 'hello' # string
300'''hello''' """hello""" # triple-quoted string
301r'hello' r"hello" # raw string literal
302```
303
304Integer and floating-point literal tokens are defined by the following grammar:
305
306```grammar {.good}
307int = decimal_lit | octal_lit | hex_lit | binary_lit .
308decimal_lit = ('1' … '9') {decimal_digit} | '0' .
309octal_lit = '0' ('o'|'O') octal_digit {octal_digit} .
310hex_lit = '0' ('x'|'X') hex_digit {hex_digit} .
311binary_lit = '0' ('b'|'B') binary_digit {binary_digit} .
312
313float = decimals '.' [decimals] [exponent]
314 | decimals exponent
315 | '.' decimals [exponent]
316 .
317decimals = decimal_digit {decimal_digit} .
318exponent = ('e'|'E') ['+'|'-'] decimals .
319
320decimal_digit = '0' … '9' .
321octal_digit = '0' … '7' .
322hex_digit = '0' … '9' | 'A' … 'F' | 'a' … 'f' .
323binary_digit = '0' | '1' .
324```
325
326### String literals
327
328A Starlark string literal denotes a string value.
329In its simplest form, it consists of the desired text
330surrounded by matching single- or double-quotation marks:
331
332```python
333"abc"
334'abc'
335```
336
337Literal occurrences of the chosen quotation mark character must be
338escaped by a preceding backslash. So, if a string contains several
339of one kind of quotation mark, it may be convenient to quote the string
340using the other kind, as in these examples:
341
342```python
343'Have you read "To Kill a Mockingbird?"'
344"Yes, it's a classic."
345
346"Have you read \"To Kill a Mockingbird?\""
347'Yes, it\'s a classic.'
348```
349
350Literal occurrences of the _opposite_ kind of quotation mark, such as
351an apostrophe within a double-quoted string literal, may be escaped
352by a backslash, but this is not necessary: `"it's"` and `"it\'s"` are
353equivalent.
354
355
356#### String escapes
357
358Within a string literal, the backslash character `\` indicates the
359start of an _escape sequence_, a notation for expressing things that
360are impossible or awkward to write directly.
361
362The following *traditional escape sequences* represent the ASCII control
363codes 7-13:
364
365```
366\a \x07 alert or bell
367\b \x08 backspace
368\f \x0C form feed
369\n \x0A line feed
370\r \x0D carriage return
371\t \x09 horizontal tab
372\v \x0B vertical tab
373```
374
375A *literal backslash* is written using the escape `\\`.
376
377An *escaped newline*---that is, a backslash at the end of a line---is ignored,
378allowing a long string to be split across multiple lines of the source file.
379
380```python
381"abc\
382def" # "abcdef"
383```
384
385An *octal escape* encodes a single byte using its octal value.
386It consists of a backslash followed by one, two, or three octal digits [0-7].
387It is error if the value is greater than decimal 255.
388
389```python
390'\0' # "\x00" a string containing a single NUL byte
391'\12' # "\n" octal 12 = decimal 10
392'\101-\132' # "A-Z"
393'\119' # "\t9" = "\11" + "9"
394```
395
396<b>Implementation note:</b>
397The Java implementation encodes strings using UTF-16,
398so an octal escape encodes a single UTF-16 code unit.
399Octal escapes for values above 127 are therefore not portable across implementations.
400There is little reason to use octal escapes in new code.
401
402A *hex escape* encodes a single byte using its hexadecimal value.
403It consists of `\x` followed by exactly two hexadecimal digits [0-9A-Fa-f].
404
405```python
406"\x00" # "\x00" a string containing a single NUL byte
407"(\x20)" # "( )" ASCII 0x20 = 32 = space
408
409red, reset = "\x1b[31m", "\x1b[0m" # ANSI terminal control codes for color
410"(" + red + "hello" + reset + ")" # "(hello)" with red text, if on a terminal
411```
412
413<b>Implementation note:</b>
414The Java implementation does not support hex escapes.
415
416An ordinary string literal may not contain an unescaped newline,
417but a *multiline string literal* may spread over multiple source lines.
418It is denoted using three quotation marks at start and end.
419Within it, unescaped newlines and quotation marks (or even pairs of
420quotation marks) have their literal meaning, but three quotation marks
421end the literal. This makes it easy to quote large blocks of text with
422few escapes.
423
424```
425haiku = '''
426Yesterday it worked.
427Today it is not working.
428That's computers. Sigh.
429'''
430```
431
432Regardless of the platform's convention for text line endings---for
433example, a linefeed (\n) on UNIX, or a carriage return followed by a
434linefeed (\r\n) on Microsoft Windows---an unescaped line ending in a
435multiline string literal always denotes a line feed (\n).
436
437Starlark also supports *raw string literals*, which look like an
438ordinary single- or double-quotation preceded by `r`. Within a raw
439string literal, there is no special processing of backslash escapes,
440other than an escaped quotation mark (which denotes a literal
441quotation mark), or an escaped newline (which denotes a backslash
442followed by a newline). This form of quotation is typically used when
443writing strings that contain many quotation marks or backslashes (such
444as regular expressions or shell commands) to reduce the burden of
445escaping:
446
447```python
448"a\nb" # "a\nb" = 'a' + '\n' + 'b'
449r"a\nb" # "a\\nb" = 'a' + '\\' + 'n' + 'b'
450
451"a\
452b" # "ab"
453r"a\
454b" # "a\\\nb"
455```
456
457It is an error for a backslash to appear within a string literal other
458than as part of one of the escapes described above.
459
460TODO: define indent, outdent, semicolon, newline, eof
461
462## Data types
463
464These are the main data types built in to the interpreter:
465
466```python
467NoneType # the type of None
468bool # True or False
469int # a signed integer of arbitrary magnitude
470float # an IEEE 754 double-precision floating point number
471string # a byte string
472list # a modifiable sequence of values
473tuple # an unmodifiable sequence of values
474dict # a mapping from values to values
475set # a set of values
476function # a function implemented in Starlark
477builtin_function_or_method # a function or method implemented by the interpreter or host application
478```
479
480Some functions, such as the iteration methods of `string`, or the
481`range` function, return instances of special-purpose types that don't
482appear in this list.
483Additional data types may be defined by the host application into
484which the interpreter is embedded, and those data types may
485participate in basic operations of the language such as arithmetic,
486comparison, indexing, and function calls.
487
488<!-- We needn't mention the stringIterable type here. -->
489
490Some operations can be applied to any Starlark value. For example,
491every value has a type string that can be obtained with the expression
492`type(x)`, and any value may be converted to a string using the
493expression `str(x)`, or to a Boolean truth value using the expression
494`bool(x)`. Other operations apply only to certain types. For
495example, the indexing operation `a[i]` works only with strings, lists,
496and tuples, and any application-defined types that are _indexable_.
497The [_value concepts_](#value-concepts) section explains the groupings of
498types by the operators they support.
499
500
501### None
502
503`None` is a distinguished value used to indicate the absence of any other value.
504For example, the result of a call to a function that contains no return statement is `None`.
505
506`None` is equal only to itself. Its [type](#type) is `"NoneType"`.
507The truth value of `None` is `False`.
508
509
510### Booleans
511
512There are two Boolean values, `True` and `False`, representing the
513truth or falsehood of a predicate. The [type](#type) of a Boolean is `"bool"`.
514
515Boolean values are typically used as conditions in `if`-statements,
516although any Starlark value used as a condition is implicitly
517interpreted as a Boolean.
518For example, the values `None`, `0`, `0.0`, and the empty sequences
519`""`, `()`, `[]`, and `{}` have a truth value of `False`, whereas non-zero
520numbers and non-empty sequences have a truth value of `True`.
521Application-defined types determine their own truth value.
522Any value may be explicitly converted to a Boolean using the built-in `bool`
523function.
524
525```python
5261 + 1 == 2 # True
5272 + 2 == 5 # False
528
529if 1 + 1:
530 print("True")
531else:
532 print("False")
533```
534
535### Integers
536
537The Starlark integer type represents integers. Its [type](#type) is `"int"`.
538
539Integers may be positive or negative, and arbitrarily large.
540Integer arithmetic is exact.
541Integers are totally ordered; comparisons follow mathematical
542tradition.
543
544The `+` and `-` operators perform addition and subtraction, respectively.
545The `*` operator performs multiplication.
546
547The `//` and `%` operations on integers compute floored division and
548remainder of floored division, respectively.
549If the signs of the operands differ, the sign of the remainder `x % y`
550matches that of the divisor, `y`.
551For all finite x and y (y ≠ 0), `(x // y) * y + (x % y) == x`.
552The `/` operator implements real division, and
553yields a `float` result even when its operands are both of type `int`.
554
555Integers, including negative values, may be interpreted as bit vectors.
556The `|`, `&`, and `^` operators implement bitwise OR, AND, and XOR,
557respectively. The unary `~` operator yields the bitwise inversion of its
558integer argument. The `<<` and `>>` operators shift the first argument
559to the left or right by the number of bits given by the second argument.
560
561Any bool, number, or string may be interpreted as an integer by using
562the `int` built-in function.
563
564An integer used in a Boolean context is considered true if it is
565non-zero.
566
567```python
568100 // 5 * 9 + 32 # 212
5693 // 2 # 1
5703 / 2 # 1.5
571111111111 * 111111111 # 12345678987654321
572"0x%x" % (0x1234 & 0xf00f) # "0x1004"
573int("ffff", 16) # 65535, 0xffff
574```
575
576### Floating-point numbers
577
578The Starlark floating-point data type represents an IEEE 754
579double-precision floating-point number. Its [type](#type) is `"float"`.
580
581Arithmetic on floats using the `+`, `-`, `*`, `/`, `//`, and `%`
582 operators follows the IEE 754 standard.
583However, computing the division or remainder of division by zero is a dynamic error.
584
585An arithmetic operation applied to a mixture of `float` and `int`
586operands works as if the `int` operand is first converted to a
587`float`. For example, `3.141 + 1` is equivalent to `3.141 +
588float(1)`.
589There are two floating-point division operators:
590`x / y ` yields the floating-point quotient of `x` and `y`,
591whereas `x // y` yields `floor(x / y)`, that is, the largest
592integer value not greater than `x / y`.
593Although the resulting number is integral, it is represented as a
594`float` if either operand is a `float`.
595
596The `%` operation computes the remainder of floored division.
597As with the corresponding operation on integers,
598if the signs of the operands differ, the sign of the remainder `x % y`
599matches that of the divisor, `y`.
600
601The infinite float values `+Inf` and `-Inf` represent numbers
602greater/less than all finite float values.
603
604The non-finite `NaN` value represents the result of dubious operations
605such as `Inf/Inf`. A NaN value compares neither less than, nor
606greater than, nor equal to any value, including itself.
607
608All floats other than NaN are totally ordered, so they may be compared
609using operators such as `==` and `<`.
610
611Any bool, number, or string may be interpreted as a floating-point
612number by using the `float` built-in function.
613
614A float used in a Boolean context is considered true if it is
615non-zero.
616
617```python
6181.23e45 * 1.23e45 # 1.5129e+90
6191.111111111111111 * 1.111111111111111 # 1.23457
6203.0 / 2 # 1.5
6213 / 2.0 # 1.5
622float(3) / 2 # 1.5
6233.0 // 2.0 # 1.0
624```
625
626### Strings
627
628A string represents an immutable sequence of bytes.
629The [type](#type) of a string is `"string"`.
630
631Strings can represent arbitrary binary data, including zero bytes, but
632most strings contain text, encoded by convention using UTF-8.
633
634The built-in `len` function returns the number of bytes in a string.
635
636Strings may be concatenated with the `+` operator.
637
638The substring expression `s[i:j]` returns the substring of `s` from
639index `i` up to index `j`. The index expression `s[i]` returns the
6401-byte substring `s[i:i+1]`.
641
642Strings are hashable, and thus may be used as keys in a dictionary.
643
644Strings are totally ordered lexicographically, so strings may be
645compared using operators such as `==` and `<`.
646
647Strings are _not_ iterable sequences, so they cannot be used as the operand of
648a `for`-loop, list comprehension, or any other operation than requires
649an iterable sequence.
650To obtain a view of a string as an iterable sequence of numeric byte
651values, 1-byte substrings, numeric Unicode code points, or 1-code
652point substrings, you must explicitly call one of its four methods:
653`elems`, `elem_ords`, `codepoints`, or `codepoint_ords`.
654
655Any value may formatted as a string using the `str` or `repr` built-in
656functions, the `str % tuple` operator, or the `str.format` method.
657
658A string used in a Boolean context is considered true if it is
659non-empty.
660
661Strings have several built-in methods:
662
663* [`capitalize`](#string·capitalize)
664* [`codepoint_ords`](#string·codepoint_ords)
665* [`codepoints`](#string·codepoints)
666* [`count`](#string·count)
667* [`elem_ords`](#string·elem_ords)
668* [`elems`](#string·elems)
669* [`endswith`](#string·endswith)
670* [`find`](#string·find)
671* [`format`](#string·format)
672* [`index`](#string·index)
673* [`isalnum`](#string·isalnum)
674* [`isalpha`](#string·isalpha)
675* [`isdigit`](#string·isdigit)
676* [`islower`](#string·islower)
677* [`isspace`](#string·isspace)
678* [`istitle`](#string·istitle)
679* [`isupper`](#string·isupper)
680* [`join`](#string·join)
681* [`lower`](#string·lower)
682* [`lstrip`](#string·lstrip)
683* [`partition`](#string·partition)
684* [`replace`](#string·replace)
685* [`removeprefix`](#string·removeprefix)
686* [`removesuffix`](#string·removesuffix)
687* [`rfind`](#string·rfind)
688* [`rindex`](#string·rindex)
689* [`rpartition`](#string·rpartition)
690* [`rsplit`](#string·rsplit)
691* [`rstrip`](#string·rstrip)
692* [`split`](#string·split)
693* [`splitlines`](#string·splitlines)
694* [`startswith`](#string·startswith)
695* [`strip`](#string·strip)
696* [`title`](#string·title)
697* [`upper`](#string·upper)
698
699<b>Implementation note:</b>
700The type of a string element varies across implementations.
701There is agreement that byte strings, with text conventionally encoded
702using UTF-8, is the ideal choice, but the Java implementation treats
703strings as sequences of UTF-16 codes and changing it appears
704intractible; see Google Issue b/36360490.
705
706<b>Implementation note:</b>
707The Java implementation does not consistently treat strings as
708iterable; see `testdata/string.star` in the test suite and Google Issue
709b/34385336 for further details.
710
711### Lists
712
713A list is a mutable sequence of values.
714The [type](#type) of a list is `"list"`.
715
716Lists are indexable sequences: the elements of a list may be iterated
717over by `for`-loops, list comprehensions, and various built-in
718functions.
719
720List may be constructed using bracketed list notation:
721
722```python
723[] # an empty list
724[1] # a 1-element list
725[1, 2] # a 2-element list
726```
727
728Lists can also be constructed from any iterable sequence by using the
729built-in `list` function.
730
731The built-in `len` function applied to a list returns the number of elements.
732The index expression `list[i]` returns the element at index i,
733and the slice expression `list[i:j]` returns a new list consisting of
734the elements at indices from i to j.
735
736List elements may be added using the `append` or `extend` methods,
737removed using the `remove` method, or reordered by assignments such as
738`list[i] = list[j]`.
739
740The concatenation operation `x + y` yields a new list containing all
741the elements of the two lists x and y.
742
743For most types, `x += y` is equivalent to `x = x + y`, except that it
744evaluates `x` only once. However, if `x` refers to a list, the statement
745`x += y` does not allocate a new list as `x = x + y` would, but instead
746mutates the original list in place, similar to `x.extend(y)`.
747
748Lists are not hashable, so may not be used in the keys of a dictionary.
749
750A list used in a Boolean context is considered true if it is
751non-empty.
752
753A [_list comprehension_](#comprehensions) creates a new list whose elements are the
754result of some expression applied to each element of another sequence.
755
756```python
757[x*x for x in [1, 2, 3, 4]] # [1, 4, 9, 16]
758```
759
760A list value has these methods:
761
762* [`append`](#list·append)
763* [`clear`](#list·clear)
764* [`extend`](#list·extend)
765* [`index`](#list·index)
766* [`insert`](#list·insert)
767* [`pop`](#list·pop)
768* [`remove`](#list·remove)
769
770### Tuples
771
772A tuple is an immutable sequence of values.
773The [type](#type) of a tuple is `"tuple"`.
774
775Tuples are constructed using parenthesized list notation:
776
777```python
778() # the empty tuple
779(1,) # a 1-tuple
780(1, 2) # a 2-tuple ("pair")
781(1, 2, 3) # a 3-tuple
782```
783
784Observe that for the 1-tuple, the trailing comma is necessary to
785distinguish it from the parenthesized expression `(1)`.
7861-tuples are seldom used.
787
788Starlark, unlike Python, does not permit a trailing comma to appear in
789an unparenthesized tuple expression:
790
791```python
792for k, v, in dict.items(): pass # syntax error at 'in'
793_ = [(v, k) for k, v, in dict.items()] # syntax error at 'in'
794f = lambda a, b, : None # syntax error at ':'
795
796sorted(3, 1, 4, 1,) # ok
797[1, 2, 3, ] # ok
798{1: 2, 3:4, } # ok
799```
800
801Any iterable sequence may be converted to a tuple by using the
802built-in `tuple` function.
803
804Like lists, tuples are indexed sequences, so they may be indexed and
805sliced. The index expression `tuple[i]` returns the tuple element at
806index i, and the slice expression `tuple[i:j]` returns a sub-sequence
807of a tuple.
808
809Tuples are iterable sequences, so they may be used as the operand of a
810`for`-loop, a list comprehension, or various built-in functions.
811
812Unlike lists, tuples cannot be modified.
813However, the mutable elements of a tuple may be modified.
814
815Tuples are hashable (assuming their elements are hashable),
816so they may be used as keys of a dictionary.
817
818Tuples may be concatenated using the `+` operator.
819
820A tuple used in a Boolean context is considered true if it is
821non-empty.
822
823
824### Dictionaries
825
826A dictionary is a mutable mapping from keys to values.
827The [type](#type) of a dictionary is `"dict"`.
828
829Dictionaries provide constant-time operations to insert an element, to
830look up the value for a key, or to remove an element. Dictionaries
831are implemented using hash tables, so keys must be hashable. Hashable
832values include `None`, Booleans, numbers, and strings, and tuples
833composed from hashable values. Most mutable values, such as lists,
834dictionaries, and sets, are not hashable, even when frozen.
835Attempting to use a non-hashable value as a key in a dictionary
836results in a dynamic error.
837
838A [dictionary expression](#dictionary-expressions) specifies a
839dictionary as a set of key/value pairs enclosed in braces:
840
841```python
842coins = {
843 "penny": 1,
844 "nickel": 5,
845 "dime": 10,
846 "quarter": 25,
847}
848```
849
850The expression `d[k]`, where `d` is a dictionary and `k` is a key,
851retrieves the value associated with the key. If the dictionary
852contains no such item, the operation fails:
853
854```python
855coins["penny"] # 1
856coins["dime"] # 10
857coins["silver dollar"] # error: key not found
858```
859
860The number of items in a dictionary `d` is given by `len(d)`.
861A key/value item may be added to a dictionary, or updated if the key
862is already present, by using `d[k]` on the left side of an assignment:
863
864```python
865len(coins) # 4
866coins["shilling"] = 20
867len(coins) # 5, item was inserted
868coins["shilling"] = 5
869len(coins) # 5, existing item was updated
870```
871
872A dictionary can also be constructed using a [dictionary
873comprehension](#comprehension), which evaluates a pair of expressions,
874the _key_ and the _value_, for every element of another iterable such
875as a list. This example builds a mapping from each word to its length
876in bytes:
877
878```python
879words = ["able", "baker", "charlie"]
880{x: len(x) for x in words} # {"charlie": 7, "baker": 5, "able": 4}
881```
882
883Dictionaries are iterable sequences, so they may be used as the
884operand of a `for`-loop, a list comprehension, or various built-in
885functions.
886Iteration yields the dictionary's keys in the order in which they were
887inserted; updating the value associated with an existing key does not
888affect the iteration order.
889
890```python
891x = dict([("a", 1), ("b", 2)]) # {"a": 1, "b": 2}
892x.update([("a", 3), ("c", 4)]) # {"a": 3, "b": 2, "c": 4}
893```
894
895```python
896for name in coins:
897 print(name, coins[name]) # prints "quarter 25", "dime 10", ...
898```
899
900Like all mutable values in Starlark, a dictionary can be frozen, and
901once frozen, all subsequent operations that attempt to update it will
902fail.
903
904A dictionary used in a Boolean context is considered true if it is
905non-empty.
906
907The binary `|` operation may be applied to two dictionaries.
908It yields a new dictionary whose set of keys is the union of the sets
909of keys of the two operands. The corresponding values are taken from
910the operands, where the value taken from the right operand takes
911precedence if both contain a given key. Iterating over the keys in
912the resulting dictionary first yields all keys in the left operand in
913insertion order, then all keys in the right operand that were not
914present in the left operand, again in insertion order.
915
916There is also an augmented assignment version of the `|` operation.
917For two dictionaries `x` and `y`, the statement `x |= y` behaves
918similar to `x = x | y`, but updates `x` in place rather than assigning
919a new dictionary to it.
920
921Dictionaries may be compared for equality using `==` and `!=`. Two
922dictionaries compare equal if they contain the same number of items
923and each key/value item (k, v) found in one dictionary is also present
924in the other. Dictionaries are not ordered; it is an error to compare
925two dictionaries with `<`.
926
927
928A dictionary value has these methods:
929
930* [`clear`](#dict·clear)
931* [`get`](#dict·get)
932* [`items`](#dict·items)
933* [`keys`](#dict·keys)
934* [`pop`](#dict·pop)
935* [`popitem`](#dict·popitem)
936* [`setdefault`](#dict·setdefault)
937* [`update`](#dict·update)
938* [`values`](#dict·values)
939
940### Sets
941
942A set is a mutable set of values.
943The [type](#type) of a set is `"set"`.
944
945Like dictionaries, sets are implemented using hash tables, so the
946elements of a set must be hashable.
947
948Sets may be compared for equality or inequality using `==` and `!=`.
949Two sets compare equal if they contain the same elements.
950
951Sets are iterable sequences, so they may be used as the operand of a
952`for`-loop, a list comprehension, or various built-in functions.
953Iteration yields the set's elements in the order in which they were
954inserted.
955
956The binary `|` and `&` operators compute union and intersection when
957applied to sets. The right operand of the `|` operator may be any
958iterable value. The binary `in` operator performs a set membership
959test when its right operand is a set.
960
961The binary `^` operator performs symmetric difference of two sets.
962
963Sets are instantiated by calling the built-in `set` function, which
964returns a set containing all the elements of its optional argument,
965which must be an iterable sequence. Sets have no literal syntax.
966
967The only method of a set is `union`, which is equivalent to the `|` operator.
968
969A set used in a Boolean context is considered true if it is non-empty.
970
971<b>Implementation note:</b>
972The Go implementation of Starlark requires the `-set` flag to
973enable support for sets.
974The Java implementation does not support sets.
975
976
977### Functions
978
979A function value represents a function defined in Starlark.
980Its [type](#type) is `"function"`.
981A function value used in a Boolean context is always considered true.
982
983Functions defined by a [`def` statement](#function-definitions) are named;
984functions defined by a [`lambda` expression](#lambda-expressions) are anonymous.
985
986Function definitions may be nested, and an inner function may refer to a local variable of an outer function.
987
988A function definition defines zero or more named parameters.
989Starlark has a rich mechanism for passing arguments to functions.
990
991<!-- TODO break up this explanation into caller-side and callee-side
992 parts, and put the former under function calls and the latter
993 under function definitions. Also try to convey that the Callable
994 interface sees the flattened-out args and kwargs and that's what
995 built-ins get.
996-->
997
998The example below shows a definition and call of a function of two
999required parameters, `x` and `y`.
1000
1001```python
1002def idiv(x, y):
1003 return x // y
1004
1005idiv(6, 3) # 2
1006```
1007
1008A call may provide arguments to function parameters either by
1009position, as in the example above, or by name, as in first two calls
1010below, or by a mixture of the two forms, as in the third call below.
1011All the positional arguments must precede all the named arguments.
1012Named arguments may improve clarity, especially in functions of
1013several parameters.
1014
1015```python
1016idiv(x=6, y=3) # 2
1017idiv(y=3, x=6) # 2
1018
1019idiv(6, y=3) # 2
1020```
1021
1022<b>Optional parameters:</b> A parameter declaration may specify a
1023default value using `name=value` syntax; such a parameter is
1024_optional_. The default value expression is evaluated during
1025execution of the `def` statement or evaluation of the `lambda`
1026expression, and the default value forms part of the function value.
1027All optional parameters must follow all non-optional parameters.
1028A function call may omit arguments for any suffix of the optional
1029parameters; the effective values of those arguments are supplied by
1030the function's parameter defaults.
1031
1032```python
1033def f(x, y=3):
1034 return x, y
1035
1036f(1, 2) # (1, 2)
1037f(1) # (1, 3)
1038```
1039
1040If a function parameter's default value is a mutable expression,
1041modifications to the value during one call may be observed by
1042subsequent calls.
1043Beware of this when using lists or dicts as default values.
1044If the function becomes frozen, its parameters' default values become
1045frozen too.
1046
1047```python
1048# module a.star
1049def f(x, list=[]):
1050 list.append(x)
1051 return list
1052
1053f(4, [1,2,3]) # [1, 2, 3, 4]
1054f(1) # [1]
1055f(2) # [1, 2], not [2]!
1056
1057# module b.star
1058load("a.star", "f")
1059f(3) # error: cannot append to frozen list
1060```
1061
1062<b>Variadic functions:</b> Some functions allow callers to provide an
1063arbitrary number of arguments.
1064After all required and optional parameters, a function definition may
1065specify a _variadic arguments_ or _varargs_ parameter, indicated by a
1066star preceding the parameter name: `*args`.
1067Any surplus positional arguments provided by the caller are formed
1068into a tuple and assigned to the `args` parameter.
1069
1070```python
1071def f(x, y, *args):
1072 return x, y, args
1073
1074f(1, 2) # (1, 2, ())
1075f(1, 2, 3, 4) # (1, 2, (3, 4))
1076```
1077
1078<b>Keyword-variadic functions:</b> Some functions allow callers to
1079provide an arbitrary sequence of `name=value` keyword arguments.
1080A function definition may include a final _keyword arguments_ or
1081_kwargs_ parameter, indicated by a double-star preceding the parameter
1082name: `**kwargs`.
1083Any surplus named arguments that do not correspond to named parameters
1084are collected in a new dictionary and assigned to the `kwargs` parameter:
1085
1086```python
1087def f(x, y, **kwargs):
1088 return x, y, kwargs
1089
1090f(1, 2) # (1, 2, {})
1091f(x=2, y=1) # (2, 1, {})
1092f(x=2, y=1, z=3) # (2, 1, {"z": 3})
1093```
1094
1095It is a static error if any two parameters of a function have the same name.
1096
1097Just as a function definition may accept an arbitrary number of
1098positional or named arguments, a function call may provide an
1099arbitrary number of positional or named arguments supplied by a
1100list or dictionary:
1101
1102```python
1103def f(a, b, c=5):
1104 return a * b + c
1105
1106f(*[2, 3]) # 11
1107f(*[2, 3, 7]) # 13
1108f(*[2]) # error: f takes at least 2 arguments (1 given)
1109
1110f(**dict(b=3, a=2)) # 11
1111f(**dict(c=7, a=2, b=3)) # 13
1112f(**dict(a=2)) # error: f takes at least 2 arguments (1 given)
1113f(**dict(d=4)) # error: f got unexpected keyword argument "d"
1114```
1115
1116Once the parameters have been successfully bound to the arguments
1117supplied by the call, the sequence of statements that comprise the
1118function body is executed.
1119
1120It is a static error if a function call has two named arguments of the
1121same name, such as `f(x=1, x=2)`. A call that provides a `**kwargs`
1122argument may yet have two values for the same name, such as
1123`f(x=1, **dict(x=2))`. This results in a dynamic error.
1124
1125Function arguments are evaluated in the order they appear in the call.
1126<!-- see https://github.com/bazelbuild/starlark/issues/13 -->
1127
1128Unlike Python, Starlark does not allow more than one `*args` argument in a
1129call, and if a `*args` argument is present it must appear after all
1130positional and named arguments.
1131
1132The final argument to a function call may be followed by a trailing comma.
1133
1134A function call completes normally after the execution of either a
1135`return` statement, or of the last statement in the function body.
1136The result of the function call is the value of the return statement's
1137operand, or `None` if the return statement had no operand or if the
1138function completeted without executing a return statement.
1139
1140```python
1141def f(x):
1142 if x == 0:
1143 return
1144 if x < 0:
1145 return -x
1146 print(x)
1147
1148f(1) # returns None after printing "1"
1149f(0) # returns None without printing
1150f(-1) # returns 1 without printing
1151```
1152
1153<b>Implementation note:</b>
1154The Go implementation of Starlark requires the `-recursion`
1155flag to allow recursive functions.
1156
1157
1158If the `-recursion` flag is not specified it is a dynamic error for a
1159function to call itself or another function value with the same
1160declaration.
1161
1162```python
1163def fib(x):
1164 if x < 2:
1165 return x
1166 return fib(x-2) + fib(x-1) # dynamic error: function fib called recursively
1167
1168fib(5)
1169```
1170
1171This rule, combined with the invariant that all loops are iterations
1172over finite sequences, implies that Starlark programs can not be
1173Turing complete unless the `-recursion` flag is specified.
1174
1175<!-- This rule is supposed to deter people from abusing Starlark for
1176 inappropriate uses, especially in the build system.
1177 It may work for that purpose, but it doesn't stop Starlark programs
1178 from consuming too much time or space. Perhaps it should be a
1179 dialect option.
1180-->
1181
1182
1183
1184### Built-in functions
1185
1186A built-in function is a function or method implemented in Go by the interpreter
1187or the application into which the interpreter is embedded.
1188
1189The [type](#type) of a built-in function is `"builtin_function_or_method"`.
1190
1191A built-in function value used in a Boolean context is always considered true.
1192
1193Many [built-in functions](#built-in-constants-and-functions) are predeclared
1194in the environment (see [Name binding and variables](#name-binding-and-variables)).
1195Some built-in functions such as `len` are _universal_, that is,
1196available to all Starlark programs.
1197The host application may predeclare additional built-in functions
1198in the environment of a specific module.
1199
1200Except where noted, built-in functions accept only positional arguments.
1201The parameter names serve merely as documentation.
1202
1203Most built-in functions that have a Boolean parameter require its
1204argument to be `True` or `False`. Unlike `if` statements, other values
1205are not implicitly converted to their truth value and instead cause a
1206dynamic error.
1207
1208
1209## Name binding and variables
1210
1211After a Starlark file is parsed, but before its execution begins, the
1212Starlark interpreter checks statically that the program is well formed.
1213For example, `break` and `continue` statements may appear only within
1214a loop; a `return` statement may appear only within a
1215function; and `load` statements may appear only outside any function.
1216
1217_Name resolution_ is the static checking process that
1218resolves names to variable bindings.
1219During execution, names refer to variables. Statically, names denote
1220places in the code where variables are created; these places are
1221called _bindings_. A name may denote different bindings at different
1222places in the program. The region of text in which a particular name
1223refers to the same binding is called that binding's _scope_.
1224
1225Four Starlark constructs bind names, as illustrated in the example below:
1226`load` statements (`a` and `b`),
1227`def` statements (`c`),
1228function parameters (`d`),
1229and assignments (`e`, `h`, including the augmented assignment `e += 1`).
1230Variables may be assigned or re-assigned explicitly (`e`, `h`), or implicitly, as
1231in a `for`-loop (`f`) or comprehension (`g`, `i`).
1232
1233```python
1234load("lib.star", "a", b="B")
1235
1236def c(d):
1237 e = 0
1238 for f in d:
1239 print([True for g in f])
1240 e += 1
1241
1242h = [2*i for i in a]
1243```
1244
1245The environment of a Starlark program is structured as a tree of
1246_lexical blocks_, each of which may contain name bindings.
1247The tree of blocks is parallel to the syntax tree.
1248Blocks are of five kinds.
1249
1250<!-- Avoid the term "built-in" block since that's also a type. -->
1251At the root of the tree is the _predeclared_ block,
1252which binds several names implicitly.
1253The set of predeclared names includes the universal
1254constant values `None`, `True`, and `False`, and
1255various built-in functions such as `len` and `list`;
1256these functions are immutable and stateless.
1257An application may pre-declare additional names
1258to provide domain-specific functions to that file, for example.
1259These additional functions may have side effects on the application.
1260Starlark programs cannot change the set of predeclared bindings
1261or assign new values to them.
1262
1263Nested beneath the predeclared block is the _module_ block,
1264which contains the bindings of the current module.
1265Bindings in the module block (such as `c`, and `h` in the
1266example) are called _global_ and may be visible to other modules.
1267The module block is empty at the start of the file
1268and is populated by top-level binding statements.
1269
1270Nested beneath the module block is the _file_ block,
1271which contains bindings local to the current file.
1272Names in this block (such as `a` and `b` in the example)
1273are bound only by `load` statements.
1274The sets of names bound in the file block and in the module block do not overlap:
1275it is an error for a load statement to bind the name of a global,
1276or for a top-level statement to bind a name bound by a load statement.
1277
1278A file block contains a _function_ block for each top-level
1279function, and a _comprehension_ block for each top-level comprehension.
1280Bindings in either of these kinds of block,
1281and in the file block itself, are called _local_.
1282(In the example, the bindings for `e`, `f`, `g`, and `i` are all local.)
1283Additional functions and comprehensions, and their blocks, may be
1284nested in any order, to any depth.
1285
1286If name is bound anywhere within a block, all uses of the name within
1287the block are treated as references to that binding,
1288even if the use appears before the binding.
1289This is true even at the top level, unlike Python.
1290The binding of `y` on the last line of the example below makes `y`
1291local to the function `hello`, so the use of `y` in the print
1292statement also refers to the local `y`, even though it appears
1293earlier.
1294
1295```python
1296y = "goodbye"
1297
1298def hello():
1299 for x in (1, 2):
1300 if x == 2:
1301 print(y) # prints "hello"
1302 if x == 1:
1303 y = "hello"
1304```
1305It is a dynamic error to evaluate a reference to a local variable
1306before it has been bound:
1307
1308```python
1309def f():
1310 print(x) # dynamic error: local variable x referenced before assignment
1311 x = "hello"
1312```
1313
1314The same is true for global variables:
1315
1316```python
1317print(x) # dynamic error: global variable x referenced before assignment
1318x = "hello"
1319```
1320
1321The same is also true for nested loops in comprehensions.
1322In the (unnatural) examples below, the scope of the variables `x`, `y`,
1323and `z` is the entire compehension block, except the operand of the first
1324loop (`[]` or `[1]`), which is resolved in the enclosing environment.
1325The second loop may thus refer to variables defined by the third (`z`),
1326even though such references would fail if actually executed.
1327
1328```
1329[1//0 for x in [] for y in z for z in ()] # [] (no error)
1330[1//0 for x in [1] for y in z for z in ()] # dynamic error: local variable z referenced before assignment
1331```
1332
1333
1334<!-- This is similar to Python[23]. Presumed rational: it resembles
1335 the desugaring to nested loop statements, in which the scope
1336 of all three variables is the entire enclosing function,
1337 including the portion before the bindings.
1338
1339 def f():
1340 ...
1341 for x in []:
1342 for y in z:
1343 for z in ():
1344 1//0
1345-->
1346
1347It is a static error to refer to a name that has no binding at all.
1348```
1349def f():
1350 if False:
1351 g() # static error: undefined: g
1352```
1353(This behavior differs from Python, which treats such references as global,
1354and thus does not report an error until the expression is evaluated.)
1355
1356<!-- Consequently, the REPL, which consumes one compound statement at a time,
1357 cannot resolve forward references such as
1358 def f(): return K
1359 K = 1
1360 because the first chunk has an unresolved reference to K.
1361-->
1362
1363It is a static error to bind a global variable already explicitly bound in the file:
1364
1365```python
1366x = 1
1367x = 2 # static error: cannot reassign global x declared on line 1
1368```
1369
1370<!-- The above rule, and the rule that forbids if-statements and loops at
1371 top level, exist to ensure that there is exactly one statement
1372 that binds each global variable, which makes cross-referenced
1373 documentation more useful, the designers assure me, but
1374 I am skeptical that it's worth the trouble. -->
1375
1376If a name was pre-bound by the application, the Starlark program may
1377explicitly bind it, but only once.
1378
1379An augmented assignment statement such as `x += y` is considered both a
1380reference to `x` and a binding use of `x`, so it may not be used at
1381top level.
1382
1383<b>Implementation note:</b>
1384The Go implementation of Starlark permits augmented assignments to appear
1385at top level if the `-globalreassign` flag is enabled.
1386
1387A function may refer to variables defined in an enclosing function.
1388In this example, the inner function `f` refers to a variable `x`
1389that is local to the outer function `squarer`.
1390`x` is a _free variable_ of `f`.
1391The function value (`f`) created by a `def` statement holds a
1392reference to each of its free variables so it may use
1393them even after the enclosing function has returned.
1394
1395```python
1396def squarer():
1397 x = [0]
1398 def f():
1399 x[0] += 1
1400 return x[0]*x[0]
1401 return f
1402
1403sq = squarer()
1404print(sq(), sq(), sq(), sq()) # "1 4 9 16"
1405```
1406
1407An inner function cannot assign to a variable bound in an enclosing
1408function, because the assignment would bind the variable in the
1409inner function.
1410In the example below, the `x += 1` statement binds `x` within `f`,
1411hiding the outer `x`.
1412Execution fails because the inner `x` has not been assigned before the
1413attempt to increment it.
1414
1415```python
1416def squarer():
1417 x = 0
1418 def f():
1419 x += 1 # dynamic error: local variable x referenced before assignment
1420 return x*x
1421 return f
1422
1423sq = squarer()
1424```
1425
1426(Starlark has no equivalent of Python's `nonlocal` or `global`
1427declarations, but as the first version of `squarer` showed, this
1428omission can be worked around by using a list of a single element.)
1429
1430
1431A name appearing after a dot, such as `split` in
1432`get_filename().split('/')`, is not resolved statically.
1433The [dot expression](#dot-expressions) `.split` is a dynamic operation
1434on the value returned by `get_filename()`.
1435
1436
1437## Value concepts
1438
1439Starlark has eleven core [data types](#data-types). An application
1440that embeds the Starlark intepreter may define additional types that
1441behave like Starlark values. All values, whether core or
1442application-defined, implement a few basic behaviors:
1443
1444```text
1445str(x) -- return a string representation of x
1446type(x) -- return a string describing the type of x
1447bool(x) -- convert x to a Boolean truth value
1448```
1449
1450### Identity and mutation
1451
1452Starlark is an imperative language: programs consist of sequences of
1453statements executed for their side effects.
1454For example, an assignment statement updates the value held by a
1455variable, and calls to some built-in functions such as `print` change
1456the state of the application that embeds the interpreter.
1457
1458Values of some data types, such as `NoneType`, `bool`, `int`, `float`, and
1459`string`, are _immutable_; they can never change.
1460Immutable values have no notion of _identity_: it is impossible for a
1461Starlark program to tell whether two integers, for instance, are
1462represented by the same object; it can tell only whether they are
1463equal.
1464
1465Values of other data types, such as `list`, `dict`, and `set`, are
1466_mutable_: they may be modified by a statement such as `a[i] = 0` or
1467`items.clear()`. Although `tuple` and `function` values are not
1468directly mutable, they may refer to mutable values indirectly, so for
1469this reason we consider them mutable too. Starlark values of these
1470types are actually _references_ to variables.
1471
1472Copying a reference to a variable, using an assignment statement for
1473instance, creates an _alias_ for the variable, and the effects of
1474operations applied to the variable through one alias are visible
1475through all others.
1476
1477```python
1478x = [] # x refers to a new empty list variable
1479y = x # y becomes an alias for x
1480x.append(1) # changes the variable referred to by x
1481print(y) # "[1]"; y observes the mutation
1482```
1483
1484Starlark uses _call-by-value_ parameter passing: in a function call,
1485argument values are assigned to function parameters as if by
1486assignment statements. If the values are references, the caller and
1487callee may refer to the same variables, so if the called function
1488changes the variable referred to by a parameter, the effect may also
1489be observed by the caller:
1490
1491```python
1492def f(y):
1493 y.append(1) # changes the variable referred to by x
1494
1495x = [] # x refers to a new empty list variable
1496f(x) # f's parameter y becomes an alias for x
1497print(x) # "[1]"; x observes the mutation
1498```
1499
1500
1501As in all imperative languages, understanding _aliasing_, the
1502relationship between reference values and the variables to which they
1503refer, is crucial to writing correct programs.
1504
1505### Freezing a value
1506
1507Starlark has a feature unusual among imperative programming languages:
1508a mutable value may be _frozen_ so that all subsequent attempts to
1509mutate it fail with a dynamic error; the value, and all other values
1510reachable from it, become _immutable_.
1511
1512Immediately after execution of a Starlark module, all values in its
1513top-level environment are frozen. Because all the global variables of
1514an initialized Starlark module are immutable, the module may be published to
1515and used by other threads in a parallel program without the need for
1516locks. For example, the Bazel build system loads and executes BUILD
1517and .bzl files in parallel, and two modules being executed
1518concurrently may freely access variables or call functions from a
1519third without the possibility of a race condition.
1520
1521### Hashing
1522
1523The `dict` and `set` data types are implemented using hash tables, so
1524only _hashable_ values are suitable as keys of a `dict` or elements of
1525a `set`. Attempting to use a non-hashable value as the key in a hash
1526table results in a dynamic error.
1527
1528The hash of a value is an unspecified integer chosen so that two equal
1529values have the same hash, in other words, `x == y => hash(x) == hash(y)`.
1530A hashable value has the same hash throughout its lifetime.
1531
1532Values of the types `NoneType`, `bool`, `int`, `float`, and `string`,
1533which are all immutable, are hashable.
1534
1535Values of mutable types such as `list`, `dict`, and `set` are not
1536hashable. These values remain unhashable even if they have become
1537immutable due to _freezing_.
1538
1539A `tuple` value is hashable only if all its elements are hashable.
1540Thus `("localhost", 80)` is hashable but `([127, 0, 0, 1], 80)` is not.
1541
1542Values of the types `function` and `builtin_function_or_method` are also hashable.
1543Although functions are not necessarily immutable, as they may be
1544closures that refer to mutable variables, instances of these types
1545are compared by reference identity (see [Comparisons](#comparisons)),
1546so their hash values are derived from their identity.
1547
1548
1549### Sequence types
1550
1551Many Starlark data types represent a _sequence_ of values: lists,
1552tuples, and sets are sequences of arbitrary values, and in many
1553contexts dictionaries act like a sequence of their keys.
1554
1555We can classify different kinds of sequence types based on the
1556operations they support.
1557Each is listed below using the name of its corresponding interface in
1558the interpreter's Go API.
1559
1560* `Iterable`: an _iterable_ value lets us process each of its elements in a fixed order.
1561 Examples: `dict`, `set`, `list`, `tuple`, but not `string`.
1562* `Sequence`: a _sequence of known length_ lets us know how many elements it
1563 contains without processing them.
1564 Examples: `dict`, `set`, `list`, `tuple`, but not `string`.
1565* `Indexable`: an _indexed_ type has a fixed length and provides efficient
1566 random access to its elements, which are identified by integer indices.
1567 Examples: `string`, `tuple`, and `list`.
1568* `SetIndexable`: a _settable indexed type_ additionally allows us to modify the
1569 element at a given integer index. Example: `list`.
1570* `Mapping`: a mapping is an association of keys to values. Example: `dict`.
1571
1572Although all of Starlark's core data types for sequences implement at
1573least the `Sequence` contract, it's possible for an application
1574that embeds the Starlark interpreter to define additional data types
1575representing sequences of unknown length that implement only the `Iterable` contract.
1576
1577Strings are not iterable, though they do support the `len(s)` and
1578`s[i]` operations. Starlark deviates from Python here to avoid a common
1579pitfall in which a string is used by mistake where a list containing a
1580single string was intended, resulting in its interpretation as a sequence
1581of bytes.
1582
1583Most Starlark operators and built-in functions that need a sequence
1584of values will accept any iterable.
1585
1586It is a dynamic error to mutate a sequence such as a list, set, or
1587dictionary while iterating over it.
1588
1589```python
1590def increment_values(dict):
1591 for k in dict:
1592 dict[k] += 1 # error: cannot insert into hash table during iteration
1593
1594dict = {"one": 1, "two": 2}
1595increment_values(dict)
1596```
1597
1598
1599### Indexing
1600
1601Many Starlark operators and functions require an index operand `i`,
1602such as `a[i]` or `list.insert(i, x)`. Others require two indices `i`
1603and `j` that indicate the start and end of a sub-sequence, such as
1604`a[i:j]`, `list.index(x, i, j)`, or `string.find(x, i, j)`.
1605All such operations follow similar conventions, described here.
1606
1607Indexing in Starlark is *zero-based*. The first element of a string
1608or list has index 0, the next 1, and so on. The last element of a
1609sequence of length `n` has index `n-1`.
1610
1611```python
1612"hello"[0] # "h"
1613"hello"[4] # "o"
1614"hello"[5] # error: index out of range
1615```
1616
1617For sub-sequence operations that require two indices, the first is
1618_inclusive_ and the second _exclusive_. Thus `a[i:j]` indicates the
1619sequence starting with element `i` up to but not including element
1620`j`. The length of this sub-sequence is `j-i`. This convention is known
1621as *half-open indexing*.
1622
1623```python
1624"hello"[1:4] # "ell"
1625```
1626
1627Either or both of the index operands may be omitted. If omitted, the
1628first is treated equivalent to 0 and the second is equivalent to the
1629length of the sequence:
1630
1631```python
1632"hello"[1:] # "ello"
1633"hello"[:4] # "hell"
1634```
1635
1636It is permissible to supply a negative integer to an indexing
1637operation. The effective index is computed from the supplied value by
1638the following two-step procedure. First, if the value is negative, the
1639length of the sequence is added to it. This provides a convenient way
1640to address the final elements of the sequence:
1641
1642```python
1643"hello"[-1] # "o", like "hello"[4]
1644"hello"[-3:-1] # "ll", like "hello"[2:4]
1645```
1646
1647Second, for sub-sequence operations, if the value is still negative, it
1648is replaced by zero, or if it is greater than the length `n` of the
1649sequence, it is replaced by `n`. In effect, the index is "truncated" to
1650the nearest value in the range `[0:n]`.
1651
1652```python
1653"hello"[-1000:+1000] # "hello"
1654```
1655
1656This truncation step does not apply to indices of individual elements:
1657
1658```python
1659"hello"[-6] # error: index out of range
1660"hello"[-5] # "h"
1661"hello"[4] # "o"
1662"hello"[5] # error: index out of range
1663```
1664
1665
1666## Expressions
1667
1668An expression specifies the computation of a value.
1669
1670The Starlark grammar defines several categories of expression.
1671An _operand_ is an expression consisting of a single token (such as an
1672identifier or a literal), or a bracketed expression.
1673Operands are self-delimiting.
1674An operand may be followed by any number of dot, call, or slice
1675suffixes, to form a _primary_ expression.
1676In some places in the Starlark grammar where an expression is expected,
1677it is legal to provide a comma-separated list of expressions denoting
1678a tuple.
1679The grammar uses `Expression` where a multiple-component expression is allowed,
1680and `Test` where it accepts an expression of only a single component.
1681
1682```grammar {.good}
1683Expression = Test {',' Test} .
1684
1685Test = LambdaExpr | IfExpr | PrimaryExpr | UnaryExpr | BinaryExpr .
1686
1687PrimaryExpr = Operand
1688 | PrimaryExpr DotSuffix
1689 | PrimaryExpr CallSuffix
1690 | PrimaryExpr SliceSuffix
1691 .
1692
1693Operand = identifier
1694 | int | float | string
1695 | ListExpr | ListComp
1696 | DictExpr | DictComp
1697 | '(' [Expression] [,] ')'
1698 | ('-' | '+') PrimaryExpr
1699 .
1700
1701DotSuffix = '.' identifier .
1702CallSuffix = '(' [Arguments [',']] ')' .
1703SliceSuffix = '[' [Expression] [':' Test [':' Test]] ']' .
1704```
1705
1706TODO: resolve position of +x, -x, and 'not x' in grammar: Operand or UnaryExpr?
1707
1708### Identifiers
1709
1710```grammar {.good} {.good}
1711Primary = identifier
1712```
1713
1714An identifier is a name that identifies a value.
1715
1716Lookup of locals and globals may fail if not yet defined.
1717
1718### Literals
1719
1720Starlark supports literals of three different kinds:
1721
1722```grammar {.good}
1723Primary = int | float | string
1724```
1725
1726Evaluation of a literal yields a value of the given type (string, int,
1727or float) with the given value.
1728See [Literals](#lexical-elements) for details.
1729
1730### Parenthesized expressions
1731
1732```grammar {.good}
1733Primary = '(' [Expression] ')'
1734```
1735
1736A single expression enclosed in parentheses yields the result of that expression.
1737Explicit parentheses may be used for clarity,
1738or to override the default association of subexpressions.
1739
1740```python
17411 + 2 * 3 + 4 # 11
1742(1 + 2) * (3 + 4) # 21
1743```
1744
1745If the parentheses are empty, or contain a single expression followed
1746by a comma, or contain two or more expressions, the expression yields a tuple.
1747
1748```python
1749() # (), the empty tuple
1750(1,) # (1,), a tuple of length 1
1751(1, 2) # (1, 2), a 2-tuple or pair
1752(1, 2, 3) # (1, 2, 3), a 3-tuple or triple
1753```
1754
1755In some contexts, such as a `return` or assignment statement or the
1756operand of a `for` statement, a tuple may be expressed without
1757parentheses.
1758
1759```python
1760x, y = 1, 2
1761
1762return 1, 2
1763
1764for x in 1, 2:
1765 print(x)
1766```
1767
1768Starlark (like Python 3) does not accept an unparenthesized tuple
1769expression as the operand of a list comprehension:
1770
1771```python
1772[2*x for x in 1, 2, 3] # parse error: unexpected ','
1773```
1774
1775### Dictionary expressions
1776
1777A dictionary expression is a comma-separated list of colon-separated
1778key/value expression pairs, enclosed in curly brackets, and it yields
1779a new dictionary object.
1780An optional comma may follow the final pair.
1781
1782```grammar {.good}
1783DictExpr = '{' [Entries [',']] '}' .
1784Entries = Entry {',' Entry} .
1785Entry = Test ':' Test .
1786```
1787
1788Examples:
1789
1790
1791```python
1792{}
1793{"one": 1}
1794{"one": 1, "two": 2,}
1795```
1796
1797The key and value expressions are evaluated in left-to-right order.
1798Evaluation fails if the same key is used multiple times.
1799
1800Only [hashable](#hashing) values may be used as the keys of a dictionary.
1801This includes all built-in types except dictionaries, sets, and lists;
1802a tuple is hashable only if its elements are hashable.
1803
1804
1805### List expressions
1806
1807A list expression is a comma-separated list of element expressions,
1808enclosed in square brackets, and it yields a new list object.
1809An optional comma may follow the last element expression.
1810
1811```grammar {.good}
1812ListExpr = '[' [Expression [',']] ']' .
1813```
1814
1815Element expressions are evaluated in left-to-right order.
1816
1817Examples:
1818
1819```python
1820[] # [], empty list
1821[1] # [1], a 1-element list
1822[1, 2, 3,] # [1, 2, 3], a 3-element list
1823```
1824
1825### Unary operators
1826
1827There are three unary operators, all appearing before their operand:
1828`+`, `-`, `~`, and `not`.
1829
1830```grammar {.good}
1831UnaryExpr = '+' PrimaryExpr
1832 | '-' PrimaryExpr
1833 | '~' PrimaryExpr
1834 | 'not' Test
1835 .
1836```
1837
1838```text
1839+ number unary positive (int, float)
1840- number unary negation (int, float)
1841~ number unary bitwise inversion (int)
1842not x logical negation (any type)
1843```
1844
1845The `+` and `-` operators may be applied to any number
1846(`int` or `float`) and return the number unchanged.
1847Unary `+` is never necessary in a correct program,
1848but may serve as an assertion that its operand is a number,
1849or as documentation.
1850
1851```python
1852if x > 0:
1853 return +1
1854else if x < 0:
1855 return -1
1856else:
1857 return 0
1858```
1859
1860The `not` operator returns the negation of the truth value of its
1861operand.
1862
1863```python
1864not True # False
1865not False # True
1866not [1, 2, 3] # False
1867not "" # True
1868not 0 # True
1869```
1870
1871The `~` operator yields the bitwise inversion of its integer argument.
1872The bitwise inversion of x is defined as -(x+1).
1873
1874```python
1875~1 # -2
1876~-1 # 0
1877~0 # -1
1878```
1879
1880
1881### Binary operators
1882
1883Starlark has the following binary operators, arranged in order of increasing precedence:
1884
1885```text
1886or
1887and
1888== != < > <= >= in not in
1889|
1890^
1891&
1892<< >>
1893- +
1894* / // %
1895```
1896
1897Comparison operators, `in`, and `not in` are non-associative,
1898so the parser will not accept `0 <= i < n`.
1899All other binary operators of equal precedence associate to the left.
1900
1901```grammar {.good}
1902BinaryExpr = Test {Binop Test} .
1903
1904Binop = 'or'
1905 | 'and'
1906 | '==' | '!=' | '<' | '>' | '<=' | '>=' | 'in' | 'not' 'in'
1907 | '|'
1908 | '^'
1909 | '&'
1910 | '-' | '+'
1911 | '*' | '%' | '/' | '//'
1912 | '<<' | '>>'
1913 .
1914```
1915
1916#### `or` and `and`
1917
1918The `or` and `and` operators yield, respectively, the logical disjunction and
1919conjunction of their arguments, which need not be Booleans.
1920The expression `x or y` yields the value of `x` if its truth value is `True`,
1921or the value of `y` otherwise.
1922
1923```starlark
1924False or False # False
1925False or True # True
1926True or False # True
1927True or True # True
1928
19290 or "hello" # "hello"
19301 or "hello" # 1
1931```
1932
1933Similarly, `x and y` yields the value of `x` if its truth value is
1934`False`, or the value of `y` otherwise.
1935
1936```starlark
1937False and False # False
1938False and True # False
1939True and False # False
1940True and True # True
1941
19420 and "hello" # 0
19431 and "hello" # "hello"
1944```
1945
1946These operators use "short circuit" evaluation, so the second
1947expression is not evaluated if the value of the first expression has
1948already determined the result, allowing constructions like these:
1949
1950```python
1951len(x) > 0 and x[0] == 1 # x[0] is not evaluated if x is empty
1952x and x[0] == 1
1953len(x) == 0 or x[0] == ""
1954not x or not x[0]
1955```
1956
1957#### Comparisons
1958
1959The `==` operator reports whether its operands are equal; the `!=`
1960operator is its negation.
1961
1962The operators `<`, `>`, `<=`, and `>=` perform an ordered comparison
1963of their operands. It is an error to apply these operators to
1964operands of unequal type, unless one of the operands is an `int` and
1965the other is a `float`. Of the built-in types, only the following
1966support ordered comparison, using the ordering relation shown:
1967
1968```shell
1969NoneType # None <= None
1970bool # False < True
1971int # mathematical
1972float # as defined by IEEE 754
1973string # lexicographical
1974tuple # lexicographical
1975list # lexicographical
1976```
1977
1978Comparison of floating point values follows the IEEE 754 standard,
1979which breaks several mathematical identities. For example, if `x` is
1980a `NaN` value, the comparisons `x < y`, `x == y`, and `x > y` all
1981yield false for all values of `y`.
1982
1983Applications may define additional types that support ordered
1984comparison.
1985
1986The remaining built-in types support only equality comparisons.
1987Values of type `dict` or `set` compare equal if their elements compare
1988equal, and values of type `function` or `builtin_function_or_method` are equal only to
1989themselves.
1990
1991```shell
1992dict # equal contents
1993set # equal contents
1994function # identity
1995builtin_function_or_method # identity
1996```
1997
1998#### Arithmetic operations
1999
2000The following table summarizes the binary arithmetic operations
2001available for built-in types:
2002
2003```shell
2004Arithmetic (int or float; result has type float unless both operands have type int)
2005 number + number # addition
2006 number - number # subtraction
2007 number * number # multiplication
2008 number / number # real division (result is always a float)
2009 number // number # floored division
2010 number % number # remainder of floored division
2011 number ^ number # bitwise XOR
2012 number << number # bitwise left shift
2013 number >> number # bitwise right shift
2014
2015Concatenation
2016 string + string
2017 list + list
2018 tuple + tuple
2019
2020Repetition (string/list/tuple)
2021 int * sequence
2022 sequence * int
2023
2024String interpolation
2025 string % any # see String Interpolation
2026
2027Sets
2028 int | int # bitwise union (OR)
2029 set | set # set union
2030 int & int # bitwise intersection (AND)
2031 set & set # set intersection
2032 set ^ set # set symmetric difference
2033
2034Dict
2035 dict | dict # ordered union
2036```
2037
2038The operands of the arithmetic operators `+`, `-`, `*`, `//`, and
2039`%` must both be numbers (`int` or `float`) but need not have the same type.
2040The type of the result has type `int` only if both operands have that type.
2041The result of real division `/` always has type `float`.
2042
2043The `+` operator may be applied to non-numeric operands of the same
2044type, such as two lists, two tuples, or two strings, in which case it
2045computes the concatenation of the two operands and yields a new value of
2046the same type.
2047
2048```python
2049"Hello, " + "world" # "Hello, world"
2050(1, 2) + (3, 4) # (1, 2, 3, 4)
2051[1, 2] + [3, 4] # [1, 2, 3, 4]
2052```
2053
2054The `*` operator may be applied to an integer _n_ and a value of type
2055`string`, `list`, or `tuple`, in which case it yields a new value
2056of the same sequence type consisting of _n_ repetitions of the original sequence.
2057The order of the operands is immaterial.
2058Negative values of _n_ behave like zero.
2059
2060```python
2061'mur' * 2 # 'murmur'
20623 * range(3) # [0, 1, 2, 0, 1, 2, 0, 1, 2]
2063```
2064
2065Applications may define additional types that support any subset of
2066these operators.
2067
2068The `&` operator requires two operands of the same type, either `int` or `set`.
2069For integers, it yields the bitwise intersection (AND) of its operands.
2070For sets, it yields a new set containing the intersection of the
2071elements of the operand sets, preserving the element order of the left
2072operand.
2073
2074The `|` operator likewise computes bitwise, set, or dict unions.
2075The result of `set | set` is a new set whose elements are the
2076union of the operands, preserving the order of the elements of the
2077operands, left before right.
2078Similarly, the result of `dict | dict` is a new dict whose entries are
2079the union of the operands, preserving the order in which keys first
2080appear, but using the value from the right operand for each key
2081common to both dicts.
2082
2083The `^` operator accepts operands of either `int` or `set` type.
2084For integers, it yields the bitwise XOR (exclusive OR) of its operands.
2085For sets, it yields a new set containing elements of either first or second
2086operand but not both (symmetric difference).
2087
2088The `<<` and `>>` operators require operands of `int` type both. They shift
2089the first operand to the left or right by the number of bits given by the
2090second operand. It is a dynamic error if the second operand is negative.
2091Implementations may impose a limit on the second operand of a left shift.
2092
2093```python
20940x12345678 & 0xFF # 0x00000078
20950x12345678 | 0xFF # 0x123456FF
20960b01011101 ^ 0b110101101 # 0b111110000
20970b01011101 >> 2 # 0b010111
20980b01011101 << 2 # 0b0101110100
2099
2100set([1, 2]) & set([2, 3]) # set([2])
2101set([1, 2]) | set([2, 3]) # set([1, 2, 3])
2102set([1, 2]) ^ set([2, 3]) # set([1, 3])
2103```
2104
2105<b>Implementation note:</b>
2106The Go implementation of Starlark requires the `-set` flag to
2107enable support for sets.
2108The Java implementation does not support sets.
2109
2110
2111#### Membership tests
2112
2113```text
2114 any in sequence (list, tuple, dict, set, string)
2115 any not in sequence
2116```
2117
2118The `in` operator reports whether its first operand is a member of its
2119second operand, which must be a list, tuple, dict, set, or string.
2120The `not in` operator is its negation.
2121Both return a Boolean.
2122
2123The meaning of membership varies by the type of the second operand:
2124the members of a list, tuple, or set are its elements;
2125the members of a dict are its keys;
2126the members of a string are all its substrings.
2127
2128```python
21291 in [1, 2, 3] # True
21304 in (1, 2, 3) # False
21314 not in set([1, 2, 3]) # True
2132
2133d = {"one": 1, "two": 2}
2134"one" in d # True
2135"three" in d # False
21361 in d # False
2137[] in d # False
2138
2139"nasty" in "dynasty" # True
2140"a" in "banana" # True
2141"f" not in "way" # True
2142```
2143
2144#### String interpolation
2145
2146The expression `format % args` performs _string interpolation_, a
2147simple form of template expansion.
2148The `format` string is interpreted as a sequence of literal portions
2149and _conversions_.
2150Each conversion, which starts with a `%` character, is replaced by its
2151corresponding value from `args`.
2152The characters following `%` in each conversion determine which
2153argument it uses and how to convert it to a string.
2154
2155Each `%` character marks the start of a conversion specifier, unless
2156it is immediately followed by another `%`, in which case both
2157characters together denote a literal percent sign.
2158
2159If the `"%"` is immediately followed by `"(key)"`, the parenthesized
2160substring specifies the key of the `args` dictionary whose
2161corresponding value is the operand to convert.
2162Otherwise, the conversion's operand is the next element of `args`,
2163which must be a tuple with exactly one component per conversion,
2164unless the format string contains only a single conversion, in which
2165case `args` itself is its operand.
2166
2167Starlark does not support the flag, width, and padding specifiers
2168supported by Python's `%` and other variants of C's `printf`.
2169
2170After the optional `(key)` comes a single letter indicating what
2171operand types are valid and how to convert the operand `x` to a string:
2172
2173```text
2174% none literal percent sign
2175s any as if by str(x)
2176r any as if by repr(x)
2177d number signed integer decimal
2178i number signed integer decimal
2179o number signed octal
2180x number signed hexadecimal, lowercase
2181X number signed hexadecimal, uppercase
2182e number float exponential format, lowercase
2183E number float exponential format, uppercase
2184f number float decimal format, lowercase
2185F number float decimal format, uppercase
2186g number like %e for large exponents, %f otherwise
2187G number like %E for large exponents, %F otherwise
2188c string x (string must encode a single Unicode code point)
2189 int as if by chr(x)
2190```
2191
2192It is an error if the argument does not have the type required by the
2193conversion specifier. A Boolean argument is not considered a number.
2194
2195Examples:
2196
2197```python
2198"Hello %s, your score is %d" % ("Bob", 75) # "Hello Bob, your score is 75"
2199
2200"%d %o %x %c" % (65, 65, 65, 65) # "65 101 41 A" (decimal, octal, hexadecimal, Unicode)
2201
2202"%(greeting)s, %(audience)s" % dict( # "Hello, world"
2203 greeting="Hello",
2204 audience="world",
2205)
2206
2207"rate = %g%% APR" % 3.5 # "rate = 3.5% APR"
2208```
2209
2210One subtlety: to use a tuple as the operand of a conversion in format
2211string containing only a single conversion, you must wrap the tuple in
2212a singleton tuple:
2213
2214```python
2215"coordinates=%s" % (40.741491, -74.003680) # error: too many arguments for format string
2216"coordinates=%s" % ((40.741491, -74.003680),) # "coordinates=(40.741491, -74.003680)"
2217```
2218
2219TODO: specify `%e` and `%f` more precisely.
2220
2221### Conditional expressions
2222
2223A conditional expression has the form `a if cond else b`.
2224It first evaluates the condition `cond`.
2225If it's true, it evaluates `a` and yields its value;
2226otherwise it yields the value of `b`.
2227
2228```grammar {.good}
2229IfExpr = Test 'if' Test 'else' Test .
2230```
2231
2232Example:
2233
2234```python
2235"yes" if enabled else "no"
2236```
2237
2238### Comprehensions
2239
2240A comprehension constructs new list or dictionary value by looping
2241over one or more iterables and evaluating a _body_ expression that produces
2242successive elements of the result.
2243
2244A list comprehension consists of a single expression followed by one
2245or more _clauses_, the first of which must be a `for` clause.
2246Each `for` clause resembles a `for` statement, and specifies an
2247iterable operand and a set of variables to be assigned by successive
2248values of the iterable.
2249An `if` cause resembles an `if` statement, and specifies a condition
2250that must be met for the body expression to be evaluated.
2251A sequence of `for` and `if` clauses acts like a nested sequence of
2252`for` and `if` statements.
2253
2254```grammar {.good}
2255ListComp = '[' Test {CompClause} ']'.
2256DictComp = '{' Entry {CompClause} '}' .
2257
2258CompClause = 'for' LoopVariables 'in' Test
2259 | 'if' Test .
2260
2261LoopVariables = PrimaryExpr {',' PrimaryExpr} .
2262```
2263
2264Examples:
2265
2266```python
2267[x*x for x in range(5)] # [0, 1, 4, 9, 16]
2268[x*x for x in range(5) if x%2 == 0] # [0, 4, 16]
2269[(x, y) for x in range(5)
2270 if x%2 == 0
2271 for y in range(5)
2272 if y > x] # [(0, 1), (0, 2), (0, 3), (0, 4), (2, 3), (2, 4)]
2273```
2274
2275A dict comprehension resembles a list comprehension, but its body is a
2276pair of expressions, `key: value`, separated by a colon,
2277and its result is a dictionary containing the key/value pairs
2278for which the body expression was evaluated.
2279Evaluation fails if the value of any key is unhashable.
2280
2281As with a `for` loop, the loop variables may exploit compound
2282assignment:
2283
2284```python
2285[x*y+z for (x, y), z in [((2, 3), 5), (("o", 2), "!")]] # [11, 'oo!']
2286```
2287
2288Starlark, following Python 3, does not accept an unparenthesized
2289tuple or lambda expression as the operand of a `for` clause:
2290
2291```python
2292[x*x for x in 1, 2, 3] # parse error: unexpected comma
2293[x*x for x in lambda: 0] # parse error: unexpected lambda
2294```
2295
2296Comprehensions in Starlark, again following Python 3, define a new lexical
2297block, so assignments to loop variables have no effect on variables of
2298the same name in an enclosing block:
2299
2300```python
2301x = 1
2302_ = [x for x in [2]] # new variable x is local to the comprehension
2303print(x) # 1
2304```
2305
2306The operand of a comprehension's first clause (always a `for`) is
2307resolved in the lexical block enclosing the comprehension.
2308In the examples below, identifiers referring to the outer variable
2309named `x` have been distinguished by subscript.
2310
2311```python
2312x₀ = (1, 2, 3)
2313[x*x for x in x₀] # [1, 4, 9]
2314[x*x for x in x₀ if x%2 == 0] # [4]
2315```
2316
2317All subsequent `for` and `if` expressions are resolved within the
2318comprehension's lexical block, as in this rather obscure example:
2319
2320```python
2321x₀ = ([1, 2], [3, 4], [5, 6])
2322[x*x for x in x₀ for x in x if x%2 == 0] # [4, 16, 36]
2323```
2324
2325which would be more clearly rewritten as:
2326
2327```python
2328x = ([1, 2], [3, 4], [5, 6])
2329[z*z for y in x for z in y if z%2 == 0] # [4, 16, 36]
2330```
2331
2332
2333### Function and method calls
2334
2335```grammar {.good}
2336CallSuffix = '(' [Arguments [',']] ')' .
2337
2338Arguments = Argument {',' Argument} .
2339Argument = Test | identifier '=' Test | '*' Test | '**' Test .
2340```
2341
2342A value `f` of type `function` or `builtin_function_or_method` may be called using the expression `f(...)`.
2343Applications may define additional types whose values may be called in the same way.
2344
2345A method call such as `filename.endswith(".star")` is the composition
2346of two operations, `m = filename.endswith` and `m(".star")`.
2347The first, a dot operation, yields a _bound method_, a function value
2348that pairs a receiver value (the `filename` string) with a choice of
2349method ([string·endswith](#string·endswith)).
2350
2351Only built-in or application-defined types may have methods.
2352
2353See [Functions](#functions) for an explanation of function parameter passing.
2354
2355### Dot expressions
2356
2357A dot expression `x.f` selects the attribute `f` (a field or method)
2358of the value `x`.
2359
2360Fields are possessed by none of the main Starlark [data types](#data-types),
2361but some application-defined types have them.
2362Methods belong to the built-in types `string`, `list`, `dict`, and
2363`set`, and to many application-defined types.
2364
2365```grammar {.good}
2366DotSuffix = '.' identifier .
2367```
2368
2369A dot expression fails if the value does not have an attribute of the
2370specified name.
2371
2372Use the built-in function `hasattr(x, "f")` to ascertain whether a
2373value has a specific attribute, or `dir(x)` to enumerate all its
2374attributes. The `getattr(x, "f")` function can be used to select an
2375attribute when the name `"f"` is not known statically.
2376
2377A dot expression that selects a method typically appears within a call
2378expression, as in these examples:
2379
2380```python
2381["able", "baker", "charlie"].index("baker") # 1
2382"banana".count("a") # 3
2383"banana".reverse() # error: string has no .reverse field or method
2384```
2385
2386But when not called immediately, the dot expression evaluates to a
2387_bound method_, that is, a method coupled to a specific receiver
2388value. A bound method can be called like an ordinary function,
2389without a receiver argument:
2390
2391```python
2392f = "banana".count
2393f # <built-in method count of string value>
2394f("a") # 3
2395f("n") # 2
2396```
2397
2398### Index expressions
2399
2400An index expression `a[i]` yields the `i`th element of an _indexable_
2401type such as a string, tuple, or list. The index `i` must be an `int`
2402value in the range -`n` ≤ `i` < `n`, where `n` is `len(a)`; any other
2403index results in an error.
2404
2405```grammar {.good}
2406SliceSuffix = '[' [Expression] [':' Test [':' Test]] ']' .
2407```
2408
2409A valid negative index `i` behaves like the non-negative index `n+i`,
2410allowing for convenient indexing relative to the end of the
2411sequence.
2412
2413```python
2414"abc"[0] # "a"
2415"abc"[1] # "b"
2416"abc"[-1] # "c"
2417
2418("zero", "one", "two")[0] # "zero"
2419("zero", "one", "two")[1] # "one"
2420("zero", "one", "two")[-1] # "two"
2421```
2422
2423An index expression `d[key]` may also be applied to a dictionary `d`,
2424to obtain the value associated with the specified key. It is an error
2425if the dictionary contains no such key.
2426
2427An index expression appearing on the left side of an assignment causes
2428the specified list or dictionary element to be updated:
2429
2430```starlark
2431a = range(3) # a == [0, 1, 2]
2432a[2] = 7 # a == [0, 1, 7]
2433
2434coins["suzie b"] = 100
2435```
2436
2437It is a dynamic error to attempt to update an element of an immutable
2438type, such as a tuple or string, or a frozen value of a mutable type.
2439
2440### Slice expressions
2441
2442A slice expression `a[start:stop:stride]` yields a new value containing a
2443sub-sequence of `a`, which must be a string, tuple, or list.
2444
2445```grammar {.good}
2446SliceSuffix = '[' [Expression] [':' Test [':' Test]] ']' .
2447```
2448
2449Each of the `start`, `stop`, and `stride` operands is optional;
2450if present, and not `None`, each must be an integer.
2451The `stride` value defaults to 1.
2452If the stride is not specified, the colon preceding it may be omitted too.
2453It is an error to specify a stride of zero.
2454
2455Conceptually, these operands specify a sequence of values `i` starting
2456at `start` and successively adding `stride` until `i` reaches or
2457passes `stop`. The result consists of the concatenation of values of
2458`a[i]` for which `i` is valid.`
2459
2460The effective start and stop indices are computed from the three
2461operands as follows. Let `n` be the length of the sequence.
2462
2463<b>If the stride is positive:</b>
2464If the `start` operand was omitted, it defaults to -infinity.
2465If the `end` operand was omitted, it defaults to +infinity.
2466For either operand, if a negative value was supplied, `n` is added to it.
2467The `start` and `end` values are then "clamped" to the
2468nearest value in the range 0 to `n`, inclusive.
2469
2470<b>If the stride is negative:</b>
2471If the `start` operand was omitted, it defaults to +infinity.
2472If the `end` operand was omitted, it defaults to -infinity.
2473For either operand, if a negative value was supplied, `n` is added to it.
2474The `start` and `end` values are then "clamped" to the
2475nearest value in the range -1 to `n`-1, inclusive.
2476
2477```python
2478"abc"[1:] # "bc" (remove first element)
2479"abc"[:-1] # "ab" (remove last element)
2480"abc"[1:-1] # "b" (remove first and last element)
2481"banana"[1::2] # "aaa" (select alternate elements starting at index 1)
2482"banana"[4::-2] # "nnb" (select alternate elements in reverse, starting at index 4)
2483```
2484
2485Unlike Python, Starlark does not allow a slice expression on the left
2486side of an assignment.
2487
2488Slicing a tuple or string may be more efficient than slicing a list
2489because tuples and strings are immutable, so the result of the
2490operation can share the underlying representation of the original
2491operand (when the stride is 1). By contrast, slicing a list requires
2492the creation of a new list and copying of the necessary elements.
2493
2494<!-- TODO tighten up this section -->
2495
2496### Lambda expressions
2497
2498A `lambda` expression yields a new function value.
2499
2500```grammar {.good}
2501LambdaExpr = 'lambda' [Parameters] ':' Test .
2502
2503Parameters = Parameter {',' Parameter} .
2504Parameter = identifier
2505 | identifier '=' Test
2506 | '*'
2507 | '*' identifier
2508 | '**' identifier
2509 .
2510```
2511
2512Syntactically, a lambda expression consists of the keyword `lambda`,
2513followed by a parameter list like that of a `def` statement but
2514unparenthesized, then a colon `:`, and a single expression, the
2515_function body_.
2516
2517Example:
2518
2519```python
2520def map(f, list):
2521 return [f(x) for x in list]
2522
2523map(lambda x: 2*x, range(3)) # [0, 2, 4]
2524```
2525
2526As with functions created by a `def` statement, a lambda function
2527captures the syntax of its body, the default values of any optional
2528parameters, the value of each free variable appearing in its body, and
2529the global dictionary of the current module.
2530
2531The name of a function created by a lambda expression is `"lambda"`.
2532
2533The two statements below are essentially equivalent, but the
2534function created by the `def` statement is named `twice` and the
2535function created by the lambda expression is named `lambda`.
2536
2537```python
2538def twice(x):
2539 return x * 2
2540
2541twice = lambda x: x * 2
2542```
2543
2544## Statements
2545
2546```grammar {.good}
2547Statement = DefStmt | IfStmt | ForStmt | SimpleStmt .
2548SimpleStmt = SmallStmt {';' SmallStmt} [';'] '\n' .
2549SmallStmt = ReturnStmt
2550 | BreakStmt | ContinueStmt | PassStmt
2551 | AssignStmt
2552 | ExprStmt
2553 | LoadStmt
2554 .
2555```
2556
2557### Pass statements
2558
2559A `pass` statement does nothing. Use a `pass` statement when the
2560syntax requires a statement but no behavior is required, such as the
2561body of a function that does nothing.
2562
2563```grammar {.good}
2564PassStmt = 'pass' .
2565```
2566
2567Example:
2568
2569```python
2570def noop():
2571 pass
2572
2573def list_to_dict(items):
2574 # Convert list of tuples to dict
2575 m = {}
2576 for k, m[k] in items:
2577 pass
2578 return m
2579```
2580
2581### Assignments
2582
2583An assignment statement has the form `lhs = rhs`. It evaluates the
2584expression on the right-hand side then assigns its value (or values) to
2585the variable (or variables) on the left-hand side.
2586
2587```grammar {.good}
2588AssignStmt = Expression '=' Expression .
2589```
2590
2591The expression on the left-hand side is called a _target_. The
2592simplest target is the name of a variable, but a target may also have
2593the form of an index expression, to update the element of a list or
2594dictionary, or a dot expression, to update the field of an object:
2595
2596```python
2597k = 1
2598a[i] = v
2599m.f = ""
2600```
2601
2602Compound targets may consist of a comma-separated list of
2603subtargets, optionally surrounded by parentheses or square brackets,
2604and targets may be nested arbitrarily in this way.
2605An assignment to a compound target checks that the right-hand value is a
2606sequence with the same number of elements as the target.
2607Each element of the sequence is then assigned to the corresponding
2608element of the target, recursively applying the same logic.
2609
2610```python
2611pi, e = 3.141, 2.718
2612(x, y) = f()
2613[zero, one, two] = range(3)
2614
2615[(a, b), (c, d)] = {"a": "b", "c": "d"}.items()
2616a, b = {"a": 1, "b": 2}
2617```
2618
2619The same process for assigning a value to a target expression is used
2620in `for` loops and in comprehensions.
2621
2622
2623### Augmented assignments
2624
2625An augmented assignment, which has the form `lhs op= rhs` updates the
2626variable `lhs` by applying a binary arithmetic operator `op` (one of
2627`+`, `-`, `*`, `/`, `//`, `%`, `&`, `|`, `^`, `<<`, `>>`) to the previous
2628value of `lhs` and the value of `rhs`.
2629
2630```grammar {.good}
2631AssignStmt = Expression ('+=' | '-=' | '*=' | '/=' | '//=' | '%=' | '&=' | '|=' | '^=' | '<<=' | '>>=') Expression .
2632```
2633
2634The left-hand side must be a simple target:
2635a name, an index expression, or a dot expression.
2636
2637```python
2638x -= 1
2639x.filename += ".star"
2640a[index()] *= 2
2641```
2642
2643Any subexpressions in the target on the left-hand side are evaluated
2644exactly once, before the evaluation of `rhs`.
2645The first two assignments above are thus equivalent to:
2646
2647```python
2648x = x - 1
2649x.filename = x.filename + ".star"
2650```
2651
2652and the third assignment is similar in effect to the following two
2653statements but does not declare a new temporary variable `i`:
2654
2655```python
2656i = index()
2657a[i] = a[i] * 2
2658```
2659
2660### Function definitions
2661
2662A `def` statement creates a named function and assigns it to a variable.
2663
2664```grammar {.good}
2665DefStmt = 'def' identifier '(' [Parameters [',']] ')' ':' Suite .
2666```
2667
2668Example:
2669
2670```python
2671def twice(x):
2672 return x * 2
2673
2674str(twice) # "<function twice>"
2675twice(2) # 4
2676twice("two") # "twotwo"
2677```
2678
2679The function's name is preceded by the `def` keyword and followed by
2680the parameter list (which is enclosed in parentheses), a colon, and
2681then an indented block of statements which form the body of the function.
2682
2683The parameter list is a comma-separated list whose elements are of
2684several kinds. First come zero or more required parameters, which are
2685simple identifiers; all calls must provide an argument value for these parameters.
2686
2687The required parameters are followed by zero or more optional
2688parameters, of the form `name=expression`. The expression specifies
2689the default value for the parameter for use in calls that do not
2690provide an argument value for it.
2691
2692The required parameters are optionally followed by a single parameter
2693name preceded by a `*`. This is the called the _varargs_ parameter,
2694and it accumulates surplus positional arguments specified by a call.
2695It is conventionally named `*args`.
2696
2697The varargs parameter may be followed by zero or more
2698parameters, again of the forms `name` or `name=expression`,
2699but these parameters differ from earlier ones in that they are
2700_keyword-only_: if a call provides their values, it must do so as
2701keyword arguments, not positional ones.
2702
2703```python
2704def f(a, *, b=2, c):
2705 print(a, b, c)
2706
2707f(1) # error: function f missing 1 argument (c)
2708f(1, 3) # error: function f accepts 1 positional argument (2 given)
2709f(1, c=3) # "1 2 3"
2710
2711def g(a, *args, b=2, c):
2712 print(a, b, c, args)
2713
2714g(1, 3) # error: function g missing 1 argument (c)
2715g(1, 4, c=3) # "1 2 3 (4,)"
2716
2717```
2718
2719A non-variadic function may also declare keyword-only parameters,
2720by using a bare `*` in place of the `*args` parameter.
2721This form does not declare a parameter but marks the boundary
2722between the earlier parameters and the keyword-only parameters.
2723This form must be followed by at least one optional parameter.
2724
2725Finally, there may be an optional parameter name preceded by `**`.
2726This is called the _keyword arguments_ parameter, and accumulates in a
2727dictionary any surplus `name=value` arguments that do not match a
2728prior parameter. It is conventionally named `**kwargs`.
2729
2730The final parameter may be followed by a trailing comma.
2731
2732Here are some example parameter lists:
2733
2734```python
2735def f(): pass
2736def f(a, b, c): pass
2737def f(a, b, c=1): pass
2738def f(a, b, c=1, *args): pass
2739def f(a, b, c=1, *args, **kwargs): pass
2740def f(**kwargs): pass
2741def f(a, b, c=1, *, d=1): pass
2742
2743def f(
2744 a,
2745 *args,
2746 **kwargs,
2747)
2748```
2749
2750Execution of a `def` statement creates a new function object. The
2751function object contains: the syntax of the function body; the default
2752value for each optional parameter; the value of each free variable
2753referenced within the function body; and the global dictionary of the
2754current module.
2755
2756<!-- this is too implementation-oriented; it's not a spec. -->
2757
2758
2759### Return statements
2760
2761A `return` statement ends the execution of a function and returns a
2762value to the caller of the function.
2763
2764```grammar {.good}
2765ReturnStmt = 'return' [Expression] .
2766```
2767
2768A return statement may have zero, one, or more
2769result expressions separated by commas.
2770With no expressions, the function has the result `None`.
2771With a single expression, the function's result is the value of that expression.
2772With multiple expressions, the function's result is a tuple.
2773
2774```python
2775return # returns None
2776return 1 # returns 1
2777return 1, 2 # returns (1, 2)
2778```
2779
2780### Expression statements
2781
2782An expression statement evaluates an expression and discards its result.
2783
2784```grammar {.good}
2785ExprStmt = Expression .
2786```
2787
2788Any expression may be used as a statement, but an expression statement is
2789most often used to call a function for its side effects.
2790
2791```python
2792list.append(1)
2793```
2794
2795### If statements
2796
2797An `if` statement evaluates an expression (the _condition_), then, if
2798the truth value of the condition is `True`, executes a list of
2799statements.
2800
2801```grammar {.good}
2802IfStmt = 'if' Test ':' Suite {'elif' Test ':' Suite} ['else' ':' Suite] .
2803```
2804
2805Example:
2806
2807```python
2808if score >= 100:
2809 print("You win!")
2810 return
2811```
2812
2813An `if` statement may have an `else` block defining a second list of
2814statements to be executed if the condition is false.
2815
2816```python
2817if score >= 100:
2818 print("You win!")
2819 return
2820else:
2821 print("Keep trying...")
2822 continue
2823```
2824
2825It is common for the `else` block to contain another `if` statement.
2826To avoid increasing the nesting depth unnecessarily, the `else` and
2827following `if` may be combined as `elif`:
2828
2829```python
2830if x > 0:
2831 result = +1
2832elif x < 0:
2833 result = -1
2834else:
2835 result = 0
2836```
2837
2838An `if` statement is permitted only within a function definition.
2839An `if` statement at top level results in a static error.
2840
2841<b>Implementation note:</b>
2842The Go implementation of Starlark permits `if`-statements to appear at top level
2843if the `-globalreassign` flag is enabled.
2844
2845
2846### While loops
2847
2848A `while` loop evaluates an expression (the _condition_) and if the truth
2849value of the condition is `True`, it executes a list of statement and repeats
2850the process until the truth value of the condition becomes `False`.
2851
2852```grammar {.good}
2853WhileStmt = 'while' Test ':' Suite .
2854```
2855
2856Example:
2857
2858```python
2859while n > 0:
2860 r = r + n
2861 n = n - 1
2862```
2863
2864A `while` statement is permitted only within a function definition.
2865A `while` statement at top level results in a static error.
2866
2867<b>Implementation note:</b>
2868The Go implementation of Starlark permits `while` loops only if the `-recursion` flag is enabled.
2869A `while` statement is permitted at top level if the `-globalreassign` flag is enabled.
2870
2871
2872### For loops
2873
2874A `for` loop evaluates its operand, which must be an iterable value.
2875Then, for each element of the iterable's sequence, the loop assigns
2876the successive element values to one or more variables and executes a
2877list of statements, the _loop body_.
2878
2879```grammar {.good}
2880ForStmt = 'for' LoopVariables 'in' Expression ':' Suite .
2881```
2882
2883Example:
2884
2885```python
2886for x in range(10):
2887 print(10)
2888```
2889
2890The assignment of each value to the loop variables follows the same
2891rules as an ordinary assignment. In this example, two-element lists
2892are repeatedly assigned to the pair of variables (a, i):
2893
2894```python
2895for a, i in [["a", 1], ["b", 2], ["c", 3]]:
2896 print(a, i) # prints "a 1", "b 2", "c 3"
2897```
2898
2899Because Starlark loops always iterate over a finite sequence, they are
2900guaranteed to terminate, unlike loops in most languages which can
2901execute an arbitrary and perhaps unbounded number of iterations.
2902
2903Within the body of a `for` loop, `break` and `continue` statements may
2904be used to stop the execution of the loop or advance to the next
2905iteration.
2906
2907In Starlark, a `for` loop is permitted only within a function definition.
2908A `for` loop at top level results in a static error.
2909
2910<b>Implementation note:</b>
2911The Go implementation of Starlark permits loops to appear at top level
2912if the `-globalreassign` flag is enabled.
2913
2914
2915### Break and Continue
2916
2917The `break` and `continue` statements terminate the current iteration
2918of a `for` loop. Whereas the `continue` statement resumes the loop at
2919the next iteration, a `break` statement terminates the entire loop.
2920
2921```grammar {.good}
2922BreakStmt = 'break' .
2923ContinueStmt = 'continue' .
2924```
2925
2926Example:
2927
2928```python
2929for x in range(10):
2930 if x%2 == 1:
2931 continue # skip odd numbers
2932 if x > 7:
2933 break # stop at 8
2934 print(x) # prints "0", "2", "4", "6"
2935```
2936
2937Both statements affect only the innermost lexically enclosing loop.
2938It is a static error to use a `break` or `continue` statement outside a
2939loop.
2940
2941
2942### Load statements
2943
2944The `load` statement loads another Starlark module, extracts one or
2945more values from it, and binds them to names in the current module.
2946
2947<!--
2948The awkwardness of load statements is a consequence of staying a
2949strict subset of Python syntax, which allows reuse of existing tools
2950such as editor support. Python import statements are inadequate for
2951Starlark because they don't allow arbitrary file names for module names.
2952-->
2953
2954Syntactically, a load statement looks like a function call `load(...)`.
2955
2956```grammar {.good}
2957LoadStmt = 'load' '(' string {',' [identifier '='] string} [','] ')' .
2958```
2959
2960A load statement requires at least two "arguments".
2961The first must be a literal string; it identifies the module to load.
2962Its interpretation is determined by the application into which the
2963Starlark interpreter is embedded, and is not specified here.
2964
2965During execution, the application determines what action to take for a
2966load statement.
2967A typical implementation locates and executes a Starlark file,
2968populating a cache of files executed so far to avoid duplicate work,
2969to obtain a module, which is a mapping from global names to values.
2970
2971The remaining arguments are a mixture of literal strings, such as
2972`"x"`, or named literal strings, such as `y="x"`.
2973
2974The literal string (`"x"`), which must denote a valid identifier not
2975starting with `_`, specifies the name to extract from the loaded
2976module. In effect, names starting with `_` are not exported.
2977The name (`y`) specifies the local name;
2978if no name is given, the local name matches the quoted name.
2979
2980```python
2981load("module.star", "x", "y", "z") # assigns x, y, and z
2982load("module.star", "x", y2="y", "z") # assigns x, y2, and z
2983```
2984
2985A load statement may not be nested inside any other statement.
2986
2987
2988## Module execution
2989
2990Each Starlark file defines a _module_, which is a mapping from the
2991names of global variables to their values.
2992When a Starlark file is executed, whether directly by the application
2993or indirectly through a `load` statement, a new Starlark thread is
2994created, and this thread executes all the top-level statements in the
2995file.
2996Because if-statements and for-loops cannot appear outside of a function,
2997control flows from top to bottom.
2998
2999If execution reaches the end of the file, module initialization is
3000successful.
3001At that point, the value of each of the module's global variables is
3002frozen, rendering subsequent mutation impossible.
3003The module is then ready for use by another Starlark thread, such as
3004one executing a load statement.
3005Such threads may access values or call functions defined in the loaded
3006module.
3007
3008A Starlark thread may carry state on behalf of the application into
3009which it is embedded, and application-defined functions may behave
3010differently depending on this thread state.
3011Because module initialization always occurs in a new thread, thread
3012state is never carried from a higher-level module into a lower-level
3013one.
3014The initialization behavior of a module is thus independent of
3015whichever module triggered its initialization.
3016
3017If a Starlark thread encounters an error, execution stops and the error
3018is reported to the application, along with a backtrace showing the
3019stack of active function calls at the time of the error.
3020If an error occurs during initialization of a Starlark module, any
3021active `load` statements waiting for initialization of the module also
3022fail.
3023
3024Starlark provides no mechanism by which errors can be handled within
3025the language.
3026
3027
3028## Built-in constants and functions
3029
3030The outermost block of the Starlark environment is known as the "predeclared" block.
3031It defines a number of fundamental values and functions needed by all Starlark programs,
3032such as `None`, `True`, `False`, and `len`, and possibly additional
3033application-specific names.
3034
3035These names are not reserved words so Starlark programs are free to
3036redefine them in a smaller block such as a function body or even at
3037the top level of a module. However, doing so may be confusing to the
3038reader. Nonetheless, this rule permits names to be added to the
3039predeclared block in later versions of the language (or
3040application-specific dialect) without breaking existing programs.
3041
3042
3043### None
3044
3045`None` is the distinguished value of the type `NoneType`.
3046
3047### True and False
3048
3049`True` and `False` are the two values of type `bool`.
3050
3051### abs
3052
3053`abs(x)` returns the absolute value of its argument `x`, which must be an int or float.
3054The result has the same type as `x`.
3055
3056### any
3057
3058`any(x)` returns `True` if any element of the iterable sequence x has a truth value of true.
3059If the iterable is empty, it returns `False`.
3060
3061### all
3062
3063`all(x)` returns `False` if any element of the iterable sequence x has a truth value of false.
3064If the iterable is empty, it returns `True`.
3065
3066### bool
3067
3068`bool(x)` interprets `x` as a Boolean value---`True` or `False`.
3069With no argument, `bool()` returns `False`.
3070
3071
3072### chr
3073
3074`chr(i)` returns a string that encodes the single Unicode code point
3075whose value is specified by the integer `i`. `chr` fails unless 0 ≤
3076`i` ≤ 0x10FFFF.
3077
3078Example:
3079
3080```python
3081chr(65) # "A",
3082chr(1049) # "Й", CYRILLIC CAPITAL LETTER SHORT I
3083chr(0x1F63F) # "😿", CRYING CAT FACE
3084```
3085
3086See also: `ord`.
3087
3088<b>Implementation note:</b> `chr` is not provided by the Java implementation.
3089
3090### dict
3091
3092`dict` creates a dictionary. It accepts up to one positional
3093argument, which is interpreted as an iterable of two-element
3094sequences (pairs), each specifying a key/value pair in
3095the resulting dictionary.
3096
3097`dict` also accepts any number of keyword arguments, each of which
3098specifies a key/value pair in the resulting dictionary;
3099each keyword is treated as a string.
3100
3101```python
3102dict() # {}, empty dictionary
3103dict([(1, 2), (3, 4)]) # {1: 2, 3: 4}
3104dict([(1, 2), ["a", "b"]]) # {1: 2, "a": "b"}
3105dict(one=1, two=2) # {"one": 1, "two", 1}
3106dict([(1, 2)], x=3) # {1: 2, "x": 3}
3107```
3108
3109With no arguments, `dict()` returns a new empty dictionary.
3110
3111`dict(x)` where x is a dictionary returns a new copy of x.
3112
3113### dir
3114
3115`dir(x)` returns a new sorted list of the names of the attributes (fields and methods) of its operand.
3116The attributes of a value `x` are the names `f` such that `x.f` is a valid expression.
3117
3118For example,
3119
3120```python
3121dir("hello") # ['capitalize', 'count', ...], the methods of a string
3122```
3123
3124Several types known to the interpreter, such as list, string, and dict, have methods, but none have fields.
3125However, an application may define types with fields that may be read or set by statements such as these:
3126
3127```text
3128y = x.f
3129x.f = y
3130```
3131
3132### enumerate
3133
3134`enumerate(x)` returns a list of (index, value) pairs, each containing
3135successive values of the iterable sequence xand the index of the value
3136within the sequence.
3137
3138The optional second parameter, `start`, specifies an integer value to
3139add to each index.
3140
3141```python
3142enumerate(["zero", "one", "two"]) # [(0, "zero"), (1, "one"), (2, "two")]
3143enumerate(["one", "two"], 1) # [(1, "one"), (2, "two")]
3144```
3145
3146### fail
3147
3148The `fail(*args, sep=" ")` function causes execution to fail
3149with the specified error message.
3150Like `print`, arguments are formatted as if by `str(x)` and
3151separated by a space, unless an alternative separator is
3152specified by a `sep` named argument.
3153
3154```python
3155fail("oops") # "fail: oops"
3156fail("oops", 1, False, sep='/') # "fail: oops/1/False"
3157```
3158
3159### float
3160
3161`float(x)` interprets its argument as a floating-point number.
3162
3163If x is a `float`, the result is x.
3164if x is an `int`, the result is the nearest floating point value to x.
3165If x is a string, the string is interpreted as a floating-point literal.
3166With no arguments, `float()` returns `0.0`.
3167
3168
3169### getattr
3170
3171`getattr(x, name)` returns the value of the attribute (field or method) of x named `name`.
3172It is a dynamic error if x has no such attribute.
3173
3174`getattr(x, "f")` is equivalent to `x.f`.
3175
3176```python
3177getattr("banana", "split")("a") # ["b", "n", "n", ""], equivalent to "banana".split("a")
3178```
3179
3180The three-argument form `getattr(x, name, default)` returns the
3181provided `default` value instead of failing.
3182
3183### hasattr
3184
3185`hasattr(x, name)` reports whether x has an attribute (field or method) named `name`.
3186
3187### hash
3188
3189`hash(x)` returns an integer hash of a string x
3190such that two equal strings have the same hash.
3191In other words `x == y` implies `hash(x) == hash(y)`.
3192
3193In the interests of reproducibility of Starlark program behavior over time and
3194across implementations, the specific hash function is the same as that implemented by
3195[java.lang.String.hashCode](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html#hashCode),
3196a simple polynomial accumulator over the UTF-16 transcoding of the string:
3197 ```
3198s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
3199```
3200
3201`hash` fails if given a non-string operand,
3202even if the value is hashable and thus suitable as the key of dictionary.
3203
3204### int
3205
3206`int(x[, base])` interprets its argument as an integer.
3207
3208If x is an `int`, the result is x.
3209If x is a `float`, the result is the integer value nearest to x,
3210truncating towards zero; it is an error if x is not finite (`NaN`,
3211`+Inf`, `-Inf`).
3212If x is a `bool`, the result is 0 for `False` or 1 for `True`.
3213
3214If x is a string, it is interpreted as a sequence of digits in the
3215specified base, decimal by default.
3216If `base` is zero, x is interpreted like an integer literal, the base
3217being inferred from an optional base prefix such as `0b`, `0o`, or
3218`0x` preceding the first digit.
3219When the `base` is provided explicitly, a matching base prefix is
3220also permitted, and has no effect.
3221Irrespective of base, the string may start with an optional `+` or `-`
3222sign indicating the sign of the result.
3223
3224```python
3225int("11") # 11
3226int("11", 0) # 11
3227int("11", 10) # 11
3228int("11", 2) # 3
3229int("11", 8) # 9
3230int("11", 16) # 17
3231
3232int("0x11", 0) # 17
3233int("0x11", 16) # 17
3234int("0b1", 16) # 177 (0xb1)
3235int("0b1", 2) # 1
3236int("0b1", 0) # 1
3237
3238int("0x11") # error: invalid literal with base 10
3239```
3240
3241### len
3242
3243`len(x)` returns the number of elements in its argument.
3244
3245It is a dynamic error if its argument is not a sequence.
3246
3247### list
3248
3249`list` constructs a list.
3250
3251`list(x)` returns a new list containing the elements of the
3252iterable sequence x.
3253
3254With no argument, `list()` returns a new empty list.
3255
3256### max
3257
3258`max(x)` returns the greatest element in the iterable sequence x.
3259
3260It is an error if any element does not support ordered comparison,
3261or if the sequence is empty.
3262
3263The optional named parameter `key` specifies a function to be applied
3264to each element prior to comparison.
3265
3266```python
3267max([3, 1, 4, 1, 5, 9]) # 9
3268max("two", "three", "four") # "two", the lexicographically greatest
3269max("two", "three", "four", key=len) # "three", the longest
3270```
3271
3272### min
3273
3274`min(x)` returns the least element in the iterable sequence x.
3275
3276It is an error if any element does not support ordered comparison,
3277or if the sequence is empty.
3278
3279```python
3280min([3, 1, 4, 1, 5, 9]) # 1
3281min("two", "three", "four") # "four", the lexicographically least
3282min("two", "three", "four", key=len) # "two", the shortest
3283```
3284
3285
3286### ord
3287
3288`ord(s)` returns the integer value of the sole Unicode code point encoded by the string `s`.
3289
3290If `s` does not encode exactly one Unicode code point, `ord` fails.
3291Each invalid code within the string is treated as if it encodes the
3292Unicode replacement character, U+FFFD.
3293
3294Example:
3295
3296```python
3297ord("A") # 65
3298ord("Й") # 1049
3299ord("😿") # 0x1F63F
3300ord("Й"[1:]) # 0xFFFD (Unicode replacement character)
3301```
3302
3303See also: `chr`.
3304
3305<b>Implementation note:</b> `ord` is not provided by the Java implementation.
3306
3307### print
3308
3309`print(*args, sep=" ")` prints its arguments, followed by a newline.
3310Arguments are formatted as if by `str(x)` and separated with a space,
3311unless an alternative separator is specified by a `sep` named argument.
3312
3313Example:
3314
3315```python
3316print(1, "hi") # "1 hi\n"
3317print("hello", "world") # "hello world\n"
3318print("hello", "world", sep=", ") # "hello, world\n"
3319```
3320
3321Typically the formatted string is printed to the standard error file,
3322but the exact behavior is a property of the Starlark thread and is
3323determined by the host application.
3324
3325### range
3326
3327`range` returns an immutable sequence of integers defined by the specified interval and stride.
3328
3329```python
3330range(stop) # equivalent to range(0, stop)
3331range(start, stop) # equivalent to range(start, stop, 1)
3332range(start, stop, step)
3333```
3334
3335`range` requires between one and three integer arguments.
3336With one argument, `range(stop)` returns the ascending sequence of non-negative integers less than `stop`.
3337With two arguments, `range(start, stop)` returns only integers not less than `start`.
3338
3339With three arguments, `range(start, stop, step)` returns integers
3340formed by successively adding `step` to `start` until the value meets or passes `stop`.
3341A call to `range` fails if the value of `step` is zero.
3342
3343A call to `range` does not materialize the entire sequence, but
3344returns a fixed-size value of type `"range"` that represents the
3345parameters that define the sequence.
3346The `range` value is iterable and may be indexed efficiently.
3347
3348```python
3349list(range(10)) # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
3350list(range(3, 10)) # [3, 4, 5, 6, 7, 8, 9]
3351list(range(3, 10, 2)) # [3, 5, 7, 9]
3352list(range(10, 3, -2)) # [10, 8, 6, 4]
3353```
3354
3355The `len` function applied to a `range` value returns its length.
3356The truth value of a `range` value is `True` if its length is non-zero.
3357
3358Range values are comparable: two `range` values compare equal if they
3359denote the same sequence of integers, even if they were created using
3360different parameters.
3361
3362Range values are not hashable. <!-- should they be? -->
3363
3364The `str` function applied to a `range` value yields a string of the
3365form `range(10)`, `range(1, 10)`, or `range(1, 10, 2)`.
3366
3367The `x in y` operator, where `y` is a range, reports whether `x` is equal to
3368some member of the sequence `y`; the operation fails unless `x` is a
3369number.
3370
3371### repr
3372
3373`repr(x)` formats its argument as a string.
3374
3375All strings in the result are double-quoted.
3376
3377```python
3378repr(1) # '1'
3379repr("x") # '"x"'
3380repr([1, "x"]) # '[1, "x"]'
3381```
3382
3383### reversed
3384
3385`reversed(x)` returns a new list containing the elements of the iterable sequence x in reverse order.
3386
3387```python
3388reversed(range(5)) # [4, 3, 2, 1, 0]
3389reversed("stressed".codepoints()) # ["d", "e", "s", "s", "e", "r", "t", "s"]
3390reversed({"one": 1, "two": 2}.keys()) # ["two", "one"]
3391```
3392
3393### set
3394
3395`set(x)` returns a new set containing the elements of the iterable x.
3396With no argument, `set()` returns a new empty set.
3397
3398```python
3399set([3, 1, 4, 1, 5, 9]) # set([3, 1, 4, 5, 9])
3400```
3401
3402<b>Implementation note:</b>
3403Sets are an optional feature of the Go implementation of Starlark,
3404enabled by the `-set` flag.
3405
3406
3407### sorted
3408
3409`sorted(x)` returns a new list containing the elements of the iterable sequence x,
3410in sorted order. The sort algorithm is stable.
3411
3412The optional named parameter `reverse`, if true, causes `sorted` to
3413return results in reverse sorted order.
3414
3415The optional named parameter `key` specifies a function of one
3416argument to apply to obtain the value's sort key.
3417The default behavior is the identity function.
3418
3419```python
3420sorted(set("harbors".codepoints())) # ['a', 'b', 'h', 'o', 'r', 's']
3421sorted([3, 1, 4, 1, 5, 9]) # [1, 1, 3, 4, 5, 9]
3422sorted([3, 1, 4, 1, 5, 9], reverse=True) # [9, 5, 4, 3, 1, 1]
3423
3424sorted(["two", "three", "four"], key=len) # ["two", "four", "three"], shortest to longest
3425sorted(["two", "three", "four"], key=len, reverse=True) # ["three", "four", "two"], longest to shortest
3426```
3427
3428
3429### str
3430
3431`str(x)` formats its argument as a string.
3432
3433If x is a string, the result is x (without quotation).
3434All other strings, such as elements of a list of strings, are double-quoted.
3435
3436```python
3437str(1) # '1'
3438str("x") # 'x'
3439str([1, "x"]) # '[1, "x"]'
3440```
3441
3442### tuple
3443
3444`tuple(x)` returns a tuple containing the elements of the iterable x.
3445
3446With no arguments, `tuple()` returns the empty tuple.
3447
3448### type
3449
3450type(x) returns a string describing the type of its operand.
3451
3452```python
3453type(None) # "NoneType"
3454type(0) # "int"
3455type(0.0) # "float"
3456```
3457
3458### zip
3459
3460`zip()` returns a new list of n-tuples formed from corresponding
3461elements of each of the n iterable sequences provided as arguments to
3462`zip`. That is, the first tuple contains the first element of each of
3463the sequences, the second tuple contains the second element of each
3464of the sequences, and so on. The result list is only as long as the
3465shortest of the input sequences.
3466
3467```python
3468zip() # []
3469zip(range(5)) # [(0,), (1,), (2,), (3,), (4,)]
3470zip(range(5), "abc") # [(0, "a"), (1, "b"), (2, "c")]
3471```
3472
3473## Built-in methods
3474
3475This section lists the methods of built-in types. Methods are selected
3476using [dot expressions](#dot-expressions).
3477For example, strings have a `count` method that counts
3478occurrences of a substring; `"banana".count("a")` yields `3`.
3479
3480As with built-in functions, built-in methods accept only positional
3481arguments except where noted.
3482The parameter names serve merely as documentation.
3483
3484
3485<a id='dict·clear'></a>
3486### dict·clear
3487
3488`D.clear()` removes all the entries of dictionary D and returns `None`.
3489It fails if the dictionary is frozen or if there are active iterators.
3490
3491```python
3492x = {"one": 1, "two": 2}
3493x.clear() # None
3494print(x) # {}
3495```
3496
3497<a id='dict·get'></a>
3498### dict·get
3499
3500`D.get(key[, default])` returns the dictionary value corresponding to the given key.
3501If the dictionary contains no such value, `get` returns `None`, or the
3502value of the optional `default` parameter if present.
3503
3504`get` fails if `key` is unhashable, or the dictionary is frozen or has active iterators.
3505
3506```python
3507x = {"one": 1, "two": 2}
3508x.get("one") # 1
3509x.get("three") # None
3510x.get("three", 0) # 0
3511```
3512
3513<a id='dict·items'></a>
3514### dict·items
3515
3516`D.items()` returns a new list of key/value pairs, one per element in
3517dictionary D, in the same order as they would be returned by a `for` loop.
3518
3519```python
3520x = {"one": 1, "two": 2}
3521x.items() # [("one", 1), ("two", 2)]
3522```
3523
3524<a id='dict·keys'></a>
3525### dict·keys
3526
3527`D.keys()` returns a new list containing the keys of dictionary D, in the
3528same order as they would be returned by a `for` loop.
3529
3530```python
3531x = {"one": 1, "two": 2}
3532x.keys() # ["one", "two"]
3533```
3534
3535<a id='dict·pop'></a>
3536### dict·pop
3537
3538`D.pop(key[, default])` returns the value corresponding to the specified
3539key, and removes it from the dictionary. If the dictionary contains no
3540such value, and the optional `default` parameter is present, `pop`
3541returns that value; otherwise, it fails.
3542
3543`pop` fails if `key` is unhashable, or the dictionary is frozen or has active iterators.
3544
3545```python
3546x = {"one": 1, "two": 2}
3547x.pop("one") # 1
3548x # {"two": 2}
3549x.pop("three", 0) # 0
3550x.pop("four") # error: missing key
3551```
3552
3553<a id='dict·popitem'></a>
3554### dict·popitem
3555
3556`D.popitem()` returns the first key/value pair, removing it from the dictionary.
3557
3558`popitem` fails if the dictionary is empty, frozen, or has active iterators.
3559
3560```python
3561x = {"one": 1, "two": 2}
3562x.popitem() # ("one", 1)
3563x.popitem() # ("two", 2)
3564x.popitem() # error: empty dict
3565```
3566
3567<a id='dict·setdefault'></a>
3568### dict·setdefault
3569
3570`D.setdefault(key[, default])` returns the dictionary value corresponding to the given key.
3571If the dictionary contains no such value, `setdefault`, like `get`,
3572returns `None` or the value of the optional `default` parameter if
3573present; `setdefault` additionally inserts the new key/value entry into the dictionary.
3574
3575`setdefault` fails if the key is unhashable, or if the dictionary is frozen or has active iterators.
3576
3577```python
3578x = {"one": 1, "two": 2}
3579x.setdefault("one") # 1
3580x.setdefault("three", 0) # 0
3581x # {"one": 1, "two": 2, "three": 0}
3582x.setdefault("four") # None
3583x # {"one": 1, "two": 2, "three": None}
3584```
3585
3586<a id='dict·update'></a>
3587### dict·update
3588
3589`D.update([pairs][, name=value[, ...])` makes a sequence of key/value
3590insertions into dictionary D, then returns `None.`
3591
3592If the positional argument `pairs` is present, it must be `None`,
3593another `dict`, or some other iterable.
3594If it is another `dict`, then its key/value pairs are inserted into D.
3595If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2),
3596each of which is treated as a key/value pair to be inserted into D.
3597
3598For each `name=value` argument present, the name is converted to a
3599string and used as the key for an insertion into D, with its corresponding
3600value being `value`.
3601
3602`update` fails if the dictionary is frozen or has active iterators.
3603
3604```python
3605x = {}
3606x.update([("a", 1), ("b", 2)], c=3)
3607x.update({"d": 4})
3608x.update(e=5)
3609x # {"a": 1, "b": "2", "c": 3, "d": 4, "e": 5}
3610```
3611
3612<a id='dict·values'></a>
3613### dict·values
3614
3615`D.values()` returns a new list containing the dictionary's values, in the
3616same order as they would be returned by a `for` loop over the
3617dictionary.
3618
3619```python
3620x = {"one": 1, "two": 2}
3621x.values() # [1, 2]
3622```
3623
3624<a id='list·append'></a>
3625### list·append
3626
3627`L.append(x)` appends `x` to the list L, and returns `None`.
3628
3629`append` fails if the list is frozen or has active iterators.
3630
3631```python
3632x = []
3633x.append(1) # None
3634x.append(2) # None
3635x.append(3) # None
3636x # [1, 2, 3]
3637```
3638
3639<a id='list·clear'></a>
3640### list·clear
3641
3642`L.clear()` removes all the elements of the list L and returns `None`.
3643It fails if the list is frozen or if there are active iterators.
3644
3645```python
3646x = [1, 2, 3]
3647x.clear() # None
3648x # []
3649```
3650
3651<a id='list·extend'></a>
3652### list·extend
3653
3654`L.extend(x)` appends the elements of `x`, which must be iterable, to
3655the list L, and returns `None`.
3656
3657`extend` fails if `x` is not iterable, or if the list L is frozen or has active iterators.
3658
3659```python
3660x = []
3661x.extend([1, 2, 3]) # None
3662x.extend(["foo"]) # None
3663x # [1, 2, 3, "foo"]
3664```
3665
3666<a id='list·index'></a>
3667### list·index
3668
3669`L.index(x[, start[, end]])` finds `x` within the list L and returns its index.
3670
3671The optional `start` and `end` parameters restrict the portion of
3672list L that is inspected. If provided and not `None`, they must be list
3673indices of type `int`. If an index is negative, `len(L)` is effectively
3674added to it, then if the index is outside the range `[0:len(L)]`, the
3675nearest value within that range is used; see [Indexing](#indexing).
3676
3677`index` fails if `x` is not found in L, or if `start` or `end`
3678is not a valid index (`int` or `None`).
3679
3680```python
3681x = list("banana".codepoints())
3682x.index("a") # 1 (bAnana)
3683x.index("a", 2) # 3 (banAna)
3684x.index("a", -2) # 5 (bananA)
3685```
3686
3687<a id='list·insert'></a>
3688### list·insert
3689
3690`L.insert(i, x)` inserts the value `x` in the list L at index `i`, moving
3691higher-numbered elements along by one. It returns `None`.
3692
3693As usual, the index `i` must be an `int`. If its value is negative,
3694the length of the list is added, then its value is clamped to the
3695nearest value in the range `[0:len(L)]` to yield the effective index.
3696
3697`insert` fails if the list is frozen or has active iterators.
3698
3699```python
3700x = ["b", "c", "e"]
3701x.insert(0, "a") # None
3702x.insert(-1, "d") # None
3703x # ["a", "b", "c", "d", "e"]
3704```
3705
3706<a id='list·pop'></a>
3707### list·pop
3708
3709`L.pop([index])` removes and returns the last element of the list L, or,
3710if the optional index is provided, at that index.
3711
3712`pop` fails if the index is not valid for `L[i]`,
3713or if the list is frozen or has active iterators.
3714
3715```python
3716x = [1, 2, 3, 4, 5]
3717x.pop() # 5
3718x # [1, 2, 3, 4]
3719x.pop(-2) # 3
3720x # [1, 2, 4]
3721x.pop(-3) # 1
3722x # [2, 4]
3723x.pop() # 4
3724x # [2]
3725```
3726
3727<a id='list·remove'></a>
3728### list·remove
3729
3730`L.remove(x)` removes the first occurrence of the value `x` from the list L, and returns `None`.
3731
3732`remove` fails if the list does not contain `x`, is frozen, or has active iterators.
3733
3734```python
3735x = [1, 2, 3, 2]
3736x.remove(2) # None (x == [1, 3, 2])
3737x.remove(2) # None (x == [1, 3])
3738x.remove(2) # error: element not found
3739```
3740
3741<a id='set·union'></a>
3742### set·union
3743
3744`S.union(iterable)` returns a new set into which have been inserted
3745all the elements of set S and all the elements of the argument, which
3746must be iterable.
3747
3748`union` fails if any element of the iterable is not hashable.
3749
3750```python
3751x = set([1, 2])
3752y = set([2, 3])
3753x.union(y) # set([1, 2, 3])
3754```
3755
3756<a id='string·elem_ords'></a>
3757### string·elem_ords
3758
3759`S.elem_ords()` returns an iterable value containing the
3760sequence of numeric bytes values in the string S.
3761
3762To materialize the entire sequence of bytes, apply `list(...)` to the result.
3763
3764Example:
3765
3766```python
3767list("Hello, 世界".elem_ords()) # [72, 101, 108, 108, 111, 44, 32, 228, 184, 150, 231, 149, 140]
3768```
3769
3770See also: `string·elems`.
3771
3772<b>Implementation note:</b> `elem_ords` is not provided by the Java implementation.
3773
3774<a id='string·capitalize'></a>
3775### string·capitalize
3776
3777`S.capitalize()` returns a copy of string S with its first code point
3778changed to its title case and all subsequent letters changed to their
3779lower case.
3780
3781```python
3782"hello, world!".capitalize() # "Hello, world!"
3783"hElLo, wOrLd!".capitalize() # "Hello, world!"
3784"¿Por qué?".capitalize() # "¿por qué?"
3785```
3786
3787<a id='string·codepoint_ords'></a>
3788### string·codepoint_ords
3789
3790`S.codepoint_ords()` returns an iterable value containing the
3791sequence of integer Unicode code points encoded by the string S.
3792Each invalid code within the string is treated as if it encodes the
3793Unicode replacement character, U+FFFD.
3794
3795By returning an iterable, not a list, the cost of decoding the string
3796is deferred until actually needed; apply `list(...)` to the result to
3797materialize the entire sequence.
3798
3799Example:
3800
3801```python
3802list("Hello, 世界".codepoint_ords()) # [72, 101, 108, 108, 111, 44, 32, 19990, 30028]
3803
3804for cp in "Hello, 世界".codepoint_ords():
3805 print(chr(cp)) # prints 'H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界'
3806```
3807
3808See also: `string·codepoints`.
3809
3810<b>Implementation note:</b> `codepoint_ords` is not provided by the Java implementation.
3811
3812<a id='string·count'></a>
3813### string·count
3814
3815`S.count(sub[, start[, end]])` returns the number of occcurences of
3816`sub` within the string S, or, if the optional substring indices
3817`start` and `end` are provided, within the designated substring of S.
3818They are interpreted according to Starlark's [indexing conventions](#indexing).
3819
3820```python
3821"hello, world!".count("o") # 2
3822"hello, world!".count("o", 7, 12) # 1 (in "world")
3823```
3824
3825<a id='string·endswith'></a>
3826### string·endswith
3827
3828`S.endswith(suffix[, start[, end]])` reports whether the string
3829`S[start:end]` has the specified suffix.
3830
3831```python
3832"filename.star".endswith(".star") # True
3833```
3834
3835The `suffix` argument may be a tuple of strings, in which case the
3836function reports whether any one of them is a suffix.
3837
3838```python
3839'foo.cc'.endswith(('.cc', '.h')) # True
3840```
3841
3842
3843<a id='string·find'></a>
3844### string·find
3845
3846`S.find(sub[, start[, end]])` returns the index of the first
3847occurrence of the substring `sub` within S.
3848
3849If either or both of `start` or `end` are specified,
3850they specify a subrange of S to which the search should be restricted.
3851They are interpreted according to Starlark's [indexing conventions](#indexing).
3852
3853If no occurrence is found, `found` returns -1.
3854
3855```python
3856"bonbon".find("on") # 1
3857"bonbon".find("on", 2) # 4
3858"bonbon".find("on", 2, 5) # -1
3859```
3860
3861<a id='string·format'></a>
3862### string·format
3863
3864`S.format(*args, **kwargs)` returns a version of the format string S
3865in which bracketed portions `{...}` are replaced
3866by arguments from `args` and `kwargs`.
3867
3868Within the format string, a pair of braces `{{` or `}}` is treated as
3869a literal open or close brace.
3870Each unpaired open brace must be matched by a close brace `}`.
3871The optional text between corresponding open and close braces
3872specifies which argument to use and how to format it, and consists of
3873three components, all optional:
3874a field name, a conversion preceded by '`!`', and a format specifier
3875preceded by '`:`'.
3876
3877```text
3878{field}
3879{field:spec}
3880{field!conv}
3881{field!conv:spec}
3882```
3883
3884The *field name* may be either a decimal number or a keyword.
3885A number is interpreted as the index of a positional argument;
3886a keyword specifies the value of a keyword argument.
3887If all the numeric field names form the sequence 0, 1, 2, and so on,
3888they may be omitted and those values will be implied; however,
3889the explicit and implicit forms may not be mixed.
3890
3891The *conversion* specifies how to convert an argument value `x` to a
3892string. It may be either `!r`, which converts the value using
3893`repr(x)`, or `!s`, which converts the value using `str(x)` and is
3894the default.
3895
3896The *format specifier*, after a colon, specifies field width,
3897alignment, padding, and numeric precision.
3898Currently it must be empty, but it is reserved for future use.
3899
3900```python
3901"a{x}b{y}c{}".format(1, x=2, y=3) # "a2b3c1"
3902"a{}b{}c".format(1, 2) # "a1b2c"
3903"({1}, {0})".format("zero", "one") # "(one, zero)"
3904"Is {0!r} {0!s}?".format('heterological') # 'Is "heterological" heterological?'
3905```
3906
3907<a id='string·index'></a>
3908### string·index
3909
3910`S.index(sub[, start[, end]])` returns the index of the first
3911occurrence of the substring `sub` within S, like `S.find`, except
3912that if the substring is not found, the operation fails.
3913
3914```python
3915"bonbon".index("on") # 1
3916"bonbon".index("on", 2) # 4
3917"bonbon".index("on", 2, 5) # error: substring not found (in "nbo")
3918```
3919
3920<a id='string·isalnum'></a>
3921### string·isalnum
3922
3923`S.isalnum()` reports whether the string S is non-empty and consists only
3924Unicode letters and digits.
3925
3926```python
3927"base64".isalnum() # True
3928"Catch-22".isalnum() # False
3929```
3930
3931<a id='string·isalpha'></a>
3932### string·isalpha
3933
3934`S.isalpha()` reports whether the string S is non-empty and consists only of Unicode letters.
3935
3936```python
3937"ABC".isalpha() # True
3938"Catch-22".isalpha() # False
3939"".isalpha() # False
3940```
3941
3942<a id='string·isdigit'></a>
3943### string·isdigit
3944
3945`S.isdigit()` reports whether the string S is non-empty and consists only of Unicode digits.
3946
3947```python
3948"123".isdigit() # True
3949"Catch-22".isdigit() # False
3950"".isdigit() # False
3951```
3952
3953<a id='string·islower'></a>
3954### string·islower
3955
3956`S.islower()` reports whether the string S contains at least one cased Unicode
3957letter, and all such letters are lowercase.
3958
3959```python
3960"hello, world".islower() # True
3961"Catch-22".islower() # False
3962"123".islower() # False
3963```
3964
3965<a id='string·isspace'></a>
3966### string·isspace
3967
3968`S.isspace()` reports whether the string S is non-empty and consists only of Unicode spaces.
3969
3970```python
3971" ".isspace() # True
3972"\r\t\n".isspace() # True
3973"".isspace() # False
3974```
3975
3976<a id='string·istitle'></a>
3977### string·istitle
3978
3979`S.istitle()` reports whether the string S contains at least one cased Unicode
3980letter, and all such letters that begin a word are in title case.
3981
3982```python
3983"Hello, World!".istitle() # True
3984"Catch-22".istitle() # True
3985"HAL-9000".istitle() # False
3986"Dženan".istitle() # True
3987"DŽenan".istitle() # False ("DŽ" is a single Unicode letter)
3988"123".istitle() # False
3989```
3990
3991<a id='string·isupper'></a>
3992### string·isupper
3993
3994`S.isupper()` reports whether the string S contains at least one cased Unicode
3995letter, and all such letters are uppercase.
3996
3997```python
3998"HAL-9000".isupper() # True
3999"Catch-22".isupper() # False
4000"123".isupper() # False
4001```
4002
4003<a id='string·join'></a>
4004### string·join
4005
4006`S.join(iterable)` returns the string formed by concatenating each
4007element of its argument, with a copy of the string S between
4008successive elements. The argument must be an iterable whose elements
4009are strings.
4010
4011```python
4012", ".join(["one", "two", "three"]) # "one, two, three"
4013"a".join("ctmrn".codepoints()) # "catamaran"
4014```
4015
4016<a id='string·lower'></a>
4017### string·lower
4018
4019`S.lower()` returns a copy of the string S with letters converted to lowercase.
4020
4021```python
4022"Hello, World!".lower() # "hello, world!"
4023```
4024
4025<a id='string·lstrip'></a>
4026### string·lstrip
4027
4028`S.lstrip()` returns a copy of the string S with leading whitespace removed.
4029
4030Like `strip`, it accepts an optional string parameter that specifies an
4031alternative set of Unicode code points to remove.
4032
4033```python
4034" hello ".lstrip() # "hello "
4035" hello ".lstrip("h o") # "ello "
4036```
4037
4038<a id='string·partition'></a>
4039### string·partition
4040
4041`S.partition(x)` splits string S into three parts and returns them as
4042a tuple: the portion before the first occurrence of string `x`, `x` itself,
4043and the portion following it.
4044If S does not contain `x`, `partition` returns `(S, "", "")`.
4045
4046`partition` fails if `x` is not a string, or is the empty string.
4047
4048```python
4049"one/two/three".partition("/") # ("one", "/", "two/three")
4050```
4051
4052<a id='string·removeprefix'></a>
4053### string·removeprefix
4054
4055`S.removeprefix(prefix)` returns a copy of string S with the prefix `prefix`
4056removed if S starts with `prefix`, otherwise it returns S.
4057
4058```python
4059"banana".removeprefix("ban") # "ana"
4060"banana".removeprefix("foo") # "banana"
4061"foofoobar".removeprefix("foo") # "foobar"
4062```
4063
4064<a id='string·removesuffix'></a>
4065### string·removesuffix
4066
4067`S.removesuffix(suffix)` returns a copy of string S with the suffix `suffix`
4068removed if S ends with `suffix`, otherwise it returns S.
4069
4070```python
4071"banana".removesuffix("nana") # "ba"
4072"banana".removesuffix("foo") # "banana"
4073"banana".removesuffix("na") # "bana"
4074```
4075
4076<a id='string·replace'></a>
4077### string·replace
4078
4079`S.replace(old, new[, count])` returns a copy of string S with all
4080occurrences of substring `old` replaced by `new`. If the optional
4081argument `count`, which must be an `int`, is non-negative, it
4082specifies a maximum number of occurrences to replace.
4083
4084```python
4085"banana".replace("a", "o") # "bonono"
4086"banana".replace("a", "o", 2) # "bonona"
4087```
4088
4089<a id='string·rfind'></a>
4090### string·rfind
4091
4092`S.rfind(sub[, start[, end]])` returns the index of the substring `sub` within
4093S, like `S.find`, except that `rfind` returns the index of the substring's
4094_last_ occurrence.
4095
4096```python
4097"bonbon".rfind("on") # 4
4098"bonbon".rfind("on", None, 5) # 1
4099"bonbon".rfind("on", 2, 5) # -1
4100```
4101
4102<a id='string·rindex'></a>
4103### string·rindex
4104
4105`S.rindex(sub[, start[, end]])` returns the index of the substring `sub` within
4106S, like `S.index`, except that `rindex` returns the index of the substring's
4107_last_ occurrence.
4108
4109```python
4110"bonbon".rindex("on") # 4
4111"bonbon".rindex("on", None, 5) # 1 (in "bonbo")
4112"bonbon".rindex("on", 2, 5) # error: substring not found (in "nbo")
4113```
4114
4115<a id='string·rpartition'></a>
4116### string·rpartition
4117
4118`S.rpartition(x)` is like `partition`, but splits `S` at the last occurrence of `x`.
4119
4120```python
4121"one/two/three".partition("/") # ("one/two", "/", "three")
4122```
4123
4124<a id='string·rsplit'></a>
4125### string·rsplit
4126
4127`S.rsplit([sep[, maxsplit]])` splits a string into substrings like `S.split`,
4128except that when a maximum number of splits is specified, `rsplit` chooses the
4129rightmost splits.
4130
4131```python
4132"banana".rsplit("n") # ["ba", "a", "a"]
4133"banana".rsplit("n", 1) # ["bana", "a"]
4134"one two three".rsplit(None, 1) # ["one two", "three"]
4135"".rsplit("n") # [""]
4136```
4137
4138<a id='string·rstrip'></a>
4139### string·rstrip
4140
4141`S.rstrip()` returns a copy of the string S with trailing whitespace removed.
4142
4143Like `strip`, it accepts an optional string parameter that specifies an
4144alternative set of Unicode code points to remove.
4145
4146```python
4147" hello ".rstrip() # " hello"
4148" hello ".rstrip("h o") # " hell"
4149```
4150
4151<a id='string·split'></a>
4152### string·split
4153
4154`S.split([sep [, maxsplit]])` returns the list of substrings of S,
4155splitting at occurrences of the delimiter string `sep`.
4156
4157Consecutive occurrences of `sep` are considered to delimit empty
4158strings, so `'food'.split('o')` returns `['f', '', 'd']`.
4159Splitting an empty string with a specified separator returns `['']`.
4160If `sep` is the empty string, `split` fails.
4161
4162If `sep` is not specified or is `None`, `split` uses a different
4163algorithm: it removes all leading spaces from S
4164(or trailing spaces in the case of `rsplit`),
4165then splits the string around each consecutive non-empty sequence of
4166Unicode white space characters.
4167If S consists only of white space, `S.split()` returns the empty list.
4168
4169If `maxsplit` is given and non-negative, it specifies a maximum number of splits.
4170
4171```python
4172"one two three".split() # ["one", "two", "three"]
4173"one two three".split(" ") # ["one", "two", "", "three"]
4174"one two three".split(None, 1) # ["one", "two three"]
4175"banana".split("n") # ["ba", "a", "a"]
4176"banana".split("n", 1) # ["ba", "ana"]
4177"".split("n") # [""]
4178```
4179
4180<a id='string·elems'></a>
4181### string·elems
4182
4183`S.elems()` returns an iterable value containing successive
41841-byte substrings of S.
4185To materialize the entire sequence, apply `list(...)` to the result.
4186
4187Example:
4188
4189```python
4190list('Hello, 世界'.elems()) # ["H", "e", "l", "l", "o", ",", " ", "\xe4", "\xb8", "\x96", "\xe7", "\x95", "\x8c"]
4191```
4192
4193See also: `string·elem_ords`.
4194
4195
4196<a id='string·codepoints'></a>
4197### string·codepoints
4198
4199`S.codepoints()` returns an iterable value containing the sequence of
4200substrings of S that each encode a single Unicode code point.
4201Each invalid code within the string is treated as if it encodes the
4202Unicode replacement character, U+FFFD.
4203
4204By returning an iterable, not a list, the cost of decoding the string
4205is deferred until actually needed; apply `list(...)` to the result to
4206materialize the entire sequence.
4207
4208Example:
4209
4210```python
4211list('Hello, 世界'.codepoints()) # ['H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界']
4212
4213for cp in 'Hello, 世界'.codepoints():
4214 print(cp) # prints 'H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界'
4215```
4216
4217See also: `string·codepoint_ords`.
4218
4219<b>Implementation note:</b> `codepoints` is not provided by the Java implementation.
4220
4221<a id='string·splitlines'></a>
4222### string·splitlines
4223
4224`S.splitlines([keepends])` returns a list whose elements are the
4225successive lines of S, that is, the strings formed by splitting S at
4226line terminators (currently assumed to be a single newline, `\n`,
4227regardless of platform).
4228
4229The optional argument, `keepends`, is interpreted as a Boolean.
4230If true, line terminators are preserved in the result, though
4231the final element does not necessarily end with a line terminator.
4232
4233As a special case, if S is the empty string,
4234`splitlines` returns the empty list.
4235
4236```python
4237"one\n\ntwo".splitlines() # ["one", "", "two"]
4238"one\n\ntwo".splitlines(True) # ["one\n", "\n", "two"]
4239"".splitlines() # [] -- a special case
4240```
4241
4242<a id='string·startswith'></a>
4243### string·startswith
4244
4245`S.startswith(prefix[, start[, end]])` reports whether the string
4246`S[start:end]` has the specified prefix.
4247
4248```python
4249"filename.star".startswith("filename") # True
4250```
4251
4252The `prefix` argument may be a tuple of strings, in which case the
4253function reports whether any one of them is a prefix.
4254
4255```python
4256'abc'.startswith(('a', 'A')) # True
4257'ABC'.startswith(('a', 'A')) # True
4258'def'.startswith(('a', 'A')) # False
4259```
4260
4261<a id='string·strip'></a>
4262### string·strip
4263
4264`S.strip()` returns a copy of the string S with leading and trailing whitespace removed.
4265
4266It accepts an optional string argument:
4267`S.strip(cutset)` instead removes all leading
4268and trailing Unicode code points contained in `cutset`.
4269
4270```python
4271" hello ".strip() # "hello"
4272" hello ".strip("h o") # "ell"
4273```
4274
4275<a id='string·title'></a>
4276### string·title
4277
4278`S.title()` returns a copy of the string S with letters converted to title case.
4279
4280Letters are converted to upper case at the start of words, lower case elsewhere.
4281
4282```python
4283"hElLo, WoRlD!".title() # "Hello, World!"
4284"dženan".title() # "Dženan" ("Dž" is a single Unicode letter)
4285```
4286
4287<a id='string·upper'></a>
4288### string·upper
4289
4290`S.upper()` returns a copy of the string S with letters converted to uppercase.
4291
4292```python
4293"Hello, World!".upper() # "HELLO, WORLD!"
4294```
4295
4296## Dialect differences
4297
4298The list below summarizes features of the Go implementation that are
4299known to differ from the Java implementation of Starlark used by Bazel.
4300Some of these features may be controlled by global options to allow
4301applications to mimic the Bazel dialect more closely. Our goal is
4302eventually to eliminate all such differences on a case-by-case basis.
4303See [Starlark spec issue 20](https://github.com/bazelbuild/starlark/issues/20).
4304
4305* String interpolation supports the `[ioxXc]` conversions.
4306* String elements are bytes.
4307* Non-ASCII strings are encoded using UTF-8.
4308* Strings support hex byte escapes.
4309* Strings have the additional methods `elem_ords`, `codepoint_ords`, and `codepoints`.
4310* The `chr` and `ord` built-in functions are supported.
4311* The `set` built-in function is provided (option: `-set`).
4312* `set & set` and `set | set` compute set intersection and union, respectively.
4313* `assert` is a valid identifier.
4314* `if`, `for`, and `while` are permitted at top level (option: `-globalreassign`).
4315* top-level rebindings are permitted (option: `-globalreassign`).
View as plain text