Bugmenot: /* 2.1 Defines List: */ formatting

2018-02-09T14:40:32Z

2.1 Defines List:: formatting

â† Older revision		Revision as of 14:40, 9 February 2018
Line 51:		Line 51:
	* ${StrFunc_List} is automatically made by the header file. The rest is manually added to the header.		* ${StrFunc_List} is automatically made by the header file. The rest is manually added to the header.

	=== ~~2.1~~ Defines List: ===		=== Defines List ===
	~~-----------------~~

	* StrFunc_List - Lists all function names currently available on StrFunc header file.		*<code>StrFunc_List</code>
			:Lists all function names currently available on StrFunc header file.

	* _List - Lists all parameter names currently available for "" function. (* = function name - i.e. StrTok_List).		* <code>*_List</code>
			:Lists all parameter names currently available for "" function. ( = function name - i.e. StrTok_List).

	* _TypeList - Lists the types of all parameters on "" function. (* = function name - i.e. StrTok_List). Possible types for each parameter:		* <code>*_TypeList</code>
			:Lists the types of all parameters on "" function. ( = function name - i.e. StrTok_List). Possible types for each parameter:
	** Output - Needs a variable to output a function result.		:* Output - Needs a variable to output a function result.
			:* Text - Needs text or number to be input.
	** Text - Needs text or number to be input.		:* Mixed - Needs text, number or option to be inputed. Each subitem following the "Mixed" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.
			:* Option - Needs an option to be inputed. Each subitem following the "Option" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.
	** Mixed - Needs text, number or option to be inputed. Each subitem following the "Mixed" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.

	** Option - Needs an option to be inputed. Each subitem following the "Option" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.

	== 3 Commands ==		== 3 Commands ==

159.245.16.100: Undo revision 21746 by 159.245.16.100 (talk)

2012-02-24T16:57:50Z

Undo revision 21746 by 159.245.16.100 (talk)

â† Older revision		Revision as of 16:57, 24 February 2012
Line 144:		Line 144:

	=========================================================================		=========================================================================
	~~===~~ ${StrClb} ~~===~~		* ${StrClb}
	-------------------------------------------------------------------------		-------------------------------------------------------------------------
	ResultVar String Action(\|>\|<\|<>)		ResultVar String Action(\|>\|<\|<>)

159.245.16.100: /* ${StrCase} */

2012-02-24T16:56:15Z

${StrCase}

â† Older revision		Revision as of 16:56, 24 February 2012
Line 144:		Line 144:

	=========================================================================		=========================================================================
	* ${StrClb}		=== ${StrClb} ===
	-------------------------------------------------------------------------		-------------------------------------------------------------------------
	ResultVar String Action(\|>\|<\|<>)		ResultVar String Action(\|>\|<\|<>)

213.46.174.149: Pulled in strfunc info. Needs cleaning up/formatting.

2006-10-30T10:57:55Z

Pulled in strfunc info. Needs cleaning up/formatting.

New page

= Description =
StrFunc provides some additional handy string functions.
Documentation for it is surprisingly badly advertised. It is in the Docs directory of the NSIS installed package, but it is not put in the contribs menu, or really hinted at anywhere.

Before you go and reinvent the wheel because the basic stringmanip you get is not enough, do make sure you have read this!

This header is redistributed with NSIS so no additional downloads are required.
= Header File =

<highlight-nsis>
!include "StrFunc.nsh"
</highlight-nsis>

= String Functions Header File Readme =

String Functions Header File contains a set of good string manipulation
functions in a much simpler way to include and call in NSIS scripts.

== How to use ==

=== Basic Syntax ===

Parameters are specified in this format:
<highlight-nsis>required (required) (option1 | option2) [optional or add. options]
[option1 | option2]</highlight-nsis>

The stars in command titles (*****) are the function usefulness in the package creators opinion. The more starts, the more useful it is. 5 stars (*****) is the most useful.

Any time when is mentioned "Default is" means that you can use the value mentioned or keep it blank, the result is the same.

If you want a certain value (e.g. a text) to be language-specific, set a language string (using LangString) and define $(STRINGNAME) as value.

If you want to add ` to a string, you should always escape it using $\` because the header file macro functions use ` to separate parameters.

== 1. Include Header file ==

<highlight-nsis>!include "StrFunc.nsh"</highlight-nsis>

StrFunc.nsh has to be inside Include directory, so you don't have to specify a path.

You have to put this command before any command used in this header file.

== 2. Defines ==

This header file contains defines that automate the life of some who fear a lot of changes sometimes imposed in this header file, or who have applications that put it to work at maximum capacity. Before you try these, take a look at the information below:

* Every item on a define value is separated by a "|", and every subitem (items in an item) is separated by " ".

