imported>DePiep: /* todo */

2023-03-21T10:28:09Z

todo

New page

{{Documentation subpage}}
{{Template rating|alpha}}
{{Lua|Module:Str find word}}
This template looks for a ''word'' in a comma-separated ''list of words''. It returns a True (found) or False (not found) value.

By default, the True-value returned is the found word itself; the False-value is a blank string.
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=foo}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, foo, bar |word=foo}}
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=nov}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, foo, bar |word=nov}}

No partial fit. Partial word matching do ''not'' count as a hit:
:<code><nowiki>{{Str find word |source=alpha, foobar, bar |word=foo}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, foobar, bar |word=foo}}

Case-sensitive: By default, the comparison is case-sensitive ({{mono|1=Foo ≠ foo}}); all text is turned into lowercase. One can make the check case-sensitive by {{para|case|true}}
:<code><nowiki>{{Str find word |source=alpha, Foo, bar |word=foo |case=false}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, Foo, bar |word=foo |case=false}}
:<code><nowiki>{{Str find word |source=alpha, Foo, bar |word=foo |case=true}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, Foo, bar |word=foo |case=true}}

Using this template, the editor does not have to apply patterns ({{!xt|1='%f[^,][^,]+%f[,]'}}). No return value interpretation is required (like {{!xt|1=when 1 then do x}}), though is optionally possible. There is no inbetween-result: the logic says it is either T or F. The logic can not result in an error.

===options===
The True and False return values can be set through {{para|yes|}}, {{para|no|}}:
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=foo |yes=Yesss |no=Nooo}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, foo, bar |word=foo |yes=Yesss |no=Nooo}}
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=nov |yes=Yesss |no=Nooo}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, foo, bar |word=nov |yes=Yesss |no=Nooo}}

==Specifics==
;Words: A 'word' is the character string between commas. This can be all characters and inner spaces:
:<code><nowiki>{{Str find word |source=alpha, foo bar sunday, bar |word=foo bar sunday}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, foo bar sunday, bar |word=foo bar sunday}}
:<code><nowiki>{{Str find word |source=alpha, bar(22) [take care]!, foo |word=bar(22) [take care]!}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, bar(22) [take care]!, foo |word=bar(22) [take care]!}}

;Return value: True- and False-value can be set through {{para|yes|}}, {{para|no|}}:
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=foo |yes=Yesss |no=Nooo}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, foo, bar |word=foo |yes=Yesss |no=Nooo}}
:<code><nowiki>{{Str find word |source=alpha, foo, bar |word=nov |yes=Yesss |no=Nooo}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, foo, bar |word=nov |yes=Yesss |no=Nooo}}

;Boolean value read: Setting {{para|booleans|true}} will read common ''bolean words'' as boolean (true, false).
:Boolean words for true: 'True', 'T', 'Yes', '1'. False: 'False', 'F', 'No', '0'. Boolean words are always case-insensistive (True=true).
:<code><nowiki>{{Str find word |source=alpha, yes, bar |word=true |booleans=true}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, yes, bar |word=true |booleans=true}}
:<code><nowiki>{{Str find word |source=alpha, false, bar |word=0 |booleans=true}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, false, bar |word=0 |booleans=true}}
:<code><nowiki>{{Str find word |source=alpha, false, bar |word=0 |booleans=false}}</nowiki></code>(default) ({{code|1=False}}) → {{Str find word |source=alpha, false, bar |word=0 |booleans=false}}

===Word lists===
The word list {{para|source}} is comma-separated. Prefixed and suffixed spaces are discarded (trimmed).
:{{mono|1={{bg|orange|{{hair space}}}}{{bg|yellow|alpha}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|foo}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|bar}}}}{{bg|orange|{{hair space}}}}
:Inner spaces are kept, and are part of the 'word':
:{{mono|1={{bg|orange|{{hair space}}}}{{bg|yellow|alpha}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|foo}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|hello world}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|bar}}}}{{bg|orange|{{hair space}}}}
:Any character apart from {{Angle bracket|,}} comma can be part of the word:
:{{mono|1={{bg|orange|{{hair space}}}}{{bg|yellow|α(12) [mind the gap]!}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|foo}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|hello world}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|bar}}}}{{bg|orange|{{hair space}}}}

