0.11.0

docs/Changelog.md

@@ -4,6 +4,40 @@ sidebar_position: 13
 
 This page contains the changelogs from all [releases of Pluto](https://github.com/PlutoLang/Pluto/releases).
 
+## 0.11.0
+- Added preprocessor aliases (`$alias`)
+- Added compile-time evaluated statement `$assert`
+- Added warning for unused local variables
+- Added octal numerals
+- Added `__mindex` metamethod
+  - This is now used by default table metatable, elimiting the compatibility concerns it previously had.
+- Export is no longer deprecated but now implies constness
+- Walrus operator can now initialize multiple variables
+- Compile-time conditionals can now be equality checks
+- Table freezing is now an optional feature, enabled via `PLUTO_ENABLE_TABLE_FREEZING`
+- Fixed implicit conversion of booleans to strings outside of concats
+- Removed table length cache
+- Removed let & const
+
+Standard library:
+- Added buffer library
+- Added table.invert, table.dedup/deduplicate, table.deduped/deduplicated, table.values
+- Added crypto.crc32c
+- crypto.random now treats 1-2 arguments like math.random
+- Added optional 'binary' parameter to crypto.md5
+- Added ffi.alloc, ffi.write, & ffi.read
+- Added UDP support to socket.connect
+- Added socket.isudp, socket.udpserver
+- Added io.chmod
+- Added os.arch constant
+- Added callonce function
+- Added sdiv, udiv, smod, & umod functions
+- string.split's needle parameter is now required (previously defaulted to `","`)
+- socket.listen & socket.bind can now be bound to a specific IP address
+- io.part now returns 'parent, name' if part argument is omitted
+- Optimized json.encode & json.decode
+- Removed `_PSOUP` constant
+
 ## 0.10.5
 - Improved error message when `new` is provided with a nil value
 - Fixed ternary expression sometimes picking a bad register

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/Compiler Warnings.md

@@ -5,6 +5,17 @@ Pluto offers optional compiler warnings for certain misbehaviors.
 
 ## Warning Types
 
+### unused
+This is raised when a local is declared but never used.
+```pluto showLineNumbers
+local a
+```
+```
+file.pluto:1: warning: unused local variable [unused]
+    1 | local a
+      | ^^^^^^^ here: 'a' is unused
+```
+
 ### var-shadow
 This is raised when a new local is created with the same name as an existing one.
 ```pluto showLineNumbers
@@ -179,18 +190,31 @@ end
 ```
 
 ### implicit-global
-This is raised when the `global` keyword is enabled and a global was declared without it. See [Explicit Globals](<Explicit Globals>).
+This is raised when a global is declared without an explicit prefix, such as the optional `global` keyword:
 ```pluto showLineNumbers
 pluto_use global
-
 a = 1
 ```
 ```
-file.pluto:3: warning: implicit global creation [implicit-global]
-    3 | a = 1
-      | ^^^^^ here: prefix this with 'global' to be explicit
+file.pluto:2: warning: implicit global creation [implicit-global]
+    2 | a = 1
+      | ^^^^^ here: prefix this with '_G.' or 'global' to be explicit
 ```
 
+Examples of code that does not raise this warning:
+```pluto
+pluto_use global
+global a = 1
+a = 2
+```
+```pluto
+-- @pluto_warnings enable-implicit-global
+_G.a = 1
+a = 2
+```
+
+This warning type is enabled via `pluto_use global` or [compile-time configuration](#compile-time-configuration).
+
 ### discarded-return
 This is raised when the return value of a function declared `<nodiscard>` was discarded. See [Nodiscard Functions](<Nodiscard Functions>).
 ```pluto showLineNumbers

docs/New Features/Export Modifier.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 2
+---
+The `export` modifier allows you to automatically aggregate things you want to export into a table.
+
+```pluto title="Old Code"
+local version = 2
+
+local function add(a, b)
+    return a + b
+end
+
+return {
+    version = version,
+    add = add
+}
+```
+
+```pluto title="New Code"
+export version = 2
+
+export function add(a, b)
+    return a + b
+end
+```
+
+The return statement is automatically generated at the end of the block, so it is not limited to the top-level function:
+
+```pluto
+package.preload["test"] = function()
+    export version = 2
+
+    export function add(a, b)
+        return a + b
+    end
+
+    -- end of scope; 'return' is automatically generated
+end
+
+print(require"test".version)
+```
+
+## Using Compatibility Mode?
+
+You may need to use `pluto_export` instead of `export`. Alternatively, `pluto_use export` will enable the keyword independently of environment settings.

docs/New Features/Mindex Metamethod.md

@@ -0,0 +1,36 @@
+The `__mindex` metamethod stands for 'method index'. It has a secondary priority to `__index` and it's only invoked when the lookup is being performed by method invocation syntax. This is used to avoid compatibility issues regarding Pluto's default metatable for tables. For example:
+```pluto
+local t = { "a", "b", "c" }
+print(t:concat())
+```
+In this code, the following occurs:
+1. `concat` key is not directly present in the table, so `__index` is queried.
+2. `__index` returns nil.
+3. Since `__index` returned nil and this lookup is being performed by method invocation syntax (`:`), `__mindex` is queried.
+
+Another example:
+```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
+```
+
+Beware of a caveat:
+```pluto
+local t = { 1, 2 }
+print(t:min()) --> 1
+t.min = 1
+print(t:min()) -- attempt to call a number value
+```

docs/New Features/Numeral Parsing.md

@@ -6,21 +6,25 @@ Pluto makes two small changes to numeral parsing.
 ## Cosmetic Underscores
 
 You can add underscores to your numeric literals to make them more readable.
-```pluto showLineNumbers title="Example Code"
+```pluto
 local n = 10_000_000
-assert(n == 10000000)
+print(n) --> 10000000
 ```
 These underscores are ignored by the compiler, so they are purely cosmetic.
 
-## Binary Integers
+## Binary & Octal Numerals
 
 Similar to how Lua allows you to input numbers in hexadecimal:
-```pluto showLineNumbers title="Example Code"
-local n = 0x420
-assert(n == 1056)
+```pluto
+local n = 0x2A
+print(n) --> 42
 ```
-Pluto allows you to input numbers in binary as well:
-```pluto showLineNumbers title="Example Code"
-local n = 0b1000101
-assert(n == 69)
+Pluto allows you to input numbers in binary and octal as well:
+```pluto
+local n = 0b101010
+print(n) --> 42
+```
+```pluto
+local n = 0o52
+print(n) --> 42
 ```

docs/New Features/Compile-Time Evaluation.md → docs/New Features/Preprocessing.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
 ---
-Pluto's parser provides some powerful constructs which allow you to write code that will never be seen at runtime.
+Pluto provides some powerful constructs which allow you to write code that will never be seen at runtime.
 
 ## Function calls
 
@@ -36,6 +36,7 @@ And on the following functions:
 - `tonumber`
 - `utonumber`
 - `type`
+- `assert`
 
 ## Variables
 
@@ -68,3 +69,31 @@ $end
 ```
 
 In this case, only one of the two paths will be compiled in; the rest will not take up any space.
+
+## Aliases
+
+Preprocessor aliases are similar to C/C++ macros. For example, you can define an alias for a keyword:
+
+```pluto
+$alias let = local
+let a = 1
+print(a) --> 1
+```
+
+or write simple functions which will be fully inlined at the call site:
+
+```pluto
+$alias add(a, b) = a + b
+assert(add(1, 2) == 3)
+```
+
+If you want to write an alias over multiple lines, you can use a backslash to continue it:
+
+```pluto
+$alias seq = "a"  \
+             ..   \
+             "b"  \
+             ..   \
+             "c"
+assert(seq == "abc")
+```

docs/New Features/Table Freezing.md

@@ -38,4 +38,8 @@ All modifications to the table from within the Lua environment will be prevented
 
 :::caution
 If you're going to use this for a sandbox, ensure you call `table.freeze` before any users can access the Lua environment, otherwise they can replace that function.
+:::
+
+:::info
+As of Pluto 0.11.0, these functions are unavailable by default. You can enable them by defining the `PLUTO_ENABLE_TABLE_FREEZING` macro.
 :::

docs/New Operators.md

@@ -105,7 +105,6 @@ This operator does not implement any metamethods.
 
 ## Walrus Operator
 The Walrus operator allows you to perform assignments inside of conditional expresssions.
-
 ```pluto
 local get_value = || -> 1
 
@@ -116,7 +115,7 @@ else                             -- scope of 'val' ends
 end
 ```
 
-Note that for while-loops, it will be executed as many times as the condition:
+It can also be used in while loops, where it will be executed as many times as the condition:
 ```pluto norun title="Pluto Way"
 while a := next_value() do
     -- ...
@@ -130,6 +129,22 @@ while true do
 end
 ```
 
+In both cases, it is not limited to initialize only a single variable, although only the first is checked for truthiness:
+```pluto
+local co = coroutine.create(function()
+    while true do
+        while _has_val, val := coroutine.yield() do
+            print(val)
+        end
+    end
+end)
+co:resume() -- start coroutine
+co:resume(true, 1) --> 1
+co:resume(false)
+co:resume(true, 2) --> 2
+co:resume(true, nil) --> nil
+```
+
 ## Spaceship Operator
 The spaceship operator, also known as the three-way comparison operator, allows you to quickly compare 2 values for equality and order.