Giter Site home page Giter Site logo

ahkv2_definition_rewrite's Introduction

Full Definition Upgrade and Enhancement for THQBY's AutoHotkey v2 VS Code Support Addon

This is a full update for the definition file ahk2.d.ahk and the directive/flow control/variable file ahk2.json for THQBY's AHKv2 support addon.

Contents

Why use this update

This is a full rewrite from the ground up. It adds many things to the definition that it's currently missing.
All parameters are included, all functions and methods have return values, the text of the calltips are now formatted and more aesthetically pleasing, hyperlinks are added, all options are accounted for, the structure of the definition file has been expanded and updated, autocomplete features have been added for directives and flow control, and much more.

To put things in perspective, the current definition file is ~4,200 lines long and ~185,000 characters.
The updated definition file is ~24,000 lines long and ~1,510,000 characters.
The information difference is substantial and borderline palpable.
In all fairness, a chunk of this character increase comes from the numerous hyperlinks, markdown formatting, and individual GUI controls added coupled with them now having individualized methods and properties.

Please see the In-depth Showcase section to see a large listing of the numerous changes I've implemented to these files.
There are pictures and videos for almost every topic covered.

Installation

There are multiple ways to update the definition file.

To do it automatically, use the provided Auto Updater file.
definition_updater.v2.ahk

To do it manually, start by optionally backing up your original files.
ahk2.d.ahk and ahk2.json
If you delete them and decide you want to go back to the standard definition files, they can always be redownloaded from THQBY's GitHub for the addon.

Now download the ahk2.d.ahk and ahk2.json files.
Copy them into the addon's syntaxes folder.
The default location for this folder is:

C:\Users\<YourUsername>\.vscode\extensions\thqby.vscode-autohotkey2-lsp-<HighestVersionNumber>\syntaxes

Alternatively, you can always copy and paste the text from here to the installed ones on your computer.

Auto-Updater

I've written an auto-updater so you don't have to keep updating the file.
It can be ran as its own script or can be copy and pasted into a main script, as the updater is self-contained and will auto-run.

Properties and methods of the updater:

  • Methods:

    • Start() = Starts/enables update checking
    • Stop() = Stops/disables update checking

  • Properties:

    • frequency = How often to check for updates, in hours.
      This can be a fractional number: 1.5 = 1 hr 30 min
      Default value is 4.
    • notify = If set to true, TrayTips will pop up to notify of updates or errors.
      Setting this to false will suspend all TrayTip popups.
    • update_updater = Set to false if you don't want the auto-updater updating itself.

Change Log

2024-03-20
  • Updated JSON file to include new version.
2024-03-20

  • Did a full rewrite of the updater to fix some bugs and an error in the code.

  • Reduced code size and streamlined things. (The code looks way better now.)

  • Pushed a second update because I got confirmation that encoding must be UTF-8-RAW as the file expected to be without BOM.

2024-03-19
  • Fixed some bugs in the auto-updater.
  • Added a property to enable/disable auto-updating the auto-updater.