:Multiple spaces (whitespace) inside a string is reduced to a single space:
:{{bg|orange|{{hair space}}}}{{bg|yellow|alpha}}{{bg|orange|,}}{{bg|#e6e6e6|  }}{{bg|yellow|foo    bar}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|orange|{{hair space}}}}

:equals {{bg|orange|{{hair space}}}}{{bg|yellow|alpha}}{{bg|orange|,}}{{bg|#e6e6e6| }}{{bg|yellow|foo bar}}{{bg|orange|,}}{{bg|orange|{{hair space}}}}

;Spaces {{Angle bracket| }}, Comma {{Angle bracket|,}}, quote {{Angle bracket|"}}, pipe {{Angle bracket|{{!}}}}

;Trimmed spaces: All words are trimmed before checking (leading and trailing whitespace is removed; repeated inner whitespaces are reduced to one space):
:<code><nowiki>{{Str find word |source=alpha , hello   world, foo |word=hello world}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha , hello   world, foo|word=hello world}}
:::...but the remaining in-word space does matter:
:<code><nowiki>{{Str find word |source=alpha, hello   world, foo |word=helloworld}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, hello   world, foo |word=helloworld}}

;Comma {{Angle bracket|,}}: When a comma {{Angle bracket|,}} is part of the word to check. Word strings that contain a comma can be made literal (escape the comma):
:{{nay}} {{red|TODO check this doc claim}} <code><nowiki>{{Str find word |source=alpha, "hello, world", foo |word="hello, world"}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, "hello, world", foo |word="hello, world"}}
:??chk: <code><nowiki>{{Str find word |source=alpha, "hello, world", foo |word="hello, world"|literals=false}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, "hello, world", foo |word="hello, world"|literals=false}}
:??chk: <code><nowiki>{{Str find word |source=alpha, "hello, world", foo |word="hello, world"|literals=true}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, "hello, world", foo |word="hello, world"|literals=true}}

;Quote character {{Angle bracket|"}}: Conversely, quote characters {{Angle bracket|"}} that are part of the word are escaped by setting {{para|literals|false}}:
:<code><nowiki>{{Str find word |source=alpha, she said "hello world", "foo" |word=she said "hello world" |literals=false}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, she said "hello world", "foo" |word=she said "hello world" |literals=false}}

;Pipe {{Angle bracket|{{!}}}}: The pipe character can be entered as <code><nowiki>{{!}}</nowiki></code>
:<code><nowiki>{{Str find word |source=alpha, hello{{!}}world, foo |word=hello{{!}}world }}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, hello{{!}}world, foo |word=hello{{!}}world }}

===Checking multiple words===
It is possible to check ''multiple words'' against the source wordlist.
;AND-words to check
:{{para|andwords|}}: can have a ''wordlist'' (comma-separated as {{para|source|}} is). Each word will be checked against the source. When all and-words are found, the return value is True.
:<code><nowiki>{{Str find word |source=alpha, beta, gamma, foo, bar |andwords=alpha, foo}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, beta, gamma, foo, bar |andwords=alpha, foo}}
:<code><nowiki>{{Str find word |source=alpha, beta, gamma, foo, bar |andwords=bar, foo, beta, alpha}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, beta, gamma, foo, bar |andwords=bar, foo, beta, alpha}}
:<code><nowiki>{{Str find word |source=alpha, beta, gamma, foo, bar |andwords=alpha, nov}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, beta, gamma, foo, bar |andwords=alpha, nov}}

;OR-words to check
:{{para|orwords|}}: can have a ''wordlist'' (comma-separated as {{para|source|}} is). Each word will be checked against the source. When a single or-words is found, the return value is True. Default True return value is the list with all words found.
:<code><nowiki>{{Str find word |source=alpha, beta, gamma, foo, bar |orwords=alpha, foo}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, beta, gamma, foo, bar |orwords=alpha, nov}}
:<code><nowiki>{{Str find word |source=alpha, happy, gamma, nice, foo, bar |orwords=april, sad, happy, ugly, nice}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, happy, gamma, nice, foo, bar |orwords=april, sad, happy, ugly, nice}}
:<code><nowiki>{{Str find word |source=alpha, happy, gamma, nice, foo, bar |orwords=sad, ugly, november}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, happy, gamma, nice, foo, bar |orwords=sad, ugly, november}}

