low-luajit 0.5.0

use core::ptr::{self, NonNull};
use crate::ffi::{self, lua_State};

/// Opaque container of the state of a Lua interpreter and entry point to the LuaJIT C API.
///
/// See the [top-level documentation](index.html) for details on how to access `LuaState`.
///
/// Most functions assume you have a general understanding of the virtual stack the Lua interpreter uses.
/// If not, refer to [§3.1](https://www.lua.org/manual/5.1/manual.html#3.1) and [§3.2](https://www.lua.org/manual/5.1/manual.html#3.1).
///
/// A `LuaState` (and its wrapped pointer) should always be valid (unless unsafe constructors are used incorrectly) and will be treated as such.
///
/// *(Most of the methods' documentation below, and a few other places,
/// has been written using the [Lua 5.1 Reference Manual](https://www.lua.org/manual/5.1/manual.html) as reference:
/// Copyright © 2006–2012 Lua.org, PUC-Rio. Licensed under the [MIT license](https://www.lua.org/license.html).*)
#[repr(transparent)]
#[derive(Debug, PartialEq, Eq)]
pub struct LuaState(NonNull<lua_State>);

/// State handling functions.
impl LuaState {
	/* Not yet...
	/// Creates a new valid and independent Lua state.
	///
	/// This state will use the standard C `realloc` function as its allocator.
	///
	/// # Safety
	///
	/// While there is nothing inherently unsafe about creating a new `LuaState`,
	/// using the state without a protected environment could end badly in case a Lua error is triggered:
	/// at best, Rust simply aborts abruptly...but I've had segmentation faults happen sometimes too.
	#[inline]
	pub unsafe fn new_unchecked() -> Self {
		let ptr = unsafe { luaL_newstate() };
		assert!(!ptr.is_null(), "cannot create new Lua state: memory allocation error");
		Self(ptr)
	}*/

	/// Wraps a pre-existing raw [`lua_State`] pointer.
	///
	/// # Safety
	///
	/// `ptr` **must** be a valid non-null pointer of an already existing state, as all other methods will assume it to be so.
	///
	/// Additionally, there must not be an existing accessible `LuaState` that is already using this pointer.
	#[must_use]
	pub const unsafe fn from_ptr(ptr: *mut lua_State) -> Self {
		// SAFETY: The caller must ensure ptr is a valid non-null pointer.
		unsafe { Self::from_non_null(NonNull::new_unchecked(ptr) ) }
	}

	/// Wraps a pre-existing non-null [`lua_State`] pointer.
	///
	/// # Safety
	///
	/// `ptr` **must** be a valid pointer of an already existing state, as all other methods will assume it to be so.
	///
	/// Additionally, there must not be an existing accessible `LuaState` that is already using this pointer.
	#[must_use]
	pub const unsafe fn from_non_null(ptr: NonNull<lua_State>) -> Self {
		Self(ptr)
	}

	/// Returns the underlying raw [`lua_State`] pointer.
	/// This can be used to pass the `LuaState` to raw [`ffi`] functions.
	///
	/// The caller must ensure that the `LuaState` outlives the pointer this function returns, or else it will end up dangling.
	///
	/// The returned pointer should also not be passed to functions that might invalidate the `LuaState` (like [`lua_close`]).
	///
	/// [`lua_close`]: ./ffi/fn.lua_close.html
	#[must_use]
	pub const fn as_ptr(&self) -> *mut lua_State {
		self.as_non_null().as_ptr()
	}

	/// Returns the underlying non-null [`lua_State`] pointer.
	///
	/// The caller must ensure that the `LuaState` outlives the pointer this function returns, or else it will end up dangling.
	///
	/// To pass the `LuaState` to raw [`ffi`] functions, see [`LuaState::as_ptr`].
	#[must_use]
	pub const fn as_non_null(&self) -> NonNull<lua_State> {
		self.0
	}

	/// Grants temporary mutable access to the [`LuaState`] from an immutable reference.
	/// This function should be used seldomly.
	///
	/// # Safety
	///
	/// `f` must not pop any pre-existing element and any element pushed onto the stack by `f` should be popped before the function ends.
	///
	/// While not popping all pushed elements will *not* result in undefined behavior,
	/// it must still be treated as a logic error that should not be relied upon.
	/// *(Compiling with `debug_assertions` enabled will even includes an extra check for this.)*
	pub unsafe fn access_mut<T>(&self, f: impl FnOnce(&mut Self) -> T) -> T {
		#[cfg(debug_assertions)]
		let top = self.get_top();
		// SAFETY: self.as_ptr() is always valid and the caller must uphold the safety conditions.
		let mut lua = unsafe { Self::from_ptr(self.as_ptr()) };
		let result = f(&mut lua);

		#[cfg(debug_assertions)]
		debug_assert!(top == self.get_top(), "mutably accessed the Lua state as the stack held {top} elements, but left it with {} elements instead", self.get_top());
		result
	}

	/// Destroys all objects and frees all dynamic memory of the state.
	///
	/// # Safety
	///
	/// Can only be called if this `LuaState` is not being used anywhere else.
	///
	/// If your crate is a Lua module, this function must *not* return back to the Lua interpreter (as it would no longer exist).
	#[inline]
	pub unsafe fn close(self) {
		// SAFETY: self.as_ptr() is always valid and the caller must make sure that the LuaState is not used anywhere else.
		unsafe { ffi::lua_close(self.as_ptr()); }
	}

	/// Returns a reference to a number that represents the version of Lua.
	///
	/// For LuaJIT, this should always returns `501` (which represents 5.1, the Lua version LuaJIT is based on).
	#[inline]
	#[must_use]
	pub fn version() -> &'static f64 {
		// SAFETY: lua_version doesn't actually use the pointer given to it and always returns a valid pointer to a static f64.
		unsafe { &*ffi::lua_version(ptr::null_mut()) }
	}
}

/// Creates a new `LuaState` for internal testing purposes.
#[macro_export]
#[doc(hidden)]
macro_rules! __test {
	($($lib:ident),*) => {{
		#[cfg(not(windows))]
		#[link(name = "luajit-5.1")]
		unsafe extern "C" {}

		let ptr = $crate::ffi::luaL_newstate();
		$($crate::ffi::$lib(ptr);)*
		$crate::LuaState::from_ptr(ptr)
	}};
}