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

<small>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</small>

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