Getting Started with Qilletni

Welcome to Qilletni, a Domain-Specific Language (DSL) designed for advanced playlist management, music curation, and seamless integration with Spotify and Java libraries.

Introduction

Qilletni simplifies the creation and manipulation of playlists and music data, allowing you to automate tasks, integrate with external libraries, and leverage a rich standard library. If you’d like a broader overview of Qilletni, see the Home page for more details.

Installation

Start Database

Qilletni leverages a database for caching music data for efficient lookups and conversions. The easiest way to start a caching database is via docker, using a command such as:

docker run -d \
  --name qilletni-db \
  -p 5435:5432 \
  -e POSTGRES_USER=qilletni \
  -e POSTGRES_PASSWORD=pass \
  -e POSTGRES_DB=qilletni \
  -v ~/.qilletni/cache:/var/lib/postgresql/data \
  postgres

Install Qilletni

There are two ways to use Qilletni. You may install it on your system, or use the Docker image. A normal system install is recommended (everything is put under ~/.qilletni), but a Docker install is great for trying things out.

Install on System

For a system install, first install you have at least Java 22 installed. To install Qilletni, run the following in a bash shell:

curl https://raw.githubusercontent.com/RubbaBoy/QilletniToolchain/refs/heads/master/scripts/install.sh | bash

Then, open a new shell or run source ~/.bashrc

From there, you can run qilletni --help for a list of commands.

Use with Docker

To use with Docker, run the following:

docker run --rm \
  --network host \
  -v qilletni-docker-run:/root \
  -v "/$(pwd)":/data \
  ghcr.io/rubbaboy/qilletni:latest \
  --help

Which is equivalent to running qilletni --help

To run a file, it's recommended to cd into the parent directory of the file and run it from there. For example, to run /e/qilletni/demo.ql you would do, from the /e/qilletni directory,

docker run --rm \
  --network host \
  -v qilletni-docker-run:/root \
  -v "/$(pwd)":/data \
  ghcr.io/rubbaboy/qilletni:latest \
  run demo.ql

Hello World (Your First Program)

Let’s create a simple "Hello, World!" program:

Initialize a project Create a project directory, and then run the command

qilletni init qilletni_demo/

It will ask you for a project name, and the author's name. In this case, we'll give it the name qilletni_demo. It will also ask for an optional native binding class name, which may be left blank for now.

This will create a file tree of the following structure:

qilletni_demo/
└── qilletni-src/
    ├── qilletni_demo.ql
    └── qilletni_info.yml

The file created, qilletni_demo.ql, is the start of your source code. Right now, it only contains:

qilletni_demo.ql

print("Hello, World!")

A more in-depth explanation of the project structure, and other project types, can be found in the Project Structure guide.

Run the program via command line:

qilletni run qilletni-src/qilletni_demo.ql

If everything is set up correctly, you should see:

Hello, World!

Next Steps

Now that you have a Qilletni program running, it's time to link a music service. Check out the Spotify or Last.Fm pages for more info. If you've done that, feel tree to check out the Language Introduction or some of the official packages.