@@ -454,223 +454,265 @@ pub const Lua = struct {
454
454
}
455
455
456
456
/// 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
459
459
/// Lua may preallocate memory for the table based on the hints
460
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_createtable
460
461
pub fn createTable (lua : * Lua , num_arr : i32 , num_rec : i32 ) void {
461
462
c .lua_createtable (lua .state , num_arr , num_rec );
462
463
}
463
464
464
465
/// Dumps a function as a binary chunk
466
+ /// Data is a pointer passed to the writer function
465
467
/// Returns an error if writing was unsuccessful
468
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_dump
466
469
pub fn dump (lua : * Lua , writer : CWriterFn , data : * anyopaque , strip : bool ) ! void {
467
470
if (c .lua_dump (lua .state , writer , data , @boolToInt (strip )) != 0 ) return error .Fail ;
468
471
}
469
472
470
473
/// Raises a Lua error using the value at the top of the stack as the error object
471
474
/// Does a longjump and therefore never returns
475
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_error
472
476
pub fn raiseError (lua : * Lua ) noreturn {
473
477
_ = c .lua_error (lua .state );
474
478
unreachable ;
475
479
}
476
480
477
481
/// Perform a full garbage-collection cycle
482
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
478
483
pub fn gcCollect (lua : * Lua ) void {
479
484
_ = c .lua_gc (lua .state , c .LUA_GCCOLLECT );
480
485
}
481
486
482
487
/// Stops the garbage collector
488
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
483
489
pub fn gcStop (lua : * Lua ) void {
484
490
_ = c .lua_gc (lua .state , c .LUA_GCSTOP );
485
491
}
486
492
487
493
/// Restarts the garbage collector
494
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
488
495
pub fn gcRestart (lua : * Lua ) void {
489
496
_ = c .lua_gc (lua .state , c .LUA_GCRESTART );
490
497
}
491
498
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
493
501
pub fn gcStep (lua : * Lua , step_size : i32 ) void {
494
502
_ = c .lua_gc (lua .state , c .LUA_GCSTEP , step_size );
495
503
}
496
504
497
505
/// 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
498
507
pub fn gcCount (lua : * Lua ) i32 {
499
508
return c .lua_gc (lua .state , c .LUA_GCCOUNT );
500
509
}
501
510
502
511
/// 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
503
513
pub fn gcCountB (lua : * Lua ) i32 {
504
514
return c .lua_gc (lua .state , c .LUA_GCCOUNTB );
505
515
}
506
516
507
517
/// Returns a boolean that tells whether the garbage collector is running
518
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
508
519
pub fn gcIsRunning (lua : * Lua ) bool {
509
520
return c .lua_gc (lua .state , c .LUA_GCISRUNNING ) != 0 ;
510
521
}
511
522
512
523
/// Changes the collector to incremental mode
513
524
/// Returns true if the previous mode was generational
525
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
514
526
pub fn gcSetIncremental (lua : * Lua , pause : i32 , step_mul : i32 , step_size : i32 ) bool {
515
527
return c .lua_gc (lua .state , c .LUA_GCINC , pause , step_mul , step_size ) == c .LUA_GCGEN ;
516
528
}
517
529
518
530
/// Changes the collector to generational mode
519
531
/// Returns true if the previous mode was incremental
532
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gc
520
533
pub fn gcSetGenerational (lua : * Lua , minor_mul : i32 , major_mul : i32 ) bool {
521
534
return c .lua_gc (lua .state , c .LUA_GCGEN , minor_mul , major_mul ) == c .LUA_GCINC ;
522
535
}
523
536
524
537
/// 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 {
527
541
// Assert cannot be null because it is impossible (and not useful) to pass null
528
542
// to the functions that set the allocator (setallocf and newstate)
529
543
return c .lua_getallocf (lua .state , @ptrCast ([* c ]? * anyopaque , data )).? ;
530
544
}
531
545
532
546
/// Returns a slice of a raw memory area associated with the given Lua state
533
547
/// 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
534
550
pub fn getExtraSpace (lua : * Lua ) []u8 {
535
551
return @ptrCast ([* ]u8 , c .lua_getextraspace (lua .state ).? )[0.. @sizeOf (isize )];
536
552
}
537
553
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
539
556
pub fn getField (lua : * Lua , index : i32 , key : [:0 ]const u8 ) LuaType {
540
557
return @intToEnum (LuaType , c .lua_getfield (lua .state , index , key ));
541
558
}
542
559
543
- /// Pushes onto the stack the value of the global ` name`
560
+ /// Pushes onto the stack the value of the global name
544
561
/// Returns an error if the global does not exist (is nil)
562
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_getglobal
545
563
pub fn getGlobal (lua : * Lua , name : [:0 ]const u8 ) ! void {
546
564
_ = try lua .getGlobalEx (name );
547
565
}
548
566
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
550
568
/// Returns an error if the global does not exist (is nil)
569
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_getglobal
551
570
pub fn getGlobalEx (lua : * Lua , name : [:0 ]const u8 ) ! LuaType {
552
571
const lua_type = @intToEnum (LuaType , c .lua_getglobal (lua .state , name ));
553
572
if (lua_type == .nil ) return error .Fail ;
554
573
return lua_type ;
555
574
}
556
575
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
558
577
/// Returns the type of the pushed value
578
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_geti
559
579
pub fn getIndex (lua : * Lua , index : i32 , i : Integer ) LuaType {
560
580
return @intToEnum (LuaType , c .lua_geti (lua .state , index , i ));
561
581
}
562
582
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
566
587
pub fn getIndexUserValue (lua : * Lua , index : i32 , n : i32 ) ! LuaType {
567
588
const val_type = @intToEnum (LuaType , c .lua_getiuservalue (lua .state , index , n ));
568
589
if (val_type == .none ) return error .Fail ;
569
590
return val_type ;
570
591
}
571
592
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
573
594
/// Otherwise an error is returned
595
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_getmetatable
574
596
pub fn getMetatable (lua : * Lua , index : i32 ) ! void {
575
597
if (c .lua_getmetatable (lua .state , index ) == 0 ) return error .Fail ;
576
598
}
577
599
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
579
601
/// Returns the type of the pushed value
602
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_gettable
580
603
pub fn getTable (lua : * Lua , index : i32 ) LuaType {
581
604
return @intToEnum (LuaType , c .lua_gettable (lua .state , index ));
582
605
}
583
606
584
607
/// Returns the index of the top element in the stack
585
608
/// 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
586
610
pub fn getTop (lua : * Lua ) i32 {
587
611
return c .lua_gettop (lua .state );
588
612
}
589
613
590
614
/// 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
591
616
pub fn insert (lua : * Lua , index : i32 ) void {
592
617
// translate-c cannot translate this macro correctly
593
618
// c.lua_insert(lua.state, index);
594
619
lua .rotate (index , 1 );
595
620
}
596
621
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
598
624
pub fn isBoolean (lua : * Lua , index : i32 ) bool {
599
625
return c .lua_isboolean (lua .state , index );
600
626
}
601
627
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
603
630
pub fn isCFunction (lua : * Lua , index : i32 ) bool {
604
631
return c .lua_iscfunction (lua .state , index ) != 0 ;
605
632
}
606
633
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
608
636
pub fn isFunction (lua : * Lua , index : i32 ) bool {
609
637
return c .lua_isfunction (lua .state , index );
610
638
}
611
639
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
613
642
pub fn isInteger (lua : * Lua , index : i32 ) bool {
614
643
return c .lua_isinteger (lua .state , index ) != 0 ;
615
644
}
616
645
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
618
648
pub fn isLightUserdata (lua : * Lua , index : i32 ) bool {
619
649
return c .lua_islightuserdata (lua .state , index );
620
650
}
621
651
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
623
654
pub fn isNil (lua : * Lua , index : i32 ) bool {
624
655
return c .lua_isnil (lua .state , index );
625
656
}
626
657
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
628
660
pub fn isNone (lua : * Lua , index : i32 ) bool {
629
661
return c .lua_isnone (lua .state , index );
630
662
}
631
663
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
633
666
pub fn isNoneOrNil (lua : * Lua , index : i32 ) bool {
634
667
return c .lua_isnoneornil (lua .state , index );
635
668
}
636
669
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
638
672
pub fn isNumber (lua : * Lua , index : i32 ) bool {
639
673
return c .lua_isnumber (lua .state , index ) != 0 ;
640
674
}
641
675
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
643
678
pub fn isString (lua : * Lua , index : i32 ) bool {
644
679
return c .lua_isstring (lua .state , index ) != 0 ;
645
680
}
646
681
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
648
684
pub fn isTable (lua : * Lua , index : i32 ) bool {
649
685
return c .lua_istable (lua .state , index );
650
686
}
651
687
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
653
690
pub fn isThread (lua : * Lua , index : i32 ) bool {
654
691
return c .lua_isthread (lua .state , index );
655
692
}
656
693
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
658
696
pub fn isUserdata (lua : * Lua , index : i32 ) bool {
659
697
return c .lua_isuserdata (lua .state , index ) != 0 ;
660
698
}
661
699
662
700
/// Returns true if the given coroutine can yield
701
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_isyieldable
663
702
pub fn isYieldable (lua : * Lua ) bool {
664
703
return c .lua_isyieldable (lua .state ) != 0 ;
665
704
}
666
705
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
669
709
pub fn len (lua : * Lua , index : i32 ) void {
670
710
c .lua_len (lua .state , index );
671
711
}
672
712
673
713
/// 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
674
716
pub fn load (lua : * Lua , reader : CReaderFn , data : * anyopaque , chunk_name : [:0 ]const u8 , mode : Mode ) ! void {
675
717
const mode_str = switch (mode ) {
676
718
.binary = > "b" ,
@@ -682,43 +724,48 @@ pub const Lua = struct {
682
724
StatusCode .ok = > return ,
683
725
StatusCode .err_syntax = > return error .Syntax ,
684
726
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
686
728
StatusCode .err_runtime = > return error .Runtime ,
687
729
StatusCode .err_error = > return error .MsgHandler ,
688
730
else = > unreachable ,
689
731
}
690
732
}
691
733
692
734
/// Creates a new independent state and returns its main thread
735
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_newstate
693
736
pub fn newState (alloc_fn : AllocFn , data : ? * anyopaque ) ! Lua {
694
737
const state = c .lua_newstate (alloc_fn , data ) orelse return error .Memory ;
695
738
return Lua { .state = state };
696
739
}
697
740
698
741
/// 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
700
744
pub fn newTable (lua : * Lua ) void {
701
745
c .lua_newtable (lua .state );
702
746
}
703
747
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
705
749
/// 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
706
751
pub fn newThread (lua : * Lua ) Lua {
707
752
const state = c .lua_newthread (lua .state ).? ;
708
753
return .{ .state = state };
709
754
}
710
755
711
756
/// 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
713
758
/// Returns the address of the block of memory
759
+ /// See https://www.lua.org/manual/5.4/manual.html#lua_newuserdatauv
714
760
pub fn newUserdata (lua : * Lua , comptime T : type , upvalues : i32 ) * T {
715
761
// safe to .? because this function throws a Lua error on out of memory
716
762
// so the returned pointer should never be null
717
763
const ptr = c .lua_newuserdatauv (lua .state , @sizeOf (T ), upvalues ).? ;
718
764
return opaqueCast (T , ptr );
719
765
}
720
766
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
722
769
pub fn next (lua : * Lua , index : i32 ) bool {
723
770
return c .lua_next (lua .state , index ) != 0 ;
724
771
}
0 commit comments