Introduction

This article gives a practical example of the functionality described in the language documentation about include. The code of this example is kept as simple as possible, focusing on being a guide of correct library usage. All action steps you should follow are in a numbered list.

The project: a work day

In order to write an example project that everyone can relate to, without using more than the most basic code, we chose a simulation of a work day. Pressing 'play' on your main robot should start the simulated day from a set starting time. Every second, a simulated hour passes. During this 'day', some devices (included as libraries) are used, which means that functions from them are called. The work day ends at a set time. A separate file (or robot) keeps these personal and project properties as a library as well.

Start your project

  1. Open Xill IDE
  2. Add a new project (name it 'Library tutorial' or 'Work day')
  3. Add a new robot called 'Main' in the project root
  4. Add a new robot called 'WorkDay' in a folder named 'script'
Main.xill is the root robot. It runs the complete project.
The script folder contains all custom project scripts.
  1. Now add the function workOneDay() to the robot WorkDay.xill:
function workOneDay() {
}


(double-click and copy the code, and paste in the robot)

  1. Include the WorkDay robot to Main and add a call to the above function:
include script.WorkDay;

workOneDay();

You should be able to run Main now, even though it does not do anything yet.

Include settings and set up a work day

Like said before, you will set a start- and end time for your work day. You might also need other user properties and/or project properties. A good way to store these in one place is with a new robot called 'Settings.xill'.

  1. Add a Settings robot to the project root
  2. Paste this code inside (change the values if you want):
function getSettings() {
    var settings = {
        "userName" : "myName", // fill in your own name
        "workStartHour": 9,
        "workEndHour" : 17,
        "coffeeHours" : [10,13]
    };
    return settings;
}

These settings should be available to your workOneDay() function. To achieve this:

  1. include Settings in the WorkDay bot
  2. Add a settings variable to the start of the workOneDay() function

The robot should now look like this:

include Settings;

function workOneDay() {
var settings = getSettings();
}

It should now be clear what the Xill syntax is for using libraries. We'll add some code to the WorkDay robot to actually see it doing something.

  1. Replace the code in WorkDay with the code below:
use Date,System,Collection;

include Settings;

workOneDay();
 
function workOneDay() {
    var settings = getSettings();
var currentHour = settings.workStartHour;
var simulatedTime = dateTimeFromHour(settings.workStartHour);

while(currentHour < settings.workEndHour) {
System.print("It is now " :: simulatedTime :: ".");
if(currentHour==settings.workStartHour) {
System.print("We arrived at the work floor. Let's start working.");
}

// TO DO: use coffee coffee machine 

System.wait(2000);
currentHour++;
simulatedTime = Date.change(simulatedTime, {"HOURS":1});
}
System.print("It is the end of the work day. Let's go home.");
}

function dateTimeFromHour(hour) {
var today = Date.info(Date.now());
return Date.of(today.year, today.monthOfYear, today.dayOfMonth, hour,0,0);
}

As you can see, the function call workOneDay() was added to the robot, enabling you to run it independently from Main.xill. This makes debugging easier.

  1. Run the project and look at the output

Add external libraries


It is time to add some external libraries. Those are robot files that are not (or as little as possible) project-specific, and often made by a collegue or someone else from the Xill user community. There is no difference in syntax from the includes that we have already done in the previous steps, but these libraries should have their own folder, not in the root or script folder. Connectors are (ideally) also an example of non-project-specific libraries, but since they have quite a special status for Xill, they usually have their own 'connector' folder, next to the 'lib' folder.

 The lib folder contains project-independent libraries.
Connectors are a special case, and should reside in a connector folder.  

So, back to the work day simulation: what do you think we need on a work day to do our job well? At least some coffee, of course, which is made by a coffee machine. This is a good example of an automatic process you want to use from someone else, instead of inventing it from scratch on your own. Therefore:

  1. Download the MakeCoffee robot from the bottom of this page
  2. Store MakeCoffee in lib/coffeemachine/ (package names should only have lowercase letters)

Your project tree should now look like this (check if it's the same in your IDE):

The last steps are:

  1. include the coffee machine library in your WorkDay robot
  2. start using the coffee machine by inserting the following code at the TO DO comment:
if(Collection.contains(settings.coffeeHours,currentHour)) {
System.print("Time to get some coffee.");
var coffee = makeCoffee(settings.userName);
System.print(coffee);
}

Now you can run your work day from the Main robot. Play around with the settings if you wish.

In case you gut stuck somewhere, check out the full project zip file below. If anything about using libraries in Xill is still not clear, feel free to click 'Not helpful' below and tell us.