Free Bidi Editor

Free Bidi VS Code Extension Overview The Free Bidi extension for Visual Studio Code simplifies working with COBOL files containing RTL language text. It automatically converts files from a configurable RTL encoding (default: ISO-8859-8) to UTF-8, adding Left-to-Right Override (LRO, \u202D) markers before RTL language text to ensure proper display. The converted files are stored in a .freebidi directory and opened in VS Code with UTF-8 encoding. When typing new RTL language characters in these converted files, the extension automatically inserts LRO markers to maintain consistent text direction. Features

Automatic Conversion: Converts COBOLIT files (.cob, .inc, .cpy, .pco) with RTL language text from a configurable RTL encoding (default: ISO-8859-8) to UTF-8 with LRO markers. Readonly Virtual View: When the extension cannot create a local .freebidi directory because of filesystem permissions, it opens a readonly virtual document in VS Code instead of creating a fallback file on disk. Smart Tab Management: When opening a source file that has an existing .freebidi version, automatically closes the original file tab and opens only the freebidi version. Line Number Preservation: When opening a file with a specific line number (e.g., src/file.cob:100), the freebidi version opens at the same line position. Temporary Files: Saves converted files in a .freebidi directory, which are automatically deleted when their tabs are closed. Real-Time RTL language Support: Automatically inserts LRO markers (\u202D) before new RTL language characters typed in .freebidi files. Encoding Enforcement: Ensures .freebidi files are opened with UTF-8 encoding, regardless of VS Code?s files.encoding or files.autoGuessEncoding settings. Non-Recursive: Prevents recursive file opening for .freebidi files. Save Back: Updates the original file using the configured RTL encoding (default: ISO-8859-8) when saving changes to the .freebidi file, removing LRO markers. Find RTL Text: Searches FreeBidi-managed documents using Hebrew text entered in normal readable RTL order, while matching the reversed visual-order sequence stored in the generated file. COBOL Outline: Provides the Free Bidi Editor outline for file-backed COBOLIT files, including regular COBOL files and generated .freebidi files. COBOL Go to Definition: Supports native VS Code Go to Definition for COBOLIT CALL program references and COPY copybook references, searching the workspace and optional configured external roots.

Installation

Install the Extension:

Open VS Code. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on macOS). Search for Free Bidi by NLTCInc. Click Install.

Set Up Dependencies:

Ensure Node.js is installed for development (optional). Run npm install in the extension directory (~/free-bidi) to install dependencies like iconv-lite.

Configure VS Code Settings:

Open VS Code settings (Ctrl+, or Cmd+, on macOS). Add the following to settings.json for the best experience:{ "editor.renderControlCharacters": false, "editor.unicodeHighlight.invisibleCharacters": false, "freeBidi.rtlEncoding": "ISO-8859-8", "freeBidi.outline": true, "freeBidi.enableRtlSearch": true, "freeBidi.normalizeRtlWhileTyping": true, "freeBidi.definitionSearchRoots": [], "freeBidi.definitionSearchRootPrefixes": {} }

The settings "editor.renderControlCharacters": false and "editor.unicodeHighlight.invisibleCharacters": false prevent visual glyphs for LRO markers and other invisible Unicode characters, ensuring a clean editing experience.

freeBidi.outline enables the Free Bidi Editor outline provider for COBOLIT files. Set it to false to disable the Free Bidi Editor outline and use another COBOL outline provider instead.

freeBidi.enableRtlSearch enables the FreeBidi RTL search commands. It is enabled by default.

freeBidi.normalizeRtlWhileTyping normalizes a newly typed RTL run as soon as a following non-RTL character is typed in a writable .freebidi file. It is enabled by default.

freeBidi.definitionSearchRoots adds external filesystem roots for Go to Definition lookup. Workspace files are searched first. Use this when COBOL programs or copybooks live outside the opened VS Code workspace. Simple wildcard directory segments are supported, for example:

{
    "freeBidi.definitionSearchRoots": [
        "/path/to/cobol/project/src",
        "/path/to/cobol/project/pco",
        "/path/to/cobol/project/cpy",
        "/path/to/cobol/project/inc"
    ]
}

freeBidi.definitionSearchRootPrefixes narrows Go to Definition lookup by COBOL program or copybook name prefix. When a prefix matches, only that prefix's roots are searched; otherwise lookup falls back to freeBidi.definitionSearchRoots. If more than one prefix matches, the longest prefix wins.

{
    "freeBidi.definitionSearchRootPrefixes": {
        "APP_": [
            "/path/to/cobol/app/cpy",
            "/path/to/cobol/app/pco"
        ],
        "UTIL_": [
            "/path/to/cobol/shared/inc"
        ]
    }
}

Git Recommendation

If your project uses Git, add the temporary .freebidi/ directory to .gitignore so converted working files are not tracked:

.freebidi/

Usage

Open a COBOL File:

Open a COBOLIT file (.cob, .inc, .cpy, or .pco) containing RTL language text (e.g., /path/to/project/src/example.cob). Set the language mode to COBOLIT (Ctrl+Shift+P ? ?Change Language Mode? ? COBOLIT).

