Insert-Dynamic-Handler-Description.applescript

(*
===============================================================================
                    Insert Dynamic Handler Description
===============================================================================

Version: 1.0                                     Updated: 05/16/19 19:31:26 CST
By: Kevin Funderburg

PURPOSE:

To insert a handler description at the beginning of the handler currently
selected. The description will inserted by creating a Script Debugger clipping
dynamically with the handler's name and parameters. 

NOTE:

• You will probably need to update the clipPath variable to the default path
for the User's clipping folder in Script Debugger (comments explain)

VERSION HISTORY:
1.0 - Initial version.
===============================================================================
*)
use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

on run
	
	-- I keep my clippings in Dropbox and use an alias in the default folder so you will probably want to change this line to 
	-- set clipPath to "~/Library/Application\\ Support/Script\\ Debugger\\ 7/Clippings/Comments/handler\\ description.txt"
	set clipPath to "~/Dropbox/Library/Application\\ Support/Script\\ Debugger\\ 7/Clippings/Comments/handler\\ description.txt"
	
	do shell script "touch " & clipPath
	
	tell application "Script Debugger"
		tell document 1
			set {theLocation, theRange} to (get character range of selection)
			set sourceText to source text
			set endOfSelection to theLocation + theRange
			
			set ps to count of paragraphs of sourceText
			set currentLine to 1
			set currentHandler to missing value
			
			set lineCount to 0
			set charCount to 0
			repeat with x from 1 to count of paragraphs of sourceText
				considering white space
					set charCount to charCount + (count of characters of paragraph x of sourceText) + 1
					if charCount < theLocation then
						if paragraph x of sourceText begins with "on " then
							set currentHandler to paragraph x of sourceText as text
							
							set insertion to charCount - (count of characters of paragraph x of sourceText)
							set newSelection to {insertion, count of characters of paragraph x of sourceText}
						end if
					else
						exit repeat
					end if
				end considering
			end repeat
			
			# Move cursor to beginning of handler
			set selection to {insertion, 0}
			
			if currentHandler is missing value then set currentHandler to "run"
			
			# get the name of handler
			set tid to AppleScript's text item delimiters
			set AppleScript's text item delimiters to "on "
			set endItems to text of text item -1 of currentHandler
			set AppleScript's text item delimiters to "("
			set beginningToEnd to text of text item 1 of endItems
			set AppleScript's text item delimiters to tid
			set currentHandler to beginningToEnd
			
			# make the handler description template
			set handlerDescrip to "-- @description" & return & "-- [[template:description]]" & return & "--" & return
			set theHandler to first script handler whose name is currentHandler
			tell theHandler
				repeat with i in handler parameters
					set handlerDescrip to handlerDescrip & "-- @param $" & name of i & " - [[template:description]]" & return
				end repeat
			end tell
			set handlerDescrip to handlerDescrip & "--" & return
			
			# Write new handler description template to the clipping
			do shell script "echo " & quoted form of handlerDescrip & " > " & clipPath
			
			# Click the clipping in the menu bar to insert it
			tell application "System Events"
				tell process "Script Debugger"
					click (first menu item of menu 1 of menu item 2 of menu 1 of menu bar item 10 of menu bar 1 whose name is "handler description")
				end tell
			end tell
			
		end tell
	end tell
end run