Many extensions specific to A-Shell Basic are implemented as scripts (written in Python). The scripts are stored in the %APN%\scripts directory as .py files. A handful of general-purpose scripts are included in the PN2 package, and we supply a collection of ASB-specific scripts in asb scripts.py which share common routines from asb.py. You can browse a collection available for download from the general public at http://scriptshare.rocketmonkeys.com/.
After downloading a new script, or editing an existing one, you may need to close and relaunch APN to get it to recognize the changes. Any new or updated scripts are automatically compiled when APN is launched (creating a .pyc file). If an error occurs during compilation, it will appear in the Output window (hit F8 or View > Windows to display.)
Documentation for the PyPN API can be found at http://www.pnotepad.org/docs/pypn_api_pages/
There are admittedly a lot of gaps, although you can probably fill in many of them by also looking at the Scintilla API doc, since much of the PyPN API is just a wrapper for the Scintilla API.
Also see the Technical Notes in the Appendix for tips and other details that may apply here.
Other than that, the best reference source is to browse the existing scripts. Here’s an example from the asb scripts.py file of a routine to comment or uncomment a block of selected lines which illustrates some of the basics:
@script("Block Comment Toggle", "ASB")
def BlockCommentToggle():
""" block comment/uncomment """
marker = "!>!"
sci = scintilla.Scintilla(pn.CurrentDoc()) # get reference to editor
spos = sci.SelectionStart # get current selection start/end pos
epos = sci.SelectionEnd
if epos > spos:
| sci.BeginUndoAction() |
| sline = sci.LineFromPosition(spos) # convert start/end pos |
| eline = sci.LineFromPosition(epos) # to start/end line |
| for curlin in range(sline,eline+1): # for the selected lines |
| sci.GotoLine(curlin) # go to start of line |
| curpos = sci.CurrentPos # get position |
| match = sci.GetTextRange(curpos,curpos+3) # get first 3 chars |
| if match == marker: # if they match our comment marker |
| sci.CurrentPos += 3 # position past the marker |
| sci.DelLineLeft() # delete from start of line to cursor |
| else: |
| sci.AddText(3,marker) # else insert the marker |
| sci.SelectionStart = spos # reset selection start/end pos |
| sci.SelectionEnd = sci.GetLineEndPosition(eLine) # (leave lines selected) |
| sci.EndUndoAction() |
The first line specifies a title and category name for the script so that it can appear in the Scripts panel, i.e.
The next line (def BlockCommentToggle()) is a standard Python function definition. The name is essentially arbitrary for scripts, since APN will automatically associate it with the title from the @script line preceding it. Script functions are called with no explicit arguments (typically they get their parameter information from the context of the editing window, position of the cursor and/or selection). The remainder of the script is a mixture of generic Python logic and calls to functions or methods imported from elsewhere, most importantly the Scintilla and PN modules, which provide access to the editor and the Programmer’s Notepad APIs.
Refer to the Using Scripts section for examples of using the provided scripts. Refer to the Keyboard Shortcuts section for information on assigning a keyboard shortcut to the script.
