Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ mix usage_rules.search_docs "Enum.zip" --query-by title
- Only use macros if explicitly requested
- There are many useful standard library functions, prefer to use them where possible

## Code Style
- Use `alias Module.Submodule` instead of `alias Module.{Submodule}` - avoid curly braces for single aliases
- When aliasing multiple modules from the same namespace, use separate `alias` statements on individual lines

## Function Design
- Use guard clauses: `when is_binary(name) and byte_size(name) > 0`
- Prefer multiple function clauses over complex conditional logic
Expand Down
127 changes: 127 additions & 0 deletions lib/lua/vm/argument_error.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
defmodule Lua.VM.ArgumentError do
@moduledoc """
Raised when a function is called with invalid arguments.

This exception provides standardized error messages for bad arguments across
all Lua standard library functions.

## Fields

- `:function_name` - The fully qualified function name (e.g., "string.rep")
- `:arg_num` - The argument number (1-based)
- `:expected` - What type or value was expected (e.g., "number", "string")
- `:got` - What was actually received (optional, e.g., "nil", "boolean")
- `:details` - Additional details about the error (optional)

## Examples

# Basic type error
raise ArgumentError,
function_name: "string.rep",
arg_num: 2,
expected: "number"

# With actual type received
raise ArgumentError,
function_name: "string.sub",
arg_num: 2,
expected: "number",
got: "string"

# With additional details
raise ArgumentError,
function_name: "string.char",
arg_num: 1,
expected: "number",
details: "value out of range"
"""

defexception [:function_name, :arg_num, :expected, :got, :details]

@impl true
def exception(opts) do
function_name = Keyword.fetch!(opts, :function_name)
arg_num = Keyword.get(opts, :arg_num)
expected = Keyword.get(opts, :expected)
got = Keyword.get(opts, :got)
details = Keyword.get(opts, :details)

%__MODULE__{
function_name: function_name,
arg_num: arg_num,
expected: expected,
got: got,
details: details
}
end

@impl true
def message(%__MODULE__{
function_name: function_name,
arg_num: arg_num,
expected: expected,
got: got,
details: details
}) do
build_message(function_name, arg_num, expected, got, details)
end

defp build_message(function_name, arg_num, expected, got, details) do
base =
if arg_num do
"bad argument ##{arg_num} to '#{function_name}'"
else
"bad argument to '#{function_name}'"
end

expectation =
case {expected, got} do
{nil, nil} ->
nil

{exp, nil} ->
"(#{exp} expected)"

{exp, got_val} ->
"(#{exp} expected, got #{got_val})"
end

case {expectation, details} do
{nil, nil} -> base
{exp, nil} -> "#{base} #{exp}"
{nil, detail} -> "#{base} (#{detail})"
{_exp, detail} -> "#{base} (#{detail})"
end
end

@doc """
Creates an ArgumentError when no value is provided for a required argument.

## Example

ArgumentError.value_expected("string.lower", 1)
"""
def value_expected(function_name, arg_num) do
exception(
function_name: function_name,
arg_num: arg_num,
expected: "value"
)
end

@doc """
Creates an ArgumentError for type mismatches.

## Example

ArgumentError.type_error("string.rep", 2, "number", "string")
"""
def type_error(function_name, arg_num, expected, got) do
exception(
function_name: function_name,
arg_num: arg_num,
expected: expected,
got: got
)
end
end
1 change: 1 addition & 0 deletions lib/lua/vm/stdlib.ex
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ defmodule Lua.VM.Stdlib do
|> State.register_function("next", &lua_next/2)
|> State.register_function("pairs", &lua_pairs/2)
|> State.register_function("ipairs", &lua_ipairs/2)
|> Lua.VM.Stdlib.String.install()
end

# type(v) — returns the type of v as a string
Expand Down
41 changes: 41 additions & 0 deletions lib/lua/vm/stdlib/library.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
defmodule Lua.VM.Stdlib.Library do
@moduledoc """
Behaviour for Lua standard library modules.

All standard library modules (string, math, table, os, etc.) should implement
this behaviour to provide a consistent interface for installation into the VM state.

## Example

defmodule Lua.VM.Stdlib.String do
@behaviour Lua.VM.Stdlib.Library

@impl true
def install(state) do
# Create and register the string library
string_table = %{...}
{tref, state} = State.alloc_table(state, string_table)
State.set_global(state, "string", tref)
end
end

"""

alias Lua.VM.State

@doc """
Installs the library into the given VM state.

This function should register all library functions in the appropriate global
namespace (e.g., "string", "math", "table") and return the updated state.

## Parameters

- `state` - The VM state to install the library into

## Returns

The updated VM state with the library installed
"""
@callback install(State.t()) :: State.t()
end
Loading