diff options
Diffstat (limited to 'api')
| -rw-r--r-- | api/api.md | 17 | ||||
| -rw-r--r-- | api/booleans.md | 2 | ||||
| -rw-r--r-- | api/booleans.yaml | 3 | ||||
| -rw-r--r-- | api/builtins.yaml | 9 | ||||
| -rw-r--r-- | api/bytes.yaml | 4 | ||||
| -rw-r--r-- | api/integers.yaml | 15 | ||||
| -rw-r--r-- | api/lists.yaml | 26 | ||||
| -rw-r--r-- | api/nums.yaml | 65 | ||||
| -rw-r--r-- | api/paths.yaml | 39 | ||||
| -rw-r--r-- | api/sets.yaml | 11 | ||||
| -rw-r--r-- | api/tables.yaml | 6 | ||||
| -rw-r--r-- | api/text.md | 15 | ||||
| -rw-r--r-- | api/text.yaml | 54 |
13 files changed, 243 insertions, 23 deletions
@@ -189,7 +189,7 @@ sleep(1.5) Bool.parse : func(text: Text -> Bool?) ``` -Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. +Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. Argument | Type | Description | Default ---------|------|-------------|--------- @@ -4664,13 +4664,14 @@ last | `Int` | The index of the last grapheme cluster to include (1-indexed). | ## Text.translate ```tomo -Text.translate : func(translations: {Text=Text} -> Text) +Text.translate : func(text: Text, translations: {Text=Text} -> Text) ``` Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See Text.replace() for more information about replacement behavior. Argument | Type | Description | Default ---------|------|-------------|--------- +text | `Text` | The text to be translated. | - translations | `{Text=Text}` | A table mapping from target text to its replacement. | - **Return:** The text with all occurrences of the targets replaced with their corresponding replacement text. @@ -4679,12 +4680,12 @@ translations | `{Text=Text}` | A table mapping from target text to its replaceme **Example:** ```tomo >> "A <tag> & an amperand".translate({ -"&" = "&", -"<" = "<", -">" = ">", -'"" = """, -"'" = "'", -} + "&" = "&", + "<" = "<", + ">" = ">", + '"" = """, + "'" = "'", +}) = "A <tag> & an ampersand" ``` diff --git a/api/booleans.md b/api/booleans.md index 338a26e9..d45be505 100644 --- a/api/booleans.md +++ b/api/booleans.md @@ -9,7 +9,7 @@ Bool.parse : func(text: Text -> Bool?) ``` -Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. +Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. Argument | Type | Description | Default ---------|------|-------------|--------- diff --git a/api/booleans.yaml b/api/booleans.yaml index 851b7b0b..0831ac18 100644 --- a/api/booleans.yaml +++ b/api/booleans.yaml @@ -1,6 +1,7 @@ Bool.parse: + short: parse into boolean description: > - Converts a string representation of a boolean value into a boolean. Acceptable + Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. return: diff --git a/api/builtins.yaml b/api/builtins.yaml index 269380ca..6bb6d762 100644 --- a/api/builtins.yaml +++ b/api/builtins.yaml @@ -1,4 +1,5 @@ ask: + short: get user input description: > Gets a line of user input text with a prompt. note: > @@ -34,6 +35,7 @@ ask: = "Arthur Dent" exit: + short: exit the program description: > Exits the program with a given status and optionally prints a message. return: @@ -56,6 +58,7 @@ exit: exit(status=1, "Goodbye forever!") getenv: + short: get an environment variable description: > Gets an environment variable. return: @@ -72,6 +75,7 @@ getenv: = "xterm-256color"? print: + short: print some text description: > Prints a message to the console (alias for say()). return: @@ -93,6 +97,7 @@ print: print("world!") say: + short: print some text description: > Prints a message to the console. return: @@ -114,6 +119,7 @@ say: say("world!") setenv: + short: set an environment variable description: > Sets an environment variable. return: @@ -133,6 +139,7 @@ setenv: setenv("FOOBAR", "xyz") sleep: + short: wait for an interval description: > Pause execution for a given number of seconds. return: @@ -148,6 +155,7 @@ sleep: sleep(1.5) fail: + short: abort the program description: > Prints a message to the console, aborts the program, and prints a stack trace. return: @@ -163,6 +171,7 @@ fail: fail("Oh no!") USE_COLOR: + short: whether to use colors type: Bool description: > Whether or not the console prefers ANSI color escape sequences in the output. diff --git a/api/bytes.yaml b/api/bytes.yaml index 01f27fc3..52f48528 100644 --- a/api/bytes.yaml +++ b/api/bytes.yaml @@ -1,4 +1,5 @@ Byte.hex: + short: convert to hexidecimal description: > Convert a byte to a hexidecimal text representation. return: @@ -25,6 +26,7 @@ Byte.hex: = "0x12" Byte.is_between: + short: test if inside a range description: > Determines if an integer is between two numbers (inclusive). return: @@ -53,6 +55,7 @@ Byte.is_between: = yes Byte.parse: + short: convert text to a byte description: > Parse a byte literal from text. return: @@ -71,6 +74,7 @@ Byte.parse: = none Byte.to: + short: iterate over a range of bytes description: > Returns an iterator function that iterates over the range of bytes specified. return: diff --git a/api/integers.yaml b/api/integers.yaml index e13246e8..4e5ec46c 100644 --- a/api/integers.yaml +++ b/api/integers.yaml @@ -1,4 +1,5 @@ Int.abs: + short: absolute value description: > Calculates the absolute value of an integer. return: @@ -15,6 +16,7 @@ Int.abs: = 10 Int.choose: + short: binomial coefficient description: > Computes the binomial coefficient of the given numbers (the equivalent of `n` choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * @@ -38,6 +40,7 @@ Int.choose: = 6 Int.clamped: + short: clamp an integer description: > Returns the given number clamped between two values so that it is within that range. @@ -63,6 +66,7 @@ Int.clamped: = 5 Int.factorial: + short: factorial description: > Computes the factorial of an integer. return: @@ -79,6 +83,7 @@ Int.factorial: = 3628800 Int.format: + short: text formatting description: > Formats an integer as a string with a specified number of digits. return: @@ -100,6 +105,7 @@ Int.format: = "00042" Int.hex: + short: convert to hexidecimal description: > Converts an integer to its hexadecimal representation. return: @@ -131,6 +137,7 @@ Int.hex: = "0x00FF" Int.is_between: + short: test if an int is in a range description: > Determines if an integer is between two numbers (inclusive). return: @@ -159,6 +166,7 @@ Int.is_between: = yes Int.is_prime: + short: check if an integer is prime description: > Determines if an integer is a prime number. note: > @@ -187,6 +195,7 @@ Int.is_prime: = no Int.next_prime: + short: get the next prime description: > Finds the next prime number greater than the given integer. note: > @@ -208,6 +217,7 @@ Int.next_prime: = 13 Int.octal: + short: convert to octal description: > Converts an integer to its octal representation. return: @@ -234,6 +244,7 @@ Int.octal: = "0o0100" Int.onward: + short: iterate from a number onward description: > Return an iterator that counts infinitely from the starting integer (with an optional step size). @@ -260,6 +271,7 @@ Int.onward: = [5, 6, 7, 8, 9, 10] Int.parse: + short: convert text to integer description: > Converts a text representation of an integer into an integer. return: @@ -288,6 +300,7 @@ Int.parse: = none : Int8? Int.prev_prime: + short: get the previous prime description: > Finds the previous prime number less than the given integer. If there is no previous prime number (i.e. if a number less than `2` is @@ -311,6 +324,7 @@ Int.prev_prime: = 7 Int.sqrt: + short: square root description: > Calculates the nearest square root of an integer. return: @@ -329,6 +343,7 @@ Int.sqrt: = 4 Int.to: + short: iterate a range of integers description: > Returns an iterator function that iterates over the range of numbers specified. return: diff --git a/api/lists.yaml b/api/lists.yaml index c746cf57..4a7c48c1 100644 --- a/api/lists.yaml +++ b/api/lists.yaml @@ -1,4 +1,5 @@ List.binary_search: + short: binary search description: > Performs a binary search on a sorted list. return: @@ -30,6 +31,7 @@ List.binary_search: = 6 List.by: + short: slice by a step value description: > Creates a new list with elements spaced by the specified step value. return: @@ -50,6 +52,7 @@ List.by: = [1, 3, 5] List.clear: + short: clear a list description: > Clears all elements from the list. return: @@ -65,6 +68,7 @@ List.clear: >> my_list.clear() List.counts: + short: count occurrences description: > Counts the occurrences of each element in the list. return: @@ -81,6 +85,7 @@ List.counts: = {10=1, 20=1, 30=3} List.find: + short: find an element's index description: > Finds the index of the first occurrence of an element (if any). return: @@ -104,6 +109,7 @@ List.find: = none : Int? List.first: + short: find an index where a predicate matches description: > Find the index of the first item that matches a predicate function (if any). return: @@ -128,6 +134,7 @@ List.first: = none : Int? List.from: + short: slice an array from a start index description: > Returns a slice of the list starting from a specified index. return: @@ -148,6 +155,7 @@ List.from: = [30, 40, 50] List.has: + short: check for member description: > Checks if the list has an element. return: @@ -168,6 +176,7 @@ List.has: = yes List.heap_pop: + short: heap pop description: > Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap. @@ -193,6 +202,7 @@ List.heap_pop: = 10 List.heap_push: + short: heap push description: > Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. @@ -218,6 +228,7 @@ List.heap_push: >> my_heap.heap_push(10) List.heapify: + short: convert a list into a heap description: > Converts a list into a heap. return: @@ -240,6 +251,7 @@ List.heapify: >> my_heap.heapify() List.insert: + short: add an item to a list description: > Inserts an element at a specified position in the list. return: @@ -274,6 +286,7 @@ List.insert: = [10, 999, 20, 30] List.insert_all: + short: add multiple items to a list description: > Inserts a list of items at a specified position in the list. return: @@ -308,6 +321,7 @@ List.insert_all: = [10, 99, 100, 20, 30, 40] List.pop: + short: pop an item from a list description: > Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one @@ -344,6 +358,7 @@ List.pop: = &[10, 30] List.random: + short: pick a random element description: > Selects a random element from the list. return: @@ -367,6 +382,7 @@ List.random: = 20 List.remove_at: + short: remove an item by index description: > Removes elements from the list starting at a specified index. return: @@ -402,6 +418,7 @@ List.remove_at: = [10, 50] List.remove_item: + short: remove an item by value description: > Removes all occurrences of a specified item from the list. return: @@ -435,6 +452,7 @@ List.remove_item: = [20, 30] List.reversed: + short: get a reversed list description: > Returns a reversed slice of the list. return: @@ -451,6 +469,7 @@ List.reversed: = [30, 20, 10] List.sample: + short: weighted random choices description: > Selects a sample of elements from the list, optionally with weighted probabilities. @@ -495,6 +514,7 @@ List.sample: = [10, 10] List.shuffle: + short: shuffle a list in place description: > Shuffles the elements of the list in place. return: @@ -517,6 +537,7 @@ List.shuffle: >> list.shuffle() List.shuffled: + short: return a shuffled list description: > Creates a new list with elements shuffled. return: @@ -540,6 +561,7 @@ List.shuffled: = [40, 10, 30, 20] List.slice: + short: get a slice of a list description: > Returns a slice of the list spanning the given indices (inclusive). return: @@ -569,6 +591,7 @@ List.slice: = [30, 40] List.sort: + short: sort a list description: > Sorts the elements of the list in place in ascending order (small to large). return: @@ -596,6 +619,7 @@ List.sort: = [10, 20, -30, 40] List.sorted: + short: sorted copy of a list description: > Creates a new list with elements sorted. return: @@ -620,6 +644,7 @@ List.sorted: = [10, 20, -30, 40] List.to: + short: slice a list to an end index description: > Returns a slice of the list from the start of the original list up to a specified index (inclusive). return: @@ -643,6 +668,7 @@ List.to: = [10, 20, 30, 40] List.unique: + short: convert a list to a set description: > Returns a Set that contains the unique elements of the list. return: diff --git a/api/nums.yaml b/api/nums.yaml index d69a6b9e..37b2c7c5 100644 --- a/api/nums.yaml +++ b/api/nums.yaml @@ -1,4 +1,5 @@ Num.abs: + short: absolute value description: > Calculates the absolute value of a number. return: @@ -15,6 +16,7 @@ Num.abs: = 3.5 Num.acos: + short: arc cosine description: > Computes the arc cosine of a number. return: @@ -31,6 +33,7 @@ Num.acos: = 1.5708 Num.acosh: + short: arc hyperbolic cosine description: > Computes the inverse hyperbolic cosine of a number. return: @@ -47,6 +50,7 @@ Num.acosh: = 0 Num.asin: + short: arc sine description: > Computes the arc sine of a number. return: @@ -63,6 +67,7 @@ Num.asin: = 0.5236 Num.asinh: + short: arc hyperbolic sine description: > Computes the inverse hyperbolic sine of a number. return: @@ -79,6 +84,7 @@ Num.asinh: = 0 Num.atan: + short: arc tangent description: > Computes the arc tangent of a number. return: @@ -95,6 +101,7 @@ Num.atan: = 0.7854 Num.atan2: + short: arc tangent from 2 variables description: > Computes the arc tangent of the quotient of two numbers. return: @@ -115,6 +122,7 @@ Num.atan2: = 0.7854 Num.atanh: + short: arc hyperbolic tangent. description: > Computes the inverse hyperbolic tangent of a number. return: @@ -131,6 +139,7 @@ Num.atanh: = 0.5493 Num.cbrt: + short: cube root description: > Computes the cube root of a number. return: @@ -147,6 +156,7 @@ Num.cbrt: = 3 Num.ceil: + short: ceiling function description: > Rounds a number up to the nearest integer. return: @@ -163,6 +173,7 @@ Num.ceil: = 4 Num.clamped: + short: clamp a number description: > Returns the given number clamped between two values so that it is within that range. @@ -188,6 +199,7 @@ Num.clamped: = 5.5 Num.copysign: + short: copy a number's sign description: > Copies the sign of one number to another. return: @@ -208,6 +220,7 @@ Num.copysign: = -3 Num.cos: + short: cosine description: > Computes the cosine of a number (angle in radians). return: @@ -224,6 +237,7 @@ Num.cos: = 1 Num.cosh: + short: hyperbolic cosine description: > Computes the hyperbolic cosine of a number. return: @@ -240,6 +254,7 @@ Num.cosh: = 1 Num.erf: + short: error function description: > Computes the error function of a number. return: @@ -256,6 +271,7 @@ Num.erf: = 0 Num.erfc: + short: complimentary error function description: > Computes the complementary error function of a number. return: @@ -272,6 +288,7 @@ Num.erfc: = 1 Num.exp: + short: base-e exponentiation description: > Computes the exponential function $e^x$ for a number. return: @@ -288,6 +305,7 @@ Num.exp: = 2.7183 Num.exp2: + short: base-2 exponentiation description: > Computes $2^x$ for a number. return: @@ -304,6 +322,7 @@ Num.exp2: = 8 Num.expm1: + short: base-e exponential minus 1 description: > Computes $e^x - 1$ for a number. return: @@ -320,6 +339,7 @@ Num.expm1: = 1.7183 Num.fdim: + short: positive difference description: > Computes the positive difference between two numbers. return: @@ -342,6 +362,7 @@ Num.fdim: = 2 Num.floor: + short: floor function description: > Rounds a number down to the nearest integer. return: @@ -358,6 +379,7 @@ Num.floor: = 3 Num.format: + short: convert a number to text description: > Formats a number as a text with a specified precision. return: @@ -379,6 +401,7 @@ Num.format: = "3.14" Num.hypot: + short: Euclidean distance function description: > Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. return: @@ -399,6 +422,7 @@ Num.hypot: = 5 Num.isfinite: + short: check for finite number description: > Checks if a number is finite. return: @@ -417,6 +441,7 @@ Num.isfinite: = no Num.is_between: + short: check if a number is in a range description: > Determines if a number is between two numbers (inclusive). return: @@ -445,6 +470,7 @@ Num.is_between: = yes Num.isinf: + short: check for infinite number description: > Checks if a number is infinite. return: @@ -463,6 +489,7 @@ Num.isinf: = no Num.j0: + short: Bessel function description: > Computes the Bessel function of the first kind of order 0. return: @@ -479,6 +506,7 @@ Num.j0: = 1 Num.j1: + short: Bessel function description: > Computes the Bessel function of the first kind of order 1. return: @@ -495,6 +523,7 @@ Num.j1: = 0 Num.log: + short: natural logarithm description: > Computes the natural logarithm (base $e$) of a number. return: @@ -511,6 +540,7 @@ Num.log: = 1 Num.log10: + short: logarithm base-10 description: > Computes the base-10 logarithm of a number. return: @@ -527,6 +557,7 @@ Num.log10: = 2 Num.log1p: + short: logarithm of 1 plus x description: > Computes $\log(1 + x)$ for a number. return: @@ -543,6 +574,7 @@ Num.log1p: = 0.6931 Num.log2: + short: logarithm base-2 description: > Computes the base-2 logarithm of a number. return: @@ -559,6 +591,7 @@ Num.log2: = 3 Num.logb: + short: exponent of a floating point value description: > Computes the binary exponent (base-2 logarithm) of a number. return: @@ -575,6 +608,7 @@ Num.logb: = 3 Num.mix: + short: mix two numbers by an amount description: > Interpolates between two numbers based on a given amount. return: @@ -601,6 +635,7 @@ Num.mix: = 12.5 Num.near: + short: check if two numbers are near each other description: > Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is @@ -639,6 +674,7 @@ Num.near: = yes Num.nextafter: + short: next floating point number description: > Computes the next representable value after a given number towards a specified direction. return: @@ -659,6 +695,7 @@ Num.nextafter: = 1.0000000000000002 Num.parse: + short: convert text to number description: > Converts a text representation of a number into a floating-point number. return: @@ -678,6 +715,7 @@ Num.parse: = 1000 Num.percent: + short: format as a percentage description: > Convert a number into a percentage text with a percent sign. return: @@ -701,6 +739,7 @@ Num.percent: = "33.33%" Num.rint: + short: round to nearest integer description: > Rounds a number to the nearest integer, with ties rounded to the nearest even integer. return: @@ -719,6 +758,7 @@ Num.rint: = 2 Num.round: + short: round to nearest integer description: > Rounds a number to the nearest whole number integer. return: @@ -737,6 +777,7 @@ Num.round: = 3 Num.scientific: + short: format in scientific notation description: > Formats a number in scientific notation with a specified precision. return: @@ -758,6 +799,7 @@ Num.scientific: = "1.23e+04" Num.significand: + short: get mantissa description: > Extracts the significand (or mantissa) of a number. return: @@ -774,6 +816,7 @@ Num.significand: = 0.1234567 Num.sin: + short: sine description: > Computes the sine of a number (angle in radians). return: @@ -790,6 +833,7 @@ Num.sin: = 0 Num.sinh: + short: hyperbolic sine description: > Computes the hyperbolic sine of a number. return: @@ -806,6 +850,7 @@ Num.sinh: = 0 Num.sqrt: + short: square root description: > Computes the square root of a number. return: @@ -822,6 +867,7 @@ Num.sqrt: = 4 Num.tan: + short: tangent description: > Computes the tangent of a number (angle in radians). return: @@ -838,6 +884,7 @@ Num.tan: = 0 Num.tanh: + short: hyperbolic tangent description: > Computes the hyperbolic tangent of a number. return: @@ -854,6 +901,7 @@ Num.tanh: = 0 Num.tgamma: + short: "true gamma function" description: > Computes the gamma function of a number. return: @@ -870,6 +918,7 @@ Num.tgamma: = 1 Num.trunc: + short: truncate a number description: > Truncates a number to the nearest integer towards zero. return: @@ -888,6 +937,7 @@ Num.trunc: = -3 Num.y0: + short: Bessel function description: > Computes the Bessel function of the second kind of order 0. return: @@ -904,6 +954,7 @@ Num.y0: = -0.7652 Num.y1: + short: Bessel function description: > Computes the Bessel function of the second kind of order 1. return: @@ -921,58 +972,72 @@ Num.y1: Num.1_PI: + short: 1/pi type: Num description: > The constant $\frac{1}{\pi}$. Num.2_PI: + short: 2*pi type: Num description: > The constant $2 \times \pi$. Num.2_SQRTPI: + short: 2*sqrt(pi) type: Num description: > The constant $2 \times \sqrt{\pi}$. Num.E: + short: Euler's constant type: Num description: > The base of the natural logarithm ($e$). Num.INF: + short: infinity type: Num description: > Positive infinity. Num.LN10: + short: log(10) type: Num description: > The natural logarithm of 10. Num.LN2: + short: log(2) type: Num description: > The natural logarithm of 2. Num.LOG2E: + short: log_2(e) type: Num description: > The base 2 logarithm of $e$ Num.PI: + short: pi type: Num description: > Pi ($\pi$). Num.PI_2: + short: pi/2 type: Num description: > $\frac{\pi}{2}$ Num.PI_4: + short: pi/4 type: Num description: > $\frac{\pi}{4}$ Num.SQRT1_2: + short: sqrt(1/2) type: Num description: > $\sqrt{\frac{1}{2}}$ Num.SQRT2: + short: sqrt(2) type: Num description: > $\sqrt{2}$ Num.TAU: + short: 2*pi type: Num description: > Tau ($2 \times \pi$) diff --git a/api/paths.yaml b/api/paths.yaml index c8df3d7b..f33b7a77 100644 --- a/api/paths.yaml +++ b/api/paths.yaml @@ -1,4 +1,5 @@ Path.accessed: + short: access time description: > Gets the file access time of a file. return: @@ -23,6 +24,7 @@ Path.accessed: = none Path.append: + short: append to a file description: > Appends the given text to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. @@ -48,6 +50,7 @@ Path.append: (./log.txt).append("extra line$(\n)") Path.append_bytes: + short: append bytes to a file description: > Appends the given bytes to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. @@ -73,6 +76,7 @@ Path.append_bytes: (./log.txt).append_bytes([104, 105]) Path.base_name: + short: base name of a file description: > Returns the base name of the file or directory at the specified path. return: @@ -89,6 +93,7 @@ Path.base_name: = "file.txt" Path.by_line: + short: iterate by line description: > Returns an iterator that can be used to iterate over a file one line at a time, or returns a null value if the file could not be opened. @@ -115,6 +120,7 @@ Path.by_line: say(line.upper()) Path.can_execute: + short: check execute permissions description: > Returns whether or not a file can be executed by the current user/group. return: @@ -135,6 +141,7 @@ Path.can_execute: = no Path.can_read: + short: check read permissions description: > Returns whether or not a file can be read by the current user/group. return: @@ -155,6 +162,7 @@ Path.can_read: = no Path.can_write: + short: check write permissions description: > Returns whether or not a file can be written by the current user/group. return: @@ -175,6 +183,7 @@ Path.can_write: = no Path.changed: + short: get the last changed time description: > Gets the file change time of a file. note: > @@ -202,6 +211,7 @@ Path.changed: = none Path.child: + short: append a child to a path description: > Return a path that is a child of another path. return: @@ -222,6 +232,7 @@ Path.child: = (./directory/file.txt) Path.children: + short: get children of a directory description: > Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. return: @@ -242,6 +253,7 @@ Path.children: = [".git", "foo.txt"] Path.create_directory: + short: make a directory description: > Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. @@ -262,6 +274,7 @@ Path.create_directory: (./new_directory).create_directory() Path.current_dir: + short: get current directory description: > Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. @@ -275,6 +288,7 @@ Path.current_dir: = (/home/user/tomo) Path.exists: + short: check if a path exists description: > Checks if a file or directory exists at the specified path. return: @@ -291,6 +305,7 @@ Path.exists: = yes Path.expand_home: + short: 'expand ~ to $HOME' description: > For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory. @@ -311,6 +326,7 @@ Path.expand_home: = /foo Path.extension: + short: get file extension description: > Returns the file extension of the file at the specified path. Optionally returns the full extension. return: @@ -340,6 +356,7 @@ Path.extension: = "" Path.files: + short: list files in a directory description: > Returns a list of files within the directory at the specified path. Optionally includes hidden files. return: @@ -361,6 +378,7 @@ Path.files: = [(./directory/file1.txt), (./directory/file2.txt)] Path.from_components: + short: build a path from components description: > Returns a path built from a list of path components. return: @@ -381,6 +399,7 @@ Path.from_components: = ~/.local Path.glob: + short: perform file globbing description: > Perform a globbing operation and return a list of matching paths. Some glob specific details: @@ -422,6 +441,7 @@ Path.glob: = [] Path.group: + short: get the owning group description: > Get the owning group of a file or directory. return: @@ -445,6 +465,7 @@ Path.group: = none Path.is_directory: + short: check if a path is a directory description: > Checks if the path represents a directory. Optionally follows symbolic links. return: @@ -468,6 +489,7 @@ Path.is_directory: = no Path.is_file: + short: check if a path is a file description: > Checks if the path represents a file. Optionally follows symbolic links. return: @@ -491,6 +513,7 @@ Path.is_file: = no Path.is_socket: + short: check if a path is a socket description: > Checks if the path represents a socket. Optionally follows symbolic links. return: @@ -511,6 +534,7 @@ Path.is_socket: = yes Path.is_symlink: + short: check if a path is a symbolic link description: > Checks if the path represents a symbolic link. return: @@ -527,6 +551,7 @@ Path.is_symlink: = yes Path.modified: + short: get file modification time description: > Gets the file modification time of a file. return: @@ -551,6 +576,7 @@ Path.modified: = none Path.owner: + short: get file owner description: > Get the owning user of a file or directory. return: @@ -574,6 +600,7 @@ Path.owner: = none Path.parent: + short: get parent directory description: > Returns the parent directory of the file or directory at the specified path. return: @@ -590,6 +617,7 @@ Path.parent: = (./path/to/) Path.read: + short: read file contents description: > Reads the contents of the file at the specified path or a null value if the file could not be read. @@ -612,6 +640,7 @@ Path.read: = none Path.read_bytes: + short: read file contents as bytes description: > Reads the contents of the file at the specified path or a null value if the file could not be read. @@ -638,6 +667,7 @@ Path.read_bytes: = none Path.relative_to: + short: apply a relative path to another description: > Returns the path relative to a given base path. By default, the base path is the current directory. return: @@ -658,6 +688,7 @@ Path.relative_to: = (./to/file.txt) Path.remove: + short: remove a file or directory description: > Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. return: @@ -677,6 +708,7 @@ Path.remove: (./file.txt).remove() Path.resolved: + short: resolve a path description: > Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. return: @@ -700,6 +732,7 @@ Path.resolved: = (/foo/path/to/file.txt) Path.set_owner: + short: set the owner description: > Set the owning user and/or group for a path. return: @@ -730,6 +763,7 @@ Path.set_owner: (./file.txt).set_owner(owner="root", group="wheel") Path.subdirectories: + short: get subdirectories description: > Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. return: @@ -753,6 +787,7 @@ Path.subdirectories: = [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] Path.unique_directory: + short: create a directory with a unique name description: > Generates a unique directory path based on the given path. Useful for creating temporary directories. return: @@ -772,6 +807,7 @@ Path.unique_directory: created.remove() Path.write: + short: write to a file description: > Writes the given text to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file @@ -797,6 +833,7 @@ Path.write: (./file.txt).write("Hello, world!") Path.write_bytes: + short: write bytes to a file description: > Writes the given bytes to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file @@ -822,6 +859,7 @@ Path.write_bytes: (./file.txt).write_bytes([104, 105]) Path.write_unique: + short: write to a uniquely named file description: > Writes the given text to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary @@ -848,6 +886,7 @@ Path.write_unique: created.remove() Path.write_unique_bytes: + short: write bytes to a uniquely named file description: > Writes the given bytes to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary diff --git a/api/sets.yaml b/api/sets.yaml index 19d30f1d..6bf0d8cc 100644 --- a/api/sets.yaml +++ b/api/sets.yaml @@ -1,4 +1,5 @@ Set.add: + short: add item to a set description: > Adds an item to the set. return: @@ -18,6 +19,7 @@ Set.add: >> nums.add(42) Set.add_all: + short: add items to a set description: > Adds multiple items to the set. return: @@ -37,6 +39,7 @@ Set.add_all: >> nums.add_all([1, 2, 3]) Set.clear: + short: clear a set description: > Removes all items from the set. return: @@ -52,6 +55,7 @@ Set.clear: >> nums.clear() Set.has: + short: check if a set has an item description: > Checks if the set contains a specified item. return: @@ -72,6 +76,7 @@ Set.has: = yes Set.is_subset_of: + short: check if a set is a subset description: > Checks if the set is a subset of another set. return: @@ -97,6 +102,7 @@ Set.is_subset_of: = yes Set.is_superset_of: + short: check if a set is a superset description: > Checks if the set is a superset of another set. return: @@ -122,6 +128,7 @@ Set.is_superset_of: = yes Set.overlap: + short: set intersection description: > Creates a new set with items that are in both the original set and another set. return: @@ -142,6 +149,7 @@ Set.overlap: = |2| Set.remove: + short: remove an item from a set description: > Removes an item from the set. return: @@ -161,6 +169,7 @@ Set.remove: >> nums.remove(42) Set.remove_all: + short: remove items from a set description: > Removes multiple items from the set. return: @@ -180,6 +189,7 @@ Set.remove_all: >> nums.remove_all([1, 2, 3]) Set.with: + short: set union description: > Creates a new set that is the union of the original set and another set. return: @@ -200,6 +210,7 @@ Set.with: = |1, 2, 3| Set.without: + short: set difference description: > Creates a new set with items from the original set but without items from another set. return: diff --git a/api/tables.yaml b/api/tables.yaml index 6ab5f505..6a58e818 100644 --- a/api/tables.yaml +++ b/api/tables.yaml @@ -1,4 +1,5 @@ Table.clear: + short: clear a table description: > Removes all key-value pairs from the table. return: @@ -14,6 +15,7 @@ Table.clear: >> t.clear() Table.get: + short: get an item from a table description: > Retrieves the value associated with a key, or returns `none` if the key is not present. note: > @@ -46,6 +48,7 @@ Table.get: = 0 Table.get_or_set: + short: get an item or set a default if absent description: > If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it. @@ -85,6 +88,7 @@ Table.get_or_set: = &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} Table.has: + short: check for a key description: > Checks if the table contains a specified key. return: @@ -107,6 +111,7 @@ Table.has: = no Table.remove: + short: remove a table entry description: > Removes the key-value pair associated with a specified key. return: @@ -129,6 +134,7 @@ Table.remove: = {"B"=2} Table.set: + short: set a table entry description: > Sets or updates the value associated with a specified key. return: diff --git a/api/text.md b/api/text.md index 8f449358..e500e7bf 100644 --- a/api/text.md +++ b/api/text.md @@ -771,13 +771,14 @@ last | `Int` | The index of the last grapheme cluster to include (1-indexed). | ## Text.translate ```tomo -Text.translate : func(translations: {Text=Text} -> Text) +Text.translate : func(text: Text, translations: {Text=Text} -> Text) ``` Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See Text.replace() for more information about replacement behavior. Argument | Type | Description | Default ---------|------|-------------|--------- +text | `Text` | The text to be translated. | - translations | `{Text=Text}` | A table mapping from target text to its replacement. | - **Return:** The text with all occurrences of the targets replaced with their corresponding replacement text. @@ -786,12 +787,12 @@ translations | `{Text=Text}` | A table mapping from target text to its replaceme **Example:** ```tomo >> "A <tag> & an amperand".translate({ -"&" = "&", -"<" = "<", -">" = ">", -'"" = """, -"'" = "'", -} + "&" = "&", + "<" = "<", + ">" = ">", + '"" = """, + "'" = "'", +}) = "A <tag> & an ampersand" ``` diff --git a/api/text.yaml b/api/text.yaml index f70178b2..eb9dc286 100644 --- a/api/text.yaml +++ b/api/text.yaml @@ -1,4 +1,5 @@ Text.as_c_string: + short: convert to C-style string description: > Converts a `Text` value to a C-style string. return: @@ -15,6 +16,7 @@ Text.as_c_string: = CString("Hello") Text.at: + short: get a letter description: > Get the graphical cluster at a given index. This is similar to `str[i]` with ASCII text, but has more correct behavior for unicode text. @@ -39,6 +41,7 @@ Text.at: = "é" Text.by_line: + short: iterate by line description: > Returns an iterator function that can be used to iterate over the lines in a text. @@ -65,6 +68,7 @@ Text.by_line: say(line) Text.by_split: + short: iterate by a spliting text description: > Returns an iterator function that can be used to iterate over text separated by a delimiter. @@ -95,6 +99,7 @@ Text.by_split: say(chunk) Text.by_split_any: + short: iterate by one of many splitting characters description: > Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. @@ -125,6 +130,7 @@ Text.by_split_any: say(chunk) Text.bytes: + short: get UTF8 bytes description: > Converts a `Text` value to a list of bytes representing a UTF8 encoding of the text. @@ -142,6 +148,7 @@ Text.bytes: = [65, 109, 195, 169, 108, 105, 101] Text.caseless_equals: + short: case-insensitive comparison description: > Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). @@ -172,6 +179,7 @@ Text.caseless_equals: = no Text.codepoint_names: + short: get unicode codepoint names description: > Returns a list of the names of each codepoint in the text. return: @@ -188,6 +196,7 @@ Text.codepoint_names: = ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] Text.ends_with: + short: check suffix description: > Checks if the `Text` ends with a literal suffix text. return: @@ -208,6 +217,7 @@ Text.ends_with: = yes Text.from: + short: slice from a starting index description: > Get a slice of the text, starting at the given position. return: @@ -235,6 +245,7 @@ Text.from: = "lo" Text.from_bytes: + short: convert UTF8 byte list to text description: > Returns text that has been constructed from the given UTF8 bytes. note: > @@ -254,6 +265,7 @@ Text.from_bytes: = "Åke" Text.from_c_string: + short: convert C-style string to text description: > Converts a C-style string to a `Text` value. return: @@ -270,6 +282,7 @@ Text.from_c_string: = "Hello" Text.from_codepoint_names: + short: convert list of unicode codepoint names to text description: > Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. @@ -295,6 +308,7 @@ Text.from_codepoint_names: = "Åke" Text.from_codepoints: + short: convert UTF32 codepoints to text description: > Returns text that has been constructed from the given UTF32 codepoints. note: > @@ -314,6 +328,7 @@ Text.from_codepoints: = "Åke" Text.has: + short: check for substring description: > Checks if the `Text` contains some target text. return: @@ -336,6 +351,7 @@ Text.has: = no Text.join: + short: concatenate with separator description: > Joins a list of text pieces with a specified glue. return: @@ -356,6 +372,7 @@ Text.join: = "one, two, three" Text.middle_pad: + short: pad text, centered description: > Pad some text on the left and right side so it reaches a target width. return: @@ -390,6 +407,7 @@ Text.middle_pad: = "ABCAxABCAB" Text.left_pad: + short: left-pad text description: > Pad some text on the left side so it reaches a target width. return: @@ -424,6 +442,7 @@ Text.left_pad: = "ABCAx" Text.lines: + short: get list of lines description: > Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling `\r\n` the same as `\n`. @@ -449,6 +468,7 @@ Text.lines: = [] Text.lower: + short: convert to lowercase description: > Converts all characters in the text to lowercase. return: @@ -473,6 +493,7 @@ Text.lower: >> "ı" Text.quoted: + short: add quotation marks and escapes description: > Formats the text with quotation marks and escapes. return: @@ -499,6 +520,7 @@ Text.quoted: = "\"one\\ntwo\"" Text.repeat: + short: repeat text description: > Repeat some text multiple times. return: @@ -519,6 +541,7 @@ Text.repeat: = "AbcAbcAbc" Text.replace: + short: replace a substring description: > Replaces occurrences of a target text with a replacement text. return: @@ -543,6 +566,7 @@ Text.replace: = "Hello there" Text.reversed: + short: get a reversed copy description: > Return a text that has the grapheme clusters in reverse order. return: @@ -559,6 +583,7 @@ Text.reversed: = "cbA" Text.right_pad: + short: right-pad text description: > Pad some text on the right side so it reaches a target width. return: @@ -593,6 +618,7 @@ Text.right_pad: = "xABCA" Text.slice: + short: get a slice of a text description: > Get a slice of the text. return: @@ -629,6 +655,7 @@ Text.slice: = "ello" Text.split: + short: split a text by a delimiter description: > Splits the text into a list of substrings based on exact matches of a delimiter. return: @@ -659,6 +686,7 @@ Text.split: = ["a", "b", "c"] Text.split_any: + short: split a text by multiple delimiters description: > Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). @@ -686,6 +714,7 @@ Text.split_any: = ["one", "two", "three"] Text.starts_with: + short: check prefix description: > Checks if the `Text` starts with a literal prefix text. return: @@ -706,6 +735,7 @@ Text.starts_with: = yes Text.title: + short: titlecase description: > Converts the text to title case (capitalizing the first letter of each word). return: @@ -731,6 +761,7 @@ Text.title: = "İ" Text.to: + short: slice to an end index description: > Get a slice of the text, ending at the given position. return: @@ -758,6 +789,7 @@ Text.to: = "goodby" Text.translate: + short: perform multiple replacements description: > Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first @@ -770,21 +802,26 @@ Text.translate: The text with all occurrences of the targets replaced with their corresponding replacement text. args: + text: + type: 'Text' + description: > + The text to be translated. translations: type: '{Text=Text}' description: > A table mapping from target text to its replacement. example: | >> "A <tag> & an amperand".translate({ - "&" = "&", - "<" = "<", - ">" = ">", - '"" = """, - "'" = "'", - } + "&" = "&", + "<" = "<", + ">" = ">", + '"" = """, + "'" = "'", + }) = "A <tag> & an ampersand" Text.trim: + short: trim characters description: > Trims the given characters (grapheme clusters) from the left and/or right side of the text. return: @@ -822,6 +859,7 @@ Text.trim: = "xyz " Text.upper: + short: uppercase description: > Converts all characters in the text to uppercase. return: @@ -847,6 +885,7 @@ Text.upper: = "İ" Text.utf32_codepoints: + short: get UTF32 codepoints description: > Returns a list of Unicode code points for UTF32 encoding of the text. return: @@ -863,6 +902,7 @@ Text.utf32_codepoints: = [65, 109, 233, 108, 105, 101] Text.width: + short: get display width description: > Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's `.length`, but there are @@ -886,6 +926,7 @@ Text.width: = 2 Text.without_prefix: + short: remove prefix description: > Returns the text with a given prefix removed (if present). return: @@ -909,6 +950,7 @@ Text.without_prefix: = "qux" Text.without_suffix: + short: remove suffix description: > Returns the text with a given suffix removed (if present). return: |