Setting up a development environment for JSONiq

While there are online sandboxes available for you to run JSONiq queries (like here), some people prefer having a local development environment. These instructions will guide you through the process of setting up a local development environment for JSONiq using Zorba (a query processor for JSONiq) and Atom (an extensible text editor).


UPDATE: Please scroll down to the Troubleshooting section of this page for instructions on how to resolve the following error, "The program can't start because libiconv.dll is missing from your computer. Try reinstalling the program to fix this problem."

Before we begin

You will need the following things to continue:

  • A modern Windows machine
    • Free virtual machines with Windows 7 are available directly from Microsoft.
      Please be aware that these virtual machines expire after certain number of days and any data not saved after the expiration date will be lost.
  • Zorba query processor
  • Atom text editor
    • Download Atom for Windows 7/8/10

Step 1 – Install Zorba

After you download the Zorba 3.0 installer, start the installation process by opening the installer file (i.e. double click on it). Click through the installation screens, using the settings shown in the screenshots below:

You can test the Zorba installation by opening up a Windows command prompt and entering the following command:

zorba -q 1+1

If Zorba is correctly installed, running this command should return the following output: 

<?xml version="1.0" encoding="UTF-8"?>
2

Step 2 – Install Atom

Once you have finished installing Zorba, install the Atom text editor. It should automatically launch the editor when it finishes installing.

Step 3 – Install Atom Packages for JSONiq

Next, we need to install some additional Atom packages to support JSONiq development. This is done using the Atom Package Manager (apm). Open up a Windows command prompt, and enter the following commands:

Make sure you that you have an active internet connection before proceeding. 

apm install linter
apm install language-jsoniq
apm install atom-runner

Step 4 – Configure Atom Runner

At this point, if everything succeeded, you should be able to use Atom to write JSONiq queries and use the Zorba command prompt to execute them. It would be nice, however, to be able to execute JSONiq queries from within Atom. The Atom Runner package that we installed in the previous step provides that capability, but first it needs to be configured so that it knows how to run JSONiq queries.

To configure Atom Runner for JSONiq, open up the Atom configuration file (config.cson) and append the following text (space-sensitive): 

"runner":
  "extensions":
    "jq": "zorba"

The config.cson file is usually located in a hidden directory called ".atom" under the current user's directory, for example: C:\Users\<username>\.atom\config.cson

If Atom Runner does not appear to work, it is likely that you have a problem with spaces in the configuration file. Ensure the text in config.cson is space-aligned exactly as shown above.

Step 5 – Test and Finish

Congratulations, you should now have a fully functional JSONiq development environment installed on your local machine. Try testing out your new environment by opening up Atom and creating a new JSONiq file with a ".jq" extension. Try entering the following JSONiq code: 

jsoniq version "1.0";
1 + 1

Press ALT+R to execute the query. A new Atom Runner tab should open with the query results, as shown below:

Troubleshooting

  • The program can't start because libiconv.dll is missing from your computer. Try reinstalling the program to fix this problem.

    It appears that the current version of the Zorba installer does not include the libiconv.dll dependency, however it is in fact available as iconv.dll.

    To resolve this issue, simply copy AND rename the C:\Program Files (x86)\Zorba XQuery Processor 3.0.0\bin\iconv.dll file to C:\Program Files (x86)\Zorba XQuery Processor 3.0.0\bin\libiconv.dll


Adapted instructions for Linux and Macintosh platforms by Mohan Krishnamoorthy .

Before we begin

You will need the following things to continue:

Step 1 – Install Zorba

Install Zorba by executing the following commands on the terminal:

sudo add-apt-repository ppa:juan457/zorba
sudo apt-get update
sudo apt-get install zorba

You can test the Zorba installation by opening up a terminal and entering the following command: 

zorba -q 1+1

If Zorba is correctly installed, running this command should return the following output: 

<?xml version="1.0" encoding="UTF-8"?>
2

Step 2 – Install Atom

Once you have finished installing Zorba, install the Atom text editor. Since there is a clash of the “apm” command on some linux systems, first rename the existing apm command. If no such command exists, then directly move on to installing Atom. On the terminal, enter the following commands:

