__mindex

Author: Sainan

docs/Compatibility.md

@@ -75,31 +75,3 @@ These are what they look like:
 - `pluto_export`
 - `pluto_try`
 - `pluto_catch`
-
-## Default Table Metatable
-
-This is [a feature in Pluto](Runtime%20Environment/Global%20&%20Base#default-metatables) that, by itself, is a benign QoL improvement for developers. However, in combination with our added standard library functions like [table.min](Runtime%20Environment/Table#tablemin), it can be an unexpected semantic change:
-
-```pluto showLineNumbers
-local function roll(opts)
-    return math.random(opts.min or 1, opts.max or 100)
-end
-print(roll{ max = 10 })
-```
-```
-pluto: test.pluto:2: bad argument #1 to 'random' (number expected, got function)
-stack traceback:
-    [C]: in function 'math.rand'
-    test.pluto:2: in local 'roll'
-    test.pluto:4: in main chunk
-```
-
-Integrators can disable this feature by defining the `PLUTO_NO_DEFAULT_TABLE_METATABLE` macro in their luaconf.h or build config, to aid in a smooth transition, should scripts in their ecosystem require it.
-
-Scripters are advised to use `rawget` and/or `type` to better codify their expectations. For example, the example above seems to care only about providing fallback values and not at all about type-checking, so `rawget` would be an excellent fit for it:
-```pluto
-local function roll(opts)
-    return math.random(rawget(opts, "min") or 1, rawget(opts, "max") or 100)
-end
-print(roll{ max = 10 })
-```

docs/New Features/Mindex Metamethod.md

@@ -0,0 +1,32 @@
+The `__mindex` metatable field is accessed when a method call is attempted on a nil value.
+
+```pluto
+local t = setmetatable({}, {
+    __mindex = {
+        function sum()
+            local accum = 0
+            for self as v do
+                accum += v
+            end
+            return accum
+        end
+    }
+})
+t:insert(1)
+t:insert(2)
+print(t.sum) --> nil
+print(t:sum()) --> 3
+```
+
+Notice how the above sample uses `:insert` instead of `table.insert`, this works because:
+- Pluto sets a default metatable on every table with `{ __mindex = _G.table }`
+- `__mindex` is looked up recursively — in this case the metatable of our metatable has Pluto's default metatable.
+
+Furthermore, note that `__mindex` is only checked after direct/raw access and `__index` lookups have yielded nil:
+
+```pluto
+local t = { 1, 2 }
+print(t:min()) --> 1
+t.min = 1
+print(t:min()) -- attempt to call a number value
+```

docs/Runtime Environment/Global & Base.md

@@ -49,7 +49,9 @@ table.contains(t, 1)
 table.concat(t, "\n")
 coroutine.resume(c)
 ```
-This behavior is implemented by setting the `__index` metamethod to the respective library (`_G.table` or `_G.coroutine`). If you override the metatable, you may want to replicate that.
+The default metatables for the types are as follows:
+- Table: `{ __mindex = _G.table }` (using Pluto's own [`__mindex` metamethod](<../New Features/Mindex Metamethod.md>))
+- Coroutine/thread: `{ __index = _G.coroutine }`
 
 ---
 ### `dumpvar`