docs(examples): Vars

doc/libmodal.txt

@@ -108,6 +108,70 @@ VARIABLES                                               *libmodal-usage-variable
 		|g:|    For more information about global variables.
 		|vim.g| For info about accessing |g:| from lua.
 
+                                                              *libmodal.Mode-vars*
+                                                             *libmodal.Mode.count*
+`Mode`.count
+
+	The |v:count| of the mode.
+
+	Type: ~
+		|libmodal-Var| of |lua-number|
+
+	Example: ~
+>lua
+		libmodal.mode.enter('Foo', {
+			G = function(self)
+				local count = self.count:get()
+				vim.api.nvim_command('norm! ' .. tostring(count) .. 'G')
+			end,
+		})
+<
+
+                                                            *libmodal.Mode.count1*
+`Mode`.count1
+
+	The |v:count1| equivalent of |libmodal.Mode.count|.
+
+	Type: ~
+		|libmodal-Var| of |lua-number|
+
+                                                              *libmodal.Mode.exit*
+`Mode`.exit
+
+	If `true`, flags the mode to exit. It will read this value before reading
+	the user's next key.
+
+	Type: ~
+		|libmodal-Var| of `boolean`
+
+	Example: ~
+>lua
+		libmodal.mode.enter('Foo', {
+			q = function(self)
+				vim.notify('Hello!')
+				self.exit:set_local(true)
+			end,
+		})
+<
+
+                                                          *libmodal.Mode.timeouts*
+`Mode`.timeouts
+
+	The |libmodal-timeouts| configuration for this mode.
+
+	Type: ~
+		|libmodal-Var| of `boolean`
+
+	Example: ~
+>lua
+		libmodal.mode.enter('Foo', {
+			t = function(self)
+				local timeouts = self.timeouts:get()
+				self.timeouts:set_local(not timeouts) -- toggle timeouts
+			end,
+		})
+<
+
 --------------------------------------------------------------------------------
 FUNCTIONS                                               *libmodal-usage-functions*
 
@@ -176,10 +240,12 @@ FUNCTIONS                                               *libmodal-usage-function
 <
 
 			NOTE: Some QoL features are available by default when
-			      specifying a `dict`/`table` value for {instruction} that
+			      specifying a `dict` / |lua-table| value for {instruction} that
 			      would otherwise have to be programmed manually if a
 			      `function` is specified.
 
+			      - Bound |lua-function|s may accept a `self` parameter, which
+					allows access to |libmodal.Mode-vars|.
 			      - A user's typed characters will show in the
 			        lower right corner when {instruction} is a table.
 			      - If `g:libmodalTimeouts` is enabled, then user input will be
@@ -450,6 +516,65 @@ FUNCTIONS                                               *libmodal-usage-function
 		|lua-eval|          For type conversions between Vimscript to |Lua|.
 		|libmodal-examples| For examples of this function.
 
+                                                                    *libmodal-Var*
+`Var`
+
+	Some values mentioned above may be typed `libmodal-Var`. By default, `Var`s
+	mirror a specific |g:var|, but they may be given instance-local values as
+	well. In this case, the instance value is preferred to the global value.
+
+                                                              *libmodal.Var:get()*
+`Var`:get()
+
+	Return: ~
+		|libmodal.Var:get_local()| if a local value exists, or
+		|libmodal.Var:get_global()|.
+
+                                                       *libmodal.Var:get_global()*
+`Var`:get_global()
+
+	Return: ~
+		The global value.
+
+	See also: ~
+		|g:|    For more information about global variables.
+		|vim.g| For info about accessing |g:| from lua.
+
+                                                        *libmodal.Var:get_local()*
+`Var`:get_local()
+
+	Return: ~
+		The local value.
+
+                                                              *libmodal.Var:set()*
+`Var`:set({value})
+
+	|libmodal.Var:set_local()| if a local value exists, otherwise
+	|libmodal.Var:set_global()|.
+
+	Parameters: ~
+		{value}  to set.
+
+                                                       *libmodal.Var:set_global()*
+`Var`:set_global({value})
+
+	Set a {value} locally.
+
+	Parameters: ~
+		{value}  to set globally.
+
+	See also: ~
+		|g:|    For more information about global variables.
+		|vim.g| For info about accessing |g:| from lua.
+
+                                                        *libmodal.Var:set_local()*
+`Var`:set_local()
+
+	Set a {value} globally.
+
+	Parameters: ~
+		{value}  to set locally.
+
 --------------------------------------------------------------------------------
 EVENTS                                                     *libmodal-usage-events*
 

examples/lua/keymaps-supress-exit.lua

@@ -13,8 +13,11 @@ local fooModeKeymaps =
 {
 	[k '<Esc>'] = 'echom "You cant exit using escape."',
 	q = 'let g:fooModeExit = 1', -- exits all instances of this mode
+	w = function(self)
+		self.exit:set_global(true) -- exits all instances of the mode (with lua)
+	end,
 	x = function(self)
-		self:exit() -- exits this instance of the mode
+		self.exit:set_local(true) -- exits this instance of the mode
 	end,
 	y = function(self)
 		self:switch('Bar', barModeKeymaps) -- enters Bar and then exits Foo when it is done

examples/lua/keymaps.lua

@@ -13,6 +13,10 @@ local fooModeKeymaps =
 	j = 'norm j',
 	k = 'norm k',
 	l = 'norm l',
+	G = function(self)
+		local count = self.count:get()
+		vim.api.nvim_command('norm! ' .. count .. 'G')
+	end,
 	zf = 'split',
 	zfc = 'q',
 	zff = split_twice,

examples/lua/vars.lua

@@ -0,0 +1,79 @@
+--[[
+	This file demonstrates how `Var`s work in Modes and Prompts.
+]]
+
+--- WARN: do not import this in your code! it is not part of the public API.
+local Vars = require 'libmodal.utils.Vars'
+
+--- Check the value of the local var
+--- @param var any
+--- @param val unknown the value to check is equal to
+local function assert_local_eq(var, val)
+	assert(var:get_local() == val, 'assertion: the global value equals ' .. vim.inspect(val))
+end
+
+--- Check the value of the global var
+--- @param var any
+--- @param val unknown the value to check is equal to
+local function assert_global_eq(var, val)
+	assert(var:get_global() == val, 'assertion: the global value equals ' .. vim.inspect(val))
+end
+
+--- Check the value of the scoped var
+--- @param var any
+--- @param val unknown the value to check is equal to
+--- @param scope 'global'|'local'
+local function assert_eq(var, val, scope)
+	assert(var:get() == val, 'assertion: the value equals ' .. vim.inspect(val))
+	local fn = scope == 'local' and  assert_local_eq  or assert_global_eq
+	fn(var, val)
+end
+
+--- check the value of all vars
+--- @param var any
+--- @param val unknown the value to check is equal to
+local function assert_all_eq(var, val)
+	assert_eq(var, val, 'local')
+	assert_global_eq(var, val)
+end
+
+local mode_name = 'Foo'
+local var_name = 'Bar'
+
+--- WARN: do not use this function in your code! It is not part of the public API.
+local foo = Vars.new(mode_name, var_name)
+
+-- 1. baseline
+
+assert_all_eq(foo, nil)
+
+-- 2. without local value, `:get` and `:set` use globals
+
+local global_value = true
+
+foo:set(global_value)
+
+assert_eq(foo, global_value, 'global')
+assert_local_eq(foo, nil)
+
+-- 3. set local value
+
+foo:set_local(global_value)
+
+assert_all_eq(foo, global_value)
+
+-- 4. with local value, `:get` and `:set` use locals
+
+local local_value = false
+
+foo:set(local_value)
+
+assert_eq(foo, local_value, 'local')
+assert_global_eq(foo, global_value)
+
+-- Finally, unset all so the test can be run again
+
+foo:set_global(nil)
+foo:set_local(nil)
+
+assert_all_eq(foo, nil)