Shift6 for IBM i

Shift6 Formatter: Precision Indentation for IBM i RPG Free Development

I. Executive Summary

The Shift6 Formatter is an indispensable tool for developers targeting the IBM i platform using RPG Total Free. The Shift6 Formatter ensures IBM i developers can see the full code (including the first 5 columns hidden in PDM/SEU) by applying the required 5+1 space offset: five for the hidden columns and one extra for readability when authoring RPG Free members in VS Code.

This extension completely automates this low-level, time-consuming formatting task, enabling developers to focus exclusively on business logic within Visual Studio Code.

II. Core Features and Operational Benefits

The Shift6 Formatter is engineered for efficiency and code integrity, providing tangible benefits:

A. Feature Breakdown

• Atomic Formatting Command: Full document compliance via a single keyboard shortcut or context menu click.
  • Developer Value: Accelerated Workflow: Eliminates manual line-by-line adjustment.
• Compiler Integrity Logic: The directive **FREE is meticulously preserved in column 1.
  • Developer Value: Zero Compilation Risk: Guarantees adherence to stringent IBM i formatting rules.
• Intelligent State Preservation: Indentation is only applied to unformatted lines. Correctly indented code is ignored.
  • Developer Value: Predictable Results: Maintains code stability and prevents unnecessary file changes.
• Block Indentation: Adds extra indentation per nesting level for IF/DOW/DOU/FOR/SELECT/MONITOR/PROC, including inline openers/closers.
  • Developer Value: Readable Blocks: Maintains structure without manual alignment.
• Statement Splitting: Ensures each semicolon-terminated statement is on its own line and cleans up repeated ;.
  • Developer Value: Clear Statements: Prevents dense inline code from hiding logic.
• Comment Alignment: Full-line // comments align to the following code line.
  • Developer Value: Tighter Grouping: Keeps comment blocks visually attached to the code they describe.
• Platform Compatibility: Specifically designed to reconcile VS Code's flexible formatting with PDM's rigid requirements.
  • Developer Value: Seamless Toolchain: Ensures source code is valid across both local and remote environments.
• Local & Remote Support: Works on local files (file:), unsaved editors, and IBM i remote source members (e.g., Code for IBM i ibmi: / vscode-vfs: URIs).
  • Developer Value: Remote-first Ready: Format members directly on the host without downloading to the workstation.
• Whitespace Normalization: Collapses multiple spaces between tokens to one (e.g., dcl-pi *n; -> dcl-pi *n;, if flag = 0; -> if flag = 0;) and trims spaces inside string-only parentheses ( 'error' ) -> ('error').
  • Developer Value: Cleaner Diffs: Consistent spacing without touching string contents preserves readability and minimizes churn.
• String Concatenation Control: Optional wrapping of long literals and configurable concat layout (compact, one-per-line, or fill), plus normalization of multi-line single-quote literals into explicit concatenations.
  • Developer Value: Predictable Strings: Keeps long text readable without breaking RPG string semantics.
• Continuation Wrapping & Alignment: Wraps long binary-operator expressions at a configurable column limit and aligns leading + continuation lines under the operator in the previous line.
  • Developer Value: Readable Expressions: Keeps long conditions and assignments within a sane width without manual line breaking.
• Procedure Call Parameter Alignment (optional): Aligns :-separated parameters of a call under the opening parenthesis and places the closing ) on its own aligned line.
  • Developer Value: Scannable Calls: Multi-parameter calls read like a tidy parameter list.
• Declaration Token Joining: Joins * special-value tokens in DCL-PI/DCL-PR/DCL-PROC/CTL-OPT lines (e.g., * n -> *n, * new -> *new).
  • Developer Value: Valid Keywords: Prevents broken special values after whitespace normalization.
• Exec SQL Formatting: Structured layout for exec sql blocks (DML/DDL, cursors, dynamic SQL, diagnostics, DB2-i hints, and PSM/trigger bodies), with configurable SQL keyword casing (lower/upper).
  • Developer Value: Readable SQL: Keeps complex embedded SQL readable without breaking RPG structure.
• Change-ID Column Protection (optional): Preserves programmer change identifiers / audit tags kept in the reserved left-margin columns of traditional (non-**FREE) source members, so reformatting never shifts them into the code area.
  • Developer Value: Audit-Safe: Shops that track changes in the sequence-number area keep their tags and their source keeps compiling.

B. Settings — Easy Guide

You usually don't need to change anything. Shift6 works out of the box and the defaults below match the most common IBM i conventions. Tune a setting only if you want a different layout.

How to change a setting

1. Open Settings: Ctrl+, (macOS Cmd+,).
2. Type shift6 in the search box.
3. Toggle or edit the value — it applies on the next format.

Prefer JSON? Put any of the keys below into your user settings.json or a per-project .vscode/settings.json.

1. Indentation (the basics)

2. Whitespace & cleanup

3. Line wrapping & continuations

4. String literals

5. Embedded SQL

6. Traditional source members (legacy)

