NSISList plug-in

Introduction

A list is a dynamic data storage. It can contain an arbitrary number of items (strings) and grows dynamically. Each list is identified by a unique name, so you can handle multiple lists at the same time. Nevertheless there is a default list identified by "", which can be used if you only need one list at a time. You can create a new named list using the "Create" instruction. Initially your list will be empty. Once you have created a list, you can append as many items to as you need by calling the "Add" instruction. Alternatively you can insert items at a specified index by calling the "Insert" instruction. Items at a specified index can be read or overwritten by calling the "Get" or "Set" instructions. You can also get the first or the last item of your list by calling the "First" or "Last" instructions. In case you need to obtain ALL items of your list at once, you can call the "All" or "AllRev" instructions. The number of items in your list can be calculated by calling the "Count" instruction. If you need to find a specified item in your list, you can call "Index" in order to obtain it's current index. Furthermore you can move an item within your list by calling the "Move" instruction. Additionally you can exchange two specified items in your list by calling the "Exch" instruction. Calling the "Sort" instruction will sort all items in your list in alphabetical order. If you need to remove a specified item from your list, you can call the "Delete" instruction. You can also call "Pop" in order to obtain the last item of your list and remove that item simultaneously. The "Clear" instruction will remove ALL items from your list, but the list itself will survive. Once you are done working with your list, call "Destroy" in order to free all memory used by that list. Last but not least you can load or save your list from/to a plain text file by calling "Load" or "save". The "Debug" instruction is intended for developers, it will display all existing lists and all of their items.

General Usage

If you want to use NSISList, the header file "NSISList.nsh" must be located in your "NSIS\Includes" folder. Furthermore the plugin file "NSISList.dll" must be located in your "NSIS\Includes". Please make sure that your "NSISList.nsh" and "NSISList.dll" files are at the same release version!

In order to enable NSISList in your installer, please put these lines on the top of your script:

!include NSISList.nsh
ReserveFile "${NSISDIR}\Plugins\NSISList.dll"

After you are done working with NSISList, call the ${List.Unload} macro in order to undload the plugin !!!
The ".onGUIEnd" callback-function might be a good place to do so...

Scripting Reference

Add
Usage: ${List.Add} <key> <item>
Info: This function will append the string <item> to the list identified by <key>
Result: None

All Usage: ${List.All} <key> Info: This function will push ALL items in the list identified by <key> onto the NSIS stack, in normal order Result: n strings on the stack, last string is followed by "__LAST", errors indidcated by "__ERROR"

AllRev Usage: ${List.AllRev} <key> Info: This function will push ALL items in the list identified by <key> onto the NSIS stack, in reverse order Result: n strings on the stack, last string is followed by "__LAST", errors are indidcated by "__ERROR"

Clear Usage: ${List.Clear} <key> Info: This function will erase ALL items in the list identified by <key> Result: None

Count Usage: ${List.Count} <var_out> <key> Info: This function will calculate the number of items in the list identified by <key> Result: The number of items is returned in user var <var_out>, this can be zero, errors are indidcated by "__ERROR"

Create Usage: ${List.Create} <key> Info: This function will create a new named list, which will be identified by <key> for future access

 Result: None

Debug Usage: ${List.Debug} Info: This function will display debug information for developers, all lists and all items will be displayed

 Result: None

Delete Usage: ${List.Delete} <key> <index> Info: This function will remove the item at <index> from the list identified by <key> Result: None

Destroy Usage: ${List.Destroy} <key> Info: This function will destroy the list identified by <key>, all items will be removed, all memory will be released Result: None

Exch Usage: ${List.Exch} <key> <index1> <index2> Info: This function will exchange the item at <index1> with the item at <index2> in the list identified by <key> Result: None

First Usage: ${List.First} <var_out> <key> Info: This function obtains the FIRST item in the list identified by <key> Result: The item is returned in user var <var_out>, this can be "__EMPTY" if the list is empty, errors are indidcated by "__ERROR"

