Wednesday, April 23, 2014

#1 2012-12-02 01:31:44 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

A set of handlers for documenting handlers

Hello!

A small collection of handlers , that makes you able to select the "signature" of a handler, and produce documentation by it, works best with scripts that compiles. smile

By "signature" I mean something like: makeMarkdownDocBlock(asHandler).

I use this by selecting the line containing the signature, to produce documentation for indidividual handlers as seen below, in a markdown document. The Markdown document gets processed into html by other scripts;  I have aliases to the html documents in the infoLib folder of my Script Menu, so that when I wonder, I open up the html in Safari, and copies the full signature from there into some script I am working on.

This is kind of specifically made for Script Debugger, but should be easy to "port" to AppleScript Editor, Smile, and others.

The handlers are made so that I can select the header of a handler in say a script library, and then get a documentation block of the handle to clipbard, which I then can paste into my markdown document.
The markdown doc handler, should be equally or even easier to paste into another format.

Enjoy!

## stripTrailingComment for anAsHeaderSignature

stripTrailingComment does:  strip the trailing comment from an ASHandler signature

### Returns:

The handler without any commens


### Parameters:

#### anAsHeaderSignature

The "head" of the handler definition.


## getHandlerData()

getHandlerData does: Collect the full signature of a handler, selected in a Script Debugger document, and delivers the full signature, the name of the handler, and the argument list, for further processing by a handler that turns this information into meaningful documentation.

### Returns:

A list with { fullHandlerSignature, handlerName, argumentList }

### Parameters:

None.

## makeMarkdownDocBlock(asHandler)

makeMarkdownDocBlock does: creates a

### Returns:

### Parameters:

#### asHandler

A list with { fullHandlerSignature, handlerName, argumentList }


Applescript:

