diff options
Diffstat (limited to 'docs/yaml/elementary')
| -rw-r--r-- | docs/yaml/elementary/any.yaml | 5 | ||||
| -rw-r--r-- | docs/yaml/elementary/bool.yml | 28 | ||||
| -rw-r--r-- | docs/yaml/elementary/dict.yml | 45 | ||||
| -rw-r--r-- | docs/yaml/elementary/int.yml | 16 | ||||
| -rw-r--r-- | docs/yaml/elementary/list.yml | 38 | ||||
| -rw-r--r-- | docs/yaml/elementary/str.yml | 264 | ||||
| -rw-r--r-- | docs/yaml/elementary/void.yml | 5 |
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++ |