Docs/Examples on condition objects

Author: atticus-sullivan

DOC.md

@@ -1064,6 +1064,31 @@ ls.add_snippets("all", {
 })
 ```
 
+- `conditions.show`: Contains typical predicates/functions used as
+  `show`-condition. Currently this is just `line_end`
+- `conditions.expand`: Contains typical predicates/functions used as
+  `expand`-condition. Currently this is just `line_begin`
+  Contains everything from `conditions.show` as well.
+- `conditions`: Provides a function `make_condition(foo)` which takes a function
+  as argument and returns a *condition object* for which several operators are
+  defined:
+  - `c1 + c2 -> c1 or c2`
+  - `c1 * c2 -> c1 and c2`
+  - `-c1 -> not c1`
+  - `c1 ^ c2 -> c1 xor/!= c2`
+  - `c1 % c2 -> c1 xnor/== c2`: This decision may look weird but as we weren't
+	able to use `==`, we decided to take something that makes one scratch ones
+	head (and thus avoid making false assumptions).
+	For more details look at [this comment](https://github.com/L3MON4D3/LuaSnip/pull/612#issuecomment-1264487743).
+
+  `conditions.show`s and `conditions.expand`s members all are also condition
+  objects so you can work with those too.
+
+  Thus you can easily combine existing predicates. Like in
+  `conditions.expand.line_end + conditions.expand.line_begin` instead of doing
+  something like
+  `function(...) return conditions.expand.line_end(...) or conditions.expand.line_begin(...) end`.
+
 <!-- panvimdoc-ignore-start -->
 
 extras1: ![extras1](https://user-images.githubusercontent.com/25300418/184359431-50f90599-3db0-4df0-a3a9-27013e663649.gif)

Examples/snippets.lua

@@ -17,7 +17,8 @@ local dl = require("luasnip.extras").dynamic_lambda
 local fmt = require("luasnip.extras.fmt").fmt
 local fmta = require("luasnip.extras.fmt").fmta
 local types = require("luasnip.util.types")
-local conds = require("luasnip.extras.expand_conditions")
+local conds = require("luasnip.extras.conditions")
+local conds_expand = require("luasnip.extras.conditions.expand")
 
 -- If you're reading this file for the first time, best skip to around line 190
 -- where the actual snippet-definitions start.
@@ -320,16 +321,27 @@ ls.add_snippets("all", {
 			return line_to_cursor:match("%s*//")
 		end,
 	}),
-	-- there's some built-in conditions in "luasnip.extras.expand_conditions".
+	-- there's some built-in conditions in "luasnip.extras.conditions.expand" and "luasnip.extras.conditions.show".
 	s("cond2", {
 		t("will only expand at the beginning of the line"),
 	}, {
-		condition = conds.line_begin,
+		condition = conds_expand.line_begin,
 	}),
 	s("cond3", {
 		t("will only expand at the end of the line"),
 	}, {
-		condition = conds.line_end,
+		condition = conds_expand.line_end,
+	}),
+	-- on conditions some logic operators are defined
+	s("cond4", {
+		t("will only expand at the end and the start of the line"),
+	}, {
+		-- last function is just an example how to make own function objects and apply operators on them
+		condition = conds_expand.line_end
+			+ conds_expand.line_begin
+				* conds.make_condition(function()
+					return true
+				end),
 	}),
 	-- The last entry of args passed to the user-function is the surrounding snippet.
 	s(

doc/luasnip.txt

@@ -1,4 +1,4 @@
-*luasnip.txt*          For NVIM v0.5.0          Last change: 2022 September 28
+*luasnip.txt*           For NVIM v0.5.0           Last change: 2022 October 08
 
 ==============================================================================
 Table of Contents                                  *luasnip-table-of-contents*
@@ -1049,6 +1049,31 @@ is only a short outline, their usage is shown more expansively in
 <
 
 
+
+- `conditions.show`: Contains typical predicats/functions used as
+    `show`-condition. Currently this is just `line_end`
+- `conditions.expand`: Contains typical predicats/functions used as
+    `expand`-condition. Currently this is just `line_begin` Contains everything
+    from `conditions.show` as well.
+- `conditions`: Provides a function `make_condition(foo)` which takes a function
+    as argument and returns a _condition object_ for which several operators are
+    defined:
+    - `c1 + c2 -> c1 or c2`
+    - `c1 * c2 -> c1 and c2`
+    - `-c1 -> not c1`
+    - `c1 ^ c2 -> c1 xor/!= c2`
+    - `c1 % c2 -> c1 xnor/== c2`: This decision may look weird but as we weren’t
+        able to use `==`, we decided to take something that makes one scratch ones
+        head (and thus avoid making false assumptions).
+        For more details look at this comment <https://github.com/L3MON4D3/LuaSnip/pull/612#issuecomment-1264487743>.
+    `conditions.show`s and `conditions.expand`s members all are also condition
+    objects so you can work with those too.
+    Thus you can easily combine existing predicats. Like in
+    `conditions.expand.line_end + conditions.expand.line_begin` instead of doing
+    something like `function(...) return conditions.expand.line_end(...) or
+    conditions.expand.line_begin(...) end`.
+
+
 FMT                                                              *luasnip-fmt*
 
 `require("luasnip.extras.fmt").fmt` can be used to create snippets in a more