cd /usr/bin/
sudo mv apm apmd

Now install Atom text editor by double clicking on the .deb or .rpm file.

Step 3 – Install Atom Packages for JSONiq

Next, we need to install some additional Atom packages to support JSONiq development. This is done using the Atom Package Manager (apm). On the terminal, enter the following commands:

Make sure you that you have an active internet connection before proceeding.
apm install linter
apm install language-jsoniq
apm install atom-runner

Step 4 – Configure Atom Runner

At this point, if everything succeeded, you should be able to use Atom to write JSONiq queries and use the Zorba command prompt to execute them. It would be nice, however, to be able to execute JSONiq queries from within Atom. The Atom Runner package that we installed in the previous step provides that capability, but first it needs to be configured so that it knows how to run JSONiq queries.

To configure Atom Runner for JSONiq, open up the Atom configuration file (config.cson) and append the following text (space-sensitive): 

"runner":
  "extensions":
    "jq": "zorba"

The config.cson file is usually located in a hidden directory called ".atom" under the current user's directory, for example: /home/<username>/.atom/config.cson

If Atom Runner does not appear to work, it is likely that you have a problem with spaces in the configuration file. Ensure the text in config.cson is space-aligned exactly as shown above.

Step 5 – Test and Finish

Congratulations, you should now have a fully functional JSONiq development environment installed on your local machine. Try testing out your new environment by opening up Atom and creating a new JSONiq file with a ".jq" extension. Try entering the following JSONiq code: 

jsoniq version "1.0";
1 + 1

Press ALT+R to execute the query. A new Atom Runner tab should open with the query results, as shown below:



Adapted instructions for Linux and Macintosh platforms by Mohan Krishnamoorthy .

Before we begin

You will need the following things to continue:

Step 0 – Install Prerequisites

  1. Install Xcode and the Xcode Command Line Tools
  2. Agree to Xcode license in Terminal: 
    sudo xcodebuild -license
  3. Install MacPorts depending on the OS X version you are using from here

Step 1 – Install Zorba

Then install Zorba by opening the installer file (i.e. double click on it). Click through the installation screens, using the settings shown in the screenshots below:

You can test the Zorba installation by opening up a terminal and entering the following command: 

zorba -q 1+1

If Zorba is correctly installed, running this command should return the following output: 

<?xml version="1.0" encoding="UTF-8"?>
2

Step 2 – Install Atom

Once you have finished installing Zorba, install the Atom text editor, i.e., unzip the package and move Atom to Applications.

Step 3 – Install Atom Packages for JSONiq

Next, we need to install some additional Atom packages to support JSONiq development. This is done using the Atom Package Manager (apm). On the terminal, enter the following commands:

Make sure you that you have an active internet connection before proceeding.
apm install linter
apm install language-jsoniq
apm install atom-runner

Step 4 – Configure Atom Runner

At this point, if everything succeeded, you should be able to use Atom to write JSONiq queries and use the Zorba command prompt to execute them. It would be nice, however, to be able to execute JSONiq queries from within Atom. The Atom Runner package that we installed in the previous step provides that capability, but first it needs to be configured so that it knows how to run JSONiq queries.

To configure Atom Runner for JSONiq, open up the Atom configuration file (config.cson) and append the following text (space-sensitive): 

"runner":
  "extensions":
    "jq": "zorba"

The config.cson file is usually located in a hidden directory called ".atom" under the current user's directory, for example: /Users/<username>/.atom/config.cson

If Atom Runner does not appear to work, it is likely that you have a problem with spaces in the configuration file. Ensure the text in config.cson is space-aligned exactly as shown above.

Step 5 – Test and Finish

Congratulations, you should now have a fully functional JSONiq development environment installed on your local machine. Try testing out your new environment by opening up Atom and creating a new JSONiq file with a ".jq" extension. Try entering the following JSONiq code: 

jsoniq version "1.0";
1 + 1

Press Ctrl+R to execute the query. A new Atom Runner tab should open with the query results, as shown below: