docs: Add the YAML Reference manual

7 files changed, 401 insertions, 0 deletions

diff --git a/docs/yaml/elementary/any.yaml b/docs/yaml/elementary/any.yaml
new file mode 100644
index 0000000..70fcf27
--- /dev/null
+++ b/docs/yaml/elementary/any.yaml
@@ -0,0 +1,5 @@
+name: any
+long_name: Any
+description: |
+  A placeholder representing all types.
+  This includes builtin, as well as returned objects.
diff --git a/docs/yaml/elementary/bool.yml b/docs/yaml/elementary/bool.yml
new file mode 100644
index 0000000..061f940
--- /dev/null
+++ b/docs/yaml/elementary/bool.yml
@@ -0,0 +1,28 @@
+name: bool
+long_name: Boolean
+description: A boolean object which is either `true` or `false`
+
+methods:
+- name: to_int
+  returns: int
+  description: Returns `1` if `true` and `0` if `false`
+
+- name: to_string
+  returns: str
+  description: |
+    Returns the string `'true'` if the boolean is true or `'false'` otherwise.
+    You can also pass it two strings as positional
+    arguments to specify what to return for true/false. For instance,
+    `bool.to_string('yes', 'no')` will return `yes` if the boolean is
+    true and `no` if it is false.
+
+  optargs:
+    true_str:
+      type: str
+      default: "'true'"
+      description: The string to return when the boolean is `true`
+
+    false_str:
+      type: str
+      default: "'false'"
+      description: The string to return when the boolean is `false`
diff --git a/docs/yaml/elementary/dict.yml b/docs/yaml/elementary/dict.yml
new file mode 100644
index 0000000..5afe835
--- /dev/null
+++ b/docs/yaml/elementary/dict.yml
@@ -0,0 +1,45 @@
+name: dict
+long_name: Dict
+since: 0.47.0
+is_container: true
+description: |
+  Stores a mapping of strings to other objects. See [dictionaries](Syntax.md#dictionaries).
+
+  You can also iterate over dictionaries with the [`foreach`
+  statement](Syntax.md#foreach-statements).
+
+  *(since 0.48.0)* Dictionaries can be added (e.g. `d1 = d2 + d3` and `d1 += d2`).
+  Values from the second dictionary overrides values from the first.
+
+
+methods:
+- name: has_key
+  returns: bool
+  description: Returns `true` if the dictionary contains the key given as argument, `false` otherwise.
+
+  posargs:
+    key:
+      type: str
+      description: The key to query.
+
+- name: get
+  returns: any
+  description: |
+    returns the value for the key given as first
+    argument if it is present in the dictionary, or the optional
+    fallback value given as the second argument. If a single argument
+    was given and the key was not found, causes a fatal error
+
+  posargs:
+    key:
+      type: str
+      description: The key to query.
+
+  optargs:
+    fallback:
+      type: any
+      description: Fallback value that is returned if the key is not in the [[@dict]].
+
+- name: keys
+  returns: list[str]
+  description: Returns an array of keys in the dictionary.
diff --git a/docs/yaml/elementary/int.yml b/docs/yaml/elementary/int.yml
new file mode 100644
index 0000000..65ab959
--- /dev/null
+++ b/docs/yaml/elementary/int.yml
@@ -0,0 +1,16 @@
+name: int
+long_name: Integer
+description: All integer numbers. See [Numbers](Syntax.md#numbers) for more information.
+
+methods:
+- name: is_even
+  returns: bool
+  description: Returns true if the number is even.
+
+- name: is_odd
+  returns: bool
+  description: Returns true if the number is odd
+
+- name: to_string
+  returns: str
+  description: Returns the value of the number as a string.
diff --git a/docs/yaml/elementary/list.yml b/docs/yaml/elementary/list.yml
new file mode 100644
index 0000000..085b6ca
--- /dev/null
+++ b/docs/yaml/elementary/list.yml
@@ -0,0 +1,38 @@
+name: list
+long_name: List
+description: An array of elements. See [arrays](Syntax.md#arrays).
+is_container: true
+
+methods:
+- name: contains
+  returns: bool
+  description: |
+    Returns `true` if the array contains the object
+    given as argument, `false` otherwise
+
+  posargs:
+    item:
+      type: any
+      description: The item to check
+
+- name: get
+  returns: any
+  description: |
+    returns the object at the given index,
+    negative indices count from the back of the array, indexing out of
+    bounds returns the `fallback` value *(since 0.38.0)* or, if it is
+    not specified, causes a fatal error
+
+  posargs:
+    index:
+      type: int
+      description: Index of the list position to query. Negative values start at the end of the list
+
+  optargs:
+    fallback:
+      type: any
+      description: Fallback value that is returned if the index is out of range.
+
+- name: length
+  returns: int
+  description: Returns the current size of the array / list.
diff --git a/docs/yaml/elementary/str.yml b/docs/yaml/elementary/str.yml
new file mode 100644
index 0000000..e55243f
--- /dev/null
+++ b/docs/yaml/elementary/str.yml
@@ -0,0 +1,264 @@
+name: str
+long_name: String
+description: |
+  All [strings](Syntax.md#strings) have the following methods. Strings
+  are immutable, all operations return their results as a new string.
+
+methods:
+
+# str.format(fmt, value...)
+- name: format
+  returns: str
+  description: |
+    Strings can be built using the string formatting functionality.
+
+    See [the Meson syntax entry](Syntax.md#string-formatting) for more
+    information.
+  example: |
+    ```meson
+    template = 'string: @0@, number: @1@, bool: @2@'
+    res = template.format('text', 1, true)
+    # res now has value 'string: text, number: 1, bool: true'
+    ```
+
+  posargs:
+    fmt:
+      description: |
+        The string to format.
+
+        The formatting works by replacing placeholders of type `@number@` with
+        the corresponding varargs.
+      type: str
+
+  varargs:
+    name: value
+    description: The values to replace the @number@ placeholders in the format string.
+    type: int | bool | str
+
+# str.replace(old, new)
+- name: replace
+  description: Search all occurences of `old` and and replace it with `new`
+  returns: str
+  since: 0.58.0
+  example: |
+    ```meson
+    # Replaces all instances of one substring with another
+    s = 'semicolons;as;separators'
+    s = s.replace('as', 'are')
+    # 's' now has the value of 'semicolons;are;separators'
+    ```
+
+  posargs:
+    old:
+      description: The substring to search
+      type: str
+
+    new:
+      description: The replacement string
+      type: str
+
+# str.strip()
+- name: strip
+  description: Removes leading/ending spaces and newlines from the string.
+  returns: str
+  example: |
+    ```meson
+    # Similar to the Python str.strip(). Removes leading/ending spaces and newlines
+    define = ' -Dsomedefine '
+    stripped_define = define.strip()
+    # 'stripped_define' now has the value '-Dsomedefine'
+    ```
+
+  optargs:
+    strip_chars:
+      type: str
+      since: 0.43.0
+      description: All characters in this string will be stripped.
+
+# str.to_lower()
+- name: to_lower
+  description: Converts all characters to lower case
+  returns: str
+  example: |
+    ```meson
+    target = 'x86_FreeBSD'
+    lower = target.to_lower() # t now has the value 'x86_freebsd'
+    ```
+
+# str.to_upper()
+- name: to_upper
+  description: Converts all characters to upper case
+  returns: str
+  example: |
+    ```meson
+    target = 'x86_FreeBSD'
+    upper = target.to_upper() # t now has the value 'X86_FREEBSD'
+    ```
+
+# str.to_int()
+- name: to_int
+  description: Converts the string to an int and throws an error if it can't be
+  returns: int
+  example: |
+    ```meson
+    version = '1'
+    # Converts the string to an int and throws an error if it can't be
+    ver_int = version.to_int()
+    ```
+
+# str.contains()
+- name: contains
+  returns: bool
+  description: Returns `true` if string contains the string specified as the argument.
+  example: |
+    ```meson
+    target = 'x86_FreeBSD'
+    is_fbsd = target.to_lower().contains('freebsd')
+    # is_fbsd now has the boolean value 'true'
+    ```
+
+  posargs:
+    fragment:
+      type: str
+      description: The string fragment to check
+
+# str.startswith()
+- name: startswith
+  returns: bool
+  description: Returns true if string starts with the string specified as the argument.
+  posargs_inherit: str.contains
+  example: |
+    ```meson
+    target = 'x86_FreeBSD'
+    is_x86 = target.startswith('x86') # boolean value 'true'
+    ```
+
+# str.endswith()
+- name: endswith
+  returns: bool
+  description: Returns true if string ends with the string specified as the argument.
+  posargs_inherit: str.contains
+  example: |
+    ```meson
+    target = 'x86_FreeBSD'
+    is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'
+    ```
+
+# str.substring()
+- name: substring
+  returns: str
+  since: 0.56.0
+  description: |
+    Returns a substring specified from `start` to `end`.
+    Both `start` and `end` arguments are optional, so, for example, `'foobar'.substring()` will return `'foobar'`.
+
+    The method accepts negative values where negative `start` is relative to the end of
+    string `len(string) - start` as well as negative `end`.
+
+  example: |
+    ```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'
+    ```
+
+    Example with negative values:
+
+    ```meson
+    string = 'foobar'
+    string.substring(-5, -3) # => 'oo'
+    string.substring(1, -1) # => 'ooba'
+    ```
+
+  optargs:
+    start:
+      type: int
+      description: The start position
+
+    end:
+      type: int
+      description: The end position
+
+# str.split
+- name: split
+  returns: list[str]
+  description: |
+    Splits the string at the specified character
+    (or whitespace if not set) and returns the parts in an
+    array.
+
+  example: |
+    ```meson
+    # Similar to the Python str.split()
+    components = 'a b   c d '.split()
+    # components now has the value ['a', 'b', 'c', 'd']
+    components = 'a b   c d '.split(' ')
+    # components now has the value ['a', 'b', '', '', 'c', 'd', '']
+    ```
+
+  optargs:
+    split_string:
+      type: str
+      description: Specifies the character / substring where to split the string.
+
+# str.join()
+- name: join
+  returns: str
+  description: |
+    The opposite of split,
+    for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`.
+
+  example: |
+    ```meson
+    # Similar to the Python str.join()
+    output = ' '.join(['foo', 'bar'])
+    # Output value is 'foo bar'
+    pathsep = ':'
+    path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
+    # path now has the value '/usr/bin:/bin:/usr/local/bin'
+    ```
+
+  posargs:
+    string_list:
+      type: list[str]
+      description: The list to join with the current string
+
+# str.underscorify
+- name: underscorify
+  returns: str
+  description: Creates a string where every non-alphabetical non-number character is replaced with `_`.
+  example: |
+    ```meson
+    name = 'Meson Docs.txt#Reference-manual'
+    # Replaces all characters other than `a-zA-Z0-9` with `_` (underscore)
+    # Useful for substituting into #defines, filenames, etc.
+    underscored = name.underscorify()
+    # underscored now has the value 'Meson_Docs_txt_Reference_manual'
+    ```
+
+# str.version_compare
+- name: version_compare
+  returns: bool
+  description: Does semantic version comparison.
+  example: |
+    ```meson
+    version = '1.2.3'
+    # Compare version numbers semantically
+    is_new = version.version_compare('>=2.0')
+    # is_new now has the boolean value false
+    # Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
+    ```
+
+    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.
+
+  posargs:
+    compare_string:
+      type: str
+      description: The string to compare to.
diff --git a/docs/yaml/elementary/void.yml b/docs/yaml/elementary/void.yml
new file mode 100644
index 0000000..43f51af
--- /dev/null
+++ b/docs/yaml/elementary/void.yml
@@ -0,0 +1,5 @@
+name: void
+long_name: void
+description: |
+  Indicates that the function does not return anything.
+  Similar to `void` in C and C++