Skip to content

Commit a12e3dd

Browse files
committed
docs: continue to document functions
1 parent e32a8fe commit a12e3dd

File tree

2 files changed

+83
-36
lines changed

2 files changed

+83
-36
lines changed

src/tests.zig

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,11 @@ test "alloc functions" {
9696

9797
// get default allocator
9898
var data: *anyopaque = undefined;
99-
try expectEqual(alloc, lua.getAllocF(&data));
99+
try expectEqual(alloc, lua.getAllocFn(&data));
100100

101101
// set a bad allocator
102102
lua.setAllocF(failing_alloc, null);
103-
try expectEqual(failing_alloc, lua.getAllocF(&data));
103+
try expectEqual(failing_alloc, lua.getAllocFn(&data));
104104

105105
// reset the good one
106106
lua.setAllocF(alloc, null);

src/ziglua.zig

Lines changed: 81 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -454,223 +454,265 @@ pub const Lua = struct {
454454
}
455455

456456
/// Creates a new empty table and pushes onto the stack
457-
/// `num_arr` is a hint for how many elements the table will have as a sequence
458-
/// `num_rec` is a hint for how many other elements the table will have
457+
/// num_arr is a hint for how many elements the table will have as a sequence
458+
/// num_rec is a hint for how many other elements the table will have
459459
/// Lua may preallocate memory for the table based on the hints
460+
/// See https://www.lua.org/manual/5.4/manual.html#lua_createtable
460461
pub fn createTable(lua: *Lua, num_arr: i32, num_rec: i32) void {
461462
c.lua_createtable(lua.state, num_arr, num_rec);
462463
}
463464

464465
/// Dumps a function as a binary chunk
466+
/// Data is a pointer passed to the writer function
465467
/// Returns an error if writing was unsuccessful
468+
/// See https://www.lua.org/manual/5.4/manual.html#lua_dump
466469
pub fn dump(lua: *Lua, writer: CWriterFn, data: *anyopaque, strip: bool) !void {
467470
if (c.lua_dump(lua.state, writer, data, @boolToInt(strip)) != 0) return error.Fail;
468471
}
469472

470473
/// Raises a Lua error using the value at the top of the stack as the error object
471474
/// Does a longjump and therefore never returns
475+
/// See https://www.lua.org/manual/5.4/manual.html#lua_error
472476
pub fn raiseError(lua: *Lua) noreturn {
473477
_ = c.lua_error(lua.state);
474478
unreachable;
475479
}
476480

477481
/// Perform a full garbage-collection cycle
482+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
478483
pub fn gcCollect(lua: *Lua) void {
479484
_ = c.lua_gc(lua.state, c.LUA_GCCOLLECT);
480485
}
481486

482487
/// Stops the garbage collector
488+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
483489
pub fn gcStop(lua: *Lua) void {
484490
_ = c.lua_gc(lua.state, c.LUA_GCSTOP);
485491
}
486492

487493
/// Restarts the garbage collector
494+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
488495
pub fn gcRestart(lua: *Lua) void {
489496
_ = c.lua_gc(lua.state, c.LUA_GCRESTART);
490497
}
491498

492-
/// Performs an incremental step of garbage collection corresponding to the allocation of `step_size` Kbytes
499+
/// Performs an incremental step of garbage collection corresponding to the allocation of step_size Kbytes
500+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
493501
pub fn gcStep(lua: *Lua, step_size: i32) void {
494502
_ = c.lua_gc(lua.state, c.LUA_GCSTEP, step_size);
495503
}
496504

497505
/// Returns the current amount of memory (in Kbytes) in use by Lua
506+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
498507
pub fn gcCount(lua: *Lua) i32 {
499508
return c.lua_gc(lua.state, c.LUA_GCCOUNT);
500509
}
501510

502511
/// Returns the remainder of dividing the current amount of bytes of memory in use by Lua by 1024
512+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
503513
pub fn gcCountB(lua: *Lua) i32 {
504514
return c.lua_gc(lua.state, c.LUA_GCCOUNTB);
505515
}
506516

507517
/// Returns a boolean that tells whether the garbage collector is running
518+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
508519
pub fn gcIsRunning(lua: *Lua) bool {
509520
return c.lua_gc(lua.state, c.LUA_GCISRUNNING) != 0;
510521
}
511522

512523
/// Changes the collector to incremental mode
513524
/// Returns true if the previous mode was generational
525+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
514526
pub fn gcSetIncremental(lua: *Lua, pause: i32, step_mul: i32, step_size: i32) bool {
515527
return c.lua_gc(lua.state, c.LUA_GCINC, pause, step_mul, step_size) == c.LUA_GCGEN;
516528
}
517529

518530
/// Changes the collector to generational mode
519531
/// Returns true if the previous mode was incremental
532+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gc
520533
pub fn gcSetGenerational(lua: *Lua, minor_mul: i32, major_mul: i32) bool {
521534
return c.lua_gc(lua.state, c.LUA_GCGEN, minor_mul, major_mul) == c.LUA_GCINC;
522535
}
523536

524537
/// Returns the memory allocation function of a given state
525-
/// If `data` is not null, it is set to the opaque pointer given when the allocator function was set
526-
pub fn getAllocF(lua: *Lua, data: ?**anyopaque) AllocFn {
538+
/// If data is not null, it is set to the opaque pointer given when the allocator function was set
539+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getallocf
540+
pub fn getAllocFn(lua: *Lua, data: ?**anyopaque) AllocFn {
527541
// Assert cannot be null because it is impossible (and not useful) to pass null
528542
// to the functions that set the allocator (setallocf and newstate)
529543
return c.lua_getallocf(lua.state, @ptrCast([*c]?*anyopaque, data)).?;
530544
}
531545

532546
/// Returns a slice of a raw memory area associated with the given Lua state
533547
/// The application may use this area for any purpose; Lua does not use it for anything
548+
/// This area has a size of a pointer to void
549+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getextraspace
534550
pub fn getExtraSpace(lua: *Lua) []u8 {
535551
return @ptrCast([*]u8, c.lua_getextraspace(lua.state).?)[0..@sizeOf(isize)];
536552
}
537553

538-
/// Pushes onto the stack the value t[key] where t is the value at the given `index`
554+
/// Pushes onto the stack the value t[key] where t is the value at the given index
555+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getfield
539556
pub fn getField(lua: *Lua, index: i32, key: [:0]const u8) LuaType {
540557
return @intToEnum(LuaType, c.lua_getfield(lua.state, index, key));
541558
}
542559

543-
/// Pushes onto the stack the value of the global `name`
560+
/// Pushes onto the stack the value of the global name
544561
/// Returns an error if the global does not exist (is nil)
562+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getglobal
545563
pub fn getGlobal(lua: *Lua, name: [:0]const u8) !void {
546564
_ = try lua.getGlobalEx(name);
547565
}
548566

549-
/// Pushes onto the stack the value of the global `name`. Returns the type of that value
567+
/// Pushes onto the stack the value of the global name and returns the type of that value
550568
/// Returns an error if the global does not exist (is nil)
569+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getglobal
551570
pub fn getGlobalEx(lua: *Lua, name: [:0]const u8) !LuaType {
552571
const lua_type = @intToEnum(LuaType, c.lua_getglobal(lua.state, name));
553572
if (lua_type == .nil) return error.Fail;
554573
return lua_type;
555574
}
556575

557-
/// Pushes onto the stack the value t[`i`] where t is the value at the given `index`
576+
/// Pushes onto the stack the value t[i] where t is the value at the given index
558577
/// Returns the type of the pushed value
578+
/// See https://www.lua.org/manual/5.4/manual.html#lua_geti
559579
pub fn getIndex(lua: *Lua, index: i32, i: Integer) LuaType {
560580
return @intToEnum(LuaType, c.lua_geti(lua.state, index, i));
561581
}
562582

563-
/// Pushes onto the stack the `n`th user value associated with the full userdata at the given `index`
564-
/// Returns the type of the pushed value
565-
/// Returns an error if the userdata does not have that value
583+
/// Pushes onto the stack the nth user value associated with the full userdata at the given index
584+
/// Returns the type of the pushed value or an error if the userdata does not have that value
585+
/// Pushes nil if the userdata does not have that value
586+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getiuservalue
566587
pub fn getIndexUserValue(lua: *Lua, index: i32, n: i32) !LuaType {
567588
const val_type = @intToEnum(LuaType, c.lua_getiuservalue(lua.state, index, n));
568589
if (val_type == .none) return error.Fail;
569590
return val_type;
570591
}
571592

572-
/// If the value at the given `index` has a metatable, the function pushes that metatable onto the stack
593+
/// If the value at the given index has a metatable, the function pushes that metatable onto the stack
573594
/// Otherwise an error is returned
595+
/// See https://www.lua.org/manual/5.4/manual.html#lua_getmetatable
574596
pub fn getMetatable(lua: *Lua, index: i32) !void {
575597
if (c.lua_getmetatable(lua.state, index) == 0) return error.Fail;
576598
}
577599

578-
/// Pushes onto the stack the value t[k] where t is the value at the given `index` and k is the value on the top of the stack
600+
/// Pushes onto the stack the value t[k] where t is the value at the given index and k is the value on the top of the stack
579601
/// Returns the type of the pushed value
602+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gettable
580603
pub fn getTable(lua: *Lua, index: i32) LuaType {
581604
return @intToEnum(LuaType, c.lua_gettable(lua.state, index));
582605
}
583606

584607
/// Returns the index of the top element in the stack
585608
/// Because indices start at 1, the result is also equal to the number of elements in the stack
609+
/// See https://www.lua.org/manual/5.4/manual.html#lua_gettop
586610
pub fn getTop(lua: *Lua) i32 {
587611
return c.lua_gettop(lua.state);
588612
}
589613

590614
/// Moves the top element into the given valid `index` shifting up any elements to make room
615+
/// See https://www.lua.org/manual/5.4/manual.html#lua_insert
591616
pub fn insert(lua: *Lua, index: i32) void {
592617
// translate-c cannot translate this macro correctly
593618
// c.lua_insert(lua.state, index);
594619
lua.rotate(index, 1);
595620
}
596621

597-
/// Returns true if the value at the given `index` is a boolean
622+
/// Returns true if the value at the given index is a boolean
623+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isboolean
598624
pub fn isBoolean(lua: *Lua, index: i32) bool {
599625
return c.lua_isboolean(lua.state, index);
600626
}
601627

602-
/// Returns true if the value at the given `index` is a CFn
628+
/// Returns true if the value at the given index is a CFn
629+
/// See https://www.lua.org/manual/5.4/manual.html#lua_iscfunction
603630
pub fn isCFunction(lua: *Lua, index: i32) bool {
604631
return c.lua_iscfunction(lua.state, index) != 0;
605632
}
606633

607-
/// Returns true if the value at the given `index` is a function (C or Lua)
634+
/// Returns true if the value at the given index is a function (C or Lua)
635+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isfunction
608636
pub fn isFunction(lua: *Lua, index: i32) bool {
609637
return c.lua_isfunction(lua.state, index);
610638
}
611639

612-
/// Returns true if the value at the given `index` is an integer
640+
/// Returns true if the value at the given index is an integer
641+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isinteger
613642
pub fn isInteger(lua: *Lua, index: i32) bool {
614643
return c.lua_isinteger(lua.state, index) != 0;
615644
}
616645

617-
/// Returns true if the value at the given `index` is a light userdata
646+
/// Returns true if the value at the given index is a light userdata
647+
/// See https://www.lua.org/manual/5.4/manual.html#lua_islightuserdata
618648
pub fn isLightUserdata(lua: *Lua, index: i32) bool {
619649
return c.lua_islightuserdata(lua.state, index);
620650
}
621651

622-
/// Returns true if the value at the given `index` is nil
652+
/// Returns true if the value at the given index is nil
653+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isnil
623654
pub fn isNil(lua: *Lua, index: i32) bool {
624655
return c.lua_isnil(lua.state, index);
625656
}
626657

627-
/// Returns true if the given `index` is not valid
658+
/// Returns true if the given index is not valid
659+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isnone
628660
pub fn isNone(lua: *Lua, index: i32) bool {
629661
return c.lua_isnone(lua.state, index);
630662
}
631663

632-
/// Returns true if the given `index` is not valid or if the value at the `index` is nil
664+
/// Returns true if the given index is not valid or if the value at the index is nil
665+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isnoneornil
633666
pub fn isNoneOrNil(lua: *Lua, index: i32) bool {
634667
return c.lua_isnoneornil(lua.state, index);
635668
}
636669

637-
/// Returns true if the value at the given `index` is a number
670+
/// Returns true if the value at the given index is a number
671+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isnumber
638672
pub fn isNumber(lua: *Lua, index: i32) bool {
639673
return c.lua_isnumber(lua.state, index) != 0;
640674
}
641675

642-
/// Returns true if the value at the given `index` is a string
676+
/// Returns true if the value at the given index is a string
677+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isstring
643678
pub fn isString(lua: *Lua, index: i32) bool {
644679
return c.lua_isstring(lua.state, index) != 0;
645680
}
646681

647-
/// Returns true if the value at the given `index` is a table
682+
/// Returns true if the value at the given index is a table
683+
/// See https://www.lua.org/manual/5.4/manual.html#lua_istable
648684
pub fn isTable(lua: *Lua, index: i32) bool {
649685
return c.lua_istable(lua.state, index);
650686
}
651687

652-
/// Returns true if the value at the given `index` is a thread
688+
/// Returns true if the value at the given index is a thread
689+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isthread
653690
pub fn isThread(lua: *Lua, index: i32) bool {
654691
return c.lua_isthread(lua.state, index);
655692
}
656693

657-
/// Returns true if the value at the given `index` is a userdata (full or light)
694+
/// Returns true if the value at the given index is a userdata (full or light)
695+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isuserdata
658696
pub fn isUserdata(lua: *Lua, index: i32) bool {
659697
return c.lua_isuserdata(lua.state, index) != 0;
660698
}
661699

662700
/// Returns true if the given coroutine can yield
701+
/// See https://www.lua.org/manual/5.4/manual.html#lua_isyieldable
663702
pub fn isYieldable(lua: *Lua) bool {
664703
return c.lua_isyieldable(lua.state) != 0;
665704
}
666705

667-
/// Pushes the length of the value at the given `index` onto the stack
668-
/// Equivalent to the `#` operator in Lua
706+
/// Pushes the length of the value at the given index onto the stack
707+
/// Equivalent to the # operator in Lua
708+
/// See https://www.lua.org/manual/5.4/manual.html#lua_len
669709
pub fn len(lua: *Lua, index: i32) void {
670710
c.lua_len(lua.state, index);
671711
}
672712

673713
/// Loads a Lua chunk without running it
714+
/// If there are no errors, pushes the compiled chunk on the top of the stack as a function
715+
/// See https://www.lua.org/manual/5.4/manual.html#lua_load
674716
pub fn load(lua: *Lua, reader: CReaderFn, data: *anyopaque, chunk_name: [:0]const u8, mode: Mode) !void {
675717
const mode_str = switch (mode) {
676718
.binary => "b",
@@ -682,43 +724,48 @@ pub const Lua = struct {
682724
StatusCode.ok => return,
683725
StatusCode.err_syntax => return error.Syntax,
684726
StatusCode.err_memory => return error.Memory,
685-
// lua_load runs pcall, so can also return any result of an pcall error
727+
// lua_load runs pcall, so can also return any result of a pcall error
686728
StatusCode.err_runtime => return error.Runtime,
687729
StatusCode.err_error => return error.MsgHandler,
688730
else => unreachable,
689731
}
690732
}
691733

692734
/// Creates a new independent state and returns its main thread
735+
/// See https://www.lua.org/manual/5.4/manual.html#lua_newstate
693736
pub fn newState(alloc_fn: AllocFn, data: ?*anyopaque) !Lua {
694737
const state = c.lua_newstate(alloc_fn, data) orelse return error.Memory;
695738
return Lua{ .state = state };
696739
}
697740

698741
/// Creates a new empty table and pushes it onto the stack
699-
/// Equivalent to `Lua.createTable(lua, 0, 0)`
742+
/// Equivalent to createTable(0, 0)
743+
/// See https://www.lua.org/manual/5.4/manual.html#lua_newtable
700744
pub fn newTable(lua: *Lua) void {
701745
c.lua_newtable(lua.state);
702746
}
703747

704-
/// Creates a new thread, pushes it on the stack, and returns a `Lua` state that represents the new thread
748+
/// Creates a new thread, pushes it on the stack, and returns a Lua state that represents the new thread
705749
/// The new thread shares the global environment but has a separate execution stack
750+
/// See https://www.lua.org/manual/5.4/manual.html#lua_newthread
706751
pub fn newThread(lua: *Lua) Lua {
707752
const state = c.lua_newthread(lua.state).?;
708753
return .{ .state = state };
709754
}
710755

711756
/// This function creates and pushes a new full userdata onto the stack
712-
/// with `upvalues` associated Lua values, plus an associated block of raw memory with `size` bytes
757+
/// with upvalues associated Lua values, plus an associated block of raw memory with size bytes
713758
/// Returns the address of the block of memory
759+
/// See https://www.lua.org/manual/5.4/manual.html#lua_newuserdatauv
714760
pub fn newUserdata(lua: *Lua, comptime T: type, upvalues: i32) *T {
715761
// safe to .? because this function throws a Lua error on out of memory
716762
// so the returned pointer should never be null
717763
const ptr = c.lua_newuserdatauv(lua.state, @sizeOf(T), upvalues).?;
718764
return opaqueCast(T, ptr);
719765
}
720766

721-
/// Pops a key from the stack, and pushes a key-value pair from the table at the given `index`
767+
/// Pops a key from the stack, and pushes a key-value pair from the table at the given index
768+
/// See https://www.lua.org/manual/5.4/manual.html#lua_next
722769
pub fn next(lua: *Lua, index: i32) bool {
723770
return c.lua_next(lua.state, index) != 0;
724771
}

0 commit comments

Comments
 (0)