Despite its name, this "Converter" functions more like an Assistant for migrating scripts from AHKv1 to AHK v2 syntax. It's designed to automate the most tedious parts of the conversion process, but its scope is limited. While this tool may occasionally produce fully functional AHKv2 code, users should expect to make manual edits afterwards. Why not just use AI for the conversion? See Tool vs AI.

Recommended process for conversion:

1. See Usage 1 to open the Converter UI.
2. Set the Gui Conversion mode [Dynamic is recommended].
3. Press one of the three conversion buttons on the UI.
4. The tool should cover about 80%+ of the conversion process automatically.
5. Follow Post Conversion guidelines for the remaining 20% (as necessary).

Contributions to the project are also encouraged

1. Download the full repo. Then run the included Converter_UI.ahk script with AHK v2
2. Conversion Settings:
   • $\color{magenta}\text{TAB1:}$ [⚙] Save all settings from other tabs [Manual/Auto]. Auto-save is recommended.
   • $\color{magenta}\text{GUI:}$ Provides several modes for Gui/GuiControl conversion. Also allows user to define the default GuiName and Control Prefix for v2 variable names [for Orig/Simple modes].
   • $\color{magenta}\text{HK:}$ Will eventually provide hotkey filtering to improve conversion performance.
   • $\color{magenta}\text{GENERAL:}$ Provides general conversion settings.
3. Set Gui Conversion Mode: [IMPORTANT]
   • $\color{magenta}\text{ORIG:}$ Provides Gui conversion using orig method. Being replaced by updated modes below.
   • $\color{magenta}\text{SIMPLE:}$ Updated version of Orig mode. Provides similar [but improved] result. Recommended for converting simple [non-dynamic] v1 Gui syntax.
   • $\color{magenta}\text{DYNAMIC:}$ [RECOMMENDED] Provides the best Gui conversion results, with limited support for dynamic attributes [within loops, func params, multiple scopes, ClassNN names, etc]. The catch? The v2 syntax is much different than other modes, and it requires an #include file [before/AFTER conversion].
   • $\color{magenta}\text{AUTO:}$ Analyzes the v1 source code and selects the 'best mode' automatically [Simple or Dynamic].
4. Conversion Buttons:
   • $\color{magenta}\text{Convert V1 Script File:}$ Runs v2converter to select/convert a script file. See Usage 2:3 below for more details.
   • $\color{magenta}\text{Convert V1 Code Fragment:}$ Runs QuickConvertorV2 for v1 code paste. See Usage 3:3 below. Paste v1 code fragment in left pane, convert using orange arrow button [bottom/center].
   • $\color{magenta}\text{Run QC Unit Tests:}$ Runs QuickConvertorV2 in Unit-Test Mode [for project contributors] - See Usage 3:7 below. Shift-Click this button to show failed unit-tests (also).

1. Download the full repo.
2. Run Converter_UI.ahk, then choose 'Convert v1 Script file' button. Or run v2converter.ahk directly.
3. Choose your input scriptfile.ahk written for AHK v1. The converted script will be named scriptfile_newV2.ahk in the same directory. Use v2converter.ahk -h in cmd to use the CLI.
4. Look over the Visual Diff to manually inspect the changes

1. Download the full repo.
2. Run Converter_UI.ahk, then choose 'Convert v1 Code' button. Or run QuickConvertorV2.ahk directly.
3. Select a string in another program and press XButton1 to convert it, or paste it in the first Edit and press the convert button (orange arrow).
4. When the cursor is on a function in the edit field, press F1 to search the function in the documentation.
5. You can run and close the V1 and V2 code with the play buttons.
6. There are also compare buttons to see better the difference between the scripts.
7. When working on ConvertFuncs.ahk, please set TestMode on in the Gui Menu Settings, in this mode, all the confirmed tests will be checked if the result stays the same. In this mode you can also save tests easily.

This tool:

• Fast, consistent output. This tool has been pre-tested for common things that it supports.
• "Inspection comments" are added for things it does not support. It will not "invent" invalid code on the fly.

