Plugin.txt

:Plugin: are *.py files written in Python, which define & run commands
    ST3 use Python 3 language
    *.py files are located in:
        Packages\*.sublime-package (Default Packages)
        \Data\Installed Packages\*.sublime-package (Installed Packages)
        Packages\<pkg_name>\*.py
        Packages\User\*.py
        There's no priority difference between these location (ST loads all *.py and execute them equally)

Write a .py plugin
    Example:
        import sublime, sublime_plugin                      # import collections of Methods (see Method below)
        class ExampleCommand(sublime_plugin.TextCommand):   # initiate built-in TextCommand Class (collection of methods). Resolved command name = "example"
            def run(self, edit):                            # define action to 'run' when trigger this command
                self.view.insert(edit, 0, "Hello, World!")  # method insert(edit, point, string) in View Class [[#Method:]]
                sublime.message_dialog("string inserted")   # Easiest way to view info
                sublime.status_message("string inserted")
    Command name
        Filename of .py file does not matter
        To run a plugin, you refer to the name name defined inside that .py
        Example: class NewExampleCommand(sublime_plugin.TextCommand)  →  the raw name is NewExampleCommand
        However, ST will resolve by:
            Trim-off the suffix "Command"
            Convert CamelCase to lowercase & underscore, i.e: CamelCase → camel_case
            So, the final name is "new_example"
            to run this command via console: Ctrl+`  →  window.run_command("new_example")
    Module-Class-Methods
        Module
            is a *.py file
            Module can contain functions, classes, variables, runnable code... (aka attributes)
            Can import modules then reuse functions, classes, variables inside those modules
        Class:
            is a collection of several functions & variables, which can be reused
            Differ from module:
                module is imported and run only once  ><  can create multiple instances of a class, then run them without conflict
                module can contain multiple classes (and also module's functions & variables)
        Method:
            is a function defined inside a class and takes a class instance as 1st parameter
            i.e:  def method_name(self, arg1, arg2):
            i.e:  new_file(), get_view_index(view),...
            To use a method, we have to initiate relevant module & Class, i.e:
                import sublime, sublime_plugin, os                  # Now, all methods provided by sublime.py, sublime_plugin.py, os.py can be used
                class ExampleCommand(sublime_plugin.TextCommand):   # Define a new class, which inherit all methods from Class "TextCommand" inside sublime_plugin module [[Plugin.API.txt]]
                    run(self):                                      # call run() method from TextCommand class
                        sublime.message_dialog('Hello World')       # call message_dialog() method from "sublime" module
            ST3 can use:
                ST built-in methods [[Plugin.API.txt]]
                ST built-in commands [[Command.txt#Built-in commands]]
                Python 3.x standard methods
        Object:
            Buffer:
                is the whole text-editing region on screen
                each character is located by 1 integer count from beginning to end
            Point:
                is an integer used to locate 1 character
                i.e: sublime.message_dialog(self.view.substr(12))  =  the 12th character counted from the beginning of the buffer
            Region:
                a range from Point a to Point b
                i.e: view.substr(sublime.region(12, 15))  =  3 characters counted from Point 12 to Point 14
            Selection
                is a region  (multiple regions in case multiple selections)
                sels = self.view.sel()  => Return a List of selected regions i.e: [(3,0), (12,15)]
                sel = sels[0]  => return the first region, i.e: (3,0)
                sel.a --> the start of the selection, i.e:  =3 because user drag-selected from from Point 3 to Point 0 (right-to-left)
                sel.b --> the end of the selection, i.e: =0
                sel.begin() --> the minimum of a and b
                sel.end() --> the maximum of a and b
            view object vs window object
                Sometime, you need to feed an abstract object to a method (i.e: 1st and 3rd tab to method close())
                View object represent current buffer => feed it to text-dealing-methods [[Plugin.API.txt#sublime.View]]
                Window object represent ST's UI such as panels, tabs, bars...=> feed to [[Plugin.API.txt#sublime.Window]]
                TextCommand:
                    self.view                           return current View object
                    window = self.view.window()         return current Window object
                WindowCommand:
                    self.window                         return current Window object
                    view = self.window.active_view()    return current View object
                Example: To toggle side bar & reveal current file
                    Note:
                        a "view" is required to run_command("reveal_in_side_bar");
                        but we need a "window" to run_command("toggle_side_bar")
                    Method 1 - using WindowCommand
                        import sublime, sublime_plugin
                        class examplCommand(sublime_plugin.WindowCommand):
                            def run(self):
                                view = self.window.active_view()
                                view.run_command("reveal_in_side_bar")
                                self.window.run_command("toggle_side_bar")
                    Method 2 - using TextCommand
                        import sublime, sublime_plugin
                        class examplCommand(sublime_plugin.TextCommand):
                            def run(self, view):
                                self.view.run_command("reveal_in_side_bar")
                                window = self.view.window()
                                window.run_command("toggle_side_bar")
            Settings
                is an object, which allow [[#sublime.Settings]] methods i.e:
                SettingObject = self.view.settings()
                SettingObject.set('word_wrap', 'false')
            Value: ???
            Vector: is a combination of begin Point and end Point, i.e: (234.0, 1342.0)
    Plugin Lifecycle
        At importing time, plugins may not call any API functions, with the exception of sublime.version(), sublime.platform(), sublime.architecture() and sublime.channel().
        If a plugin defines a module level function plugin_loaded(), this will be called when the API is ready to use.
        Plugins may also define plugin_unloaded(), to get notified just before the plugin is unloaded.
    Some useful pieces of codes: [[Plugin.Snippet.py]]
    Working Example (sorted from basic → advance):
        [[obj\message.py]]
        [[obj\insert_text.py]]
        [[obj\change_settings.py]]
        [[obj\Expand selection to bracket.py]]
        [[obj\OpenInBrowser.py]]
        [[obj\view_scope.py]]
        [[obj\CopyPath.py]]
        [[obj\TrimWhiteSpace.py]]
        [[obj\Set_timeout.py]]
        Several pre-made plugins for further study: *.py inside  \Packages\Default.sublime-package
To Run a command/plugin  [[Command.txt#Commands can be triggered via]]