Lab 02 - VoltScript Project with VoltScript Library Module

Duration 15 min

What you will learn

You'll learn how to use atlas.json and structure a VoltScript project. You'll also learn how to integrate external library modules with a Use statement.

Prerequisites

• Lab 01 completed

Steps

The IDE

1. Create a new VS Code VoltScript Workspace folder called lab-02.

   1. Open Visual Studio Code.

   2. From the Explorer view, click Open Folder.

      

   3. Create a new folder in your user directory, with the name stated above.

   4. Select the newly created folder to open in VS Code.

atlas.json

1. Create a new atlas.json file:

   Note

   The atlas.json file is the VoltScript equivalent of Node.js's package.json, Maven's pom.xml or Rust's cargo.toml. It defines metadata about your project (name, version, authors, license), dependencies, structure, and scripts.

   1. Right-click in the empty pane and select New File from the context menu.
   2. Name the file atlas.json.
   3. Type an opening curly brace "{" and press enter. VS Code automatically adds the closing curly brace "}".

   4. If the PROBLEMS view isn't visible, select View → Problems. Note the validation errors, which will identify any required properties which are missing.

      

2. Set name to "lab02".

3. Set version to "1.0.0".
4. Set description to "Lab Number 2".
5. Add the authors array. Add an array element with your name.
6. Set sourceDir as "src". Set mainScripts as main.vss.
7. Use content assist (Ctrl + space) to see other elements that can be added.
8. Set libsDir as "libs".
9. Save the atlas.json.

libs directory

Note

In the same way that you can create Script Libraries and use them in Domino Designer with the Use instruction, the same can be done in VoltScript. The terminology used to refer to these is "VoltScript Library Module".

1. Right-click in the empty pane and select New Folder from the context menu. Name the directory "src".
2. Right-click in the empty pane and select New Folder from the context menu. Name the directory "libs".
3. Right-click the "libs" directory and select New File from the context menu. Name the file "Lab2Functions.vss".
4. In the .vss file, add Option Declare and Option Public.

5. Type Sub. Snippets will offer you "Sub...". Press Enter to select the snippet. The following code will be inserted.

   Sub ProcedureName(ParameterList)
   
   End Sub
   

6. ProcedureName is selected. Rename the sub "PrintMessage" and press tab to move to the next variable.

7. ParameterList is selected. Overtype it with message as String.
8. Move down to the body of the sub, and type Print message.
9. Move out of the sub, type "fun", and select the "Function..." snippet by pressing Enter.
10. FunctionName is selected. Rename the function "Square". Press tab to move to the next variable.
11. ParameterList is selected. Overtype it with value as Integer.
12. ReturnType is selected. Overtype it with Integer. Only the first instance of this will be replaced and a compilation error will remain "Variable not declared RETURNVALUE".

13. On the first line of the function, type value *= value.

    Tip

    Additional mathematical assignment operators have been added to the VoltScript language. In addition to the obvious ++ and -- options, +=, -=, *= and /= (with its alias \=) have also been added.

14. Amend the last line of the function to Square = value.

15. Save the file.

Main script

1. Right-click the "src" directory and select New File from the context menu. Name the file main.vss.
2. In the .vss file, add Option Declare and Option Public.

3. Add the statement Use "../libs/Lab2Functions".

   Warning

   VS Code might try to help you out here by providing typeahead here. If so, be sure to remove the .vss from the end of the library name!
   

   Note

   We can use relative paths in the Use statement. Using forward slashes make the Use statements cross-platform. Paths to Library Modules and downstream Library Modules (modules used in other Library Modules) need to work from any script opened. So all Library Modules should be at the same level of the hierarchy.

4. Add a Sub Initialize.

5. Add Call PrintMessage("Hello World").
6. Add Call PrintMessage("4 x 4 = " & Square(4)).
7. Press Ctrl+Shift+P (Cmd+Shift+P on Mac), then select VoltScript: Save & Run Script. (You can start typing "VoltScript" to filter the available commands).

8. Press the Enter key to confirm your input (no script arguments are necessary).

   Success

   A VoltScript terminal will open in your workspace and display the result of your script.

How to check

Print to console:

Hello World
4 x 4 = 16

The completed lab is available on GitHub.

Things to explore

• Change the content of the Square() function to Return value * value.

  Note

  The Return keyword is used to immediately cease operations and exit a method (Sub, Function or Property). It the method is a Function or Property Get, the Return keyword will also return the subsequent value to the calling code.

• Test downstream VoltScript Library Modules (one module that uses another).

• Test to understand how relative paths need to work from all levels of the hierarchy.

Next step

Proceed to Lab 03a - Using VoltScript Dependency Management for VSEs and VSS Libraries.