AI:

• AI may not be able to accept lengthy scripts due to token limits.
• Semantic and Context drift can occur with lengthy scripts.
• AI may provide invalid code (hallucinations), remove code, or change logic flow.
• Revision exchanges with AI can be time-consuming and may lead to compounded hallucinations.

Please understand that this tool is limited and may not produce fully functional AHKv2 code. Manual edits to the output should be expected. Use the tips below in your debugging process.

1. See Known Limitations. User-edit may be required for these and other situations.
2. The AHK Documentation should be utilized when converting code from AKHv1 to AHKv2.
3. Line comments added to the v2 output [prefixed with ; V1toV2: ], provide assistance for debugging.
4. This page provides a list of common conversion issues and potential fixes.
5. Issues reported by others may provide potential fixes.
6. If your issue is not found in the last step, feel free to create a new one
7. Finally, ask for help! On the discussions page, at AHK forums, or using your favorite AI tool.

You may still have the AutoHotkey V1 binary associated with *.ahk files, the converter is written in V2 so please either update AutoHotkey or open the repository in command prompt and run the following command: "AutoHotKey Exe\AutoHotkeyV2.exe" QuickConvertorV2.ahk

Better support for the following may be included in future updates of the tool.

• $\color{magenta}\text{Variable Name Conflicts:}$ These are very common and will require manual edits by the user.
• $\color{magenta}\text{Ternary If Expressions:}$ These lines may require manual edits by the user.
• $\color{magenta}\text{Nested labels:}$ Some labels and their references may require manual conversion to/for functions.
• $\color{magenta}\text{Trailing Commas:}$ Sometimes trailing commas can cause conversion issues.
• $\color{magenta}\text{Gui/GuiControl:}$ Recent improvements have been made, but may still require manual edits. IMPORTANT - READ the Gui Conversion Modes section above for best results.

This project is written/maintained by volunteers who donate their time/talents. If you would like to help improve this tool, there are several ways you can get involved:

• $\color{magenta}\text{Convert and Run:}$ Run your AutoHotkey v1 scripts through the tool, then execute the v2 output.
• $\color{magenta}\text{Debug:}$ If you encounter errors, attempt to debug them using the Post Conversion Guidelines.
• $\color{magenta}\text{Report:}$ If you still need help with a resolution, please submit the Issue here.

Write code to address bugs, issues, failed conversions, known limitations, or v1->v2 changes not yet covered.

When submitting code, please ensure you:

• $\color{magenta}\text{Include a Unit Test:}$ Provide at least one unit test that demonstrates your fix/feature (see details below).
• $\color{magenta}\text{Check Quality Control:}$ Click the Run QC Unit Tests button in the Converter UI. Ensure all tests pass (green checkmark) to verify your changes haven't broken existing tests.
• $\color{magenta}\text{Submit a Pull Request:}$ Once all tests pass, submit your code and new unit tests via a GitHub Pull Request.

Help expand test coverage by writing standalone unit tests.

• $\color{magenta}\text{Structure:}$ Each test requires a v1 source file and its expected v2 converted output.
• $\color{magenta}\text{Naming:}$ Use the .ah1 extension for the v1 source file, and .ah2 for the expected v2 output. Keep the code inside these files concise - just enough to demonstrate a successful conversion.
• $\color{magenta}\text{Location:}$ You can find existing examples for reference in the Tests\Test_Folder directory of the project.

• Frankie - Created the original v2 converter
• Uberi - For updates to the original
• Mergely Project - For the javascript diff library
• Aurelain's Exo - For the interface to run the javascript in an AHK gui
• Mmikeww - Support for AHKv2-alpha, and Yunit framework unit-tests to encourage participation from others.
• Dmtr99 - Support for AHKv2-beta, and many other fixes/enhancements.
• Banaanae - Contributor/Maintainer providing many fixes/enhancements.
• Andymbody - Recent contributor
• Others