2024-03-18 (Big Update)

  • This is one of a few big updates that will be coming to fix lots of things, continuously adding example code, and doing other improvements.

  • Added an auto-updater to the repository that should automatically keep the defintion files up-to-date.

  • ahk2.json updates:

    • Added a version key to the main json file for anyone who wants to use an auto-updater
      • Format: "version": 1.1
    • Core revisions based on updates made by THQBY.
    • ahk_criteria, such as ahk_exe, ahk_class, etc., are now recognized in any field that expects a WinTitle.
      • This includes functions like WinActivate(), WinExist(), ControlClick(), ControlGetPos(), etc.
    • THQBY has moved most built-in var descriptions to the ahk2.d.ahk file.
      • I've applied standardized tags to all of them including hyperlinks to their docs pages, formatted text, improved descriptions, and many examples of how to utilize them.
    • Hotstring options have been added to the json file but I haven't figured out exactly what they do. HotString() seems to perform the same with and without them.
    • The keyword Static now has an autocomplete for creating variables and methods
    • Per /u/Laser-Made's request, each loop type's definition includes a list of A_LoopVARTYPE variables available to that specific loop.
      • Examples:
        • Parse-loop's definition now shows it has access to A_Index and A_LoopField.
        • Registry-Loops have access to A_Index, A_LoopRegName, A_LoopRegType, A_LoopRegKey, and A_LoopRegTimeModified.

  • ahk2.d.ahk updates:

    • Added a version tag to the top of the file for anyone who wants to use an auto-updater
      • Format: ;@region v1.1
    • Per THQBY's update, most built-in variables are now included in the ahk2.d.ahk file instead of the JSON file.
    • Lots of small changes throughout the file. Grammar/captializations/corrected errors/etc.
    • The @see tags are now separated by pipes to make them more distinguishable from each other.
      • They're also stored on one line intstead of individual lines.
    • Added many more examples.
      • Started adding comments to some of the example code to assist with learning and understanding.
      • I've made it a point to not write everything the same way in an attempt to expose people to the many ways things can be structured and written.
        • Examples: Using both traditional and fat arrow functions
        • Parsing text by using both parse-loops and StrSplit()
        • Writing if-statements with curly braces (code blocks) and without by utilizing commas (multi-statement operator)
        • Putting commands on the same line as Else or Try to illustrate the different ways to use them
      • Most examples are written in a way that they can be copy+pasted into a blank file and ran.
        • Some examples are not meant to be ran, but instead illustrate the the multiple ways of using them, such as Click().

  • ahk2.d.ahk specifics:

    • Any class:

      • Improved description.

    • Any.GetMethod():

      • Updated return value.

    • Any.HasBas():

      • Updated description and corrected return type from bool to integer.

    • Any.HasMethod():

      • Rewrote to be more understandable and clearly worded.
      • Added new examples.

    • Any.HasProp():

      • Updated description.
      • Added example.

    • __Init():

      • Added a description as it lacked one.

    • __Delete():

      • Added to the definition file and should appear in autocomplete now.
      • Given a description.

    • Object class:

      • Updated description.
      • Added examples.

    • Object.Clone():

      • Updated description.
      • Improved example code.

    • Object.DefineProp():

      • Updated description.
      • Added more example code.

    • Object.DeleteProp():

      • Updated description.
      • Added better example code.

    • Object.GetOwnPropDesc():

      • Updated description.
      • Added better example code.

    • Object.OwnProps():

      • Updated description.
      • Added better example code.

    • Array class:

      • Updated description.

    • Array.__Item:

      • Updated description.
      • Corrected an error.
      • Updated and improved examples.

    • Array.Default:

    • Array.__Item:

      • Uprdated definition to be more clear and inclusive.

    • Array.Clone():

      • Updated definition to be more clear about shallow copies.
      • Improved example code.

    • Array.Delete():

      • Corrected an error in its description.
      • Added error.
      • Improved example.

    • Array.Get():

      • Clarified return value.
      • Updated example to show more variation and usage.

    • Array.Has():

      • Clarified when it returns true.
      • Improved example.

    • Array.InsertAt():

      • Rewrote definition to clarify multiple things.
      • Corrected an error in the description.
      • Improved existing code and added more examples for clairfication.
      • Updated AdditionalValues parameter to be variadic.

    • Array.Pop():

      • Improved definition.

    • Array.Push():

      • Rewrote definiton to be more accurate and informative.
      • Added more examples.

    • Array.RemoveAt():

      • Corrected erroneous information in the description.
      • Improved overall description.
      • Improved example code.

    • Array.__New():

      • Updated definition to clarify __New() should not be called directly

    • Array.__Enum():

      • Updated enumerator's definition.
      • Updated and added to examples.

    • Buffer class:

      • Updated definition.
      • Corrected default values from Unset to 0.

    • Buffer.__New():

      • Updated definition.
      • Included default values.

    • ClipboardAll class:

      • Updated definition.
      • Added example code.

    • ClipboardAll.Ptr:

      • Updated definition.
        • Added @throw error

    • ClipboardAll.Call():

      • Updated definition to be more clear.
      • Included information I missed before.

    • Class():

      • Improved and expanded the definition.

    • Class.Prototype:

      • Improved definition
      • Changed return type from Prototype to Object, as this is how the addon needs to see it
        • There is no "prototype object" in AHK. Just an object we refer to as the "prototype".

    • Error class:

      • Did a full update to all error sub-types and descriptions

    • Error.Stack:

      • Rewrote definition to be easier to understand.
      • Improved what the output structure looks like.

    • Error():

      • Example code was improved.

    • All the error subtypes:

      • Updated definitions to be more clear.
      • Provided type-specific properties and parameters.
        • Such as Message and Extra info for TypeError and ValueError

    • OSError Class:

      • Added missing number property and definition (Thanks THQBY)
      • Updated definition.
      • Changed the first parameter to ErrorNumber and assigned the correct default value to it.

    • File class:

      • Updated definitions for almost all properties and methods.
      • Included number range and byte sizes with each type of Read()/Write() method.
      • Ensured each method now has some form of example.

    • Func.Bind():

      • Improved description.
      • Added more examples.

    • Func.IsByRef():

      • Improved description.
      • Added more examples.

    • Func.IsOptional():

      • Improved description.
      • Added more examples.

    • BoundFunc Class:

      • Updated description.
      • Added examples for both types of boundfuncs.

    • Enumerator Class:

      • Added new examples to show enumerator structure and use.
      • Included examples for making any object enumerable with a custom enumerator.

    • Closure Class:

      • Updated definition and added better example code that differntiates between closures and static nested functions.

    • Gui Class:

      • New example code showing the many fascets of making a GUI.

    • Gui.Control Class:

      • Added a description and properties to class definition.
      • Updated the description of almost all properties and methods belonging to this class.
      • Added example code to all properties and methods of this class.

    • ComCall():

      • Made function call variadic as multiple type/args can be passed. (Thanks /u/bleurgh96230)
      • Changed return type form an String | Integer to Primitive.

    • DateDiff():

      • Updated description to state required format.

    • Exp():

      • Fixed return value type from String to Number.

    • NumGet():

      • Completely overhauled this function.
      • Corrected a syntax error.
      • Made things more understandable
      • Created a new "data type" table, including byte/bit information.
      • Added multiple examples.

    • NumPut():

      • Completely overhauled this function.
      • Corrected a syntax error.
      • Made things more understandable
      • Created a new "data type" table, including byte/bit information.
      • Added multiple examples.
      • Made function variadic as to not cause an error when setting multiple numbers.
        • Due to limitations, the variadic parameter is the offset, which is incorrect.
        • Currently, there is no way to tell the addon that the first 2 parameters can be repeated any number of times.
        • It's a bandaid until THQBY comes up with a more elegant solution to this.

    • ObjBindMethod():

      • Made function variadic to pre

    • PixelGetColor:

      • Added example code.

    • SendMessage():

      • Fixed doc URL.

    • SendMode():

      • Fixed doc URL.

    • WinGetTransparent():

      • Fixed @see links
