commit - ae13dd82234cfad86fec4fe959e501df5e5c6355
commit + 4932b1e895c0f581b780fdf38a60faed64cc8e00
blob - /dev/null
blob + db6bea646edfd2af59836c6a785878ebd48b0f43 (mode 644)
--- /dev/null
+++ man3/luaL_Buffer.3
@@ -0,0 +1,50 @@
+.Dd $Mdocdate: July 26 2022 $
+.Dt LUAL_BUFFER 3
+.Os
+.Sh NAME
+.Nm luaL_Buffer
+.Nd type for a string buffer
+.Sh SYNOPSIS
+.In lauxlib.h
+.Vt typedef struct luaL_Buffer luaL_Buffer ;
+.Sh DESCRIPTION
+.Fn luaL_Buffer
+type for a
+.Em string buffer .
+.Pp
+A string buffer allows C code to build Lua strings piecemeal.
+Its pattern of use is as follows:
+.Pp
+.Bl -bullet -compact
+.It
+First you declare a variable b of type
+.Nm luaL_Buffer .
+.It
+Then you initialize it with a call
+.Em luaL_buffinit(L, &b) .
+.It
+Then you add string pieces to the buffer calling any of the
+.Em luaL_add*
+functions.
+.It
+You finish by calling
+.Em luaL_pushresult(&b) .
+This call leaves the final string on the top of the stack.
+.El
+.Pp
+During its normal operation, a string buffer uses a variable number of stack
+slots.
+So, while using a buffer, you cannot assume that you know where the top
+of the stack is.
+You can use the stack between successive calls to buffer operations as long as
+that use is balanced; that is, when you call a buffer operation, the stack is
+at the same level it was immediately after the previous buffer operation.
+.Pq The only exception to this rule is Em luaL_addvalue .
+After calling
+.Xr luaL_pushresult 3
+the stack is back to its level when the buffer was initialized, plus the final
+string on its top.
+.Sh HISTORY
+The
+.Fn luaL_Buffer
+manual page was written by Sergey Bronnikov.