home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 March / CMCD0304.ISO / Software / Freeware / Programare / nullsoft / nsis20.exe / Include / StrFunc.txt < prev    next >
Text File  |  2004-02-07  |  18KB  |  609 lines
  1. String Functions Header File Readme
  2. -----------------------------------
  3.  
  4. String Functions Header File contains a set of good string manipulation
  5. functions in a much simpler way to include and call in NSIS scripts.
  6.  
  7. How to use
  8. ----------
  9.  
  10.   Syntax
  11.  
  12.   Parameters are specified in this format: required (option1 | option2)
  13.   [optional]
  14.  
  15.   The stars in command titles (*****) are the function usefulness in my
  16.   opinion. 5 stars (*****) the function is much useful.
  17.  
  18.   Any time when is mentioned "Default is" means that you can use the value
  19.   mentioned or keep blank, the result is the same.
  20.  
  21.   If you want a certain value (e.g. a text) to be language-specific, set a
  22.   language string (using LangString) and define $(STRINGNAME) as value.
  23.  
  24.   If you want to add ` to a string, you should always escape it using $\`
  25.   because the header file macro functions use ` to separate parameters.
  26.  
  27.   1. Include Header file
  28.   ----------------------
  29.  
  30.     !include "StrFunc.nsh"
  31.  
  32.     StrFunc.nsh have to be in the Include directory, so you don't have to
  33.     specify a path.
  34.  
  35.     You have to put this command before any command used in this header file.
  36.  
  37.   2. Commands
  38.   -----------
  39.  
  40.     IMPORTANT: Every command in this header file have to be called first
  41.     before, out of sections and functions and without parameters. Example:
  42.  
  43.     !include "StrFunc.nsh"
  44.  
  45.     ${StrStr}
  46.  
  47.     Section
  48.  
  49.       ${StrStr} $0 "OK! Now what?" "wh"
  50.  
  51.     SectionEnd
  52.  
  53.     =========================================================================
  54.     *****                           ${StrStr} ResultVar String StrToSearchFor
  55.     =========================================================================
  56.     Searches for "StrToSearchFor" in "String".
  57.  
  58.     Parameters:
  59.  
  60.       ResultVar
  61.       Destination where result is returned.
  62.  
  63.       String
  64.       String where to search "StrToSearchFor".
  65.  
  66.       StrToSearchFor
  67.       String to search in "String".
  68.  
  69.     Result Value -> ResultVar:
  70.  
  71.       "StrToSearchFor" + the string after where it was found in "String".
  72.  
  73.     Example: 
  74.  
  75.       ${StrStr} $0 "This is just an example" "just"
  76.  
  77.       $0 = "just an example"
  78.  
  79.     =========================================================================
  80.     **         ${StrLoc} ResultVar String StrToSearchFor OffsetDirection(>|<)
  81.     =========================================================================
  82.     Searches for "StrToSearchFor" in "String" and returns its location,
  83.     according to "OffsetDirection".
  84.  
  85.     Parameters:
  86.  
  87.       ResultVar
  88.       Destination where result is returned.
  89.  
  90.       String
  91.       String where to search "StrToSearchFor".
  92.  
  93.       StrToSearchFor
  94.       String to search in "String".
  95.  
  96.       OffsetDirection(>|<)
  97.       Direction where the counter goes to. Default is ">". (> = left to right,
  98.       < = right to left)
  99.  
  100.     Result Value -> ResultVar:
  101.  
  102.       Where "StrToSearchFor" is, according to "OffsetDirection".
  103.  
  104.     Example: 
  105.  
  106.       ${StrLoc} $0 "This is just an example" "just" "<"
  107.  
  108.       $0 = "11"
  109.  
  110.     =========================================================================
  111.     *****   ${StrStrAdv} ResultVar String StrToSearchFor SearchDirection(>|<)
  112.                         ResultStrDirection(>|<) DisplayStrToSearch(1|0) Loops
  113.     =========================================================================
  114.     Searches for "StrToSearchFor" in "String" in the direction specified by
  115.     "SearchDirection" and looping "Loops" times.
  116.  
  117.     Parameters:
  118.  
  119.       ResultVar
  120.       Destination where result is returned.
  121.  
  122.       String
  123.       String where to search "StrToSearchFor".
  124.  
  125.       StrToSearchFor
  126.       String to search in "String".
  127.  
  128.       SearchDirection (>|<)
  129.       Where do you want to direct the search. Default is ">" (to right).
  130.       (< = To left, > = To right)
  131.  
  132.       ResultStrDirection (>|<)
  133.       Where the result string will be based on in relation of "StrToSearchFor"
  134.       position. Default is ">" (to right). (< = To left, > = To right)
  135.  
  136.       DisplayStrToSearch (1|0)
  137.       Display "StrToSearchFor" in the result. Default is "1" (True). (1 = True,
  138.       0 = False)
  139.  
  140.       Loops
  141.       Number of times the code will search "StrToSearchFor" in "String" not
  142.       including the original execution. Default is "0" (1 code execution).
  143.  
  144.  
  145.     Result Value -> ResultVar:
  146.  
  147.       "StrToSearchFor" if "DisplayStrToSearch" is 1 + the result string after
  148.       or before "StrToSearchFor", depending on "ResultStrDirection".
  149.  
  150.     Result with Errors:
  151.  
  152.       When "StrToSearchFor" was not found, will return an empty string.
  153.  
  154.       When you put nothing in "StrToSearchFor", will return "String" and set
  155.       error flag.
  156.  
  157.       When you put nothing in "String", will return an empty string and set
  158.       error flag.
  159.  
  160.     Example: 
  161.  
  162.       ${StrStrAdv} $0 "This is just an example" "is" "<" "<" "1" "1"
  163.  
  164.       $0 = "This"
  165.  
  166.     =========================================================================
  167.     *****           ${StrRep} ResultVar String StrToReplace ReplacementString
  168.     =========================================================================
  169.     Searches for all "StrToReplaceFor" in "String" replacing those with
  170.     "ReplacementString".
  171.  
  172.     Parameters:
  173.  
  174.       ResultVar
  175.       Destination where result is returned.
  176.  
  177.       String
  178.       String where to search "StrToReplaceFor".
  179.  
  180.       StrToReplaceFor
  181.       String to search in "String".
  182.  
  183.       StringToBeReplacedWith
  184.       String to replace "StringToReplace" when it is found in "String".
  185.  
  186.     Result Value -> ResultVar:
  187.  
  188.       "String" with all occurences of "StringToReplace" replaced with
  189.       "ReplacementString".
  190.  
  191.     Example: 
  192.  
  193.       ${StrRep} $0 "This is just an example" "an" "one"
  194.  
  195.       $0 = "This is just one example"
  196.  
  197.  
  198.     =========================================================================
  199.     ****                                                  ${StrClbSet} String
  200.     =========================================================================
  201.     Copy "String" to clipboard.
  202.  
  203.     Parameters:
  204.  
  205.       String
  206.       String to put in the clipboard.
  207.  
  208.  
  209.     =========================================================================
  210.     ****                                               ${StrClbGet} ResultVar
  211.     =========================================================================
  212.     Get a string from the clipboard and return it to "ResultVar".
  213.  
  214.     Parameters:
  215.  
  216.       ResultVar
  217.       Destination where result is returned.
  218.  
  219.     Result Value -> ResultVar:
  220.  
  221.       The string found in clipboard.
  222.  
  223.  
  224.     =========================================================================
  225.     *****             ${StrTok} ResultVar StrToTokenize Separators ResultPart
  226.                                                           SkipEmptyParts(1|0)
  227.     =========================================================================
  228.     Returns the part "ResultPart" between two "Separators" inside
  229.     "StrToTokenize".
  230.  
  231.     Parameters:
  232.  
  233.       ResultVar
  234.       Destination where result is returned.
  235.  
  236.       StrToTokenizing
  237.       String where to search for "Separators".
  238.  
  239.       Separators
  240.       Characters to find in "StrToTokenize".
  241.  
  242.       ResultPart
  243.       The part want to be found in "StrToTokenize" between two "Separators".
  244.       Can be any number, starting at 1, and "L" that is the last part.
  245.       Default is L.
  246.  
  247.       SkipEmptyParts(1|0)
  248.       Skips empty string parts between two "Separators". Default is 1 (True).
  249.       (1 = True, 0 = False)
  250.  
  251.     Result Value -> ResultVar:
  252.  
  253.       "StrToTokenize" part "Part" between two "Separators".
  254.  
  255.     Examples: 
  256.  
  257.       1) ${StrTok} $0 "This is, or is not, just an example" " ," "5" "1"
  258.  
  259.          $0 = "not"
  260.  
  261.       2) ${StrTok} $0 "This is, or is not, just an example" " ," "5" "0"
  262.  
  263.          $0 = "is"
  264.  
  265.     =========================================================================
  266.     ***                                      ${StrUpperCase} ResultVar String
  267.     =========================================================================
  268.     Converts "String" to upper case.
  269.  
  270.     Parameters:
  271.  
  272.       ResultVar
  273.       Destination where result is returned.
  274.  
  275.       String
  276.       String to convert to upper case.
  277.  
  278.     Result Value -> ResultVar:
  279.  
  280.       "String" in upper case.
  281.  
  282.     Example:
  283.  
  284.       ${StrUpperCase} $0 "oh man!"
  285.  
  286.       $0 = "OH MAN!"
  287.  
  288.     =========================================================================
  289.     ***                                      ${StrLowerCase} ResultVar String
  290.     =========================================================================
  291.  
  292.     Converts "String" to lower case.
  293.  
  294.     Parameters:
  295.  
  296.       ResultVar
  297.       Destination where result is returned.
  298.  
  299.       String
  300.       String to convert to lower case.
  301.  
  302.     Result Value -> ResultVar:
  303.  
  304.       "String" in lower case.
  305.  
  306.     Example:
  307.  
  308.       ${StrUpperCase} $0 "OH MAN!"
  309.  
  310.       $0 = "oh man!"
  311.  
  312.     =========================================================================
  313.     *****              ${StrSort} ResultVar String CenterStr LeftStr RightStr
  314.                                IncludeLeftRightStr(1|0) IncludeCenterStr(1|0)
  315.     =========================================================================
  316.     Searches for "CenterStr" in "String", and returns only the value
  317.     between "LeftStr" and "RightStr", including or not the "CenterStr" using
  318.     "IncludeCenterStr" and/or the "LeftStr" and "RightStr" using
  319.     "IncludeLeftRightStr".
  320.  
  321.     Parameters:
  322.  
  323.       ResultVar
  324.       Destination where result is returned.
  325.  
  326.       String
  327.       String where to search "CenterStr".
  328.  
  329.       CenterStr
  330.       String to search in "String".
  331.  
  332.       LeftStr
  333.       The first occurrence of "LeftStr" on the left of "CenterStr".
  334.       If it is an empty value, or was not found, will return
  335.       everything on the left of "CenterStr".
  336.  
  337.       RightStr
  338.       The first occurrence of "RightStr" on the right of "CenterStr".
  339.       If it is an empty value, or was not found, will return
  340.       everything on the right of "CenterStr".
  341.  
  342.       IncludeLeftRightStr(1|0)
  343.       Include or not the "LeftStr" and "RightStr" in the result value.
  344.       Default is 1 (True). (1 = True, 0 = False)
  345.  
  346.       IncludeCenterStr(1|0)
  347.       Include or not the "CenterStr" in the result value. Default is 1
  348.       (True). (1 = True, 0 = False)
  349.  
  350.     Result Value -> ResultVar:
  351.  
  352.       String between "LeftStr" and "RightStr" of a found "CenterStr"
  353.       including or not the "LeftStr" and "RightStr" if
  354.       "IncludeLeftRightStr" is 1 and/or the "CenterStr" if
  355.       "IncludeCenterStr" is 1.
  356.  
  357.     Example: 
  358.  
  359.       ${StrSort} $0 "This is just an example" " just" "" "ple" "0" "0"
  360.  
  361.       $0 = "This is an exam"
  362.  
  363.     =========================================================================
  364.     *                                     ${StrTrimNewLines} ResultVar String
  365.     =========================================================================
  366.     Deletes unnecessary new lines at end of "String".
  367.  
  368.     Parameters:
  369.  
  370.       ResultVar
  371.       Destination where result is returned.
  372.  
  373.       String
  374.       String where to search unnecessary new lines at end of "String".
  375.  
  376.     Result Value -> ResultVar:
  377.  
  378.       "String" with unnecessary end new lines removed.
  379.  
  380.     Example:
  381.  
  382.       ${StrTrimNewLines} $0 "$\r$\nThis is just an example$\r$\n$\r$\n"
  383.  
  384.       $0 = "$\r$\nThis is just an example"
  385.  
  386.     =========================================================================
  387.     *****                                     ${StrNSISToIO} ResultVar String
  388.     =========================================================================
  389.     Converts "String" from NSIS to be supported by Install Options plugin.
  390.     Escape, back-slash, carriage return, line feed and tab characters are
  391.     converted.
  392.  
  393.     Parameters:
  394.  
  395.       ResultVar
  396.       Destination where result is returned.
  397.  
  398.       String
  399.       String to convert to be supportable for Install Options plugin.
  400.  
  401.     Result Value -> ResultVar:
  402.  
  403.       "String" supportable for Install Options plugin.
  404.  
  405.     Example:
  406.  
  407.       ${StrNSISToIO} $0 "$\r$\n$\t\This is just an example\"
  408.  
  409.       $0 = "\r\n\t\\This is just an example\\"
  410.  
  411.     =========================================================================
  412.     *****                                     ${StrIOToNSIS} ResultVar String
  413.     =========================================================================
  414.     Convert "String" from Install Options plugin to be supported by NSIS.
  415.     Escape, back-slash, carriage return, line feed and tab characters are
  416.     converted.
  417.  
  418.     Parameters:
  419.  
  420.       ResultVar
  421.       Destination where result is returned.
  422.  
  423.       String
  424.       String to convert to be supportable for NSIS.
  425.  
  426.     Result Value -> ResultVar:
  427.  
  428.       "String" supportable for NSIS.
  429.  
  430.     Example:
  431.  
  432.       ${StrIOToNSIS} $0 "\r\n\t\\This is just an example\\"
  433.  
  434.       $0 = "$\r$\n$\t\This is just an example\"
  435.  
  436. Comments about functions included and not included
  437. --------------------------------------------------
  438.  
  439. 13 functions have been included
  440.   7 were included was it was in Archive
  441.   5 were not included in Archive
  442.     StrTok
  443.     NSISToIO
  444.     IOToNSIS
  445.     StrLoc
  446.     StrSort
  447.   1 was been changed from original version
  448.     StrClbGet
  449.  
  450. 12 functions have not been included
  451.   8 were not included because of better functions
  452.     6 were not included because of AdvStrTok (called here as StrTok)
  453.       First String Part Function
  454.       Save on Variables Function
  455.       Sort Strings (1, 2 and 3) Functions
  456.       StrTok Function
  457.     1 was not included because of NSISToIO and IOToNSIS
  458.       Convert / to // in Paths Function
  459.     1 was not included because of original String Replace Function (called
  460.       here as StrRep)
  461.       Another String Replace Function
  462.   2 were not included because isn't useful anymore
  463.     Slash <-> Backslash Converter Function
  464.     Trim Function
  465.   1 was not included because of bugs
  466.     Number to String Converter Function
  467.  
  468. Comments
  469. ------------------------------------------------------------
  470.  
  471. Advanced Token String Function
  472.  
  473.   New function not published in Archive, much better than original StrTok,
  474.   going to replace several functions with just one. The principal idea was
  475.   based on "Save On Variables" by Afrow UK.
  476.  
  477. Advanced String Sort Function
  478.  
  479.   New function not published in Archive, much better than original StrSort.
  480.  
  481. Another String Replace Function
  482.  
  483.   Another doesn't mean better and simpler than the original version.
  484.   (Don't confuse the original StrRep that is in this header file with this
  485.   one)
  486.  
  487. Convert / to // in Paths Function
  488.  
  489.   StrNSISToIO and StrIOToNSIS are better.
  490.  
  491. Copy from Clipboard Function
  492.  
  493.   Changed just the function name to the correct "CopyFromClipboard".
  494.  
  495.  
  496. First String Part Function
  497.  
  498.   AdvStrTok (called here as StrTok) is better.
  499.  
  500.  
  501. NSIS <-> Install Options String Convertor Functions
  502.  
  503.   Included from Install Options Readme.
  504.  
  505.  
  506. Number to String Converter Function
  507.  
  508.   Have a serious bug when input is 5 chars long. Need to be remade to a
  509.   simpler one.
  510.  
  511. Save on Variables Function
  512.  
  513.   AdvStrTok (called here as StrTok) is better.
  514.  
  515. Slash <-> Backslash Converter Function
  516.  
  517.   Will convert "http://www.site.com\" to "http:\\www.site.com/", not
  518.   really useful for anyone.
  519.  
  520. Sort Strings (1, 2 and 3) Functions
  521.  
  522.   AdvStrTok (called here as StrTok), AdvStrStr (called here as StrStrAdv)
  523.   and AdvStrSort (called here as StrSort) are better.
  524.  
  525. Split String Function
  526.  
  527.   AdvStrTok (called here as StrTok) is better.
  528.  
  529.  
  530. StrTok Function
  531.  
  532.   AdvStrTok (called here as StrTok) is better.
  533.  
  534.  
  535. Trim Function
  536.  
  537.   The real purpose of this function was to remove spaces from directory
  538.   paths, and now with the NSIS command GetFullPathName this is not useful
  539.   anymore.
  540.  
  541. Version History
  542. ---------------
  543.  
  544. 1.02 - 02/07/2004
  545.  
  546. - Fixed StrLoc.
  547. - Fixed Documentation about StrLoc. "Direction" is really
  548. "OffsetDirection".
  549. - Added my new AdvStrSort, and removed the old one.
  550.  
  551. 1.01 - 02/05/2004
  552.  
  553. - Fixed Documentation about StrSort and StrTok.
  554. - Fixed StrTok default value for the string part. Now it's "L".
  555. - Fixed StrStrAdv fixed wrong search when had a combination of same
  556. substrings one after another in a string.
  557. - Fixed StrLoc, when a string isn't found, don't return any value at all.
  558.  
  559. 1.00 - 02/01/2004
  560.  
  561. - Added documentation.
  562. - Renamed header file to "StrFunc.nsh".
  563. - Added 1 function, StrLoc.
  564. - Modified StrStrAdv, removed some lines.
  565. - Fixed StrTok, 2 simple numbers made it loop every time.
  566. - Fixed some small issues in the header file.
  567.  
  568. 0.02 - 01/24/2004
  569.  
  570.   - Completed StrFunc.nsh file. Need some tests and the readme.
  571.  
  572. 0.01 - 01/22/2004
  573.  
  574.   - First version to test ideas...
  575.  
  576. Credits
  577. -------
  578.  
  579. Made by Diego Pedroso (aka deguix).
  580.  
  581. Functions Credits
  582. -----------------
  583.  
  584. - Advanced Search in String, Advanced Token String, Localize in String
  585. made by Diego Pedroso.
  586. - Copy to/from clipboard made by Nik Medved.
  587. - StrUpper made by Dave Laundon.
  588. - StrReplace made by Hendri Adriaens.
  589. - Search in a string, Trim newlines made by Ximon Eighteen.
  590. - NSISToIO and IOToNSIS made by Amir Szekely, Joost Verburg and Dave Laundon.
  591.  
  592. License
  593. -------
  594.  
  595. This header file is provided 'as-is', without any express or implied
  596. warranty. In no event will the author be held liable for any damages
  597. arising from the use of this header file.
  598.  
  599. Permission is granted to anyone to use this header file for any purpose,
  600. including commercial applications, and to alter it and redistribute
  601. it freely, subject to the following restrictions:
  602.  
  603. 1. The origin of this header file must not be misrepresented;
  604.    you must not claim that you wrote the original header file.
  605.    If you use this header file in a product, an acknowledgment in the
  606.    product documentation would be appreciated but is not required.
  607. 2. Altered versions must be plainly marked as such,
  608.    and must not be misrepresented as being the original header file.
  609. 3. This notice may not be removed or altered from any distribution.