* Use ${StrTok} $var "${DefineName}" "|" "$counter" "0" to get every item inside the define. For subitems, use ${StrTok} $var2 "$var" " " "$counter2" "0" after getting the value for a desired item.

* ${StrFunc_List} is automatically made by the header file. The rest is manually added to the header.

=== 2.1 Defines List: ===
-----------------

* StrFunc_List - Lists all function names currently available on StrFunc header file.

* *_List - Lists all parameter names currently available for "*" function. (* = function name - i.e. StrTok_List).

* *_TypeList - Lists the types of all parameters on "*" function. (* = function name - i.e. StrTok_List). Possible types for each parameter:

** Output - Needs a variable to output a function result.

** Text - Needs text or number to be input.

** Mixed - Needs text, number or option to be inputed. Each subitem following the "Mixed" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.

** Option - Needs an option to be inputed. Each subitem following the "Option" word is an option. The first option is ever the default one. Two following spaces " " means that that subitem is empty.

== 3 Commands ==

Some commands have special specifications to work. Consult command's documentation on "3.3 Commands" section.

=== 3.1 How To Use Commands In Install Sections and Functions ===

Every command used in install sections and functions have to be called first before and out of any sections and functions, and without parameters.

''''Example:''''
<highlight-nsis>
${StrStr}
</highlight-nsis>

=== 3.2 How To Use Commands In Uninstall Sections and Functions ===

Commands with Uninstall Sections and Functions support have "Un" before the words inside curly brackets "{}".

''''Example:''''

<highlight-nsis>${UnStrStr}</highlight-nsis>

=== A complete example with both Install and Uninstall Commands: ===
<highlight-nsis>
!include "StrFunc.nsh"

${StrStr} # Supportable for Install Sections and Functions

${UnStrStr} # Supportable for Uninstall Sections and Functions

Section

${StrStr} $0 "OK! Now what?" "wh"

SectionEnd

Section Uninstall

${UnStrStr} $0 "OK! Now what?" "wh"

SectionEnd
</highlight-nsis>
== 3.3 Commands ==
This will be kept verbatim for now.
=== ${StrCase} ===
Rating: **

<highlight-nsis>${StrCase} ResultVar String Type(|L|U|T|S|<>)</highlight-nsis>

Converts "String" to "Type" Case. Uses LogicLib.

Parameters:

* ResultVar Destination where result is returned.

* String String to convert to "Type" case.

* Type Type of string case to convert to:
** "" = Original Case (same as "String")
** L = Lower Case (this is just an example. a very simple one.)
** U = Upper Case (THIS IS JUST AN EXAMPLE. A VERY SIMPLE ONE.)
** T = Title Case (This Is Just An Example. A Very Simple One.)
** S = Sentence Case (This is just an example. A very simple one.)
** <> = Switch Case (This is just an example. A very simple one.)
Default value is "" (Original Case).

Result Value -> ResultVar:

"String" in "Type" case.

''''Example:''''

<highlight-nsis>${StrCase} $0 '"VocÃª" is "You" in English.' "U"</highlight-nsis>

<highlight-nsis>$0 = '"VOCÃŠ" IS "YOU" IN ENGLISH.'</highlight-nsis>

=========================================================================
* ${StrClb}
-------------------------------------------------------------------------
ResultVar String Action(|>|<|<>)
=========================================================================
Makes an action with the clipboard depending on value of parameter
"Action". Uses LogicLib.

Parameters:

String
If "Action" = ">" or "<>" - String to put on the clipboard.

Action
Can be one of the following values:

- "" = Cleans the clipboard.
- ">" = Set string to clipboard.
- "<" = Get string from clipboard.
- "<>" = Swap string with clipboard's.

Result Value -> ResultVar:

If "Action" = "<" or "<>" - String found on the clipboard.

=========================================================================
*** ${StrIOToNSIS}
-------------------------------------------------------------------------
ResultVar String
=========================================================================
Convert "String" from Install Options plugin to be supported by NSIS.
Escape, back-slash, carriage return, line feed and tab characters are
converted.

Parameters:

ResultVar
Destination where result is returned.

String
String to convert to be supportable for NSIS.

Result Value -> ResultVar:

"String" supportable for NSIS.

Example:

${StrIOToNSIS} $0 "\r\n\t\\This is just an example\\"
[()()()()_______________________()]

$0 = "$\r$\n$\t\This is just an example\"

=========================================================================
* ${StrLoc}
-------------------------------------------------------------------------
ResultVar String StrToSearchFor CounterDirection(>|<)
=========================================================================
Searches for "StrToSearchFor" in "String" and returns its location,
according to "CounterDirection".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search "StrToSearchFor".

StrToSearchFor
String to search in "String".