shift6.changeIdColumns in detail: when set (e.g. 5), a short tag confined to those columns whose code body starts in the free-form code area (column 8+) is lifted out before formatting and stamped back afterwards, so it is never shifted into the code area and the source still compiles. While enabled, the base indent is held at column 8 (RPG's free-form code area is columns 8–80), so code never collides with the reserved columns and re-formatting is idempotent. Ordinary code (e.g. RouteID = 5;, a nested if x;) is left to normal indentation, and no **FREE directive is injected into a traditional member (an existing one is preserved). Leave it at 0 for fully free-form **FREE sources, where the whole line is code.

Copy-paste defaults

{
  // Indentation
  "shift6.spaces": 6,
  "shift6.blockIndent": 2,
  // Whitespace & cleanup
  "shift6.collapseTokenSpaces": true,
  "shift6.trimStringParentheses": true,
  "shift6.joinAsteriskTokensInDecl": true,
  // Line wrapping & continuations
  "shift6.continuationColumn": 66,
  "shift6.alignPlusContinuation": true,
  "shift6.alignProcedureCallParameters": false,
  // String literals
  "shift6.fixMultilineStringLiterals": true,
  "shift6.wrapLongStrings": false,
  "shift6.concatStyle": "compact",
  // Embedded SQL
  "shift6.execSqlKeywordCase": "lower",
  // Traditional source members (legacy)
  "shift6.changeIdColumns": 0
}

C. Git Hook (optional)

• Pre-commit type check: enable the hook with git config core.hooksPath .githooks; it runs npm run typecheck and can be skipped via SKIP_SHIFT6_PRECOMMIT=1.

III. Implementation and Usage

A. Installation

1. Acquire the extension as a .vsix package.
2. In Visual Studio Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Execute the command Extensions: Install from VSIX... and select the downloaded file.

B. Execution

Formatting can be executed immediately on any open RPG Free source file:

• Keyboard Shortcut (Recommended)
  • Windows / Linux: Shift + Alt + F
  • macOS: Shift + Option + F
• Context Menu
  • Right-click in editor -> "Format Document"
• Command Palette
  • Ctrl + Shift + P -> "Format Document"

Note on Multiple Formatters: If alternative formatters are active, use "Format Document With..." to explicitly select the Shift6 Formatter. Language Mode: Shift6 is formatter-only and does not provide syntax highlighting or language registrations. Ensure the file language is RPGLE (e.g., via the IBMi Languages extension or files.associations) so formatting is available.

IV. Developer Guidance

To ensure optimal use of this extension, developers must adhere to the following best practice:

Development Standard: When composing RPG Free source code within Visual Studio Code, always begin typing at column 1 (the start of the line). The required 6-space offset will be systematically applied by the Shift6 Formatter upon execution.

Green Screen Readability: If you need to fix code manually on the green screen (without VS Code access), the 6-space offset preserves readability because the first 5 columns are not shown there. The formatter ensures the source stays legible in that environment.

Quick Rule Checks: Run npm run test:rules for a fast sanity check of core formatting rules. Exec SQL Scope: See docs/exec-sql-scope.md for the full statement coverage target.

V. Version History and Contribution

Maintainer

• Levent Akdogan (Lakdogan) - Author, architecture, maintenance.

V.I. Change Log

• See CHANGELOG.md for the full release history.

V.II. Contributors

• [Levent Akdogan aka Lakdogan] - Principal Architect and Maintainer.

VI. Contributing & Issue Reporting

Shift6 uses structured GitHub issue templates to streamline communication and keep the development experience smooth.

• Bug Reports: Please include a reproducible code sample and environment details.
• Feature Requests: Clearly describe the feature and explain why it benefits the workflow.

You can create a new issue here:
https://github.com/lakdogan/shift6foribmi/issues/new/choose

VII. Visual Demo

The following animation shows a formatting operation performed by Shift6 within Visual Studio Code.

Direct link (if the image does not load): https://github.com/lakdogan/shift6foribmi/tree/master/assets/demo.gif?raw=true

Before -> Format Document -> After (sample)

Before:

**free
// messy demo snippet
ctl-opt dftactgrp(*no) actgrp(*new);
  dcl-s counter int(10) inz(0); dcl-s msg varchar(50);;;; // extra semicolons
dcl-proc demoProc; dcl-pi *n; end-pi;
if counter=0; dow counter<3; counter+=1; if counter=2; dsply('midpoint'); endif; enddo; else; dsply('preset'); endif;
end-proc;

After (base 6, block 2):

**free
      // messy demo snippet
      ctl-opt dftactgrp(*no) actgrp(*new);
      dcl-s counter int(10) inz(0); dcl-s msg varchar(50);
      dcl-proc demoProc;
        dcl-pi *n;
        end-pi;
        if counter = 0;
          dow counter < 3;
            counter += 1;
            if counter = 2;
              dsply('midpoint');
            endif;
          enddo;
        else;
          dsply('preset');
        endif;
      end-proc;

VIII. Partners & Collaboration

This project is supported through collaboration with
PORTOLAN Commerce Solutions GmbH.

Their support and industry involvement help promote practical IBM i development workflows and tools.