Get Usage: ${List.Get} <var_out> <key> <index> Info: This function obtains the item at <index> from the list identified by <key> Result: The items is returned in user var <var_out>, errors are indidcated by "__ERROR"

Index Usage: ${List.Index} <var_out> <key> <item> Info: This function searches for the list identified by <key> for a string that equals <item> Result: The index of the first occurence of <item> is returned in user var <var_out>, this can be -1 if there is no such string, errors are indidcated by "__ERROR"

Insert Usage: ${List.Insert} <key> <index> <item> Info: This function will insert the string <item> at the position <index> into the list identified by <key> Result: None

Last Usage: ${List.Last} <var_out> <key> Info: This function obtains the LAST item in the list identified by <key> Result: The item is returned in user var <var_out>, this can be "__EMPTY" if the list is empty, errors are indidcated by "__ERROR"

Load Usage: ${List.Load} <var_out> <key> <filename> Info: This function will load the list identified by <key> from a text file identified by <filename>, the old contents of the list will be lost Result: The result is returned in user var <var_out>, this can be either "__SUCCESS" or "__ERROR"

Move Usage: ${List.Move} <key> <index_from> <index_to> Info: This function will move the item at <index_from> to the position <index_to> in the list identified by <key> Result: None

Pop Usage: ${List.Pop} <var_out> <key> Info: This function will obtain the LAST item from the list identified by <key> and it will alse REMOVE this item from the list

 Result: The result is returned in user var <var_out>, this can be "_EMPTY" if the list is empty, errors are indidcated by "__ERROR"

Save Usage: ${List.Save} <var_out> <key> <filename> Info: This function will save all items in the list identified by <key> to a plain text file identified by <filename>

 Result: The result is returned in user var <var_out>, this can be either "__SUCCESS" or "__ERROR"

Set Usage: ${List.Set} <key> <index> <value> Info: This function will change the content of the item at <index> in the list identified by <key> to <value> Result: None

Sort Usage: ${List.Sort} <key> Info: This function will sort all items in the list identified by <key> alphabetically Result: None

Unload Usage: ${List.Unload} Info: This function will unload the NSISList plugin, destroy ALL lists including all of their items and release all memory used by NSISList Result: None

Example

Here is a simple example of how to use NSISList:

!include NSISList.nsh
ReserveFile "${NSISDIR}\Plugins\NSISList.dll"
 
Name "NSISList Example Installer"
OutFile "NSISList_Example.exe"
 
Section
  ; Create a listed named "MyList"
  ${List.Create} MyList
  ; Add "Jimmy Pop Ali" to the list identified by "MyList", this will become item #0
  ${List.Add} MyList "Jimmy Pop Ali"
  ; Add "Lüpüs Thünder" to the list identified by "MyList", this will become item #1
  ${List.Add} MyList "Lüpüs Thünder"
  ; Add "Evil Jared Hasselhoff" to the list identified by "MyList", this will become item #2
  ${List.Add} MyList "Evil Jared Hasselhoff"
  ; Calculate the number of items in the list identified by "MyList", $0 <- 3
  ${List.Count} $0 MyList                      
  ; Get the item at index #1 from the list idedntified by "MyList", $1 <- "Lüpüs Thünder"
  ${List.Get} $1 MyList 1
  ; Some output for the user
  DetialPrint "Count: $0"
  ; And some more output for the user
  DetialPrint "Item at #1 is: $1"
  ; We are done here, so destroy the list identified by "MyList"
  ${List.Destroy} MyList
 
  ; Put some more important stuff here ;-)
  [...]
 
  ; Don't forget to unload the NSISList plugin at the end !!!!!
  ${List.Unload}
Section

Please see "Examples\NSISList\NSISList_Test.nsi" for a more detailed example!

Download

• NSISList-Plugin.zip (88 KB)  -  Last Update: 2008-07-12
• Thread at NSIS Discussion Forum - Feedback & Support