From ffa0bf570ddd7ed679932a9c68ef3a9aecc90294 Mon Sep 17 00:00:00 2001 From: Andy C Date: Thu, 7 Nov 2024 11:48:28 -0500 Subject: [PATCH] [doc/ref] Document __builtins__, Str/List method design I went for the non-polymorphic design, i.e. Str and List are different. Str.find(s) -> int # like Python Str.findLast(s) -> int Str.includes(s) -> bool List.indexOf(item) -> int # like JS List.lastIndexOf(item) -> int # like JS List.contains(item) -> bool This isn't set in stone. But here's some justification: - Avoid "accidentally quadratic" of the 'in' operator - it is defined to be O(1), not O(n) - the O(n) boolean test operations are includes() and contains() - Avoid "false polymorphism" - Str is NOT a container of substrings. There are arbitrarily many substrings! - It's also not a parameterized type Note that most languages are more polymorphic than this; - JavaScript uses indexOf/lastIndexOf/includes for both String and Array - Python is less consistent, but it has index() on both str and list - Ruby is pretty polymorphic However, they do NOT use the UTF-8 string model that we use. JavaScript strings are treated as an array of 16 bit code units, and Python strings are an array of 32 bit code units. So I think these things justify a different API. We have NEITHER the Python nor JavaScript string model. --- doc/ref/chap-special-var.md | 15 ++++++++++++--- doc/ref/feature-index.md | 17 +++++++++++++++++ doc/ref/toc-ysh.md | 10 +++++++--- 3 files changed, 36 insertions(+), 6 deletions(-) diff --git a/doc/ref/chap-special-var.md b/doc/ref/chap-special-var.md index ba3002123..53d71c8c0 100644 --- a/doc/ref/chap-special-var.md +++ b/doc/ref/chap-special-var.md @@ -81,6 +81,12 @@ consults `__defaults__` after consulting `ENV`. For example: +### `__builtins__` + +An object that contains names visible in every module. + +If a name is not visible in the local scope, or module global scope, then it's +looked up in `__builtins__`. ### `_this_dir` @@ -144,10 +150,13 @@ The exit status of all the process subs in the last command. ### _reply -YSH `read` sets this variable: +Builtins that `read` set this variable: + + read --all < foo.txt + = _reply # => 'contents of file' - read --all < myfile - echo $_reply + json read < foo.json + = _reply # => (Dict) {} ## Oils VM diff --git a/doc/ref/feature-index.md b/doc/ref/feature-index.md index 98f92318b..80fa4447c 100644 --- a/doc/ref/feature-index.md +++ b/doc/ref/feature-index.md @@ -97,6 +97,7 @@ OSH: - [`use`](chap-builtin-cmd.html#use) - [`is-main`](chap-builtin-cmd.html#is-main) - provide (TODO) +- [`_this_dir`](chap-special-var.html#_this_dir) - [`__provide__`](chap-special-var.html#__provide__) - An imported module is an [`Obj`][Obj] with an [`__invoke__`][__invoke__] method @@ -168,3 +169,19 @@ Also see [the Unicode doc](../unicode.html). [io]: chap-type-method.html#io [vm]: chap-type-method.html#vm + +### Namespaces + +- [`ENV`](chap-special-var.html#ENV) +- [`__builtins__`](chap-special-var.html#__builtins__) + + + + diff --git a/doc/ref/toc-ysh.md b/doc/ref/toc-ysh.md index 3a4833f6b..70c35fb7c 100644 --- a/doc/ref/toc-ysh.md +++ b/doc/ref/toc-ysh.md @@ -44,7 +44,8 @@ error handling, and more. [Numbers] Int Float Range - [String] Str X find() replace() + [String] Str X find() X findLast() + X contains() replace() trim() trimStart() trimEnd() startsWith() endsWith() upper() lower() @@ -54,9 +55,11 @@ error handling, and more. Match group() start() end() X groups() X groupDict() [Containers] List List/append() pop() extend() - indexOf() X insert() X remove() + indexOf() X lastIndexOf() X includes() + X insert() X remove() reverse() X List/clear() Dict erase() X Dict/clear() X accum() + X update() Place setValue() [Code Types] Func BuiltinFunc BoundFunc Proc BuiltinProc @@ -345,7 +348,8 @@ X [External Lang] BEGIN END when (awk) ```chapter-links-special-var - [YSH Vars] ARGV ENV __defaults__ + [YSH Vars] ARGV ENV + __defaults__ __builtins__ _this_dir [YSH Status] _error _pipeline_status _process_sub_status