Merge remote-tracking branch 'upstream/master' into lang-enumlang-enum

1 files changed, 147 insertions, 43 deletions

diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index cf0516c..bbe3dbb 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -16,12 +16,12 @@ statements* and *includes*.
 Usually one Meson statement takes just one line. There is no way to
 have multiple statements on one line as in e.g. *C*. Function and
 method calls' argument lists can be split over multiple lines. Meson
-will autodetect this case and do the right thing. In other cases you
-can get multi-line statements by ending the line with a `\`. Apart
-from line ending whitespace has no syntactic meaning.
+will autodetect this case and do the right thing.
 
-Variables
---
+In other cases, *(added 0.50)* you can get multi-line statements by ending the
+line with a `\`.  Apart from line ending whitespace has no syntactic meaning.
+
+## Variables
 
 Variables in Meson work just like in other high level programming
 languages. A variable can contain a value of any type, such as an
@@ -46,8 +46,7 @@ var2 += [4]
 # var1 is still [1, 2, 3]
 ```
 
-Numbers
---
+## Numbers
 
 Meson supports only integer numbers. They are declared simply by
 writing them out. Basic arithmetic operations are supported.
@@ -85,8 +84,7 @@ int_var = 42
 string_var = int_var.to_string()
 ```
 
-Booleans
---
+## Booleans
 
 A boolean is either `true` or `false`.
 
@@ -94,8 +92,7 @@ A boolean is either `true` or `false`.
 truth = true
 ```
 
-Strings
---
+## Strings
 
 Strings in Meson are declared with single quotes. To enter a literal
 single quote do it like this:
@@ -126,7 +123,7 @@ As in python and C, up to three octal digits are accepted in `\ooo`.
 Unrecognized escape sequences are left in the string unchanged, i.e., the
 backslash is left in the string.
 
-#### String concatenation
+### String concatenation
 
 Strings can be concatenated to form a new string using the `+` symbol.
 
@@ -136,7 +133,25 @@ str2 = 'xyz'
 combined = str1 + '_' + str2 # combined is now abc_xyz
 ```
 
-#### Strings running over multiple lines
+### String path building
+
+*(Added 0.49)*
+
+You can concatenate any two strings using `/` as an operator to build paths.
+This will always use `/` as the path separator on all platforms.
+
+```meson
+joined = '/usr/share' / 'projectname'    # => /usr/share/projectname
+joined = '/usr/local' / '/etc/name'      # => /etc/name
+
+joined = 'C:\\foo\\bar' / 'builddir'     # => C:/foo/bar/builddir
+joined = 'C:\\foo\\bar' / 'D:\\builddir' # => D:/builddir
+```
+
+Note that this is equivalent to using [`join_paths()`](Reference-manual.md#join_paths),
+which was obsoleted by this operator.
+
+### Strings running over multiple lines
 
 Strings running over multiple lines can be declared with three single
 quotes, like this:
@@ -152,7 +167,7 @@ These are raw strings that do not support the escape sequences listed
 above.  These strings can also be combined with the string formatting
 functionality described below.
 
-#### String formatting
+### String formatting
 
 Strings can be built using the string formatting functionality.
 
@@ -165,12 +180,12 @@ res = template.format('text', 1, true)
 As can be seen, the formatting works by replacing placeholders of type
 `@number@` with the corresponding argument.
 
-#### String methods
+### String methods
 
 Strings also support a number of other methods that return transformed
 copies.
 
-**.strip()**
+#### .strip()
 
 ```meson
 # Similar to the Python str.strip(). Removes leading/ending spaces and newlines
@@ -179,7 +194,7 @@ stripped_define = define.strip()
 # 'stripped_define' now has the value '-Dsomedefine'
 ```
 
-**.to_upper()**, **.to_lower()**
+#### .to_upper(), .to_lower()
 
 ```meson
 target = 'x86_FreeBSD'
@@ -187,7 +202,7 @@ upper = target.to_upper() # t now has the value 'X86_FREEBSD'
 lower = target.to_lower() # t now has the value 'x86_freebsd'
 ```
 
-**.to_int()**
+#### .to_int()
 
 ```meson
 version = '1'
@@ -195,7 +210,7 @@ version = '1'
 ver_int = version.to_int()
 ```
 
-**.contains()**, **.startswith()**, **.endswith()**
+#### .contains(), .startswith(), .endswith()
 
 ```meson
 target = 'x86_FreeBSD'
