Qi Language VSCode Extension

Complete language support for Qi - A Lisp that flows.

Features

Syntax Highlighting

• Keywords: def, defn, defn-, fn, let, if, do, when, while, until, while-some, until-error, each, match, try, defer, loop, recur, use, export, module
• Keyword Literals: :keyword syntax
• Operators:
  • Pipeline operators: |>, ||>, |>?, ~>
  • Match arrows: ->, =>
  • Spread operator: ...
  • Arithmetic: +, -, *, /, %, =, !=, <, >, <=, >=
• Strings:
  • Regular strings: "hello"
  • Triple-quoted strings: """multi-line"""
  • F-strings: f"Hello {name}"
  • Triple-quoted f-strings: f"""multi-line with {interpolation}"""
• Comments: Line comments with ;
• Numbers: Integer and floating-point literals
• Constants: nil, true, false
• Predicates: nil?, list?, map?, string?, integer?, etc.
• Built-in Functions: atom, deref, swap!, reset!, print, println, error, tap, etc.
• Module System: Highlighting for str/, list/, map/, go/, io/, http/, db/, kvs/, etc.

Editor Features

• Auto-closing pairs: (), [], {}, ""
• Bracket matching
• Comment toggling (; line comments)

Commands

• Run Qi File (Ctrl+F5 / Cmd+F5) - Execute current Qi file
• Start Qi REPL (Ctrl+Shift+R / Cmd+Shift+R) - Start interactive REPL
• Debug Qi File (F5) - Debug current file with breakpoints and step execution
• Show Documentation - Open Qi documentation

Debugging

The extension provides full debugging support via the Debug Adapter Protocol (DAP):

• Breakpoints: Set breakpoints by clicking on the gutter
• Step Execution: Step over, step into, step out of functions
• Call Stack: View the current call stack
• Variables: Inspect variables and scopes
• Continue/Pause: Control program execution
• Standard Input: Send input to programs using .stdin command

Basic Debugging

1. Open a .qi file
2. Set breakpoints by clicking on the line numbers
3. Press F5 or click "Debug Qi File" in the command palette
4. Use the debug toolbar to step through your code

Sending Input to Programs

When debugging programs that use io/stdin-line or io/stdin-lines, you can send input via the Debug Console:

Single line input:

.stdin Hello, World!

Multiple lines (use \n for newlines):

.stdin Line 1\nLine 2\nLine 3

Tab-separated values:

.stdin Column1\tColumn2\tColumn3

Example program:

;; test-stdin.qi
(println "Enter your name:")
(def name (io/stdin-line))
(println f"Hello, {name}!")

1. Set a breakpoint on line 2
2. Start debugging with F5
3. Continue to the breakpoint
4. Open Debug Console
5. Type .stdin Alice and press Enter
6. Continue execution - output will show "Hello, Alice!"

Note: Make sure the Qi executable is built with the dap-server feature:

cargo build --features dap-server --release

Installation

From Source

1. Clone this repository
2. Copy the qi-vscode folder to your VSCode extensions directory:
   • Windows: %USERPROFILE%\.vscode\extensions
   • macOS: ~/.vscode/extensions
   • Linux: ~/.vscode/extensions
3. Reload VSCode

Development

1. Install dependencies:

   cd qi-vscode
   npm install

2. Compile TypeScript:

   npm run compile

3. Open this folder in VSCode
4. Press F5 to launch Extension Development Host
5. Open a .qi file to test the extension

Configuration

The extension can be configured via VSCode settings:

{
  "qi.executablePath": "qi",
  "qi.enableLinting": true,
  "qi.repl.autoStart": false
}

Settings

• qi.executablePath (string, default: "qi") - Path to the Qi executable. If qi is in your PATH, you can use "qi". Otherwise, specify the full path.
• qi.enableLinting (boolean, default: true) - Enable linting (planned).
• qi.repl.autoStart (boolean, default: false) - Automatically start REPL when opening Qi files.

Language Overview

Qi is a modern Lisp dialect focused on flow-oriented programming with:

• Pipeline operators for data transformation
• Pattern matching with destructuring
• Async/concurrent programming primitives
• Module system with public/private exports
• Rich standard library (HTTP, DB, JSON, CSV, etc.)

Examples

;; Pipeline processing
(use str :as s)
(use list :only [take filter])

("hello world"
  |> s/upper
  |> (s/split " ")
  |> (filter (fn [w] (> (s/length w) 4)))
  |> first)
;=> "HELLO"

;; F-strings with interpolation
(def name "Alice")
(def age 30)
(println f"Hello, {name}! You are {age} years old.")
;; => Hello, Alice! You are 30 years old.

;; Pattern matching
(match [1 2 3]
  [] -> "empty"
  [x] -> f"single: {x}"
  [x y ...rest] -> f"x={x}, y={y}, rest={rest}")
;=> "x=1, y=2, rest=(3)"

;; Module system
(defn- private-helper []
  "Only visible in this module")

(defn public-api [data]
  "Public API function"
  (private-helper))

(export [public-api])

Links

• Qi Language Repository
• Language Specification

バージョン管理

このVSCode拡張機能のバージョンは、qi-langのバージョンと同期しています。

• 現在のバージョン: 0.1.0
• 対応するqi-langバージョン: 0.1.0
• バージョン管理方式: 手動同期

バージョン更新手順

qi-langのバージョンを更新する際は、以下の手順でこの拡張機能のバージョンも更新してください：

1. package.jsonのversionフィールドを更新
2. CHANGELOG.mdに変更内容を記録
3. 新しいバージョンのタグを作成してプッシュ

例：

# package.jsonのバージョンを更新
vim package.json  # "version": "0.2.0"に変更

# CHANGELOGを更新
vim CHANGELOG.md  # 変更内容を追記

# コミットしてタグを作成
git add package.json CHANGELOG.md
git commit -m "バージョン0.2.0にアップデート"
git tag v0.2.0
git push origin main --tags

詳細な変更履歴はCHANGELOG.mdを参照してください。

License

MIT OR Apache-2.0