Please enable JavaScript to view this site.

A-Shell Consolidated Reference

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.

apn1_img60

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.