@@ -205,7 +220,27 @@ is_x86 = target.startswith('x86') # boolean value 'true'
 is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'
 ```
 
-**.split()**, **.join()**
+#### .substring()
+
+Since 0.56.0, you can extract a substring from a string.
+
+```meson
+# Similar to the Python str[start:end] syntax
+target = 'x86_FreeBSD'
+platform = target.substring(0, 3) # prefix string value 'x86'
+system = target.substring(4) # suffix string value 'FreeBSD'
+```
+
+The method accepts negative values where negative `start` is relative to the end of
+string `len(string) - start` as well as negative `end`.
+
+```meson
+string = 'foobar'
+target.substring(-5, -3) # => 'oo'
+target.substring(1, -1) # => 'ooba'
+```
+
+#### .split(), .join()
 
 ```meson
 # Similar to the Python str.split()
@@ -246,7 +281,7 @@ api_version = '@0@.@1@'.format(version_array[0], version_array[1])
 # api_version now (again) has the value '0.2'
 ```
 
-**.underscorify()**
+#### .underscorify()
 
 ```meson
 name = 'Meson Docs.txt#Reference-manual'
@@ -256,7 +291,7 @@ underscored = name.underscorify()
 # underscored now has the value 'Meson_Docs_txt_Reference_manual'
 ```
 
-**.version_compare()**
+#### .version_compare()
 
 ```meson
 version = '1.2.3'
@@ -266,8 +301,15 @@ is_new = version.version_compare('>=2.0')
 # Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
 ```
 
-Arrays
---
+Meson version comparison conventions include:
+
+```meson
+'3.6'.version_compare('>=3.6.0') == false
+```
+
+It is best to be unambiguous and specify the full revision level to compare.
+
+## Arrays
 
 Arrays are delimited by brackets. An array can contain an arbitrary number of objects of any type.
 
@@ -302,6 +344,7 @@ assign it to `my_array` instead of modifying the original since all
 objects in Meson are immutable.
 
 Since 0.49.0, you can check if an array contains an element like this:
+
 ```meson
 my_array = [1, 2]
 if 1 in my_array
@@ -312,7 +355,7 @@ if 1 not in my_array
 endif
 ```
 
-#### Array methods
+### Array methods
 
 The following methods are defined for all arrays:
 
@@ -320,8 +363,7 @@ The following methods are defined for all arrays:
  - `contains`, returns `true` if the array contains the object given as argument, `false` otherwise
  - `get`, returns the object at the given index, negative indices count from the back of the array, indexing out of bounds is a fatal error. Provided for backwards-compatibility, it is identical to array indexing.
 
-Dictionaries
---
+## Dictionaries
 
 Dictionaries are delimited by curly braces. A dictionary can contain an
 arbitrary number of key value pairs. Keys are required to be strings, values can
@@ -346,6 +388,7 @@ Visit the [Reference Manual](Reference-manual.md#dictionary-object) to read
 about the methods exposed by dictionaries.
 
 Since 0.49.0, you can check if a dictionary contains a key like this:
+
 ```meson
 my_dict = {'foo': 42, 'bar': 43}
 if 'foo' in my_dict
@@ -361,14 +404,14 @@ endif
 
 *Since 0.53.0* Keys can be any expression evaluating to a string value, not limited
 to string literals any more.
+
 ```meson
 d = {'a' + 'b' : 42}
 k = 'cd'
 d += {k : 43}
 ```
 
-Function calls
---
+## Function calls
 
 Meson provides a set of usable functions. The most common use case is
 creating build objects.