;Both AND-words, OR-words to check
:{{para|andwords|}}, :{{para|orwords|}} can be used together. Each wordlist will get its own logical checks (AND-words must all be present; OR-words at least one)
:T: <code><nowiki>{{Str find word |source=alpha, beta, april, gamma, foo, happy |andwords=alpha, beta |orwords=april, november, sad, ugly}}</nowiki></code> ({{code|1=True}}) → {{Str find word |source=alpha, beta, april, gamma, foo, happy |andwords=alpha, beta |orwords=april, november, sad, ugly}}
:<code><nowiki>{{Str find word |source=alpha, beta, april, gamma, foo, happy |andwords=alpha, november |orwords=april, november, sad, ugly}}</nowiki></code> ({{code|1=False}}) → {{Str find word |source=alpha, beta, april, gamma, foo, happy |andwords=alpha, november |orwords=april, november, sad, ugly}}

==Examples==
{| class="wikitable"
|-
! {{para|1=source}}
! {{para|1=word}}
! colspan="2" | result
! note
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foo}}
| {{aye}}
|
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|nov}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=nov}}
| {{nay}}
|
|-
| {{para|1=source|2=alpha, uc-all}}
| {{para|word|uc-all}}
| {{#invoke:Str find word|main |explain=true |source=alpha, uc-all|word=uc-all}}
| {{aye}}
|
|-
| {{para|1=source|2=alpha, hello world_, bar}}
| {{para|word|hello world_}}
| {{#invoke:Str find word|main |explain=true |source=alpha, hello world_, bar|word=hello world_}}
| {{aye}}
| The comma is the word-delimiter
|-
| {{para|1=source|2=alpha,foo   bar , lima}}
| {{para|word|  foo   bar}}
| {{#invoke:Str find word|main |explain=true |source=alpha,foo   bar , lima|word=  foo   bar}}
| {{aye}}
| Spaces are trimmed, multi-space into one space
|-
| {{para|1=source|2=alpha, foo bar, lima}}
| {{para|word|foobar}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo bar, lima|word=foobar}}
| {{nay}}
| An inner space is a character too
|-
| {{para|1=source|2=alpha, FOO, bAr, lima}}
| {{para|word|bar, foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, FOO, bAr, lima|word=bar, foo}}
| {{aye}}
| Not case-sensistive by default
|-
| {{para|1=source|2=alpha, FOO, bAr, lima}}
| {{para|word|bar, foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, FOO, bAr, lima|word=bar, foo|case=true}}
| {{nay}}
| {{para|case|true}}: case-sensistive

|}

==note==
:The editor does not have to apply Lua patterns like {{code|1=[%a%d]*}}
:The editor does not have to interpret the return value (as in: "when ='blue' then ..."). They can prescribe the value even (yes-value, no-value).

== Usage ==
===Basic===
Core function:
<pre>
{{Str find word
|source =
|word =
|yes =
|no =
}}
</pre>

:When the ''word'' is found in the ''source'' (True), the function returns the ''word'' itself (by default), or {{para|yes}} value (when entered non-empty).
:When not found (False), the function returns an empty string ({{code|''}}), or the {{para|no}} value when entered.

{| class="wikitable"
|-
! {{para|1=source}}
! {{para|1=word}}
! colspan="2" | result
! note
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foo}}
| {{aye}}
|
|-
| {{para|1=source|2=alpha, uc-all}}
| {{para|word|uc-all}}
| {{#invoke:Str find word|main |explain=true |source=alpha, uc-all|word=uc-all}}
| {{aye}}
| "-" (hyphen) is part of the word
|-
| {{para|1=source|2=alpha, do_something, white}}
| {{para|word|do_something}}
| {{#invoke:Str find word|main |explain=true |source=alpha, do_something, white|word=do_something}}
| {{aye}}
| "_" (underscore) is part of the word
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|november}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=november}}
| {{nay}}
|
|-
| {{para|1=source|2=alpha, foobar, lima}}
| {{para|word|foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foobar, lima|word=foo}}
| {{nay}}
| 'foo' is not the complete word
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=}}
| {{nay}}
| no {{para|word}} entered
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foobar}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foo-bar|yes=Yes, hit|no=No, not found}}
| {{nay}}
| full word ''foo-bar'' not in the source
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foobar}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo-bar, lima|word=foo|yes=Yes, hit|no=No, not found}}
| {{nay}}
| word ''foo'' not in the source as full word
|- 
! colspan="5" style="padding-left:3em; text-align:left;" | {{code|1=...}} {{para|yes|Yes, hit}} {{para|no|Not found}}
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foo}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foo|yes=Yes, hit|no=No, not found}}
| {{aye}}
|
|-
| {{para|1=source|2=alpha, foo, lima}}
| {{para|word|foobar}}
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foobar|yes=Yes, hit|no=No, not found}}
| {{nay}}
|
|}