2024-01-10
  • Updated a lot of the verbiage in the Format() tag to make it more understandable.
  • Removed unused tags left over from template pasting.
  • Adjusted formatting of @throw tags.
  • Added missing "Related" links to the @see tag for OnError().
2024-01-09
  • Rewrote and restructured the entire ReadMe file for this GitHub page.
  • Added a plethora of pictures and videos to the showcase section.
  • Fixed InputBox() Result and Value information, as they were accidentally swapped.
  • Added more examples to the code.
  • Multiple formatting fixes.
  • Fixed ObjRelease() not having the Ptr param in the function definition. (Thanks camkidd)
  • Fixed a description error in Array's Get() and Has() methods.
2024-01-08
  • Fixed a typo in the autocomplete for Loop Count that included an invalid comma between the two. (Thanks /u/Hukepi)
    • This shows how ingrained some v1 syntax is in me.
  • Fixed FileSelect() root directory and title parameter default.
2023-12-24
  • Fixed a bunch of typos and errors.
  • Fixed functions/methods that should have had variadic parameters.
  • Added String, Integer, Number, and Float class Call() functions and calltips.
  • Added ComObjArray, ComObject, and ComValue class Call() functions and calltips.
  • Cleaned up a lot of tags to try and make them more compact.
  • Updated ahk2.json with new version for #Requires.
2023-12-18
  • All functions, classes, methods, and properties are done.
  • Added ahk2.json file. This includes many updates to directives and flow control statements.
  • Some examples can be seen here.