CounterDirection(>|<)
Direction where the counter increases to. Default is ">".
(> = increases from left to right, < = increases from right to left)

Result Value -> ResultVar:

Where "StrToSearchFor" is, according to "OffsetDirection".

Example:

${StrLoc} $0 "This is just an example" "just" "<"
(__)<<<<<<<<<<<

$0 = "11"

=========================================================================
*** ${StrNSISToIO}
-------------------------------------------------------------------------
ResultVar String
=========================================================================
Converts "String" from NSIS to be supported by Install Options plugin.
Escape, back-slash, carriage return, line feed and tab characters are
converted.

Parameters:

ResultVar
Destination where result is returned.

String
String to convert to be supportable for Install Options plugin.

Result Value -> ResultVar:

"String" supportable for Install Options plugin.

Example:

${StrNSISToIO} $0 "$\r$\n$\t\This is just an example\"
[(_)(_)(_)^_______________________^]

$0 = "\r\n\t\\This is just an example\\"

=========================================================================
***** ${StrRep}
-------------------------------------------------------------------------
ResultVar String StrToReplace ReplacementString
=========================================================================
Searches for all "StrToReplace" in "String" replacing those with
"ReplacementString".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search "StrToReplace".

StrToReplaceFor
String to search in "String".

StringToBeReplacedWith
String to replace "StringToReplace" when it is found in "String".

Result Value -> ResultVar:

"String" with all occurrences of "StringToReplace" replaced with
"ReplacementString".

Example:

${StrRep} $0 "This is just an example" "an" "one"
[____________()_______]

$0 = "This is just one example"

=========================================================================
*** ${StrSort}
-------------------------------------------------------------------------
ResultVar String LeftStr CenterStr RightStr IncludeLeftStr(1|0)
IncludeCenterStr(1|0) IncludeRightStr(1|0)
=========================================================================
Searches for "CenterStr" in "String", and returns only the value
between "LeftStr" and "RightStr", including or not the "CenterStr" using
"IncludeCenterStr" and/or the "LeftStr" using "IncludeLeftStr" and
"RightStr" using "IncludeRightStr".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search "CenterStr".

LeftStr
The first occurrence of "LeftStr" on the left of "CenterStr".
If it is an empty value, or was not found, will return
everything on the left of "CenterStr".

CenterStr
String to search in "String".

RightStr
The first occurrence of "RightStr" on the right of "CenterStr".
If it is an empty value, or was not found, will return
everything on the right of "CenterStr".

IncludeLeftStr(1|0)
Include or not the "LeftStr" in the result value. Default is 1
(True). (1 = True, 0 = False)

IncludeCenterStr(1|0)
Include or not the "CenterStr" in the result value. Default is 1
(True). (1 = True, 0 = False)

IncludeRightStr(1|0)
Include or not the "RightStr" in the result value. Default is 1
(True). (1 = True, 0 = False)

Result Value -> ResultVar:

String between "LeftStr" and "RightStr" of a found "CenterStr"
including or not the "LeftStr" and "RightStr" if
"IncludeLeftRightStr" is 1 and/or the "CenterStr" if
"IncludeCenterStr" is 1.

Example:

${StrSort} $0 "This is just an example" " just" "" "ple" "0" "0" "0"
[_______(___)_______]( )
C R

$0 = "This is an exam"

=========================================================================
***** ${StrStr}
-------------------------------------------------------------------------
ResultVar String StrToSearchFor
=========================================================================
Searches for "StrToSearchFor" in "String".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search "StrToSearchFor".

StrToSearchFor
String to search in "String".

Result Value -> ResultVar:

"StrToSearchFor" + the string after where "StrToSearchFor" was found in
"String".

Example:

${StrStr} $0 "This is just an example" "just"
>>>>>>>>>{_)____________]

$0 = "just an example"

=========================================================================
***** ${StrStrAdv}
-------------------------------------------------------------------------
ResultVar String StrToSearchFor SearchDirection(>|<)
ResultStrDirection(>|<) DisplayStrToSearch(1|0) Loops CaseSensitive(0|1)
=========================================================================
Searches for "StrToSearchFor" in "String" in the direction specified by
"SearchDirection" and looping "Loops" times.

Parameters:

ResultVar
Destination where result is returned.

String
String where to search "StrToSearchFor".

StrToSearchFor
String to search in "String".

SearchDirection (>|<)
Where do you want to direct the search. Default is ">" (to right).
(< = To left, > = To right)

ResultStrDirection (>|<)
Where the result string will be based on in relation of
"StrToSearchFor"
position. Default is ">" (to right). (< = To left, > = To right)

DisplayStrToSearch (1|0)
Display "StrToSearchFor" in the result. Default is "1" (True).
(1 = True, 0 = False)