===All parameters===
:All parameters, in three options
{|
|-
|<pre>
{{Str find word
|string =
|word =
|allwords =
|orwords =
|case=
|yes =
|no =
|explain =
}}
</pre>
|<pre>
{{Str find word
|s =
|w =
|allw=
|orw =
|case=
|yes =
|no =
|explain =
}}
</pre>
|}
<pre>{{Str find word |s= |w= |allw= |orw= |case= |yes= |no= |explain=}}</pre>

===More options===
{| class="wikitable" style=""
|-
! {{para|1=source}} {{para|1=s}} {{para|1=1}}
! {{para|1=word}} {{para|1=w}} {{para|1=2}}
! {{para|1=case}}
! colspan="2" | result
! note
|-
| {{para|1=s|2=alpha, foo, lima}}
| {{para|w|foo}}
|
|
| {{#invoke:Str find word|main |explain=true |s=alpha, foo, lima|w=foo|yes=yes|no=no}}
|
|-
| {{para|1=s|2=alpha, foo, lima}}
| {{para|w|foobar}}
|
|
| {{#invoke:Str find word|main |explain=true |source=alpha, foo, lima|word=foobar|yes=yes|no=no}}
|
|-
| {{para|1=s|2=alpha, foobar, lima}}
| {{para|w|foo}}
|
|
| {{#invoke:Str find word|main |explain=true |source=alpha, foobar, lima|word=foo|yes=yes|no=no}}
| 'foo' is not the complete word
|-
| {{para|1=s|2=alpha, FOO, lima}}
| {{para|w|foo}}
|
|
| {{#invoke:Str find word|main |explain=true |source=alpha, FOO, lima|word=foo|yes=yes|no=no|case=false}}
| {{para|case|false}}: a=A ''(default)''
|-
| {{para|1=s|2=alpha, FOO, lima}}
| {{para|w|foo}}
|
|
| {{#invoke:Str find word|main |explain=true |source=alpha, FOO, lima|word=foo|yes=yes|no=no|case=true}}
| {{para|case|true}}: a=/=A
|}

===word list===
:Instead of a single word to check, a '''list of target words''' can be entered: {{para|word|alpha, foo, bingo}}. This {{para|word}}-list will be treated with ''AND''-logic: each and all of the words ''must'' be present. See:

===AND-, OR-wordlist checks===
:{{para|word}} as noted, can be a ''list of words''. all will be checked with the ''AND''-requirement (each word must be present).
:{{para|andwords}} accepts a ''list of words'' that all will be checked with the ''AND''-requirement (each word must be present).
::When both {{para|word}}, {{para|andwords}} are present, they are combined into one single ''AND''-wordlist.
:{{para|orwords}} accepts a ''list of words'' that all will be checked with the ''OR''-requirement (at least one of the words must be present).

==Errors and analysis==
* The logic itself does not produce errors. There is always a True of False result.

* Pages with Unknown parameters are listed in {{clc|Category:Pages using str find word with unknown parameters}}.

:There are no logical errors foreseen: any flaw in the input will return a False result (for example, no input strings to check were entered).

* {{para|explain|true}}: when in {{button|Preview}}, display a report on input, output and the logical steps (debug).
* {{para|explain|testcases}}: When set in ns {{mono|1=Template}} or {{mono|1=User}} on subpage {{mono|1=/testcases}}, the Preview report is static (shown permanently).

===See also===
{{String-handling templates |anlys/tech}}

<includeonly>{{sandbox other||

[[Category:String manipulation templates]]
}}</includeonly>

Template:Str find word/doc - Revision history

imported>DePiep: /* todo */