Automatic Conversion:

The extension uses freeBidi.rtlEncoding from settings.json (default: ISO-8859-8) and creates a UTF-8 version with LRO markers in the .freebidi directory (e.g., /path/to/project/src/.freebidi/example.cob). If that directory cannot be created because the source tree is readonly, the extension opens a readonly virtual version of the converted content directly in VS Code instead of creating a temporary fallback file. The converted file opens automatically in VS Code with UTF-8 encoding.

Edit RTL language Text:

When typing RTL language characters in the .freebidi file, the extension normalizes the active RTL run after the next non-RTL character is typed, adding the needed LRO/PDF controls to maintain text direction. Line-leave and save-time normalization remain as a fallback.

Save Changes:

Saving the .freebidi file updates the original file, removing LRO markers and encoding it back using freeBidi.rtlEncoding (default: ISO-8859-8). Readonly virtual documents opened because the source tree is not writable cannot be edited or saved back to the original source location.

Close File:

Closing a writable .freebidi file deletes it to keep your workspace clean. Readonly virtual documents do not create temporary fallback files on disk.

Manual Conversion

Run the command Free Bidi Editor: Convert File (Ctrl+Shift+P ? type ?Free Bidi?) to manually convert the active COBOLIT file (.cob, .inc, .cpy, or .pco).

Find RTL Text

Use FreeBidi: Find RTL Text when the visible Hebrew text is readable in the editor but the underlying generated .freebidi text is stored in reversed visual order.

1. Open a writable .freebidi document or a readonly FreeBidi virtual document.
2. Run FreeBidi: Find RTL Text from the Command Palette or the editor context menu.
3. Enter the Hebrew text in normal readable RTL order.
4. Use FreeBidi: Find Next RTL Text and FreeBidi: Find Previous RTL Text to move through the current matches.

The command performs a literal search in the active document only. It converts the search value internally, highlights matches with normal VS Code selection/decorations, and does not modify the source file, generated .freebidi file, encoding, line endings, or directional control characters.

Fix Pasted RTL Text

If Hebrew or another RTL language was pasted into VS Code and appears reversed, use the internal command:

1. Open the converted .freebidi file, or convert the COBOL file first with Free Bidi Editor: Convert File.
2. Select the pasted lines, or leave no selection to fix the whole current document.
3. Run Free Bidi Editor: Fix Pasted RTL Text from the Command Palette.
4. Save the .freebidi file to write the corrected content back to the original file encoding.

COBOL Go to Definition

Use VS Code's native Go to Definition actions on COBOLIT CALL and COPY references:

1. Place the cursor on a called program name, such as CALL 'APP_UPDATE_CUSTOMER', or on a copybook name, such as COPY "COMMON_MESSAGE.INC".
2. Run Go to Definition (F12), Peek Definition (Alt+F12), Ctrl/Cmd+Click, or right-click and choose Go to Definition.
3. The extension searches the workspace first, then any roots configured for a matching freeBidi.definitionSearchRootPrefixes prefix, or freeBidi.definitionSearchRoots when no prefix matches.

For called programs without an extension, the lookup lowercases the called routine name and tries the configured freeBidi.callDefinitionExtensions. By default it searches .cob, .cbl, .cobol, .pco, and .inc. To include mixed-language routines, configure the setting with only the extensions you want searched, such as .c and .cpp.

For copybooks without an extension, lookup remains unchanged and tries .cpy, .inc, and .coy. Generated .freebidi folders are excluded from lookup results.

Troubleshooting

File Not Converting:

Ensure the file has the COBOLIT language ID. Check the Output panel (free-bidi) for error messages. Verify the file contains RTL language characters.

Encoding Issues:

Confirm the .freebidi file opens with UTF-8 (check the status bar). Run the following to inspect the file:xxd -l 3 /path/to/project/src/.freebidi/example.cob

Expect: 00000000: efbb bf ... (UTF-8 BOM).

LRO Not Inserted:

Ensure you're editing the .freebidi file, not the original .cob file. Check the Output panel for Inserted LRO before RTL language text....

Extension Not Activating:

Check the Output panel for Free Bidi extension activated on platform: .... Disable conflicting extensions like redhat.java (see settings above). Clear workspace storage:rm -rf ~/Library/Application\ Support/Code/User/workspaceStorage/9eee23559e7c9649f178964da0909a5c

Debugging:

Open the extension in VS Code (~/free-bidi). Set breakpoints in src/extension.ts. Run ?Run Extension? in the Debug view (F5). Share Debug Console and Output panel logs if issues persist.

Development

Clone the Repository: git clone https://github.com/Nautilus009/free-bidi.git ~/free-bidi

Install Dependencies: cd ~/free-bidi npm install

Compile: npm run compile

Test: npm test

Publish: npx vsce login NLTCInc npx vsce publish

Contact For issues, feature requests, or contributions, visit the GitHub repository or file an issue.