Loops
Number of times the code will search "StrToSearchFor" in "String" not
including the original execution. Default is "0" (1 code execution).

CaseSensitive(0|1)
If "1" the search will be case-sensitive (differentiates between cases).
If "0" it is case-insensitive (does not differentiate between cases).
Default is "0" (Case-Insensitive).

Result Value -> ResultVar:

"StrToSearchFor" if "DisplayStrToSearch" is 1 + the result string after
or before "StrToSearchFor", depending on "ResultStrDirection".

Result with Errors:

When "StrToSearchFor" was not found, will return an empty string.

When you put nothing in "StrToSearchFor", will return "String" and set
error flag.

When you put nothing in "String", will return an empty string and set
error flag.

Example:

${StrStrAdv} $0 "This IS really just an example" "IS " ">" ">" "0" "0" "1"
>>>>>( )[____________________]

$0 = "really just an example"

=========================================================================
**** ${StrTok}
-------------------------------------------------------------------------
ResultVar String Separators ResultPart[L] SkipEmptyParts(1|0)
=========================================================================
Returns the part "ResultPart" between two "Separators" inside
"String".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search for "Separators".

Separators
Characters to find on "String".

ResultPart[L]
The part want to be found on "StrToTokenize" between two "Separators".
Can be any number, starting at 0, and "L" that is the last part.
Default is L (Last part).

SkipEmptyParts(1|0)
Skips empty string parts between two "Separators". Default is 1 (True).
(1 = True, 0 = False)

Result Value -> ResultVar:

"String" part number "Part" between two "Separators".

Examples:

1) ${StrTok} $0 "This is, or is not, just an example" " ," "4" "1"
( ) () () () [_] ( ) () ( )
0 1 2 3 4 5 6 7
$0 = "not"

2) ${StrTok} $0 "This is, or is not, just an example" " ," "4" "0"
( ) () ^() [] ( ) ^( ) () ( )
0 1 23 4 5 67 8 9
$0 = "is"

=========================================================================
* ${StrTrimNewLines}
-------------------------------------------------------------------------
ResultVar String
=========================================================================
Deletes unnecessary new lines at end of "String".

Parameters:

ResultVar
Destination where result is returned.

String
String where to search unnecessary new lines at end of "String".

Result Value -> ResultVar:

"String" with unnecessary end new lines removed.

Example:

${StrTrimNewLines} $0 "$\r$\nThis is just an example$\r$\n$\r$\n"
[_____________________________(_)(_)(_)(_)]

$0 = "$\r$\nThis is just an example"

== Functions included and not included ==
<nowiki>
11 functions have been included
They are not available on Archive
They are on LogicLib format

15 functions have not been included
12 were not included because of better functions
6 were not included because of AdvStrTok (called here as StrTok)
First String Part Function
Save on Variables Function
Sort Strings (1, 2 and 3) Functions
StrTok Function
2 were not included because of StrCase
StrLower Function
StrUpper Function
2 were not included because of StrClb
StrClbSet Function
StrClbGet Function
1 was not included because of NSISToIO and IOToNSIS
Convert / to // in Paths Function
1 was not included because of original String Replace Function (called
here as StrRep)
Another String Replace Function
2 were not included because they aren't useful anymore
Slash <-> Backslash Converter Function
Trim Function
1 was not included because of bugs
Number to String Converter Function
</nowiki>

= Version History =
Please read the Doc/Strfunc.txt readme file for version history.

= Credits =

Made by Diego Pedroso (aka deguix).

= Functions Credits =

All functions are made by Diego Pedroso on LogicLib format. They are based on functions by Amir Szekely, Dave Laundon, Hendri Adriaens, Nik Medved, Joost Verburg, Stuart Welch, Ximon Eighteen, "bigmac666" and "bluenet". "bluenet"'s version of StrIOToNSIS and StrNSISToIO on LogicLib format were included.

= License =

This header file is provided 'as-is', without any express or implied
warranty. In no event will the author be held liable for any damages
arising from the use of this header file.

Permission is granted to anyone to use this header file for any purpose,
including commercial applications, and to alter it and redistribute
it freely, subject to the following restrictions:

1. The origin of this header file must not be misrepresented; you must not claim that you wrote the original header file. If you use this header file in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered versions must be plainly marked as such, and must not be misrepresented as being the original header file.
3. This notice may not be removed or altered from any distribution.

StrFunc - Revision history

Bugmenot: /* 2.1 Defines List: */ formatting

159.245.16.100: Undo revision 21746 by 159.245.16.100 (talk)

159.245.16.100: /* ${StrCase} */

213.46.174.149: Pulled in strfunc info. Needs cleaning up/formatting.