In-depth Showcase

  • All classes, functions, methods, and properties now have complete information provided for them.

  • I've applied a set standard of JSDoc tags to all these items.

  • I've applied Markdown formatting to each item so the displayed popup (called a widget) has formatted text.

  • ALL methods and functions now have a return value.

  • I've updated and rewritten some of the descriptions, parameters, etc. to be more clear and understandable.

    • This is a big one for me. It's important that people understand exactly how something works.
    • I strive to use proper terminology, but I also choose my words carefully, trying to never be ambiguous.

  • Added my own custom "things" to the script

    • Examples:
      • My own personal RegEx cheat sheets that I created for this file.
      • Custom @example tags (mentioned below).
      • Other stuff.

  • Hyperlinks (everything in blue text) have been added. Plenty of them.

  • The ahk2.json file has also been updated with a lot of new menus and auto-complete features.

  • Custom examples galore.

    • I've written an @example tag for many of the functions and methods (though only about 1/2 of them are done)
      • Doing this exposes people to the different ways something can be used or even different ways to write code in general.
      • I'll be continuing to add more over time.
      • Some examples show the different configurations or ways to use a command.
        • Click() would be a good example of this.
      • A lot of examples show a functioning piece of code that demonstrates how to use one or more items.
    • Code in the @example tag is properly syntax highlighted. How very meta!
    • Text from the calltips can be copied and pasted directly into the editor.
      • This can eliminate a lot of typing, especially when working with GUIs.

  • All GUI controls are now defined as their own class.

    • Blanket methods and properties for GUI Controls have been removed and replaced with individual classes.
    • This ensures each control object now registers as its own control type.
      • Before, a button, checkbox, and edit field would all show as a Gui.Control whereas now they show as Gui.Button, Gui.Checkbox, and Gui.Edit respectively.
    • Each control now only contains information pertaining to that specific control.
      • OnEvent() for example:
        • Before, OnEvent() listed all possible event types for all control types, regardless if they can be used by the control type.
        • Now, each method and property that contains unique information has its own calltip.
        • A Button control's OnEvent() includes "Click" but not "Change" because buttons don't have change events.
        • Conversley, an Edit control's OnEvent() includes "Change" but not "Click", making writing code easier.
      • Value for example:
        • A Checkbox control's value explains it stores the state of the checkbox and can be a 1, 0, or -1
        • A DateTime control's value sets/gets the current date-time stamp in YYYYMMDDHH24MISS format.
          • Don't know what that format means? Good thing it's a hyperlink to the docs page explaining it!

  • @throw tags have been included to show what causes certain errors.

    • This should help when troubleshooting or writing your own error handling.

  • An InputBox object class has been added to the definition file and associated with the return value of InputBox().

    • This ensures that when working with any object returned by InputBox(), it will provide the Value and Result properties to the user in the autocomplete menu.
    • This also allows those specific properties to be defined like all other properties.

  • I've tried to ensure every possible option available for each parameter and property (within reason) is included.

    • For some functions and methods, this can cause some calltips to be long. For example:
    • Note that cards with elongated parameters aren't too much of a problem b/c when typing out parameters, the addon puts the current param up top.
      • This prevents a huge parameter section from eclipsing another one while you're typing out each param.

  • There are other things I'm sure I'm forgetting.

Different Widget Types

It should pointed out that there are multiple types of widgets that popup.

  • If you hover a function/method/class/property, the hover widget shows up.
    • It's resizeable, has the best header syntax highlighting out of all the widgets, and shows all calltip information, in order
  • If you start typing a new name, the autocomplete widget shows up.
    • This window is also resizeable.
    • This view can be expanded or hidden
      • Pressing Ctrl+Space brings up autocomplete as well as toggles the widget window.
  • If you start typing the parameters of a method of function, the parameter widget shows up.
    • This widget is unique in the fact that it can't be resized (and I don't know why b/c all the other ones are resizeable).
    • It also puts the current parameter at the top of the card, preventing the need to scroll to get to the info.
    • Pressing Ctrl+Shift+Space brings up the parmeter widget whenever you're between the parentheses of a function or method.

Will THQBY Implement This?

It seems unlikely.
I showed the updated files to him and he immediately pass on them.
I'm not sure he even tried them...
I cannot convey how disappointed I am thinking about the hours I invested into this thinking it'd be picked up immediately.
Especially considering the current incomplete and lacking state the definition file is in.
I don't know. Maybe he'll get curious about it later, try it, and change his mind.
Until then, I fully intend on maintaining these files and keeping them up to date.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.