script asLibDoc
   -- http://macscripter.net/viewtopic.php?pid=158192#p158192
   -- Version 1.0.5 Line-endings!
   -- © 2012 McUsr BSD 2.0 Please refer to this link: http://macscripter.net/edit.php?id=158191
   on run
       local handlerData
       
       set handlerData to getHandlerData()
       if handlerData is not null then
           set the clipboard to "" as text # hopefully a fix for line-ending problems.
           set the clipboard to makeMarkdownDocBlock(handlerData) as text
       end if
       # gets the data
       # pastes formatted handler definition to clipboard.
       tell application id "sevs"
           set otherApp to name of item -1 of (every application process whose visible is true)
       end tell
       tell application otherApp to activate
   end run
   
   to makeMarkdownDocBlock(asHandler)
       local twoLfs, theHeader, initial_comment, returnline, parameterline
       set twoLfs to return & return
       set theHeader to "## " & item 1 of asHandler & twoLfs -- the full signature
       set initial_comment to item 2 of asHandler & " does: " & twoLfs
       set returnline to "### Returns:" & twoLfs
       set parameterline to "### Parameters: " & twoLfs
       local argList
       set argList to item 3 of asHandler
       if argList = {} then
           set parameterline to parameterline & "None." & twoLfs
       else
           repeat with anArg in item 3 of asHandler
               local argline, theofs, theArg
               set thOfs to offset of ":" in (contents of anArg)
               if thOfs > 0 then
                   set theArg to text 1 thru (thOfs - 1) of contents of anArg
               else
                   set theArg to contents of anArg
               end if
               set argline to "#### " & theArg & twoLfs
               set parameterline to parameterline & argline
           end repeat
       end if
       local theDocBlock
       set theDocBlock to theHeader & initial_comment & returnline & parameterline
       return theDocBlock as text
   end makeMarkdownDocBlock
   
   to getHandlerData()
       tell application "Script Debugger 4.5"
           set a to its document 1
           set textSel to selection of a
           try
               set handlerKeyword to first word of textSel
           on error
               activate
               display alert "Not handler signature."
               return null
           end try
           
           if handlerKeyword is not in {"on", "to"} then
               activate
               display alert "Not handler signature."
               return null
           else
               set textSel to text ((offset of handlerKeyword in textSel) + 3) thru -1 of textSel
               # we remove the space as well
           end if
           set fullHandlerSignature to stripTrailingComment of me for textSel
           if (offset of "*)" in fullHandlerSignature) is not 0 then
               activate
               display alert "bad bad handler signature"
               return null
           else
               # time to split into parts, handler name and a list of its arguments.
               local handlerName, parensStart, startArgList, endArgList, tids, parensStart
               
               set parensStart to (offset of "(" in fullHandlerSignature)
               # figure out the form of the handler: parens or label predicates
               if parensStart is not 0 then -- parenthized arg list
                   set handlerName to text 1 thru (parensStart - 1) of fullHandlerSignature
                   set startArgList to parensStart + 1
                   set endArgList to (offset of ")" in fullHandlerSignature) - 1
                   set argList to text startArgList thru endArgList of fullHandlerSignature
                   if length of argList = 2 then
                       set argList to {}
                   else
                       set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, ", "}
                       set argList to text items of argList
                       set AppleScript's text item delimiters to tids
                   end if
               else
                   local theLabelList
                   set theLabelList to {" about ", " above ", " against ", " apart from ", " around ", " aside from ", " at ", " below ", " beneath ", " beside ", " between ", " by ", " for ", " from ", " instead of ", " into ", " on ", " onto ", " out of ", " over ", " since ", " thru ", " through ", " under ", " given "}
                   # we are having the predicate thing
                   set startArgList to (offset of " " in fullHandlerSignature)
                   set endArgList to -1
                   set handlerName to text 1 thru (startArgList - 1) of fullHandlerSignature
                   set argList to text startArgList thru endArgList of fullHandlerSignature
                   considering white space
                       set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, theLabelList}
                       set argList to text items 2 thru -1 of argList
                   end considering
                   set AppleScript's text item delimiters to tids
               end if
           end if
       end tell
       return {fullHandlerSignature, handlerName, argList}
   end getHandlerData
   
   to stripTrailingComment for anAsHeaderSignature
       # removes any comment at the end of a headerSignature
       local commentOpeners, tids
       set {commentOpeners, tids} to {{"#", "--", "(*"}, AppleScript's text item delimiters}
       
       repeat with aComment in commentOpeners
           set AppleScript's text item delimiters to contents of aComment
           local theBits, nrBits
           set theBits to text items of anAsHeaderSignature
           set nrBits to length of theBits
           if nrBits > 1 then
               set anAsHeaderSignature to text item 1 of theBits as text
           end if
       end repeat
       set AppleScript's text item delimiters to tids
       repeat while text -1 of anAsHeaderSignature = space
           set anAsHeaderSignature to text 1 thru -2 of anAsHeaderSignature
       end repeat
       return anAsHeaderSignature
   end stripTrailingComment
end script
tell asLibDoc to run

Last edited by McUsrII (2013-11-20 05:01:54 am)

Offline

 

#2 2012-12-02 02:19:57 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

A spinoff, I don't remember all of the parameter labels, so this opens up a TextEdit document, with the labels within.

Applescript:

script showLabels
   set L to {"about", "above", "against", "apart from", "around", "aside from", "at", "below", "beneath", "beside", "between", "by", "for", "from", "instead of", "into", "on", "onto", "out of", "over", "since", "thru", "through", "under"}
   set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, linefeed}
   set L to L as text
   set AppleScript's text item delimiters to tids
   do shell script "cat <<<" & quoted form of L & ">|/tmp/labels.txt ; open -ge /tmp/labels.txt "
end script
tell showLabels to run


Filed under: TextEdit, labels

Offline

 

#3 2012-12-02 02:49:03 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

Changed text item delimeters from " ," to ", " to pull off paremters in parenthesis correctly in the script in post #1. yikes


Filed under: documentation, markdown

Offline

 

#4 2012-12-02 03:04:34 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

Posted my version, so I have changed the Script Debugger document from 2 to 1! :0

Offline

 

#5 2012-12-02 03:29:49 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

The linefeed stopped working, so I have changed those to return.

Offline

 

#6 2012-12-03 03:09:27 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

The script didn't take height for the given keyword. That is hereby fixed.


Filed under: Handlers, as, markdown, Doc

Offline

 

#7 2013-11-20 05:03:05 am

McUsrII
Member
Registered: 2012-11-20
Posts: 2254
Website

Re: A set of handlers for documenting handlers

Hello.

I have changed the script, so that it now activates the previous app. when the script has run, the idea is that this is your editor of choice, so that you just run the script, and paste the documentation skeleton of the handler into your documentation.

Offline

 

Board footer

Powered by FluxBB

[ Generated in 0.058 seconds, 10 queries executed ]

RSS (new topics) RSS (active topics)