@@ -413,8 +456,7 @@ executable('progname', 'prog.c',
 
 Attempting to do this causes Meson to immediately exit with an error.
 
-Method calls
---
+## Method calls
 
 Objects can have methods, which are called with the dot operator. The
 exact methods it provides depends on the object.
@@ -424,8 +466,7 @@ myobj = some_function()
 myobj.do_something('now')
 ```
 
-If statements
---
+## If statements
 
 If statements work just like in other languages.
 
@@ -446,8 +487,7 @@ if opt != 'foo'
 endif
 ```
 
-Logical operations
---
+## Logical operations
 
 Meson has the standard range of logical operations which can be used in
 `if` statements.
@@ -537,8 +577,7 @@ endforeach
 # result is ['a', 'b']
 ```
 
-Comments
---
+## Comments
 
 A comment starts with the `#` character and extends until the end of the line.
 
@@ -547,8 +586,7 @@ some_function() # This is a comment
 some_other_function()
 ```
 
-Ternary operator
---
+## Ternary operator
 
 The ternary operator works just like in other languages.
 
@@ -560,8 +598,7 @@ The only exception is that nested ternary operators are forbidden to
 improve legibility. If your branching needs are more complex than this
 you need to write an `if/else` construct.
 
-Includes
---
+## Includes
 
 Most source trees have multiple subdirectories to process. These can
 be handled by Meson's `subdir` command. It changes to the given
@@ -576,8 +613,7 @@ test_data_dir = 'data'
 subdir('tests')
 ```
 
-User-defined functions and methods
---
+## User-defined functions and methods
 
 Meson does not currently support user-defined functions or
 methods. The addition of user-defined functions would make Meson
@@ -588,3 +624,71 @@ FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup
 because of this limitation you find yourself copying and pasting code
 a lot you may be able to use a [`foreach` loop
 instead](#foreach-statements).
+
+## Stability Promises
+
+Meson is very actively developed and continuously improved. There is a
+possibility that future enhancements to the Meson build system will require
+changes to the syntax. Such changes might be the addition of new reserved
+keywords, changing the meaning of existing keywords or additions around the
+basic building blocks like statements and fundamental types. It is planned
+to stabilize the syntax with the 1.0 release.
+
+## Grammar
+
+This is the full Meson grammar, as it is used to parse Meson build definition files:
+
+```
+additive_expression: multiplicative_expression | (additive_expression additive_operator multiplicative_expression)
+additive_operator: "+" | "-"
+argument_list: positional_arguments ["," keyword_arguments] | keyword_arguments
+array_literal: "[" [expression_list] "]"
+assignment_expression: conditional_expression | (logical_or_expression assignment_operator assignment_expression)
+assignment_operator: "=" | "*=" | "/=" | "%=" | "+=" | "-="
+boolean_literal: "true" | "false"
+build_definition: (NEWLINE | statement)*
+condition: expression
+conditional_expression: logical_or_expression | (logical_or_expression "?" expression ":" assignment_expression
+decimal_literal: DECIMAL_NUMBER
+DECIMAL_NUMBER: /[1-9][0-9]*/
+dictionary_literal: "{" [key_value_list] "}"
+equality_expression: relational_expression | (equality_expression equality_operator relational_expression)
+equality_operator: "==" | "!="
+expression: assignment_expression
+expression_list: expression ("," expression)*
+expression_statememt: expression
+function_expression: id_expression "(" [argument_list] ")"
+hex_literal: "0x" HEX_NUMBER
+HEX_NUMBER: /[a-fA-F0-9]+/
+id_expression: IDENTIFIER
+IDENTIFIER: /[a-zA-Z_][a-zA-Z_0-9]*/
+identifier_list: id_expression ("," id_expression)*
+integer_literal: decimal_literal | octal_literal | hex_literal
+iteration_statement: "foreach" identifier_list ":" id_expression NEWLINE (statement | jump_statement)* "endforeach"
+jump_statement: ("break" | "continue") NEWLINE
+key_value_item: expression ":" expression
+key_value_list: key_value_item ("," key_value_item)*
+keyword_item: id_expression ":" expression
+keyword_arguments: keyword_item ("," keyword_item)*
+literal: integer_literal | string_literal | boolean_literal | array_literal | dictionary_literal
+logical_and_expression: equality_expression | (logical_and_expression "and" equality_expression)
+logical_or_expression: logical_and_expression | (logical_or_expression "or" logical_and_expression)
+method_expression: postfix_expression "." function_expression
+multiplicative_expression: unary_expression | (multiplicative_expression multiplicative_operator unary_expression)
+multiplicative_operator: "*" | "/" | "%"
+octal_literal: "0o" OCTAL_NUMBER
+OCTAL_NUMBER: /[0-7]+/
+positional_arguments: expression ("," expression)*
+postfix_expression: primary_expression | subscript_expression | function_expression | method_expression
+primary_expression: literal | ("(" expression ")") | id_expression
+relational_expression: additive_expression | (relational_expression relational_operator additive_expression)
+relational_operator: ">" | "<" | ">=" | "<=" | "in" | ("not" "in")
+selection_statement: "if" condition NEWLINE (statement)* ("elif" condition NEWLINE (statement)*)* ["else" (statement)*] "endif"
+statement: (expression_statement | selection_statement | iteration_statement) NEWLINE
+string_literal: ("'" STRING_SIMPLE_VALUE "'") | ("'''" STRING_MULTILINE_VALUE "'''")
+STRING_MULTILINE_VALUE: \.*?(''')\
+STRING_SIMPLE_VALUE: \.*?(?<!\\)(\\\\)*?'\
+subscript_expression: postfix_expression "[" expression "]"
+unary_expression: postfix_expression | (unary_operator unary_expression)
+unary_operator: "not" | "+" | "-"
+```