Komodo User Guide - ActiveState Community Site

Komodo User Guide
Komodo User Guide
Table of Contents
Welcome to Komodo IDE..................................................................................................................1
What's new in Komodo 4.2......................................................................................................1
Support and Community..........................................................................................................1
Release Notes.........................................................................................................................1
New in 4.2.0 Beta 2............................................................................................................................2
New in 4.0...........................................................................................................................................3
Code Intelligence.....................................................................................................................3
Editing......................................................................................................................................3
HTTP InspectorKomodo IDE only............................................................................................3
JavaScript DebuggingKomodo IDE only..................................................................................3
Projects....................................................................................................................................4
Other Improvements................................................................................................................4
Starting Komodo................................................................................................................................5
Windows..................................................................................................................................5
Mac OS X.................................................................................................................................5
Linux........................................................................................................................................6
Installing Komodo 4.2.0 Beta 2.........................................................................................................7
Windows..................................................................................................................................7
Prerequisites......................................................................................................................7
Installing the Komodo License on Windows.......................................................................8
Upgrading from Previous Komodo Versions......................................................................8
Installing Komodo on Windows..........................................................................................8
Command Line Installation Options...................................................................................9
Uninstalling Komodo on Windows....................................................................................10
Starting Komodo on Windows..........................................................................................10
Uninstalling Komodo on Windows....................................................................................10
Mac OS X...............................................................................................................................10
Prerequisites....................................................................................................................10
Installing the Komodo License on OS X...........................................................................10
Upgrading from Previous Komodo Versions....................................................................11
Installing Komodo on Mac OS X......................................................................................11
Starting Komodo on OS X................................................................................................11
Uninstalling Komodo on OS X..........................................................................................11
Linux......................................................................................................................................11
Prerequisites....................................................................................................................11
Installing the Komodo License on Linux...........................................................................12
Upgrading from Previous Komodo Versions....................................................................12
Installing Komodo on Linux..............................................................................................13
Starting Komodo on Linux................................................................................................13
Uninstalling Komodo on Linux..........................................................................................14
Language and Debugging Prerequisites................................................................................14
Source Code Control Integration Prerequisites.....................................................................14
i
Komodo User Guide
Table of Contents
The Komodo Workspace.................................................................................................................16
The Start Page.......................................................................................................................16
Menus....................................................................................................................................16
Context Menus.......................................................................................................................17
Toolbars.................................................................................................................................17
Left Pane................................................................................................................................19
Projects Tab.....................................................................................................................19
Code Tab Komodo IDE only............................................................................................19
DOM Viewer Tab Komodo IDE only.................................................................................20
Right Pane.............................................................................................................................21
Toolbox Tab.....................................................................................................................21
Shared Toolbox Tab Komodo IDE only............................................................................21
Editor Pane............................................................................................................................22
Bottom Pane..........................................................................................................................23
Managing Tabs and Panes....................................................................................................23
Showing and Hiding Tabs................................................................................................23
Showing and Hiding Panes..............................................................................................23
Resizing Panes................................................................................................................24
Enabling Full Screen Mode....................................................................................................24
Getting Started with the Sample Project.......................................................................................25
Opening the Sample Project and Files..................................................................................25
Editing a Sample Program.....................................................................................................25
Debugging a Sample Program...............................................................................................25
Release Notes..................................................................................................................................26
New in Komodo 4.2................................................................................................................26
Bug Fixes...............................................................................................................................27
Known Issues.........................................................................................................................31
Object Browser.................................................................................................................31
Installation & Upgrade......................................................................................................31
Startup.............................................................................................................................32
Projects and Toolboxes....................................................................................................32
Editing..............................................................................................................................32
Debugging........................................................................................................................33
Interactive Shell................................................................................................................35
Source Code Control........................................................................................................35
GUI Builder.......................................................................................................................35
Mac OS X.........................................................................................................................35
Linux................................................................................................................................36
Other................................................................................................................................37
Revision History..............................................................................................................................39
Komodo IDE/Edit 4.1 (May 15, 2007)....................................................................................40
Komodo IDE/Edit 4.1 Beta 3 (May 9, 2007)...........................................................................40
Komodo IDE/Edit 4.1 Beta 2 (April 27, 2007)........................................................................41
Komodo IDE/Edit 4.0.3 (April 17, 2007).................................................................................42
Komodo IDE/Edit 4.1 Beta 1 (March 6, 2007)........................................................................43
ii
Komodo User Guide
Table of Contents
Revision History
Komodo IDE/Edit 4.0.2 (February 13, 2007)..........................................................................44
Komodo IDE 4.0.1 (January 29, 2007)..................................................................................45
Komodo IDE 4.0, Edit 4.0 Beta 5 (January 22, 2007)............................................................45
Komodo 4.0 Beta 4 (January 11, 2007).................................................................................46
Komodo 4.0 Beta 3 (December 14, 2006).............................................................................46
Komodo 4.0 Beta 2 (November 27, 2006).............................................................................47
Komodo 4.0 Beta 1 (October 31, 2006).................................................................................48
Komodo 4.0 Alpha 7 (October 24, 2006)...............................................................................48
Komodo 4.0 Alpha 6 (September 19, 2006)..........................................................................48
Komodo 4.0 Alpha 5 (September 1, 2006)............................................................................48
Komodo 4.0 Alpha 4 (August 24, 2006).................................................................................49
Komodo 4.0 Alpha 3 (July 25, 2006)......................................................................................49
Komodo 4.0 Alpha 2 (July 11, 2006)......................................................................................49
Komodo 4.0 Alpha 1 (June 26, 2006)....................................................................................49
Komodo 3.5.3 (May 4, 2006).................................................................................................49
Komodo 3.5.3 Beta 1 (March, 2006)......................................................................................49
Komodo 3.5.2 (December 6, 2005)........................................................................................49
Komodo 3.5.1 (November, 2005)...........................................................................................50
Komodo 3.5 (November 2, 2005)...........................................................................................50
Komodo 3.1 (February, 2005)................................................................................................50
Komodo 3.1 Beta 2 (January, 2005)......................................................................................51
Komodo 3.1 Beta 1 (January, 2005)......................................................................................51
Komodo 3.1 Alpha 4 (December, 2004)................................................................................52
Komodo 3.1 Alpha 3 (November, 2004)................................................................................53
Komodo 3.1 Alpha 2 (October, 2004)....................................................................................53
Komodo 3.1 Alpha 1 (October, 2004)....................................................................................53
Komodo 3.0.1 (August, 2004)................................................................................................54
Komodo 3.0 (July, 2004)........................................................................................................54
Code Intelligence.............................................................................................................54
Komodo 3.0 Beta 4 (June, 2004).....................................................................................57
Komodo 3.0 Beta 3 (May, 2004)......................................................................................57
Komodo 3.0 Beta 2 (May, 2004)......................................................................................57
Komodo 3.0 Beta 1 (May, 2004)......................................................................................57
Komodo 2.5.2 (January, 2004)..............................................................................................57
Komodo 2.5.1 (October, 2003)..............................................................................................58
Komodo 2.5 for Windows, Linux (September, 2003).............................................................59
Komodo 2.5 Technology Preview 1 for Solaris (August, 2003)........................................61
Komodo 2.5 Beta 1 for Windows, Linux (August, 2003)..................................................61
Komodo 2.5 Alpha 2 (July, 2003).....................................................................................62
Komodo 2.3 (February, 2003)................................................................................................62
Komodo 2.3 beta 2 (February, 2003)...............................................................................64
Komodo 2.3 beta 1 (January, 2003).................................................................................64
Komodo 2.0.1 for Linux (November, 2002)............................................................................64
Komodo 2.0.1 for Windows (October, 2002)....................................................................64
Komodo 2.0 beta 3 for Linux (October, 2002)..................................................................64
Komodo 2.0 beta 2 for Linux (September, 2002).............................................................64
Komodo 2.0 for Windows (September, 2002)........................................................................64
iii
Komodo User Guide
Table of Contents
Revision History
Komodo 2.0 beta 2 for Windows (September, 2002).......................................................65
Komodo 2.0 beta 1 for Linux (September, 2002).............................................................65
Komodo 2.0 beta 1 for Windows (August, 2002).............................................................65
Komodo 1.2.9 (July, 2002).....................................................................................................66
Komodo 1.2.7 RC1 for Windows and Linux (March, 2002)..............................................67
Komodo 1.2 for Windows and Linux (December, 2001)........................................................67
Komodo 1.2 beta 1 for Linux (November, 2001)..............................................................69
Komodo 1.2 beta 2 for Windows (November, 2001)........................................................69
Komodo 1.2 beta 1 for Windows (October, 2001)............................................................69
Komodo 1.1 (June, 2001)......................................................................................................69
Komodo 1.0 (April, 2001).................................................................................................70
Komodo .1 (November, 2000)..........................................................................................70
License and Copyrights..................................................................................................................71
Komodo License....................................................................................................................71
Sending Feedback...........................................................................................................................73
Comments and Feature Requests.........................................................................................73
Reporting Bugs......................................................................................................................73
Working with Projects.....................................................................................................................74
Displaying the Project Tab.....................................................................................................74
Creating Projects...................................................................................................................74
Live Import.......................................................................................................................75
Opening Projects...................................................................................................................75
Setting the Active Project.......................................................................................................75
Adding Components to Projects............................................................................................76
Project Display Settings.........................................................................................................77
Saving Projects......................................................................................................................77
Refreshing Project Status......................................................................................................78
Importing and Exporting Projects via Packages....................................................................78
Importing Files from the File System.....................................................................................79
Source Code ControlKomodo IDE only.................................................................................79
Reverting Projects..................................................................................................................80
Closing Projects.....................................................................................................................80
Deleting Projects....................................................................................................................81
Project Properties and Settings.............................................................................................81
Project Templates..................................................................................................................81
Using the Toolbox...........................................................................................................................82
Displaying the Toolbox...........................................................................................................82
Adding Components to the Toolbox.......................................................................................82
Exporting and Importing Toolbox Contents............................................................................83
Sharing Toolboxes.................................................................................................................84
iv
Komodo User Guide
Table of Contents
Working with Files...........................................................................................................................85
Creating Files.........................................................................................................................85
Creating Files from Templates.........................................................................................85
Storing Files within a Project or the Toolbox..........................................................................85
Creating an Open Shortcut to the Current File Location..................................................86
Exporting Files as Projects...............................................................................................86
Exporting Files to a Package...........................................................................................86
Opening Files.........................................................................................................................86
Opening Files with the Open/Find Toolbar.......................................................................87
Opening Remote Files.....................................................................................................88
Opening Mapped URIs.....................................................................................................89
Switching Between Files........................................................................................................89
Comparing Files.....................................................................................................................89
Refreshing File Status............................................................................................................90
Source Code Control.............................................................................................................90
File Properties and Settings...................................................................................................91
File Properties..................................................................................................................91
File Source Control Settings............................................................................................92
File Editor Settings...........................................................................................................92
Indentation Tab................................................................................................................92
Browser Preview..............................................................................................................92
Printing Files..........................................................................................................................92
Page Setup......................................................................................................................93
Print to HTML File............................................................................................................93
Saving Files...........................................................................................................................93
Saving Files Remotely.....................................................................................................94
Show Unsaved Changes..................................................................................................94
Reverting Files.......................................................................................................................94
Closing Files..........................................................................................................................94
Searching.........................................................................................................................................95
Searching for Strings.............................................................................................................95
Searching Within Open Files: Find Dialog.......................................................................95
Replacing Within Open Files: Replace Dialog.................................................................96
Searching for the Word Under the Cursor........................................................................97
Incremental Search..........................................................................................................98
Searching All Files: Find in Files Dialog...........................................................................98
Fast Search: Open/Find Toolbar......................................................................................99
Find Results Tabs..........................................................................................................100
Finding Functions: Function Search....................................................................................101
Moving Between Functions............................................................................................101
Displaying a List of Functions........................................................................................101
Editing.............................................................................................................................................102
Language Support...............................................................................................................102
Syntax Coloring and Indentation....................................................................................102
Background Syntax Checking........................................................................................103
AutoComplete and CallTips...........................................................................................104
v
Komodo User Guide
Table of Contents
Editing
Viewing the Current File as Another Language.............................................................108
Commenting Blocks of Code..........................................................................................109
Manipulating Code...............................................................................................................109
Automatically Repeating Keystrokes..............................................................................109
Indenting and Un-indenting Lines of Code.....................................................................109
Reflowing Paragraphs....................................................................................................110
Joining Lines..................................................................................................................110
Converting between Uppercase and Lowercase...........................................................110
Transposing Characters.................................................................................................110
Literal Characters...........................................................................................................110
Commenting and Un-commenting Lines or Blocks of Code..........................................111
Cleaning Line Endings...................................................................................................111
Tabifying and Untabifying Regions................................................................................111
Selecting Columns or Blocks.........................................................................................112
Completing Words..........................................................................................................112
Selecting Blocks of Code...............................................................................................112
Editor Display Characteristics..............................................................................................113
Toggling Whitespace On and Off...................................................................................113
Toggling Indentation Guides On and Off........................................................................113
Toggling Line Numbers On and Off...............................................................................113
Toggling EOL (end of line) Markers On and Off.............................................................113
Increasing and Decreasing the Code Font Size.............................................................113
Toggling Fixed and Non-Fixed Width Fonts...................................................................114
Folding and Unfolding Code...........................................................................................114
Navigating Within Files........................................................................................................115
Moving to a Specific Line...............................................................................................115
Go to Definition..............................................................................................................115
Setting and Moving to Bookmarks and Marks................................................................115
Matching Braces............................................................................................................116
Detecting Changed Files......................................................................................................116
Preview in Browser..............................................................................................................116
Editor Tab Display................................................................................................................117
Working with Folders....................................................................................................................118
Folder Options.....................................................................................................................118
Import from File System.................................................................................................118
Export Contents to Package..........................................................................................119
Import Contents from Package......................................................................................120
Refresh Folder Contents Status.....................................................................................120
Adding Components to Folders......................................................................................120
Exporting Contents as Project File.................................................................................120
Renaming Folders..........................................................................................................120
Source Control on Folder Contents................................................................................121
Deleting Folders.............................................................................................................121
vi
Komodo User Guide
Table of Contents
Snippets..........................................................................................................................................122
Creating Snippets................................................................................................................122
Configuring Snippets............................................................................................................122
Using Snippets.....................................................................................................................123
Snippet Options...................................................................................................................123
Snippet Properties..........................................................................................................124
Macros............................................................................................................................................125
Creating Macros...................................................................................................................125
Recording Macros..........................................................................................................125
Saving Recorded Macros...............................................................................................125
Programming Macros.....................................................................................................125
Running Macros...................................................................................................................126
Specifying Macro Triggers...................................................................................................126
Running Macros in the Background...............................................................................127
Storing Macros in Projects or the Toolbox...........................................................................127
Macro Options................................................................................................................128
Assigning Custom Icons to Macros................................................................................128
Assigning Key Bindings to Macros.................................................................................129
Vi Command Mode Macros............................................................................................129
Macro API.......................................................................................................................................130
Introduction to the Komodo Macro API................................................................................130
Warning..........................................................................................................................130
Feedback.......................................................................................................................130
The editor Object.................................................................................................................130
editor Attributes..............................................................................................................131
komodo.editor Methods..................................................................................................132
editor Object Notes........................................................................................................135
The document Object...........................................................................................................136
document Attributes.......................................................................................................136
The file Object......................................................................................................................136
file attributes...................................................................................................................136
The komodo.doCommand Function.....................................................................................137
The komodo.openURI Function...........................................................................................137
The komodo.findPart Function.............................................................................................137
The komodo.interpolate Function........................................................................................138
Komodo Command Id List............................................................................................................139
Breakpoint Manager.............................................................................................................139
Code Browser......................................................................................................................139
Debugger.............................................................................................................................139
Editor....................................................................................................................................140
Find......................................................................................................................................142
General................................................................................................................................143
Help......................................................................................................................................144
Macro...................................................................................................................................144
Projects/Toolbox..................................................................................................................145
vii
Komodo User Guide
Table of Contents
Komodo Command Id List
Source Code........................................................................................................................145
Source Control.....................................................................................................................145
Toolbox................................................................................................................................146
Tools....................................................................................................................................146
User Interface......................................................................................................................146
Komodo JavaScript API................................................................................................................148
ko.........................................................................................................................................148
Classes..........................................................................................................................148
Constructor.....................................................................................................................148
Class variables...............................................................................................................148
Class functions...............................................................................................................148
ko.browse.............................................................................................................................149
Functions........................................................................................................................149
ko.commands.......................................................................................................................150
Functions........................................................................................................................150
ko.dialogs.............................................................................................................................150
Variables........................................................................................................................151
Functions........................................................................................................................151
ko.dragDrop.........................................................................................................................152
Functions........................................................................................................................152
ko.dragDrop.dragObserver..................................................................................................152
Variables........................................................................................................................152
Functions........................................................................................................................152
ko.eggs................................................................................................................................153
Functions........................................................................................................................153
ko.filepicker..........................................................................................................................153
Functions........................................................................................................................153
ko.fileutils.............................................................................................................................154
Functions........................................................................................................................154
ko.help.................................................................................................................................154
Functions........................................................................................................................154
ko.inputBuffer.......................................................................................................................155
Variables........................................................................................................................156
Functions........................................................................................................................156
ko.interpolate.......................................................................................................................156
Functions........................................................................................................................156
ko.isearch.............................................................................................................................157
Variables........................................................................................................................157
ko.isearch.controller.............................................................................................................157
Variables........................................................................................................................158
ko.keybindings.....................................................................................................................158
Variables........................................................................................................................158
Functions........................................................................................................................158
Classes..........................................................................................................................158
Constructor.....................................................................................................................158
Class variables...............................................................................................................158
viii
Komodo User Guide
Table of Contents
Komodo JavaScript API
Class functions...............................................................................................................159
ko.launch..............................................................................................................................162
Functions........................................................................................................................162
ko.lint....................................................................................................................................164
Functions........................................................................................................................164
Classes..........................................................................................................................165
Constructor.....................................................................................................................165
Class variables...............................................................................................................165
Class functions...............................................................................................................165
ko.logging.............................................................................................................................166
Variables........................................................................................................................166
Functions........................................................................................................................166
Classes..........................................................................................................................167
Constructor.....................................................................................................................167
Class variables...............................................................................................................167
Class functions...............................................................................................................167
ko.logging.LoggerMap.........................................................................................................168
ko.macros............................................................................................................................168
Variables........................................................................................................................168
Functions........................................................................................................................168
ko.macros.recorder..............................................................................................................168
Variables........................................................................................................................168
ko.main................................................................................................................................168
Functions........................................................................................................................168
ko.main.window...................................................................................................................169
Functions........................................................................................................................169
ko.markers...........................................................................................................................169
Variables........................................................................................................................169
Functions........................................................................................................................169
ko.mozhacks........................................................................................................................170
Functions........................................................................................................................170
ko.mru..................................................................................................................................170
Functions........................................................................................................................170
ko.open................................................................................................................................171
Functions........................................................................................................................171
ko.printing............................................................................................................................172
Functions........................................................................................................................172
ko.projects............................................................................................................................172
Variables........................................................................................................................172
Functions........................................................................................................................173
ko.run...................................................................................................................................176
Functions........................................................................................................................176
ko.run.output........................................................................................................................177
Functions........................................................................................................................177
ko.scc...................................................................................................................................178
Functions........................................................................................................................178
ko.scc.logger........................................................................................................................178
ix
Komodo User Guide
Table of Contents
Komodo JavaScript API
Functions........................................................................................................................178
ko.statusBar.........................................................................................................................179
Functions........................................................................................................................179
ko.stringutils.........................................................................................................................179
Functions........................................................................................................................179
ko.toolboxes.........................................................................................................................180
Variables........................................................................................................................180
Functions........................................................................................................................180
ko.toolboxes.shared.............................................................................................................180
ko.toolboxes.shared.viewMgr..............................................................................................180
ko.trace................................................................................................................................181
Functions........................................................................................................................181
Classes..........................................................................................................................181
Constructor.....................................................................................................................181
Class variables...............................................................................................................181
Class functions...............................................................................................................181
ko.uilayout............................................................................................................................182
Functions........................................................................................................................182
ko.uriparse...........................................................................................................................183
Functions........................................................................................................................184
ko.views...............................................................................................................................185
Variables........................................................................................................................185
Functions........................................................................................................................185
Classes..........................................................................................................................186
Constructor.....................................................................................................................186
Class variables...............................................................................................................186
Class functions...............................................................................................................186
ko.views.manager................................................................................................................187
ko.views.manager.currentView............................................................................................187
Variables........................................................................................................................187
ko.widgets............................................................................................................................187
Functions........................................................................................................................188
ko.window............................................................................................................................188
Functions........................................................................................................................188
ko.windowManager..............................................................................................................188
Functions........................................................................................................................188
ko.workspace.......................................................................................................................189
Functions........................................................................................................................189
Templates.......................................................................................................................................190
Creating New Files from Templates.....................................................................................190
Creating Custom Templates................................................................................................190
Using Interpolation Shortcuts in Custom Templates......................................................191
Project Templates................................................................................................................191
Storing Templates in a Project or the Toolbox.....................................................................191
Template Options...........................................................................................................192
Assigning Custom Icons to Templates...........................................................................192
x
Komodo User Guide
Table of Contents
Templates
Template Key Bindings..................................................................................................193
Open Shortcuts..............................................................................................................................194
Open Shortcut Options........................................................................................................194
Open Shortcut Properties...............................................................................................195
URL Shortcuts................................................................................................................................196
URL Shortcut Options..........................................................................................................196
URL Shortcut Properties................................................................................................197
Run Commands.............................................................................................................................198
Creating Run Commands....................................................................................................198
Simple Run Commands.................................................................................................198
Advanced Run Commands............................................................................................199
Command Output Tab....................................................................................................199
Storing Run Commands in a Project or the Toolbox............................................................200
Run Command Properties..............................................................................................200
Custom Toolbars and Menus.......................................................................................................202
Creating Custom Toolbars and Menus................................................................................202
Custom Menu and Toolbar Options.....................................................................................202
Custom Menu and Toolbar Properties...........................................................................203
Debugging ProgramsKomodo IDE only......................................................................................204
Starting the Debugger..........................................................................................................204
Multi-Session Debugging...............................................................................................205
Debugging Options..............................................................................................................205
Global Options...............................................................................................................206
General Tab...................................................................................................................206
Environment Tab............................................................................................................206
CGI Environment Tab....................................................................................................207
CGI Input Tab.................................................................................................................207
Storing Debug Configurations........................................................................................208
Breakpoints and Tcl Spawnpoints........................................................................................208
Breakpoint and Spawnpoint Management.....................................................................208
Remote Debugging..............................................................................................................212
Listen for Debugger Connections...................................................................................212
Check Listener Status....................................................................................................212
Multi-User Debugging....................................................................................................212
Debugger Proxy.............................................................................................................212
Sending Input to the Program..............................................................................................214
Using Debugger Commands................................................................................................214
Debugger Command Description...................................................................................214
Debugger Stepping Behavior.........................................................................................216
Viewing the Debugging Session..........................................................................................216
Viewing Variables...........................................................................................................217
Setting Watched Variables.............................................................................................218
xi
Komodo User Guide
Table of Contents
Debugging ProgramsKomodo IDE only
Output Tab.....................................................................................................................219
HTML Preview Tab........................................................................................................219
Viewing the Call Stack...................................................................................................219
Watching Files.....................................................................................................................219
Detaching the Debugger......................................................................................................220
Stopping the Debugger........................................................................................................220
Debugging JavaScriptKomodo IDE only.....................................................................................221
Understanding JavaScript Debugging.................................................................................221
Pretty Print.....................................................................................................................221
Configuring the JavaScript Debugger..................................................................................222
Debugging JavaScript..........................................................................................................223
Debugging PerlKomodo IDE only................................................................................................224
Configuring the Perl Debugger............................................................................................224
Enabling "Break Now"....................................................................................................224
Debugging Perl Remotely....................................................................................................224
Disabling and Enabling the Perl Dev Kit (PDK) Debugger...................................................226
Disabling the PDK Debugger on the Remote Machine..................................................226
Configuring Perl for CGI Debugging....................................................................................227
Configuring a Microsoft IIS Web Server.........................................................................227
Configuring an Apache Web Server...............................................................................228
Starting a CGI Debugging Session................................................................................228
Debugging mod_perl............................................................................................................228
Debugging mod_perl on Windows.................................................................................230
Debugging mod_perl on Linux and Mac OS X...............................................................231
Debugging PythonKomodo IDE only...........................................................................................235
Configuring the Python Debugger........................................................................................235
Using the Python Remote Debugger...................................................................................235
Installing the Python Remote Debugger on the Remote Machine.................................235
Invoking the Python Remote Debugger.........................................................................237
CGI Debugging..............................................................................................................238
Debugging PHPKomodo IDE only................................................................................................240
Installing PHP......................................................................................................................240
Windows.........................................................................................................................240
Linux..............................................................................................................................240
Mac OS X.......................................................................................................................241
Local PHP Debugging..........................................................................................................241
Configuring Local PHP Debugging................................................................................241
Starting and Stopping a PHP Local Debugging Session...............................................242
Remote PHP Debugging......................................................................................................243
Configuring Remote PHP Debugging............................................................................243
Starting and Stopping a PHP Remote Debugging Session...........................................245
Using xdebug_break()....................................................................................................247
Xdebug Logging.............................................................................................................247
xii
Komodo User Guide
Table of Contents
Debugging PHPKomodo IDE only
Common PHP Debugging Problems...................................................................................247
Debugging PHP on OS X...............................................................................................247
Debugging PHP on 64-bit Linux.....................................................................................248
Zend Optimizer and Zend Studio Debugger..................................................................248
Debugging RubyKomodo IDE only..............................................................................................249
Configuring the Ruby Debugger..........................................................................................249
Debugging Ruby Remotely..................................................................................................249
Setting a Break in your Ruby Code................................................................................250
Rubygems and RUBYOPT.............................................................................................251
Debugging Rails Applications..............................................................................................251
Local Rails Debugging...................................................................................................251
Remote Rails Debugging...............................................................................................251
Debugging TclKomodo IDE only..................................................................................................253
Configuring Local Tcl Debugging.........................................................................................253
Remote Tcl Debugging........................................................................................................253
Installing the Tcl Debugger Application on a Remote Machine......................................253
Invoking the Tcl Debugger Application...........................................................................254
Debugging XSLTKomodo IDE only..............................................................................................256
Using the XSLT Debugger...................................................................................................256
Using a Remote XML Input File.....................................................................................256
XSLT Stepping Behavior................................................................................................256
HTTP InspectorKomodo IDE only................................................................................................258
Starting the HTTP Inspector................................................................................................258
Connecting the Browser.......................................................................................................258
Inspecting the HTTP Data....................................................................................................258
Break on Request/Response...............................................................................................259
Editing a Request/Response..........................................................................................259
Rules....................................................................................................................................259
Interactive ShellKomodo IDE only...............................................................................................261
Stand-Alone Interactive Shell...............................................................................................261
Debugging with an Interactive Shell.....................................................................................261
Using the Interactive Shell...................................................................................................261
Setting Shell Preferences...............................................................................................262
Starting the Interactive Shell..........................................................................................262
Using Multiple Shells......................................................................................................262
Using AutoComplete and CallTips.................................................................................262
Customizing Colors and Fonts.......................................................................................263
Viewing Shell History.....................................................................................................263
Stopping a Shell Session...............................................................................................263
Clearing the Shell Buffer................................................................................................263
Using the Python Interactive Shell.......................................................................................263
Debugging with the Python Shell...................................................................................264
xiii
Komodo User Guide
Table of Contents
Interactive ShellKomodo IDE only
Using the Tcl Interactive Shell.............................................................................................264
Debugging with the Tcl Shell..........................................................................................264
Using the Perl Interactive Shell............................................................................................264
Debugging with the Perl Shell........................................................................................266
Using the JavaScript Interactive Shell.................................................................................267
Using the interactive shell while not debugging.............................................................268
Further information.........................................................................................................268
Code Intelligence...........................................................................................................................269
Code BrowserKomodo IDE only..........................................................................................269
Context Menu.................................................................................................................270
Sorting............................................................................................................................270
Locating Current Scope.................................................................................................270
Filtering Symbols............................................................................................................271
Object BrowserKomodo IDE only........................................................................................271
DOM ViewerKomodo IDE only......................................................................................................272
Navigating the DOM Tree....................................................................................................272
Filtering the DOM Tree........................................................................................................272
DOM Resources..................................................................................................................272
Source Code ControlKomodo IDE only.......................................................................................273
Using Source Code Control.................................................................................................274
SCC Toolbar, Menus and Output Tab............................................................................274
Source Code Control Commands..................................................................................274
File Status Icons.............................................................................................................275
Refresh Status...............................................................................................................276
Configuring Source Code Control Integration......................................................................276
Configuring CVS............................................................................................................276
Configuring Subversion..................................................................................................276
Configuring Perforce......................................................................................................277
Configuring Preferences................................................................................................277
Configuring SSH Support for CVS and Subversion.............................................................277
Installing and Configuring Putty on Windows.................................................................278
Using the Rx ToolkitKomodo IDE only........................................................................................284
Creating Regular Expressions.............................................................................................285
Adding Metacharacters to a Regular Expression...........................................................285
Setting the Match Type..................................................................................................285
Adding Modifiers to a Regular Expression.....................................................................286
Evaluating Regular Expressions..........................................................................................286
Match Results................................................................................................................287
Modifier Examples...............................................................................................................287
Using Ignore Case.........................................................................................................287
Using Multi-Line Mode...................................................................................................288
Using Single-Line Mode.................................................................................................288
Using Multi-line Mode and Single-line Mode..................................................................289
xiv
Komodo User Guide
Table of Contents
Using the Rx ToolkitKomodo IDE only
Using Verbose................................................................................................................290
Using Regular Expressions..................................................................................................291
Perl.................................................................................................................................291
Python............................................................................................................................291
Tcl..................................................................................................................................291
PHP................................................................................................................................292
Ruby...............................................................................................................................292
Regular Expressions Primer.........................................................................................................294
About this Primer.................................................................................................................294
What are regular expressions?............................................................................................294
Matching: Searching for a String..........................................................................................294
Literal Match...................................................................................................................295
Wildcards.......................................................................................................................295
Escaping Metacharacters...............................................................................................296
Quantifiers......................................................................................................................296
Alternation......................................................................................................................298
Grouping with Parentheses............................................................................................299
Character Classes..........................................................................................................299
Negated Character Classes...........................................................................................300
Anchors: Matching at Specific Locations.......................................................................301
Substitution: Searching and Replacing................................................................................302
Modifiers..............................................................................................................................303
Modifier Summary..........................................................................................................303
Python Regex Syntax..........................................................................................................304
More Regex Resources.......................................................................................................304
Komodo and the Perl Dev KitKomodo IDE only.........................................................................305
Perl Dev Kit 6.......................................................................................................................305
Perl Dev Kit 3.1 to 5.3..........................................................................................................305
Configuring the General Tab..........................................................................................306
Configuring the Modules Tab.........................................................................................306
Configuring the Files Tab...............................................................................................307
Configuring the Version Tab..........................................................................................307
Configuring the Library Paths Tab.................................................................................307
Configuring the Extra Tab..............................................................................................308
Interpolation Shortcuts and Tab Stops.......................................................................................309
Interpolation Code List.........................................................................................................309
Basic Interpolation Shortcut Syntax.....................................................................................310
Non-Bracketed Syntax...................................................................................................310
Bracketed Syntax...........................................................................................................311
Basic Interpolation Shortcut Options....................................................................................311
%(date)................................................................................................................................312
%(date) Syntax...............................................................................................................312
%(date) Format Option...................................................................................................312
%(ask) and %(askpass).......................................................................................................313
xv
Komodo User Guide
Table of Contents
Interpolation Shortcuts and Tab Stops
%(ask) and %(askpass) Syntax.....................................................................................313
%(ask) and %(askpass) Options....................................................................................314
%(path)................................................................................................................................314
%(path) Syntax...............................................................................................................314
%(path) Options.............................................................................................................314
%(debugger)........................................................................................................................315
%(debugger) Syntax......................................................................................................315
%(debugger) Options.....................................................................................................315
%(pref).................................................................................................................................315
%(pref) Syntax...............................................................................................................315
Back-References.................................................................................................................316
Back-Reference Syntax.................................................................................................316
Tab Stops.............................................................................................................................316
Customizing Komodo....................................................................................................................318
Appearance Preferences.....................................................................................................318
Code Intelligence Preferences.............................................................................................319
Debugger PreferencesKomodo IDE only.............................................................................319
Debugger Connection Preferences................................................................................320
Advanced Debugger Preferences..................................................................................320
Directory Import...................................................................................................................320
Editor Preferences...............................................................................................................321
Configuring Key Bindings...............................................................................................322
Configuring Indentation..................................................................................................324
Smart Editing..................................................................................................................325
Save Options..................................................................................................................326
Environment.........................................................................................................................327
File Associations..................................................................................................................327
Fonts and Colors Preferences.............................................................................................328
Fonts..............................................................................................................................328
Colors.............................................................................................................................329
Common Syntax Coloring..............................................................................................330
Language-Specific Coloring...........................................................................................330
HTTP Inspector PreferencesKomodo IDE only...................................................................331
Interactive Shell PreferencesKomodo IDE only...................................................................331
Internationalization Preferences..........................................................................................331
Language Help Settings.......................................................................................................332
Configuring Reference Locations...................................................................................332
Using Language Help.....................................................................................................333
Language Configuration.......................................................................................................333
Configuring JavaScript...................................................................................................333
Configuring Perl.............................................................................................................333
Configuring PHP............................................................................................................334
Configuring Python.........................................................................................................334
Configuring Ruby...........................................................................................................335
Configuring Tcl...............................................................................................................335
Configuring HTML..........................................................................................................336
xvi
Komodo User Guide
Table of Contents
Customizing Komodo
Configuring XML Catalogs.............................................................................................337
Mapped URIs.......................................................................................................................337
New Files Preferences.........................................................................................................338
Printing Preferences............................................................................................................338
Projects and Workspace Preferences..................................................................................338
Servers Preferences............................................................................................................340
Shared Support Preferences...............................................................................................341
Sharing .tip, .pcx and .pdx Files.....................................................................................341
Sharing Preferences......................................................................................................341
Source Code Control PreferencesKomodo IDE only...........................................................342
CVS Integration..............................................................................................................342
Perforce Integration........................................................................................................343
Subversion Integration...................................................................................................343
Web and Browser Preferences............................................................................................344
Windows Integration Preferences........................................................................................344
Komodo Tutorial Overview...........................................................................................................346
Feature Showcase...............................................................................................................346
Perl Tutorial..........................................................................................................................346
PHP Tutorial.........................................................................................................................346
Python Tutorial.....................................................................................................................346
Ruby Tutorial........................................................................................................................346
XSLT Tutorial.......................................................................................................................347
Run Command Tutorial........................................................................................................347
Feature Showcase.........................................................................................................................348
Editing..................................................................................................................................348
Debugging............................................................................................................................348
Search..................................................................................................................................348
Tools....................................................................................................................................348
Project and Workspace........................................................................................................348
Feature Showcase: Code Completion Snippet...........................................................................349
Feature Showcase: Custom Toolbar...........................................................................................351
Feature Showcase: Debug an XSLT Program Komodo IDE only..............................................353
Feature Showcase: Shortcut to Commonly Used Directory......................................................356
Feature Showcase: Distributing a Project in a Package............................................................358
Feature Showcase: Fast String Finder........................................................................................362
Feature Showcase: Store a Filesystem Layout in a Project......................................................364
xvii
Komodo User Guide
Table of Contents
Feature Showcase: Google Run Command................................................................................366
Feature Showcase: Incremental Search......................................................................................368
Feature Showcase: Using the Interactive Shell Komodo IDE only...........................................370
Feature Showcase: Assign a Key Binding to a Toolbox Item...................................................372
Feature Showcase: Find and Open Files with the Open/Find Toolbar.....................................374
Feature Showcase: Reuse Code Fragments...............................................................................376
Feature Showcase: Test a Regular Expression with the Rx Toolkit Komodo IDE only..........377
Feature Showcase: Snippet that Prompts for Input...................................................................380
Feature Showcase: Store a Custom Template in a Project.......................................................382
Feature Showcase: Preview Cascading Style Sheets................................................................384
Perl Tutorial....................................................................................................................................386
Perl Tutorial Overview..........................................................................................................386
Before You Start.............................................................................................................386
Perl Tutorial Scenario.....................................................................................................386
Installing Perl Modules Using PPM......................................................................................386
Running the Perl Package Manager..............................................................................386
About PPM.....................................................................................................................387
Opening Files.......................................................................................................................387
Open the Perl Tutorial Project........................................................................................387
Open the Perl Tutorial Files...........................................................................................387
Overview of the Tutorial Files.........................................................................................387
Analyzing the Program.........................................................................................................388
Introduction....................................................................................................................388
Setting Up the Program..................................................................................................388
Writing the Output Header.............................................................................................388
Setting Up Input Variables.............................................................................................389
Starting the Processing Loop.........................................................................................389
Converting Characters with a Regular Expression........................................................389
Combining Field Reference and Field Data...................................................................390
Writing Data to the Output File.......................................................................................390
Closing the Program......................................................................................................390
Run the Program to Generate Output..................................................................................390
Debugging the Program.......................................................................................................391
More Perl Resources...........................................................................................................392
ASPN, the ActiveState Programmer Network................................................................392
Documentation...............................................................................................................392
Tutorials and Reference Sites........................................................................................392
xviii
Komodo User Guide
Table of Contents
PHP Tutorial...................................................................................................................................393
Overview..............................................................................................................................393
Before You Start.............................................................................................................393
PHP Tutorial Scenario....................................................................................................393
Opening the Tutorial Project................................................................................................393
Overview of the Tutorial Files.........................................................................................394
Open the PHP Tutorial File............................................................................................394
Analyzing the PHP Tutorial File...........................................................................................394
Analyzing guestbook.php.....................................................................................................394
Introduction....................................................................................................................394
HTML Header.................................................................................................................394
PHP Declaration and Datafile........................................................................................394
GuestBook Class...........................................................................................................395
GuestBook Function.......................................................................................................395
_getData Function..........................................................................................................396
outputData Function.......................................................................................................396
_createEntryHTML Function..........................................................................................396
_writeDataFile Function.................................................................................................397
addGuestBookEntry Function........................................................................................397
outputForm Function......................................................................................................398
Closing Tags..................................................................................................................398
Running the Program...........................................................................................................398
Debugging the Program.......................................................................................................399
More PHP Resources..........................................................................................................400
ASPN, the ActiveState Programmer Network................................................................400
Tutorials and Reference Sites........................................................................................400
Python Tutorial..............................................................................................................................401
Overview..............................................................................................................................401
Before You Start.............................................................................................................401
Python Tutorial Scenario................................................................................................401
Opening the Tutorial Project................................................................................................401
Overview of the Tutorial Files.........................................................................................402
Open the Python Tutorial File........................................................................................402
Analyzing the Python Files...................................................................................................402
Analyzing preprocess.py................................................................................................402
Setting Up the preprocess.py Program..........................................................................403
Defining an Exception Class..........................................................................................403
Initializing Global Objects...............................................................................................404
Defining a Private Method..............................................................................................404
Preprocessing a File......................................................................................................404
Analyzing contenttype.py...............................................................................................405
Open contenttype.py......................................................................................................405
Setting Up the contenttype.py Module...........................................................................406
Getting Data from content.types....................................................................................406
Running the Program...........................................................................................................407
Using a Run Command..................................................................................................407
Using the Debugger.......................................................................................................408
xix
Komodo User Guide
Table of Contents
Python Tutorial
Debugging the Program.......................................................................................................409
Explore Python with the Interactive Shell.............................................................................410
More Python Resources......................................................................................................411
ASPN, the ActiveState Programmer Network................................................................411
Tutorials and Reference Sites........................................................................................412
Preprocessor Reference................................................................................................412
Ruby Tutorial..................................................................................................................................413
Overview..............................................................................................................................413
Before You Start.............................................................................................................413
Ruby Tutorial Scenario...................................................................................................413
Opening the Tutorial Project................................................................................................413
Overview of the Tutorial Files.........................................................................................413
Open the Ruby Tutorial File...........................................................................................413
Analyzing the Ruby program................................................................................................414
Introduction....................................................................................................................414
Running the Program...........................................................................................................417
Debugging the Program.......................................................................................................417
More Ruby Resources.........................................................................................................418
Tutorials and Reference Sites........................................................................................418
Ruby on Rails Tutorial...................................................................................................................420
Overview..............................................................................................................................420
Before You Start.............................................................................................................420
Tutorial Scenario............................................................................................................420
Creating a Rails Project.......................................................................................................420
Creating the Database.........................................................................................................421
Editing the database.yml file..........................................................................................421
Running the Create Databases Macro...........................................................................421
Generating Models...............................................................................................................421
The Movie Model............................................................................................................422
The Person Model..........................................................................................................422
The Checkout Model......................................................................................................422
Migration........................................................................................................................423
Creating a Scaffold..............................................................................................................423
Starting the Webrick Server.................................................................................................423
Listing and Adding Movies...................................................................................................423
Editing a Title in Place.........................................................................................................424
Check Out a Movie..............................................................................................................425
Debugging Rails Komodo IDE only......................................................................................426
Returning a movie................................................................................................................427
Viewing Checkout Details....................................................................................................428
Rails Resources...................................................................................................................428
Tutorials and Reference Sites........................................................................................428
xx
Komodo User Guide
Table of Contents
JavaScript Tutorial........................................................................................................................429
Overview..............................................................................................................................429
Before You Start.............................................................................................................429
JavaScript Tutorial Scenario..........................................................................................429
Opening the Tutorial Project................................................................................................429
Overview of the Tutorial Files.........................................................................................429
Opening the City Picker.................................................................................................429
Analyzing the JavaScript program.......................................................................................430
Debugging the Page Komodo IDE only...............................................................................430
Starting the Debugger....................................................................................................430
Viewing and Changing Variables...................................................................................431
Adding Links........................................................................................................................431
More JavaScript Resources.................................................................................................432
Tutorials and Reference Sites........................................................................................432
XSLT Tutorial.................................................................................................................................433
XSLT Tutorial Overview.......................................................................................................433
Before You Start.............................................................................................................433
XSLT Tutorial Scenario..................................................................................................433
Opening the Tutorial Project................................................................................................433
Opening the XSLT Tutorial Files....................................................................................433
Overview of the Tutorial Files.........................................................................................434
Analyzing the Program.........................................................................................................434
XSLT Header.................................................................................................................434
HTML Header.................................................................................................................434
Format Email Header.....................................................................................................435
Process Email................................................................................................................435
Format Email Addresses................................................................................................436
Running the Program...........................................................................................................436
Debugging the Program.......................................................................................................437
More XSLT Resources.........................................................................................................438
ASPN, the ActiveState Programmer Network................................................................438
Documentation...............................................................................................................438
Tutorials and Reference Sites..............................................................................................438
Run Command Tutorial.................................................................................................................439
Run Command Tutorial Overview........................................................................................439
Run Command Tutorial Scenario...................................................................................439
Opening the Tutorial Project..........................................................................................439
Running Simple Commands................................................................................................439
Hello, World!...................................................................................................................439
Command Output Tab....................................................................................................440
Inserting Command Output............................................................................................440
Filtering Parts of a Document.........................................................................................440
Using Advanced Options.....................................................................................................441
Specifying a Command's Working Directory..................................................................442
Specifying Environment Variables.................................................................................442
Running GUI Apps or Running Commands in a Console..............................................443
xxi
Komodo User Guide
Table of Contents
Run Command Tutorial
Saving and Rerunning Commands......................................................................................443
Rerunning Recent Commands.......................................................................................443
Saving Commands in the Toolbox.................................................................................443
Saving Commands in a Project......................................................................................444
Editing Saved Command Properties..............................................................................444
Using Interpolation Shortcuts...............................................................................................445
Shortcuts for the Current File.........................................................................................446
Shortcuts for the Current Selection................................................................................447
Using Shortcuts for a Command's Directory..................................................................447
Prompting for Input..............................................................................................................448
Introduction....................................................................................................................448
Always Prompting with %(ask) or %(askpass)...............................................................448
Prompting When Necessary with %(...:orask)................................................................449
Parsing Command Output...................................................................................................449
Introduction....................................................................................................................449
Parsing Output with a Regular Expression....................................................................449
Using "Find in Files".......................................................................................................451
Komodo FAQ..................................................................................................................................453
Where is Komodo installed?................................................................................................453
Where does Komodo keep settings data?...........................................................................454
Where does Komodo log output and errors?.......................................................................454
Komodo doesn't start. Why?................................................................................................454
Why can't I see my Left or Right Pane.................................................................................455
I can't see my Bottom Pane.................................................................................................455
I want to maximize the Editor Pane.....................................................................................455
How do I know if I'm debugging?.........................................................................................455
How do I know if I'm editing?...............................................................................................455
How can I add command-line arguments to my program for debugging?...........................455
Komodo crashes. What can I do?........................................................................................456
Why is Komodo so big?.......................................................................................................457
I already have Mozilla. Why do I need to have two versions?.............................................457
I'm having trouble debugging PHP. What do I do?..............................................................457
How do I emulate sessions in PHP debugging?..................................................................458
How do I configure Virtual Hosting on an Apache Web server?..........................................459
I moved my Komodo installation on Linux, and am now getting Perl debugging errors......459
How do I prevent the dialog from displaying every time I start the debugger?....................459
Why do I get a CGI security alert when debugging PHP?...................................................460
When I click Check Configuration on the Start Page, Komodo reports that a language
that is installed on my system is not available. Why?.........................................................460
My screen goes black for a second or two whenever I open files for which Komodo
performs background syntax checking. Why?....................................................................460
How can I run additonal CVS commands from within Komodo?.........................................460
Why doesn't Ruby debugging work on my Linux x64 system?............................................461
xxii
Komodo User Guide
Table of Contents
Default Key Bindings.....................................................................................................................462
Windows/Linux Key Bindings (Default).......................................................................................463
Windows/Linux Scheme.......................................................................................................463
Code Browser................................................................................................................463
Code Intelligence...........................................................................................................463
Debugger.......................................................................................................................463
Editor..............................................................................................................................464
Find................................................................................................................................466
General..........................................................................................................................466
Help................................................................................................................................466
Macro.............................................................................................................................466
Source Code..................................................................................................................467
Source Control...............................................................................................................467
Tools..............................................................................................................................467
User Interface.................................................................................................................467
Snippets.........................................................................................................................468
OS X Key Bindings (Default).........................................................................................................470
OS X Scheme......................................................................................................................470
Code Browser................................................................................................................470
Code Intelligence...........................................................................................................470
Debugger.......................................................................................................................470
Editor..............................................................................................................................470
Find................................................................................................................................473
General..........................................................................................................................473
Help................................................................................................................................474
Macro.............................................................................................................................474
Source Code..................................................................................................................474
Source Control...............................................................................................................474
Tools..............................................................................................................................475
User Interface.................................................................................................................475
Snippets.........................................................................................................................475
Emacs Key Bindings (Default)......................................................................................................477
Emacs Scheme....................................................................................................................477
Code Browser................................................................................................................477
Code Intelligence...........................................................................................................477
Debugger.......................................................................................................................477
Editor..............................................................................................................................477
Find................................................................................................................................480
General..........................................................................................................................480
Help................................................................................................................................481
Macro.............................................................................................................................481
Source Code..................................................................................................................481
Source Control...............................................................................................................481
Tools..............................................................................................................................482
User Interface.................................................................................................................482
xxiii
Komodo User Guide
Table of Contents
Emacs Key Bindings (Default)
Snippets.........................................................................................................................482
Vi Key Bindings.............................................................................................................................484
Vi Emulation.........................................................................................................................484
Custom Vi Commands...................................................................................................484
Vi Scheme............................................................................................................................485
Vi key bindings...............................................................................................................485
XML Catalogs.................................................................................................................................488
Using an Existing XML Catalog...........................................................................................488
Creating an XML Catalog.....................................................................................................488
XML Catalog Resources......................................................................................................489
User-Defined Language Support..................................................................................................490
Introduction..........................................................................................................................490
Luddite Language Overview................................................................................................490
A Sample........................................................................................................................490
Luddite in a Nutshell............................................................................................................491
Families................................................................................................................................491
Styles...................................................................................................................................492
Keywords.............................................................................................................................492
Pattern Variables.................................................................................................................493
States and Transitions.........................................................................................................493
The Initial State..............................................................................................................494
Specifying State Transitions...........................................................................................494
Include, Upto, and EOF Conditions................................................................................494
Redo and Lookahead.....................................................................................................495
Preventing Keyword Promotion......................................................................................496
Pattern Syntax................................................................................................................496
Pushing States...............................................................................................................496
Handling Newlines.........................................................................................................497
Supporting Arbitrary Delimiters......................................................................................497
Disambiguation....................................................................................................................500
Specifying Folding................................................................................................................501
Recognizing XML Vocabularies...........................................................................................501
Compiling and Installing.......................................................................................................502
Samples...............................................................................................................................502
Luddite Reference................................................................................................................502
Keywords.............................................................................................................................503
Style Names.........................................................................................................................508
Terms...................................................................................................................................509
Concepts..............................................................................................................................509
xxiv
Welcome to Komodo IDE
•
What's new in Komodo 4.2
♦ A new spell checker (Tools|Check Spelling...).
♦ Upgraded Scintilla to version 1.74.
♦ Komodo now uses Scintilla's indicator bits for showing linter errors and warnings.
♦ Cursor shape is now configurable.
♦ Several code intelligence and debugging bug fixes.
•
Support and Community
The ActiveState Community site has resources to help you use Komodo effectively:
♦ Komodo FAQs
♦ Komodo Forums
•
Release Notes
♦ Bug Fixes
♦ Known Issues
Get started fast with Komodo's Sample Project.
Quick Demos showing advanced search functionality, editing, debugging, and more.
Helpful introductions to Ruby on Rails, JavaScript, Ruby, PHP, Perl, Python, XSLT and Run
Commands.
Welcome to Komodo IDE
1
New in 4.2.0 Beta 2
• Tab Stops
• Vim registers
• Several bug fixes
New in 4.2.0 Beta 2
2
New in 4.0
Code Intelligence
• Redesigned Code Intelligence system: CSS, JavaScript, Perl, PHP, Python, Ruby, Tcl
and XML support have been re-implemented with a new code intelligence system, providing
improvements in autocompletion, calltips, the code browser, and overall performance.
• Go to Definition: A new option for quickly jumping to the definition of a code object (e.g. a
variable, a subroutine, a module, etc.) under your cursor.
• Schema-based XML Autocomplete and CallTips: Komodo now supports autocomplete
and calltips support for XML and HTML based on DTD or RelaxNG Schema. SGML and
XML Catalogs are supported.
• API Catalogs: Autocompletion for several popular JavaScript libraries can be enabled in
Preferences.
• DOM Viewer: A new tab in the left pane shows the DOM structure of XML and HTML
documents in a tree view. Double-clicking on a node in the DOM Viewer moves the cursor
to the corresponding node in the document. Komodo IDE only
• User-Defined Languages: Komodo 4 introduces a system for adding custom language
support called UDL (User-Defined Languages) which allows Komodo to properly
syntax-color multi-language files and templated files common in many web programming
frameworks. Also included is a tool called Luddite which you can use to define custom
language syntax-coloring and package those into Komodo extensions.
• New languages: Support for Template-Toolkit, HTML-Mason, Smarty, Django, and Luddite
has been added using UDL
Editing
• Vi emulation: Modal keybindings which emulate the navigation, text insertion, visual
selection and command-line modes of Vi and Vim. Custom commands can be implemented
by adding Komodo macros to a Vi Commands Toolbox folder.
• Configurable Background Syntax Checking: The frequency of background syntax
checking is now configurable, improving editor responsiveness in large files.
HTTP InspectorKomodo IDE only
• HTTP Inspector: An interface for examining HTTP requests and responses as they
happen. It runs a local proxy which intercepts HTTP traffic and records each transaction for
analysis. The Inspector can break on a request or response, which can then be edited and
submitted in its modified form.
JavaScript DebuggingKomodo IDE only
• JavaScript Debugging: Komodo now offers JavaScript debugging using the Firefox web
browser and the JavaScript DBGP extension. With the extension enabled, loading
JavaScript or triggering JavaScript controls in the browser window opens a debugging
session in Komodo, which loads the relevant JavaScript code.
• JavaScript Interactive Shell: An interactive shell for manipulating JavaScript code is
New in 4.0
3
Komodo User Guide
available within JavaScript debugging sessions. This shell is similar in functionality to the
other interactive shells in Komodo.
Projects
• Live Folders: Komodo projects now offer Live Folders which display current filesystem
contents. The previous folder behavior is still available; these folders are now referred to as
"Virtual Folders" in the documentation. By default, new projects are created with Live
Import, making the project behave as a Live Folder. Project-specific Directory Import
preferences define which files and directories to include.
• Project Settings: All project settings are now in the Project Properties dialog. This dialog
box is now used for files, folders and projects, displaying the appropriate properties for each
type.
• Project Templates: Projects templates can be created and used when creating a new
project.
• Additional Project functionality, including:
♦ Project based debugger preferences
♦ Basic file management (Delete, Rename, Show in File Manager)
♦ Project import from remote file systems
♦ New File option
Other Improvements
• SCC History: A new option has been added to the Source Control menu which displays the
revision history of a file. You can compare (diff) two selected revisions from the list, or select
one and compare it to the local copy. Komodo IDE only
• SFTP and SCP: Komodo now supports access to remote files via SFTP and SCP. Saved
password information for all remote servers is stored securely in Mozilla's native password
manager.
• Help Browser: Komodo now uses Mozilla's help browser for displaying Komodo help.
• PHP "Zero Configuration": Automatic configuration for PHP debugging. Komodo IDE only
A list of additional improvements and the most important bug fixes can be found in the Release
Notes.
JavaScript DebuggingKomodo IDE only
4
Starting Komodo
Windows
From within the Windows environment, use one of the following methods to launch Komodo:
• double-click the Komodo desktop icon
• launch Komodo from the Windows program menu (Start|Programs|ActiveState Komodo
4.2|Komodo)
• right click a file name in Windows Explorer (and other dialogs that support the standard
Windows right-click context menu) and select Edit with Komodo
To start Komodo from a command prompt, enter:
komodo [options] [filenames]
Multiple filenames may be specified; all specified filenames will be loaded in the Komodo editor
pane.
The following command-line options are available:
• Help: -h or --help
• Show Komodo version: -V or --version
• Open at a specified line number: -l line or --line=line
• Open with a specified range selected: -s range or --selection=range
(e.g. komodo -s 1,5-2,15 example.py would open example.py and select from line
1 and column 5 to line 2 column 15)
Mac OS X
From within the OS X environment, use one of the following methods to launch Komodo:
• In the Dock, click the Komodo icon.
• In the Dock, click the "Finder" icon. In the left pane of the Finder dialog box, select
Applications. In the right pane of the Finder, double-click the Komodo file.
• On the Finder's Go menu, click Applications. In the right pane, double-click the Komodo
file.
To start Komodo from the Terminal:
If you want to start to Komodo from the command line, it is best to first create the following symlink:
sudo ln -s /Applications/Komodo.app/Contents/MacOS/komodo /usr/local/bin/komodo
Once the symlink is created, the following syntax applies:
komodo [options] [filenames]
All command line options described in the Windows section are available.
Starting Komodo
5
Komodo User Guide
Linux
To start Komodo from a shell prompt, enter:
komodo [options] [filenames]
All command line options described in the Windows section are available.
Desktop icons and taskbar applets are not added automatically during installation on Linux. Check
your window manager documentation for information on creating these manually. A choice of
Komodo icons is available. By default, the icon files (.xpm) are stored in the Komodo installation
directory.
Linux
6
Installing Komodo 4.2.0 Beta 2
• Windows
♦ Prerequisites
♦ Installing the Komodo License
♦ Upgrading from a Previous Komodo Version
♦ Installing Komodo on Windows
♦ Command Line Installation Options
♦ Starting Komodo on Windows
♦ Uninstalling Komodo on Windows
• Mac OS X
♦ Prerequisites
♦ Installing the Komodo License
♦ Upgrading from a Previous Komodo Version
♦ Installing Komodo on OS X
♦ Starting Komodo on OS X
♦ Uninstalling Komodo on OS X
• Linux
♦ Prerequisites
♦ Installing the Komodo License
♦ Upgrading from a Previous Komodo Version
♦ Installing Komodo on Linux
♦ Starting Komodo on Linux
♦ Uninstalling Komodo on Linux
• Language and Debugging Prerequisites
• Source Code Control Integration Prerequisites
Windows
Prerequisites
Hardware Requirements
• Intel x86 processor, 500 MHz (or faster) with 256 MB RAM.
• Up to 230 MB in your TMP directory (as indicated by the value of your 'TMP' environment
variable) during installation, even if you plan to install Komodo to another drive. If you do not
have the required space on this drive, manually set the 'TMP' environment variable to a
directory on a drive with sufficient space.
Operating System Requirements
Supported operating systems:
The following platforms are officially supported. Current Critical Updates, Windows Updates, and
Service Packs must be installed (see http://windowsupdate.microsoft.com).
• Windows Vista
• Windows XP
• Windows Server 2003
Installing Komodo 4.2.0 Beta 2
7
Komodo User Guide
• Windows 2000
Software Prerequisites on Windows
Installation Prerequisites:
• Windows 98, Me and NT users: Microsoft Windows Installer (MSI) version 2.0 or greater (
MSI 2.0 for 9x and Me, MSI 2.0 for NT)
• Windows 98/NT4 Users: Windows Scripting Host: Microsoft's Windows Scripting Host is
required by the Microsoft Windows Installer. Older versions of Windows did not include the
Windows Scripting Host. To check if your system has the Windows Scripting Host, select
Run from the Windows Start menu, and enter wscript. If the Windows Script Host Setting
dialog appears, WSH is installed on your system. If it doesn't, download the WSH from
Microsoft website.
Miscellaneous Prerequisites:
• Perl Dev Kit: In order to build executable programs, ActiveX controls and Windows services
in Perl, you must have ActiveState's Perl Dev Kit version 3.1 or greater installed on your
system.
Installing the Komodo License on Windows
Komodo IDE requires a 21-day Trial or Permanent license to run. For a 21-day Trial, follow the
license installation prompts when running Komodo for the first time. To install a Permanent license:
• Download the license installer from the My Downloads page.
• Double-click the downloaded installer.
Upgrading from Previous Komodo Versions
Newer versions of Komodo should not be installed in the same directory as older versions. For
major version upgrades (e.g. 3.5.3 to 4.0) the installer will automatically put Komodo in a new
directory. However for "point" release upgrades (e.g. 3.5 to 3.5.3), you should completely uninstall
the older version before installing the new one.
Installing Komodo on Windows
Before you start:
• If you intend to run the installation from a shared network drive, your system must have
SYSTEM rights (or greater) to the directory from which the installation is run. Alternatively,
run the installation from a local drive.
To install Komodo on Windows:
1. Ensure you have the prerequisite hardware and software.
2. Download the Komodo installer file.
3. Double-click the installer file and follow the instructions.
Prerequisites
8
Komodo User Guide
When installation is complete, you will see an ActiveState Komodo icon on your desktop.
Command Line Installation Options
Komodo can also be installed from the command line. For example:
c:\> msiexec.exe /i Komodo-<version>.msi
Komodo's installer uses Windows Installer technology, which allows you to partially control the
install from the command line. For example:
Installing the MSI in Silent Mode
You can have the Komodo installer run with a reduced user interface. For example, the following
will install silently and only open a dialog when the installation is complete.
c:\> msiexec.exe /i Komodo-<version>.msi /qn+
The following will install with no dialog at all.
c:\> msiexec.exe /i Komodo-<version>.msi /q
Turning on Logging
You can generate a log of the Komodo installation with the following command:
c:\> msiexec.exe /i Komodo-<version>.msi /L*v install.log
Controlling the Install Directory
Command line options can be used to configure Komodo installation properties. The following will
install Komodo to "E:\myapps\Komodo", instead of the default location:
c:\> msiexec.exe /i Komodo-<version>.msi INSTALLDIR=D:\myapps\Komodo
Controlling Which Features Get Installed
Komodo is divided into a number of distinct features. In the "Customize Setup" dialog you can
select which features to install. You can also do this on the command line with the ADDLOCAL
property. For example, the following command will install just the core Komodo functionality (i.e. not
the PyWin32 extensions or the documentation.
c:\> msiexec.exe /i Komodo-<version>.msi ADDLOCAL=core
The current set of Komodo features are:
core
env
desktop
quicklaunch
register
docs
Komodo core
Windows environment settings
Desktop shortcut
Quick launch shortcut
Register this as the default Komodo
Documentation
Installing Komodo on Windows
9
Komodo User Guide
The hierarchy denotes dependencies (i.e. to install quicklaunch you must install the env.
Uninstalling Komodo on Windows
To install Komodo 4.2.0 Beta 2, you must first uninstall any other Komodo 4.2 installation. You
may, however, install Komodo 4.2.0 Beta 2 side-by-side with other Komodo X.Y version (for
example Komodo 3.1) as long as you install to a separate and unique directory. Komodo 4.2 will
import settings from previous Komodo versions.
Starting Komodo on Windows
To start Komodo on Windows, use one of the following methods:
• Double-click the desktop icon.
• Select Start|Programs|ActiveState Komodo|Komodo.
• Add the Komodo install directory to your PATH environment variable, then from the
command line prompt, enter komodo.
Uninstalling Komodo on Windows
To uninstall Komodo, select Start|Programs|ActiveState Komodo|Modify, Repair or Uninstall
Komodo.
Alternatively, use the Add/Remove Programs menu (accessible from the Windows Control Panel).
Mac OS X
Prerequisites
Hardware Requirements
• Architecture: PowerPC (G4 processor or faster) or Intel
• 256 MB RAM or more
• 90 MB hard disk space
Operating System Requirements
• Mac OS X 10.3 (Panther) or later
Installing the Komodo License on OS X
Komodo IDE requires a 21-day Trial or Permanent license to run. For a 21-day Trial, follow the
license installation prompts when running Komodo for the first time. To install a Permanent license:
• Download the license installer from the My Downloads page.
• Double-click the downloaded zip file to unpack it (this is done automatically if you are using
Safari), and double-click the enclosed license installer.
Command Line Installation Options
10
Komodo User Guide
Upgrading from Previous Komodo Versions
Newer versions of Komodo should not be installed in the same directory as older versions. You
must uninstall the older version (or rename the .app) before installing the new one.
Installing Komodo on Mac OS X
To install Komodo:
• Download the Komodo disk image
(Komodo-Professional-<version>-macosx-<powerpc|x86>.dmg).
• If the browser does not automatically mount the disk image and open the mounted folder in
Finder, double-click the .dmg file to do so.
• Open a new Finder window. Drag the Komodo icon from the mounted folder to the
Applications folder.
• If desired, drag the Komodo icon into the Dock.
Starting Komodo on OS X
Click the Komodo icon in the Dock or the Applications folder.
Uninstalling Komodo on OS X
Drag the Komodo icon into the Trash.
Linux
Prerequisites
Hardware Requirements
• Intel x86 processor, 500 MHz (or faster) with 256 MB RAM (or greater)
• 100 MB hard disk space
• up to 200 MB of temporary hard disk space during installation
Operating System Requirements
Supported operating systems:
The following platforms are officially supported.
• Red Hat Enterprise Linux 3 (WS, ES and AS)
• SuSE 9.x
• Ubuntu 5.10 or later
Other operating systems:
Komodo can also be run on the following platforms. This version of Komodo has not necessarily
been tested on these platforms; platform-specific bugs may or may not be fixed.
Upgrading from Previous Komodo Versions
11
Komodo User Guide
• Fedora Core 2
• Red Hat 9.x
• SuSE 8.2
• Debian
• FreeBSD (with Linux binary compatibility)
• Gentoo
Software Prerequisites on Linux
Installation Prerequisites:
• glibc 2.1 (or higher) and libjpeg.so.62 (or higher): These libraries are included in
standard Linux distributions.
• libstdc++5 (or higher)
Adding Perl or Python to the PATH Environment Variable
To add Perl or Python to the PATH environment variable, do one of the following:
• Modify your PATH environment variable. For example, if you use the Bash shell, add the
following line to your ~/.bashrc file:
export PATH=<installdir>/bin:$PATH
...where <installdir> points to the directory where you installed ActivePerl or ActivePython.
• Create a symbolic link to the Perl or Python executable. For example, for ActivePerl, enter:
ln -s <installdir>/bin/perl /usr/local/bin/perl
For ActivePython, enter:
ln -s <installdir>/bin/python /usr/local/bin/python
...where <installdir> points to the directory where you installed ActivePerl or ActivePython.
Installing the Komodo License on Linux
Komodo IDE requires a 21-day Trial or Permanent license to run. For a 21-day Trial, follow the
license installation prompts when running Komodo for the first time. To install a Permanent license:
• Download the license installer from the My Downloads page.
• Change the permissions on the downloaded file to allow execution (e.g. `chmod +x
Komodo_<version>_<license#>.bin`)
• Run the installer (e.g. `./Komodo_<version>_<license#>.bin`).
Upgrading from Previous Komodo Versions
Newer versions of Komodo should not be installed in the same directory as older versions. For
major version upgrades (e.g. 3.5.3 to 4.0) the installer will automatically put Komodo in a new
directory. However for "point" release upgrades (e.g. 3.5 to 3.5.3), you should completely uninstall
Prerequisites
12
Komodo User Guide
the older version before installing the new one.
Installing Komodo on Linux
This version of Komodo allows non-root installation on Linux. Note, however, that the user who
executes the license file will be the user who is licensed to use the software.
To install Komodo on Linux:
1. Download the Komodo installer (.tar.gz file) into a convenient directory.
2. Unpack the tarball:
tar -xvzf Komodo-<version>-<build>-linux-ix86.tar.gz
3. Change to the new directory:
cd Komodo-<version>-<build>-linux-ix86
4. Run the install script ("install.sh"):
./install.sh
5. Answer the installer prompts:
♦ Specify where you want Komodo installed, or press 'Enter' to accept the default
location (/home/<username>/Komodo-x.x).
If multiple users are sharing the system and will be using the same installation,
install Komodo in a location every user can access (e.g. /opt/Komodo-x.x/ or
/usr/local/Komodo-x.x/).
Note: Each Komodo user requires their own license key.
Do not install Komodo in a path that contains spaces or non-alphanumeric
characters.
Be sure to install Komodo into its own directory (i.e. not directly in an existing
directory containing shared files and directories such as /usr/local).
♦ Verify that you have enough disk space.
6. Once the installer has finished, add Komodo to your PATH with one of the following:
♦ Add a symlink to Komodo/bin/komodo from another directory in your PATH:
ln -s <installdir>/komodo /usr/local/bin/komodo
♦ Add Komodo/bin to your PATH directly:
export PATH=<installdir>:$PATH
After completing the installation, you can delete the temporary directory where the Komodo tarball
was unpacked.
Starting Komodo on Linux
To start Komodo on Linux enter `komodo` at the command line or create a shortcut on your
desktop or in your toolbar using the full path to the komodo executable.
Upgrading from Previous Komodo Versions
13
Komodo User Guide
Uninstalling Komodo on Linux
To uninstall Komodo on Linux:
1. Delete the directory that Komodo created during installation.
2. If you wish to delete your Komodo preferences, delete the ~/.komodo directory. If you do
not delete this directory, subsequent installations of Komodo will use the same preferences.
Note: You cannot relocate an existing Komodo installation to a new directory by simply moving it.
You must uninstall Komodo from the existing location and reinstall it in the new location.
Language and Debugging Prerequisites
• Debugging: If firewall software is installed on the system, it must be configured to allow
Komodo to access the network during remote debugging.
• Perl: Perl 5.6 or greater is required to debug Perl programs. Download the latest version of
ActivePerl from the ActiveState website. Ensure that the directory location of the Perl
interpreter (by default, C:\perl) is included in your system's PATH environment variable.
Some advanced features, such as background syntax checking and remote debugging,
require ActivePerl.
• Python: Python 1.5.2 or greater is required to debug Python programs. You can download
the latest version of ActivePython from the ActiveState website. Ensure that the directory
location of the Python interpreter (by default C:\Pythonxx (where "xx" is the Python
version)) is included in your system's PATH environment variable. Some advanced features,
such as background syntax checking and remote debugging, require ActivePython. Python
1.5.2 or greater and a fully configured Tkinter installation are required to create Python
dialogs with the GUI Builder.
• PHP: PHP 4.0.5 or greater is required for PHP syntax checking. PHP 4.3.10 or greater is
required to debug PHP programs. Debugging and syntax checking are also available for
PHP 5.0.3 or greater. Download PHP from http://www.php.net/downloads.php. Ensure that
the directory location of the PHP interpreter (by default C:\PHP) is included in your
system's PATH environment variable. For complete instructions for configuring Komodo and
PHP, see Configuring the PHP Debugger. PHP debugging extensions are available on
ASPN, the ActiveState Programmer Network.
• Tcl: Tcl 7.6 or greater is required to debug Tcl programs. Download the latest version of
ActiveTcl from the ActiveState website.
• Ruby: Ruby 1.8 or greater is required to debug Ruby programs. Download the latest
version of Ruby from http://rubyinstaller.rubyforge.org/wiki/wiki.pl. Cygwin-based versions
of Ruby are currently unsupported.
Source Code Control Integration Prerequisites
• CVS Source Control Integration: Requires CVS, which is available from
http://www.nongnu.org/cvs/, or the latest stable version of CVSNT, which is available from
http://www.cvsnt.org/wiki/.
• CVS Source Control Integration using Putty (Windows): Requires Putty version 0.52 or
greater.
• Perforce Source Control Integration: Requires a connection to a Perforce server with
version 99.1 or later.
Uninstalling Komodo on Linux
14
Komodo User Guide
• Subversion Source Code Control Integration: Requires the Subversion client, which is
available from http://subversion.tigris.org/.
Source Code Control Integration Prerequisites
15
The Komodo Workspace
The Start Page
Komodo's Start Page is displayed by default when Komodo is first opened. It provides quick access
to, online resources, recently opened files and projects, tutorials, and a sample project. Select
Edit|Preferences|Appearance to hide sections of the page or disable opening it at startup.
Menus
The default drop-down menus are: File, Edit, Code, View, Debug, Project, Toolbox, Tools,
Window, and Help. The functions accessed from each menu are described in detail in the relevant
section of the User Guide. For example, the items accessed from the Debug menu are described in
Debugging Programs.
Note: On Mac OS X systems, a menu labelled Komodo is displayed to the left of the File menu.
On OS X, Komodo's Preferences dialog box is accessed by clicking Komodo|Preferences.
The Komodo Workspace
16
Komodo User Guide
Context Menus
Komodo displays right-click context menus with options relative to the area of Komodo where the
option was invoked, depending the location of the mouse pointer. Use the left mouse button to
select items from context menus.
• Menu Bar Areas and Toolbar Areas: Options to view or hide individual toolbars and
toolbar text (unavailable on Mac OS X).
• Projects Tab (Project Name): Options to open, save, activate, and close the projects, and
to add a file to the selected project.
• Projects Tab (File Name): Options to edit, remove or export the selected file ,and access
to source code control commands.
• Toolbox Tab: Options to work with the specified component.
• Editor Pane (File Editing Area): Options to cut, copy, and paste text, to set a breakpoint,
and to edit the file properties and settings.
• Editor Pane (Tabs): Options to close the selected file and to view the file's properties and
settings.
• Bottom Pane: The context menus available on tabs in the Bottom Pane (e.g. the Debug
tab and the Breakpoints tab) contain subsets of Komodo's top-level menus.
Toolbars
To hide or show toolbars, or to hide or show button text, do one of the following:
• From the View menu, select Toolbars.
• Right-click on a menu bar or toolbar, and toggle the check mark beside the pertinent option.
• From the Edit menu, select Preferences. (On Mac OS X, from the Komodo menu, select
Preferences.) Then, click the Appearance option and select or clear the desired options.
The Standard Toolbar provides quick access to common editing functions. Launch the Komodo
User Guide by clicking the Help button.
Context Menus
17
Komodo User Guide
The Tools Toolbar contains the commonly used commands on the Tools menu, including Preview
in Browser, the Regular Expression Toolkit, and the the interactive shell.
Komodo IDE only
The Workspace Toolbar toggles the main components of the Komodo workspace. Use this toolbar
to show/hide the Left Pane, Bottom Pane and Right Pane, and to display or shift focus to a specific
tab in one of these panes (e.g. the Toolbox tab).
The Debug Toolbar provides quick access to common debugging functions, such as Step In and
Step Over. For more information about debugging programs, see Debugging Programs.
Komodo IDE only
Use the Open/Find Toolbar to open files and search for strings. Find strings in files currently
displayed in the editor or in files not currently open in Komodo but located on the filesystem. See
Open/Find Toolbar for more information.
The Source Code Control Toolbar (Komodo IDE only) makes it easy to work with files that are
stored in Perforce or CVS. For more about using the Source Code Control Toolbar, see Source
Code Control.
Komodo IDE only
The Macros Toolbar makes it easier to record, play and save macros. For more information see
Macros.
For users of PDK 6.0 and later, the PDK Toolbar provides quick access to Perl Dev Kit tools.
Buttons for launching the core PDK tools (PerlApp, PerlSvc, PerlCtrl, and PerlTray) are grayed out
unless a Perl file is the active file in the Editor Pane. Availability of buttons depends on which
features are included in your PDK version. If the PDK is not installed on your system, all toolbar
options are grayed out when the PDK Toolbar is displayed. For more information on how the PDK
integates with Komodo, see Komodo and the Perl Dev Kit.
Toolbars
18
Komodo User Guide
It is also possible to create Custom Toolbars consisting of items in the Toolbox or Komodo projects
(e.g. run commands, code snippets and directory shortcuts).
Left Pane
The Left Pane of the Komodo workspace contains the Projects, Code and DOM tabs.
Projects Tab
The Projects tab displays projects that are currently open. Hide or display the components
contained in a project by clicking the plus sign to the left of the project name. To display the
Projects tab, select View|Tabs|Projects, or use the associated key binding.
Related Topics:
• Managing Projects and Files
• Managing Tabs and Panes
Code Tab Komodo IDE only
The Code tab displays a hierarchical view of all code symbols (for example, variables, methods,
imports) in an open file. Symbols can be sorted and filtered, and the current scope of a symbol can
be located. To display the Code tab, select View|Tabs|Projects, or use the associated key
binding.
Left Pane
19
Komodo User Guide
Related Topics:
• Code Browser
• Managing Tabs and Panes
DOM Viewer Tab Komodo IDE only
The DOM Viewer tab displays the DOM nodes (e.g. elements and attributes) of the current
document as a collapsible tree. The DOM Viewer lets you find, view and jump to any of these
nodes quickly.
Related Topics:
• DOM Viewer
• Managing Tabs and Panes
Code Tab Komodo IDE only
20
Komodo User Guide
Right Pane
The Right Pane of the Komodo workspace contains the Toolbox and, optionally, a Shared Toolbox.
Toolbox Tab
Use the Toolbox tab to manage and store Komodo components (for example, frequently used
files, code snippets, commands, and URLs). Add items to the Toolbox, as well as to folders within
the Toolbox. Items can be imported to the Toolbox and exported as Komodo project files and
packages. Items added to the Toolbox are displayed with associated icons for easy identification.
To display the Toolbox tab, select View|Tabs|Toolbox, or use the associated key binding.
Related Topics:
• Using the Toolbox
• Managing Tabs and Panes
Shared Toolbox Tab Komodo IDE only
A Shared Toolbox has the same functionality as the Toolbox except that it can be shared among
multiple users. For example, use a Shared Toolbox to store code snippets that are frequently used
by a number of programmers. The Toolbox tab is only available if the Shared Toolbox preference
has been set (select Edit|Preferences|Shared Support, or, on Mac OS X, select
Komodo|Preferences|Shared Support).
Right Pane
21
Komodo User Guide
Related Topics:
• Sharing Toolboxes
• Managing Tabs and Panes
Editor Pane
The large pane in the middle of the Komodo workspace is the Editor Pane. The Editor Pane is used
for editing and debugging. Each open file has a corresponding tab at the top of the Editor Pane.
Change the order of the tabs by clicking and dragging tabs to the desired position. The name of the
active file (that is, the file that is currently displayed in the Editor Pane) is displayed in bold text.
Use the left and right arrow buttons on the right side of the tabs to scroll though open files. Use the
close button "X" on the right side of the tab display to close the active file. An asterisk beside the
filename indicates that the file has been changed since it was opened, and needs to be saved. If a
file is under source code control, a file status icon to the left of the filename indicates its current
status.
Related Topics:
• Editing Files
• Managing Projects and Files
• Managing Tabs and Panes
Shared Toolbox Tab Komodo IDE only
22
Komodo User Guide
Bottom Pane
The Bottom Pane spans the width of the Komodo workspace and displays at the bottom of the
screen. The Bottom Pane contains the following tabs:
• Breakpoints Tab: manage breakpoints and spawnpoints in the current debugging
session(s)
• Command Output Tab: displays the results of commands run in the Run Command dialog
box
• Find Results 1 and Find Results 2 Tabs: display the results of the Find All function
• SCC Output Tab: displays details of source code control commands, such as editing or
checking in files
• Interactive Shell Tab: displayed when the interactive shell is launched as a stand-alone
tool or from within a debugging session
• Debug Tab: consolidates views of the debugger output, call stack, program variables (local
and global), and watched variables.
The Breakpoints, SCC Output, Interactive Shell, and Debug tabs are only available in Komodo IDE.
Managing Tabs and Panes
Use the View menu, Standard Toolbar or Komodo key bindings to choose which tabs are displayed
in the Komodo workspace. Use the Standard Toolbar to show and hide the Left Pane, Right Pane
and Bottom Pane.
Showing and Hiding Tabs
To display a tab in the Left Pane, Right Pane or Bottom Pane, select View|Tabs|<TabName>, or
see Komodo's default key bindings (Help|List Key Bindings) for the appropriate keyboard shortcut.
Alternatively, click the Show Specific Tab button on the Standard Toolbar.
Showing and Hiding Panes
To show and hide the Left Pane, Right Pane or Bottom Pane, click the associated button on the
Standard Toolbar. Click the close arrow in the top right corner of a pane to close it.
Bottom Pane
23
Komodo User Guide
Resizing Panes
When you are focusing on coding alone, you may want to maximize the Editor Pane. To increase
the size of the Editor Pane, hide the Left Pane and the Right Pane. The Left, Right and Bottom
Panes can be resized by clicking and dragging.
Enabling Full Screen Mode
To take advantage of as much of the Komodo workspace as possible, select View|Full Screen.
When Full Screen mode is enabled, the workspace is maximized, and the toolbars and status bar
are hidden. To restore the previous view, select View|Full Screen again.
Resizing Panes
24
Getting Started with the Sample Project
Komodo's sample project includes a number of programs in different languages. Use these sample
programs to familiarize yourself with Komodo's functionality.
Opening the Sample Project and Files
On Komodo's Start Page, click Open Sample Project. The Sample Project and its associated files
will display on the Projects tab.
To open a sample program, double-click the file name on the Projects tab. The contents of the file
will display in the Editor Pane.
Editing a Sample Program
Komodo includes sample programs written in Perl, Python, JavaScript, PHP, Tcl, and XSLT. Each
program is annotated with comments and exercises that describe Komodo's language-specific
features. Open the sample programs for languages that interest you, and read the comments to
explore Komodo's editing and debugging functionality.
Debugging a Sample Program
Komodo provides debugging support for Perl, Python, PHP, Tcl and XSLT. Komodo works with the
core language distribution for Perl, Python and PHP to provide interpreter support. XSLT, on the
other hand, is entirely self-contained. To debug the sample files for Perl, Python, PHP and Tcl, you
must configure the location of the language interpreter. See Configuring the Perl Debugger,
Configuring the Python Debugger, Configuring the Tcl Debugger, or Debugging PHP for
instructions. Then open the sample file for the desired language, and view the comments in the
"Debugging" section. General debugging functionality is discussed below.
1. Breakpoints: In the sample program, click on the gray margin to the immediate left of the
Editor Pane. A green circle will appear, indicating that a breakpoint has been set. When you
run the debugger, program processing will stop at lines where breakpoints have been set.
2. Start / Step Over / Step In: To start debugging, click the "Go" button on the Debug Toolbar.
When debugging begins, the Bottom Pane will be displayed beneath the Editor Pane in the
Komodo workspace. The program will run until a breakpoint is encountered; when program
execution pauses at a breakpoint, click "Step In" to move through the program in single line
increments, or "Step Over" to execute the entire function (as applicable), or "Step Out" to
execute the remainder of a function (as applicable).
3. Debug Tab: The tab labelled Debug: <filename> is displayed when debugging begins. In
addition to the debug output, the Debug tab displays the call stack, variables, and variable
values.
Getting Started with the Sample Project
25
Release Notes
Welcome to Komodo, ActiveState's Integrated Development Environment (IDE). This document
accompanies Komodo 4.2.0 Beta 2. See the Revision History for more detailed change information.
• New In This Release
• Bug Fixes
• Known Issues
New in Komodo 4.2
4.2 Beta 2:
• A new spell checker!
• Upgraded Scintilla to version 1.74.
• Komodo now uses Scintilla's indicator bits for showing linter errors and warnings
• Cursor shape is now configurable.
4.2 Beta 1:
• Upgraded Scintilla (Komodo's editor component) to the latest version.
• Add CSS autocomplete in HTML style="..." attributes. (Bug 66124)
• Komodo's documentation is now under a Creative Commons license to support translations
contributed by users. (Note: we are also working towards localization of the Komodo UI.)
• Many small documentation improvements.
• Add ability to change cursor shape to block mode. (Bug 68407)
4.1:
• Includes all features and improvements introduced in the 4.1 Beta series.
4.1 Beta 3:
• New Ruby on Rails project template that makes getting started and working with a Rails
project much easier.
• Autocomplete for the Komodo JavaScript API (i.e. the "ko" namespace) when editing
JavaScript macros in an editor tab. Also documentation for the "ko" namespace in the
Reference section of the Komodo docs.
• Komodo installations now include a "Komodo SDK" with Komodo's core IDL and the 'xpidl'
utility necessary for building PyXPCOM components for user extensions.
• Ruby completion: Added support for space-based calltips (common in RHTML template
code).
• Add info for PHP 5.2 stdlib changes for autocomplete/calltips.
4.1 Beta 2:
• All enhancements included in Komodo 4.0.3.
• MXML/ActionScript support: Added schema-based XML autocompletion for MXML files and
syntax highlighting for embedded ActionScript.
Release Notes
26
Komodo User Guide
• Re-written Ruby debugger engine: Based on ruby_debug, the new engine is 50-60 times
faster. See Rails Revisited for details.
• Many Ruby on Rails completion improvements.
• A new Ruby on Rails project template that includes integration for many rails project
commands.
• Significant refactoring of the Komodo JavaScript API under the "ko" namespace (e.g.
"ko.dialogs.alert(...)" instead of "dialog_alert(...)"). Old APIs remain for backward
compatibility for JavaScript macros -- but they will eventually be removed. This is an
ongoing process: documentation and autocomplete (when authoring macros) will be added
in subsequent releases.
• Rx integration (IDE-only) and regular expression help in the Find/Replace and Find in Files
dialogs.
• Add commands to fold/expand blocks of code recursively (View|Fold|Expand Recursively &
Collapse Recursively). (Bug 27264)
• Added a JavaScript tutorial to introduce some of Komodo's JavaScript features.
• Support editing macros in a full editor tab (via "right-click|Edit" on a macro).
• JavaScript completion: Added support for JSDoc autocomplete and calltips and
autocomplete on string literals (Bug 50587).
• Autocomplete: "fill-up" characters no longer enabled by default (Bug 68726).
• Find/Replace: Default (pre-populated) search pattern is now the previous search rather than
the word under the cursor.
• Statusbar: Added selection info ("Sel:") statusbar panel.
• Add more icons from famfamfam that can be used for custom commands, macros, etc. in
the Toolbox and Projects.
4.1 Beta 1:
• Vi registers: Added numbered and named registers similar to those in Vim.
• Tab Stops: Special markers for use in snippets and templates.
Bug Fixes
Bug fixes in source code control, debugging, interactive shells, Code Browser and DOM Viewer
apply to Komodo IDE only.
4.2 Beta 2
• Auto indent: Komodo now does utf-8-safe manipulation of buffers to avoid corrupting
multi-byte data. (Bug 69731)
• Debugger: Changes to Environment preferences now correctly appear in the debugger
options environment. (Bug 46233)
• Debugger: Break-button enabled only when language supports it. (Bug 35000)
• Debugger: Correct Intel OS X remote debugging packages now available on website. (Bug
70674)
• Editor: Safer use of scintilla getTextRange() with unicode. (Bug 70693)
• Extensions: Installation of XPI from drag'n'drop URL. (Bug 68865)
• JavaScript fixes:
♦ Codeintel: 'Go to definition' no longer fails for complex javascript. (Bug 70438)
♦ Codeintel: Last object variable is now being ciled correctly. (Bug 69979)
♦ Codeintel: Fixed exception thrown whilst scanning source files . (Bug 69725)
New in Komodo 4.2
27
Komodo User Guide
♦ Codeintel: Better handling of jsdoc comments. (Bug 68727)
♦ Codeintel: Update the included YUI API to verion 2.2.2. (Bug 66019)
♦ Debugger: Fixed problem of incorrectly showing startup page as firefox starts up.
• Key bindings: Keybindings upgrade correctly. (Bug 68489)
• Macros: Added project name to macro URI so it's easier to tell which project the current
macro being edited belongs to. (Bug 69028)
• Mapped URIs: Now go through the full preference chain properly. (Bug 69686)
• Perl: Debugger: Perl module LWP socket timing problem. (Bug 69900)
• Perl: Codeintel: Allow high-bit characters in variable names. (Bug 70166)
• PHP: Codeintel: Autocomplete now respects class access levels. (Bug 70423)
• PHP: Codeintel: Re-trigger calltips after completing a variable as a function argument. (Bug
70470)
• PHP: Codeintel: Function completions not working correctly when matches to a keyword.
(Bug 70718)
• PHP: UDL: Single-line comments now end at "?>". (Bug 70630)
• Prefs: The selected tab/language in the fonts-and-colors tab is now remembered. (Bug
56937)
• Python fixes:
♦ Fixed lexing in presence of decorators. (Bug 70645)
♦ Style decorators in their own color. (Bug 70648)
♦ Debugger: pydbgp now working with unknown locales. (Bug 70101)
♦ Django: Added additional keywords. (Bug 69852)
• Rails: Debugger: Works with version 1.8.6 on Windows. (Bug 70418)
• Rails: Debugger: Nicer alert provided for Edit users. (Bug 70069)
• Rails: UDL: Handle YAML templates with the &<<* syntax. (Bug 70664)
• Remote files: Upgrade of servers works from 4.1 to 4.2. (Bug 70187)
• Remote files: Dialog now shows file/folder icons on MacOS. (Bug 69776)
• SCC: Perforce: Better handling when saving file that encounters a SCC edit error.
• Tcl: Tcl instrument_set handled correctly. (Bug 39102)
• Templates: New projects always end with a .kpz extension. (Bug 68996)
• UDL: Template-toolkit: Improved handling of comments inside [% ... %] tags. (Bug 70508)
• Vi emulation fixes:
♦ Fixed checkbox becoming unchecked when setting up vi. (Bug 69623)
♦ Fixed Increase Line Indent in visual mode. (Bug 66778)
♦ Change/delete now working with find char "f" command. (Bug 70012)
♦ Added ":split" command support (bug 70083)
4.2 Beta 1
• Fixes and improvements to the Rails project template. (Bug 68407)
• Fixed bug causing a double warning icon in Editor tab for SVN file conflicts. (Bug 68534)
• Fixed bug causing two HTTP Inspector windows to be displayed. (Bug 70176)
• Fixed Vi emulation bug for commands with a number modifier. (Bug 66085)
4.1.1
• Fixed XML completion bug. (Bug 70342)
• Added '--dest-dir' option to Linux install script to facilitate building a Komodo RPM. (Bug
70311)
• Fix PHP completion bug preventing completions if prefix happened to be a keyword. (Bug
Bug Fixes
28
Komodo User Guide
69626)
• Fixes and improvements to the Rails project template. (Bug 69737)
• Fixed possible install failure related to a partly installed SELinux. (Bug 69969)
• Corrected the JavaScript tutorial's YUI library installation. (Bug 70129)
• Fixed bug with "Add to Current Project" adding file to the Toolbox instead. (Bug 68158)
• Fixed problem with '?' breaking Ruby syntax folding and coloring. (Bug 70326)
• Updated "New File" dialog to remember user's "Add to Current Project" preference. (Bug
66627)
• Updated PHP completion to support autocomplete in short tags -- i.e. "<? ...". (Bug 70212)
• Fixed Run Command system bugs:
♦ Redraw problems on Linux for Command Output parsing. (Bug 66860)
♦ Scrollbar doesn't show up in parsed command output. (Bug 67794)
• Fixed license problem in Tcl syntax checker that could prevent it from working. (Bug 70054)
• Fixed JavaScript class completion to work even if a parent class is not found. (Bug 65447)
• Many minor fixes for HTML completion in simple cases. (Bug 69973)
• Fixes for tabstops with non-word characters in the default value. (Bug 69949)
4.1
• HTML and RHTML autocompletion fixes. (Bug 69609, 69668, 65377, 69609, 69607, 65537,
65778)
• Various fixes to the Ruby on Rails project template. (Bug 69628, 69633, 69571, 69577,
69353)
• Ruby debugger now echos output from interactive shell sessions when in remote debugging
mode. (Bug 69401)
4.1 Beta 3
• Various Ruby debugger fixes. (Bug 69405, etc.)
• Syntax highlighting fixes for Template Toolkit. (Bug 69363, 69157)
• Fixed bug with suggested upperace HTML tag completions. (Bug 69523)
• Improved autocomplete in HTML fragments to be able to get autocomplete even in
documents with multiple top-level elements. (Bug 69521)
• Fixed problem with snippets inserting incorrect EOL characters. (Bug 69535)
• Fixed a bug with display of custom toolbar entries. (Bug 69424)
• Fixed inconsistencies in Live Folder behaviour. (Bug 69045)
• Changed the Find dialog box's default search term behavior. (Bug 68431)
• Fixed syntax checking of Tcl 8.5 code.
• Several bug fixes for remote files:
♦ 'Enter' not opening selected file in the remote file dialog. (Bug 67072).
♦ FTP not working on Windows IIS server. (Bug 69434)
♦ Prompt for password when not supplied in server prefs. (Bug 69344)
♦ paramiko (used for remote file support) missing from builds (Bug 69367).
• Fixed recursion overflow with long sequences of Perl comments. (Bug 69144)
4.1 Beta 2
• All bug fixes included in Komodo 4.0.3.
• Python completion: Catch potential recursion resulting in crash. (Bug 67739)
• JavaScript completion fixes. (Bug 67123, 60347, 68295, 60267, 60347)
Bug Fixes
29
Komodo User Guide
• PHP syntax highlighting fixes. (Bug 67678, 68140)
• Perl syntax higlighting now supports "/=". (Bug 67729)
• Find/Replace: Fixed problem using ctrl-tab to change to "replace" tab breaking
Find/Replace. (Bug 67079)
• Fixed some PHP/JavaScript syntax coloring issues. (Bug 67674)
• Fixed problem with Cancel being ignored when shutting down with dirty buffers. (Bug
67974)
• Help: Find locally installed ActivePerl documentation when it's the current preferred Perl
installation. (Bug 67622)
• Statusbar: Fixed width handling to show all data without clipping. (Bug 66209, 67181)
• Fix line and column numbers not updating immediately. (Bug 65606)
• Template Toolkit syntax higlighting fixes. (Bug 69157)
• HTML/XML auto-indent: Check styles to avoid auto-indenting in plain text when a line ends
with double-quotes. (Bug 66157)
• Auto-indent fixes. (Bug 63497, 66189)
• Fixed a crash possible with UTF16 conversion on Mac OS X. (Bug 67194)
• HTML syntax highlighting: Color style tag content as CSS. (Bug 66124)
• Support use of IE-only "comment-conditional" (Bug 46243)
• Vi emulation fixes:
♦ Delete not working at end of line. (Bug 62438)
♦ Support for find/replace in visual mode. (Bug 66776)
♦ Fix find/replace using invalid lines. (Bug 68241, 65619)
♦ Support "set" command. (Bug 66452)
♦ Support 'c' and 'C' case-sensitivity flags for searching.
♦ Add general toggle fold command. (Bug 66384)
• Autocomplete/calltips: Fixed "easy to outpace completion" problem by ensuring more timely
scanning of current file. (Bug 57938)
• Code Browser: Minor improvements in the hover tip for interface and namespace elements.
JavaScript "namespace" objects are shown with a different icon than a normal variable.
(Bug 68633)
• Fixed problem causing broken Open Shortcuts. (Bug 68666)
• Fixed problem causing uppercasing/lowercasing with rectangular selection. (Bug 68547)
• Dragging a folder onto a project now creates a new live folder. (Bug 68867)
• Projects: Creating a project template from a project with unsaved changes now prompts
user to save before continuing. (Bug 66958).
• Fixed crashes in libexpat on RedHat Linux RHEL3 U6. (Bug 68801)
• Interactive shell now properly handles pasted multi-line blocks. (Bug 51947)
• Project pane now correctly keeps collapse/expand state. (Bug 28603)
4.1 Beta 1
• Fixed scrolling selection to top or middle of screen so it takes folded lines into account. (Bug
35063)
• Perl: color scalar and array variables inside interpolating strings. (Bug 34374)
• Fixed confusing exit dialog when prompted to save files on shutdown. (Bug 35770)
• Preserve selection when converting EOLs. (Bug 34776)
• Fixed Lua syntax highlighting. (Bug 66107)
• Fixed a group of Emacs emulation issues. (Bug 33211)
• Added here-documents to PHP. (Bug 54667)
• Added ability to define here-document syntax in UDL-based languages. (Bug 66712)
Bug Fixes
30
Komodo User Guide
• Fixed Ctrl+F1 and Shift+F1 in the interactive shell. (Bug 37203)
• Added content to "Samples/Python" sample template. (Bug 32715)
• Added '.lsp' extension for Lisp files. (Bug 32681)
• Greater-than chars are allowed in SGML/XML quoted attribute strings. (Bug 67019)
• Offer to save macro when the contents are modified. (Bug 63577)
• vi emulation: add "tT;," find-character-in-line (Bug 67045)
• vi emulation: fix bug with '.' (repeat) (Bug 65945)
• vi emulation: fix bug of repeat last change/insert text not recording tab keypress (Bug
65963)
• vi emulation: fix some delete/change with direction commands. (Bug 65841, 65842)
• vi emulation: search history includes history from UI as well. (Bug 65639)
• vi emulation: support for Alt/Ctrl Tab window-switching while in visual mode. (Bug 67058)
• Removed 'url' attribute from project elements that don't have one. For snippets, macros, and
commands Komodo was raising a "file_added" notifification that contained "None" as part of
the string. (Bug 67574)
• Fixed SCC exceptions occurring due to SCC trying to check status of virtual files. (Bug
67583)
• Hover tips containing high-bit data while debugging now show up with Unicode characters,
not raw utf-8, or high-bit characters in the wrong encoding (such as programs that
manipulate Cyrillic text with a global cp1251 encoding). (Bug 40317)
• Diff windows now read-only. (Bug 27910)
Known Issues
To view the status of outstanding Komodo issues, including those that have been fixed in this
release, or to add comments or additional issues, please visit the Komodo Bug Database.
Object Browser
• The Object Browser is currently being re-implemented using Komodo's new Code
Intelligence backend and is not available in this release.
Installation & Upgrade
• When upgrading to a version of Komodo with a new application data directory (i.e. 4.0.1 to
4.0.3 or 4.0.3 to 4.1), the usernames and passwords for Remote Accounts are not imported.
These must be re-entered for each Server in the Server Preferences panel after the
upgrade.
• Windows Vista will prompt you to either 'Allow' or 'Deny' the installation. Click on 'Allow' and
Komodo will install normally.
• Windows NT users may need to manually move their license file from
\WINNT\Profiles\[username]\ActiveState to
\WINNT\Profiles\[username]\Application Data\ActiveState
(Bug 20203)
• If you upgraded your system from Win9x/WinME to WinNT/2K, ensure that your ComSpec
environment variable is configured to %SystemRoot%\system32\cmd.exe (for example,
C:\system32\cmd.exe). There was a bug in the Microsoft Windows installer that did not
update the variable from its original value of command.com
(Bug 9135)
Known Issues
31
Komodo User Guide
• The Komodo installer requires up to 230 MB in your TMP directory (as indicated by the
value of your 'TMP' environment variable) during installation, even if you plan to install
Komodo to another drive. If you do not have the required space on this drive, manually set
the 'TMP' environment variable to another directory with sufficient space. Ensure that you
have enough space, temporarily, for installation. (Bug 7057)
• If you try to install Komodo on Windows and the MSI install fails with error 2355, your MSI
file is corrupt. Please download Komodo again and re-run the MSI install. (Bug 7405)
• There are known issues regarding the installation of PHP on Windows Millennium systems;
please refer to the PHP site for installation information.
Startup
• The first time Komodo is run after installation, it must register a number of components with
the operating system. This causes the first launch to be considerably slower than
subsequent launches.
Projects and Toolboxes
• Projects and toolboxes created in Alpha releases of Komodo 4.0 may display components
in incorrect locations. Komodo 4.0 Beta fixes this bug and prevents this from happening in
new projects. To fix a corrupted project or toolbox, move the components to their correct
location and re-save. (Bug 53167)
Editing
• Autocompletion on the following Python Win32 modules is not yet available: dbc, perfmon,
pywintypes, win2kras, dde, pythoncom, and the binary sub-modules of win32com.
• The line and column cursor coordinates in the status bar are not updated while the cursor is
moving.
• The macro recorder will record events that it cannot handle, such as the opening of dialogs.
The only dialog that can be opened via a macro is the Find dialog; other dialogs will cause
the macro to stop.
• Languages that are read right to left and Asian languages are not supported. All Latin and
Cyrillic languages are fully supported. (Bug 29702)
• eTrust Antivirus Realtime Monitor and Komodo on Windows 9x: When RealMon is set to
monitor outgoing files (or both incoming and outgoing files), Komodo's syntax checking
doesn't function. (Bug 7741)
• On slow networks, users may notice performance degradation when editing files on network
machines. Performance can be improved by disabling the Komodo function that checks if
files on disk have changed. Use the Editor Preferences to disable this feature. (Bug 18297)
• Interpolation shortcuts in snippets are not executed when the snippet is inserted in the
Editor Pane via dragging and dropping.
• On Linux, GTK2 hard codes 'Ctrl'+'Shift' to use international input. Therefore, all key
bindings involving 'Ctrl'+'Shift'+ (any valid hexadecimal character} do not work in Komodo. A
workaround is to start Komodo with the command: export GTK_IM_MODULE=xim;
./komodo'. Otherwise, key bindings of this kind must be changed. (Bug 38205)
• When copying text that does not have Windows line endings into another application, which
expects Windows line endings, the text may not retain the desired formatting. The text is
often pasted as a single line. (Bug 36791)
Installation & Upgrade
32
Komodo User Guide
• Code snippets that are 8-bit-encoded and contain high-bit characters may have the wrong
encoding (or no encoding) when inserted from the Toolbox into a UTF-8 encoded file in the
Editor Pane. (Bug 36769)
• When editing a code comment in Komodo you may use <Shift+Enter> to start a new line
within the comment -- the comment prefix is added automatically. Komodo may fail to
properly add the comment prefix if many new lines are added quickly with repeated
<Shift+Enter> presses. (Bug 38658)
Debugging
• The Perl debugger uses alarm() internally. This can conflict with some Perl frameworks
and modules (such as POE) which use alarm() as well. To work around this problem, add
alarm=0 to the PERLDB_OPTS environment variable (in the Environment tab of the
Debugger Options) which stops the debugger from using alarm(). With this work-around
in place, the Break Now button and menu item will not work in debugging sessions.
• Using the JavaScript debugger on files with mapped URIs can yield confusing results.
Komodo will open the mapped source file rather than querying Firefox for the runtime
JavaScript.
• Python debugging with IronPython does not currently work as there is no support for Python
debugging hooks in IronPython.
• In PerlApp executables, it is now possible to step into loaded modules, but not to set
breakpoints in them.
• The Komodo JavaScript Debugger is incompatible with the FireBug Firefox extension.
FireBug must be manually disabled (Tools|Firebug|Disable Firebug) for the JavaScript
debugger to work. (Bug 47208)
• PHP 5.0.0, 5.0.1 and 5.0.2 do not work with the debugger extension. Use PHP versions
4.3.10 or greater, or 5.0.3 or greater, including 5.1.
• If the debug listener (Debug|Listen for Debugger Connections) is off, multithreaded
applications may not run or debug as expected. Only the main thread operates through the
debugger. To debug multithreaded applications, turn on debug listening prior to debugging.
(Debug listening is turned on by default.) (Bug 32776)
• PHP configurations that use Zend Extensions (such as PHP Accelerator) are not compatible
with the Komodo PHP debugger. (Bug 21890)
• Due to the way the core Perl interpreter works, it is not possible to step over "require"
statements. (Bug 18776)
• You cannot debug 'freestanding' executables created with the PDK in Komodo. Instead,
build a 'dependant' executable, which requires a local install of ActivePerl.
• The variable watcher does not work when debugging
\\machine\d$\path\to\perl_script.pl. It does work when opening the same file
via a UNC path that does not include a '$' character. (Bug 19558)
• When debugging remote applications, Komodo fails if the remote process does not have
valid stdout and stderr handles. GUI applications, such as those started with "wperl.exe" or
"pythonw.exe", or those using the Pythonwin or wxPython frameworks, or those with certain
embedded applications, can have invalid stdout and stderr handles. Until we resolve this
issue, try to run and debug your remote program under perl.exe or python.exe.
• Python, XSLT and PHP debugging require TCP/IP to be installed and properly configured,
even if you are debugging scripts locally. While TCP/IP is configured by default on most
systems, early versions of Windows may require manual TCP/IP configuration.
• When debugging a GUI script in Komodo, adding a "watched variable" when not stopped at
a breakpoint can cause Komodo to hang. You must manually terminate the script being
Editing
33
Komodo User Guide
debugged to stop Komodo from hanging. The problem occurs because the GUI script, while
in its message loop, does not respond to Komodo's request for the variable value. (Bug
23516)
• If the Komodo debugger is configured to use a specific port, when Komodo is shut down,
the port is sometimes not immediately released. If Komodo is restarted before the port is
released by the operating system, a message is displayed advising that the system is
unable to bind that port. As a workaround, we suggest configuring port 0 as the Komodo
debugging port and using the debugger proxy for remote debugging. (Bug 32821)
• Breaking into a running Perl script can only occur while crossing sub boundaries in the Perl
code, as that's currently the only chance the Perl debugger has to check to see if the IDE
has sent the break command. (Bug 35611)
• When debugging Perl, if you set a breakpoint on the while statement, the debugger stops
on the breakpoint only once, namely before the first pass through the loop. This is a
limitation in the Perl interpreter. (Bug 34866)
• Komodo debugger uses TCP/IP networking for communications. On systems with firewalls
installed, the debugger may fail if the firewall is not configured to allow Komodo to listen for
connections. On Windows, you may see a "Windows Security Alert" dialog asking if you
want to allow Komodo to listen for connections, you will need to unblock Komodo. (Bug
21684)
• The Perl debugger cannot trap fatal runtime errors. Users can accomplish this in their code
by wrapping problematic code in an eval block, and then testing for an exception. (Bug
33855)
• Komodo does not provide proper source debugging in Python exec and eval statements.
This is a limitation of Python's interpreter. (Bug 40336)
• When debugging PHP on a remote Linux machine from a local Windows machine, the
debugging option "Try to find files on the local system when remote debugging" has no
effect. This is due to differences in Unix and Win32 file paths. (Bug 39137)
• When debugging Python, Komodo does not permit you to set local variables in the
interactive shell. However, you can edit those values from the program's variable viewers,
such as the Watch and Locals panes on the Debug tab. (Bug 36794)
• When debugging PHP scripts on Komodo with CGI emulation, you may need to change the
setting for cgi.force_redirect in the php.ini file. You may also need to set an
environment variable in the Debugger Options dialog box: "REDIRECT_STATUS=200 OK".
These settings vary depending on your system and the configuration of PHP. (Bug 35021)
• When Debugging PHP, the HTML pane of the Output tab does not refresh automatically.
To refresh the contents of this pane, click the "Reload HTML view" button on the Output
tab. (Bug 36999)
• Komodo supports full Unicode debugging with Perl 5.8. Although Perl 5.6 can be used for
debugging programs with single-byte encodings (e.g. cp1251), it is recommended that
programmers with multi-byte character sets upgrade to Perl 5.8.5 or better. (Bug 36760)
• When debugging Python, if you launch the debugger from a directory containing a module
with the same name as one of the modules used by the debugger, the wrong file is used.
For example, if you have a file named logging.py in the directory where the debugger is
launched, the debugger will fail. (Bug 36783)
• When stepping through Perl files, the Komodo debugger displays the wrong print results in
the Locals window of the Debug tab. This is because Perl provides only one iterator for
each collection variable. The Komodo debugger must iterate through a hash or an array in
order to display the values in Komodo. A workaround is to display the Watch pane instead
of the Locals pane, and type the names of the expressions that you want to view. (Bug
33668)
Debugging
34
Komodo User Guide
Interactive Shell
• Perl: Only pattern variables $1 .. $9 are preserved across each query. (Bug 34528)
• Python: The getpass package requires the use of a tty on unix systems. Komodo does not
provide a tty in it's interactive shell so getpass will fail with an exception. (Bug 34259)
Source Code Control
• A bug in CVS will cause WinCVS and TortoiseCVS to detect file changes when a Komodo
project has merely been opened. The problem is likely a bug in the cvshome.org executable
or in the cvsnt.org executable, which are used by both WinCVS and TortoiseCVS. (Bug
21085)
• Komodo's integration with the Perforce commit/submit command cannot commit files that
are not in the default changelist. These files must be submitted via an external interface
(e.g. p4, P4Win). Note that any files checked out inside Komodo are in the default
changelist, so this limitation should only apply to users who already use an external
interface to their Perforce repository. (Bug 27070)
• If the Perforce connection cannot be established, checking the status of files in a Perforce
repository will hang Komodo. (Bug 35058)
• If you are using CVS Source Code Control, note that the very first time you log in to a
repository, cvs.exe fails to create the .cvspass file correctly and will return an error. Repeat
the command to login a second time and correctly generate the file. This is a CVS bug.
(Bug 20353)
• If you are using CVS Source Code Control on Windows 98 or Me, the environment variables
HOMEDRIVE and HOMEPATH must be configured on your system. Typically, HOMEDRIVE is
set to "c:", and HOMEPATH is set to "\".
GUI Builder
• GUI Builder is no longer included with Komodo. The code has been returned to the open
source project that it came from, SpecTcl. You can find more information about SpecTcl at:
http://spectcl.sourceforge.net/
Binaries for GUI Builder that support Komodo 3.x UI projects can be found here.
Mac OS X
• If you have two drives with the same name, and you use the file open dialog in a mozilla
application, the directory menu (top middle of dialog) may crash when clicked. To avoid this,
rename one of the hard drives.
• New Custom Menus created in a Project or in the Toolbox will not appear until Komodo has
been restared.
• Throughout the Komodo documentation there are references to key bindings that use the
'Meta' key. This key may be better known to OS X users as the 'Command' key. (Bug
41959)
• Komodo will shut down and restart itself the first time it is run after installation. (Bug 40143)
• Display of text during editing ("painting") may sometimes be slow or pause momentarily.
• Certain UI elements stop working after changing key bindings. Restarting Komodo fixes this.
Interactive Shell
35
Komodo User Guide
(Bug 38683)
• When saving a file, Komodo does not set file information (type and creator) for the OS X
Finder to know that Komodo created the file. (Bug 38745)
• Breakpoints cannot be removed when debugging XSLT scripts. (Bug 40072)
• PHP debugging will not work with the PHP build distributed with OS X because it does not
load external modules. To use PHP debugging on OS X, build PHP from source or
download a binary from http://www.entropy.ch/software/macosx/php
(Bug 39901)
• Komodo is sometimes recognized as a web browser by some applications on OS X (e.g.
Safari's "Default Web Browser" setting). Using Komodo as the default web browser is not
recommended.
• Application menu items that have multi-key key bindings will not show their key bindings in a
pop-up tool tip on OS X. This is a limitation in OS X.
• Context menus may not display unless you hold down the mouse button for a period of
time. This is because the Komodo editor is implemented in Mozilla as a plugin, and it does
not access the apropriate context menu event to handle this behaviour properly without
interfering with other mouse events (for example, drag and drop). (Bug 41216)
• Due to a limitation in the Mozilla code base, key bindings for the Next File and Previous
File options on the Window menu are not displayed next to the menu items. The key
bindings are 'Meta'+'PageDown' to view the next file and 'Meta'+'PageUp' to view the
previous file. (Bug 40716)
Linux
• When closing any Komodo window that contains an editor component, a GLIB error entry
will appear in the log files (or terminal if Komodo was started from one). This error can be
safely ignored. A patch was submitted by the Mozilla group to the Gnome group that
handles this error, and should be available in GTK 2.4 or higher. The patch can be viewed
at http://bugzilla.gnome.org/show_bug.cgi?id=128546
(Bug 33817)
• The Fonts and Colors pane in the Preferences dialog box displays the same list of fonts in
both the Fixed and Proportional lists. There is no programmatic way to identify whether a
font is proportional or not on GTK; therefore, users must know the properties of the
individual fonts when modifying these values. (Bug 27206)
• If the GTK theme is changed while Komodo is running, Komodo will not change the
menu/toolbar font colors, causing usability problems in extreme cases. (Bug 34508)
• Install Komodo into a directory path that only includes alphanumeric characters. Komodo is
known to have trouble with paths that include spaces and some non-alphanumeric
characters.
• Filenames or paths containing non-ASCII characters cannot be opened remotely.
• Key bindings defined in the window manager (such as KDE) take precedence over Komodo
key bindings. In the case of conflicts, you must either change the Komodo key bindings or
the window manager key bindings. (Bug 30926)
• You cannot move an existing Komodo installation to a new directory. You must uninstall
Komodo from the existing location and reinstall it in the new location. (Bug 19478)
• When using the PHP Configuration Wizard, you must have write access to any directories
you specify in the wizard. (Bug 37176)
• Red Hat Linux 9.0 is known to have threading library bugs in its glibc that may cause
Komodo to hang in certain situations. The recommended solution is to upgrade to the latest
glibc for Red Hat Linux 9.0. (Bug 24340)
Mac OS X
36
Komodo User Guide
• Using colon-separated include paths in the Perl shebang line causes a parse failure on
some versions of Perl. Instead of using "/usr/bin/perl -cwT -I/path1:/path2 yourscript.pl", try
using multiple include arguments such as "/usr/bin/perl -cwT -I/path1 -I/path2 yourscript.pl"
(Bug 33524)
• Komodo may not start up correctly on some Linux systems if C++ compatibility libraries
have not been installed. On Fedora and Red Hat systems, install the "compat-libstdc++"
package. On SuSE, install the "compat" package. On Gentoo, as root, run emerge
lib-compat. This is not thought to be a problem on Debian systems. (Bug 36244)
• Komodo will work on Debian/Ubuntu AMD64 with some manual configuration (some
libraries were not properly ported to support 32-bit applications). (Bug 41368) Run Komodo
from a shell script which sets certain environment variables:
#!/bin/sh
export GTK_PATH=/usr/lib32/gtk-2.0/
export PANGO_RC_FILE=/etc/pango32/pangorc
komodo
The pangorc file should contain the following:
[Pango]
ModuleFiles=/etc/pango32/pango.modules
[PangoX]
AliasFiles=/etc/pango/pangox.aliases
More information on running 32 bit Mozilla applications on AMD64 can be found here.
Other
• A limitation in the parser used by the DOM Viewer causes HTML elements embedded in
JavaScript strings to appear as element nodes of the current document. Placing the
JavaScript in a CDATA section or a comment avoids this problem.
• Komodo inherits a Mozilla bug whereby certain video drivers on Windows cause Komodo to
crash. If you experience this behavior, upgrade your video driver to the latest version. If the
problem persists, reduce the color definition assigned to the driver (Control
Panel|Display|Settings). (Bug 32746)
• Komodo inherits a Mozilla bug regarding display on dual-monitor systems where the
secondary monitor is to the left of the primary monitor (causing negative coordinate results).
The Komodo display occasionally fails to refresh; Komodo must be stopped and restarted to
fix the display (Bug 26852)
• When using Komodo's Preview in Browser feature, users running Mozilla on Windows XP
Pro, Windows 2000 Pro and Windows 98 may find that they cannot exit Komodo if Mozilla is
still open. If this should occur, close all open browser windows before exiting Komodo. (Bug
26431)
• The Palm Desktop for Windows software makes exclusive use of the 'Ctrl'+'Shift'+'T' key
combination, thus making this combination unavailable in Komodo. (Bug 27851)
• When using the PDK Build Standalone Application feature in Komodo with Perl 5.8.0 on a
Linux installation where the environment is set to use UTF-8, you must add a module 'utf8'
on the modules tab. This is the equivalent of 'perlapp --add utf8'. This does not affect Perl
5.6.x or future versions of Perl 5.8.1 or higher. (Bug 26898)
• On Windows NT, some interactive commands may not work properly when run from the
Command Output tab of the Output Pane. You must run these commands in a separate
shell. (Bug 23176)
Linux
37
Komodo User Guide
• Running interactive commands (especially "command.com") on Win98/ME through
Komodo's "Run Command" feature can cause Komodo to hang. It is recommended that
Win98/ME Komodo users run only simple commands using the Run Command feature (Bug
25699)
• In file picker dialogs that display a list of files, when "All files" is specified, files that begin
with a period are not displayed (Bug 18712)
• Perforce client version 2001.1 and previous for Windows is known to hang when used for
Komodo's Perforce integration. Upgrading to the most recent version of Perforce is known
to fix the problem. (Bug 19959)
• The Output tab cuts off lines at 250 characters. (Bug 20711)
• Macros will not record certain commands, including (but possibly not limited to)
'Ctrl'+'Shift'+'B'|'R'|'E'|'D' (toggle toolbars or button text), 'Ctrl'+'Shift'+'N' (new default file),
and View as Language menu items.
• If you are using the Pop-Up Stopper ad-blocking program (Pop-Up Zapper on OS X), it will
close the Rx Toolkit window immediately after it is opened. (Bug 21768)
• When you schedule a new file to be added using CVS, CVS will not permit you to remove
the file from the repository using the "revert changes" command. (Bug 27192)
• Users of the Japanese version of Windows XP may experience difficulties in starting
Komodo.
• The Open field in the Open/Find Toolbar does not automatically display a drop-down list of
directories when an UNC path is typed. Currently, the list is only displayed when a the path
includes a subdirectory. (Bug 29011)
• When creating a "diff" in Komodo (Tools|Compare Files), the line endings of the files are
normalized to Unix style line endings. Lines in files that have different line endings are not
displayed differently in the diff (unless other differences are present), but a warning is
provided to the user in the 'diff' window, or the 'no difference' dialog. (Bug 32932)
• In Komodo's Rx Toolkit, the match offsets for unicode or high-bit data are incorrect. When
matching, the program does not account for UTF-8 multibyte characters. (Bug 33287)
• When adding new key bindings via the Preferences dialog box, Komodo displays a
message indicating that the key bindings will not take effect until Komodo is restarted.
However, some changes do take effect immediately.(Bug 36710)
• "Find" macros do not work because incorrect code is recorded. (Bug 36332)
• If you rename a folder that was added to a custom menu, the name is changed in Komodo's
Toolbox but not on the menu itself. A workaround is to move the renamed folder out and
then back into the associated custom menu icon in the Toolbox. (Bug 36679)
• The Mozilla code base currently does not support the Windows Unicode binary. As a result,
Komodo for Windows is unable to open files or paths that contain character sets that are not
in the systems locale. (Bug 33304)
• A newly created custom menu is added to the Toolbox but is not immediately displayed
alongside existing toolbars. Restarting Komodo causes the new toolbar to display. (Bug
40078)
Other
38
Revision History
This document chronicles feature additions, product enhancements and bug fixes in previous
versions of Komodo.
• Komodo IDE/Edit 4.1 (May 15, 2007)
• Komodo IDE/Edit 4.1 Beta 3 (May 9, 2007)
• Komodo IDE/Edit 4.1 Beta 2 (April 27, 2007)
• Komodo IDE/Edit 4.0.3 (April 17, 2007)
• Komodo IDE/Edit 4.1 Beta 1 (March 6, 2007)
• Komodo IDE/Edit 4.0.2 (February 13, 2007)
• Komodo IDE 4.0.1 (January 29, 2007)
• Komodo IDE 4.0, Edit 4.0 Beta 5 (January 22, 2007)
• Komodo 4.0 Beta 4 (January 11, 2007)
• Komodo 4.0 Beta 3 (December 14, 2006)
• Komodo 4.0 Beta 2 (November 27, 2006)
• Komodo 4.0 Beta 1 (October 31, 2006)
• Komodo 4.0 Alpha 7 (October 24, 2006)
• Komodo 4.0 Alpha 6 (September 19, 2006)
• Komodo 4.0 Alpha 5 (September 1, 2006)
• Komodo 4.0 Alpha 4 (August 24, 2006)
• Komodo 4.0 Alpha 3 (July 25, 2006)
• Komodo 4.0 Alpha 2 (July 11, 2006)
• Komodo 4.0 Alpha 1 (June 26, 2006)
• Komodo 3.5.3 (May 4, 2006)
• Komodo 3.5.3 Beta 1 (March, 2006)
• Komodo 3.5.2 (December 6, 2005)
• Komodo 3.5.1 (November 29, 2005)
• Komodo 3.5.1 Beta 1 (November 22, 2005)
• Komodo 3.5 for Mac OS X, 3.5 Beta 1 for Windows and Linux (November 2, 2005)
• Komodo 3.5 Beta 3 for Mac OS X, 3.5 Alpha 2 for Windows and Linux (October 28, 2005)
• Komodo 3.5 Beta 2 for Mac OS X, 3.5 Alpha 1 for Windows and Linux (October 11, 2005)
• Komodo 3.5 Beta 1 for Mac OS X (October 4, 2005)
• Komodo 3.5 Alpha 1 for Mac OS X (August 2, 2005)
• Komodo 3.1 (February, 2005)
• Komodo 3.1 Beta 2 (January, 2005)
• Komodo 3.1 Beta 1 (January, 2005)
• Komodo 3.1 Alpha 4 (December, 2004)
• Komodo 3.1 Alpha 3 (November, 2004)
• Komodo 3.1 Alpha 2 (October, 2004)
• Komodo 3.1 Alpha 1 (October, 2004)
• Komodo 3.0.1 (August, 2004)
• Komodo 3.0 (July, 2004)
• Komodo 2.5.2 (January, 2004)
• Komodo 2.5.1 (October, 2003)
• Komodo 2.5 (September, 2003)
• Komodo 2.3 (February, 2003)
• Komodo 2.0.1 for Linux (November, 2002)
• Komodo 2.0 for Windows (September, 2002)
• Komodo 1.2.9 (July, 2002)
Revision History
39
Komodo User Guide
• Komodo 1.2 for Windows and Linux (December, 2001)
• Komodo 1.1 (June, 2001)
Komodo IDE/Edit 4.1 (May 15, 2007)
Enhancements
Includes all features added in the 4.1 Beta series.
Bug Fixes
Includes all bugs fixed in the 4.1 Beta series.
Komodo IDE/Edit 4.1 Beta 3 (May 9, 2007)
Enhancements
• New Ruby on Rails project template that makes getting started and working with a Rails
project much easier.
• Autocomplete for the Komodo JavaScript API (i.e. the "ko" namespace) when editing
JavaScript macros in an editor tab. Also documentation for the "ko" namespace in the
Reference section of the Komodo docs.
• Komodo installations now include a "Komodo SDK" with Komodo's core IDL and the 'xpidl'
utility necessary for building PyXPCOM components for user extensions.
• Ruby completion: Added support for space-based calltips (common in RHTML template
code).
• Add info for PHP 5.2 stdlib changes for autocomplete/calltips.
Bug Fixes
• Various Ruby debugger fixes. (Bug 69405, etc.)
• Syntax highlighting fixes for Template Toolkit. (Bug 69363, 69157)
• Fixed bug with suggested upperace HTML tag completions. (Bug 69523)
• Improved autocomplete in HTML fragments to be able to get autocomplete even in
documents with multiple top-level elements. (Bug 69521)
• Fixed problem with snippets inserting incorrect EOL characters. (Bug 69535)
• Fixed a bug with display of custom toolbar entries. (Bug 69424)
• Fixed inconsistencies in Live Folder behaviour. (Bug 69045)
• Changed the Find dialog box's default search term behavior. (Bug 68431)
• Fixed syntax checking of Tcl 8.5 code.
• Several bug fixes for remote files:
♦ 'Enter' not opening selected file in the remote file dialog. (Bug 67072).
♦ FTP not working on Windows IIS server. (Bug 69434)
♦ Prompt for password when not supplied in server prefs. (Bug 69344)
♦ paramiko (used for remote file support) missing from builds (Bug 69367).
• Fixed recursion overflow with long sequences of Perl comments. (Bug 69144)
Komodo IDE/Edit 4.1 (May 15, 2007)
40
Komodo User Guide
Komodo IDE/Edit 4.1 Beta 2 (April 27, 2007)
Enhancements
• All enhancements included in Komodo 4.0.3.
• MXML/ActionScript support: Added schema-based XML autocompletion for MXML files and
syntax highlighting for embedded ActionScript.
• Re-written Ruby debugger engine: Based on ruby_debug, the new engine is 50-60 times
faster. See Rails Revisited for details.
• Many Ruby on Rails completion improvements.
• A new Ruby on Rails project template that includes integration for many rails project
commands.
• Significant refactoring of the Komodo JavaScript API under the "ko" namespace (e.g.
"ko.dialogs.alert(...)" instead of "dialog_alert(...)"). Old APIs remain for backward
compatibility for JavaScript macros -- but they will eventually be removed. This is an
ongoing process: documentation and autocomplete (when authoring macros) will be added
in subsequent releases.
• Rx integration (IDE-only) and regular expression help in the Find/Replace and Find in Files
dialogs.
• Add commands to fold/expand blocks of code recursively (View|Fold|Expand Recursively &
Collapse Recursively). (Bug 27264)
• Added a JavaScript tutorial to introduce some of Komodo's JavaScript features.
• Support editing macros in a full editor tab (via "right-click|Edit" on a macro).
• JavaScript completion: Added support for JSDoc autocomplete and calltips and
autocomplete on string literals (Bug 50587).
• Autocomplete: "fill-up" characters no longer enabled by default (Bug 68726).
• Find/Replace: Default (pre-populated) search pattern is now the previous search rather than
the word under the cursor.
• Statusbar: Added selection info ("Sel:") statusbar panel.
• Add more icons from famfamfam that can be used for custom commands, macros, etc. in
the Toolbox and Projects.
Bug Fixes
• All bug fixes included in Komodo 4.0.3.
• Python completion: Catch potential recursion resulting in crash. (Bug 67739)
• JavaScript completion fixes. (Bug 67123, 60347, 68295, 60267, 60347)
• PHP syntax highlighting fixes. (Bug 67678, 68140)
• Perl syntax higlighting now supports "/=". (Bug 67729)
• Find/Replace: Fixed problem using ctrl-tab to change to "replace" tab breaking
Find/Replace. (Bug 67079)
• Fixed some PHP/JavaScript syntax coloring issues. (Bug 67674)
• Fixed problem with Cancel being ignored when shutting down with dirty buffers. (Bug
67974)
• Help: Find locally installed ActivePerl documentation when it's the current preferred Perl
installation. (Bug 67622)
• Statusbar: Fixed width handling to show all data without clipping. (Bug 66209, 67181)
• Fix line and column numbers not updating immediately. (Bug 65606)
• Template Toolkit syntax higlighting fixes. (Bug 69157)
Komodo IDE/Edit 4.1 Beta 2 (April 27, 2007)
41
Komodo User Guide
• HTML/XML auto-indent: Check styles to avoid auto-indenting in plain text when a line ends
with double-quotes. (Bug 66157)
• Auto-indent fixes. (Bug 63497, 66189)
• Fixed a crash possible with UTF16 conversion on Mac OS X. (Bug 67194)
• HTML syntax highlighting: Color style tag content as CSS. (Bug 66124)
• Support use of IE-only "comment-conditional" (Bug 46243)
• Vi emulation fixes:
♦ Delete not working at end of line. (Bug 62438)
♦ Support for find/replace in visual mode. (Bug 66776)
♦ Fix find/replace using invalid lines. (Bug 68241, 65619)
♦ Support "set" command. (Bug 66452)
♦ Support 'c' and 'C' case-sensitivity flags for searching.
♦ Add general toggle fold command. (Bug 66384)
• Autocomplete/calltips: Fixed "easy to outpace completion" problem by ensuring more timely
scanning of current file. (Bug 57938)
• Code Browser: Minor improvements in the hover tip for interface and namespace elements.
JavaScript "namespace" objects are shown with a different icon than a normal variable.
(Bug 68633)
• Fixed problem causing broken Open Shortcuts. (Bug 68666)
• Fixed problem causing uppercasing/lowercasing with rectangular selection. (Bug 68547)
• Dragging a folder onto a project now creates a new live folder. (Bug 68867)
• Projects: Creating a project template from a project with unsaved changes now prompts
user to save before continuing. (Bug 66958).
• Fixed crashes in libexpat on RedHat Linux RHEL3 U6. (Bug 68801)
• Interactive shell now properly handles pasted multi-line blocks. (Bug 51947)
• Project pane now correctly keeps collapse/expand state. (Bug 28603)
Komodo IDE/Edit 4.0.3 (April 17, 2007)
Enhancements
• Recursive scanning of PHP and JavaScript Directories: PHP and JavaScript Directories set
in global and project preferences are now recursive (up to five sub-directories deep). These
directories, used by Komodo for gathering autocomplete and calltip information, previously
had to be added individually.
• Reinstated "Y" yank-command in Vi mode.
• HTML templates now start with all lower-case tags.
Bug Fixes
• Fixed problem with 'Go to Definition' on imported class instance variables in PHP. (Bug
68793)
• PHP calltips now working on inherited methods. (Bug 68759)
• Better error and timeout handling of remote connections (e.g. wrong port or protocol). (Bug
47047)
• Better handling of certain 2.5 syntax in the code browser. (Bug 68786).
• Zero-byte remote files are now opened successfully. (Bug 68783)
• Fixed bug causing 'Replace All' to fail. (Bug 67547)
• Fixed problem with missing remote files persisting in the code browser. (Bug 67614)
• Fixed problems in user data upgrades. (Bug 68755)
Komodo IDE/Edit 4.0.3 (April 17, 2007)
42
Komodo User Guide
• Fixed gtk mouse issues. (Bug 42491)
• SVN: Add locale setting/override of LANGUAGE variable. (Bug 68615)
• Fixed conditional breakpoints for languages that support them. (Bug 46327)
• An alert is now given when projects are being upgraded.
• Fixed problem using Debian's PHP for debugging. (Bug 68411)
• Run_RunEncodedCommand() macro API documentation. (Bug 33136)
• Python DBGP builds for Python 2.5. (Bug 67734)
• Fixed perl linter failure on changing output from perl. (Bug 68176)
• Fixed internal error while saving file. (Bug 65224)
• Fixed crash on PyUnicodeUCS2_AsUTF16String on inspection tooltip. (Bug 67194)
• Fixed problem with macros not ending in \n failing silently (Bug 68142)
• Fixed widths of panels in status bar. (Bug 66209, 67181)
• Fixed recursion crash in PHP autocomplete. (Bug 67774)
• Remote sites no longer lost on upgrade to 4.0.2, but username and password need to be
re-entered (see Known Issues). (Bug 67246)
• Better JavaScript macro errors. (Bug 67968)
• Fixed problem with untitled buffers causing run/debug launch to fail. (Bug 67206)
• Autosave toolbox when editing macros and snippets. (Bug 66167)
• Fixed problem with debugger skipping breakpoints in multi-threaded python apps. (Bug
67863)
• Improved auto-indent behavior in PHP. (Bug 59037)
• Fixed PHP function completions after a keyword. (Bug 67696)
• Find matching brace now scrolls left or right as necessary. (Bug 43690)
• Fixed PHP regex help page 404. (Bug 67728)
• Fixed problems with executables not being found in PATH on Windows Vista (Bug 66921)
• PHP autocompletion fixes (after '@' characters and large comments). (Bug 67329, 67094)
• Run command dialog now auto-populated based on recent commands. (Bug 67451)
• SCC/Perforce integration now supports spaces in filenames (Bug 67417)
• Fixed a problem with project trees scrolling and showing empty rows. (Bug 67324)
• Fixed bug causing projects to disappear from the project window. (Bug 41718)
• Toolbar button names now appear below, not beside the icon with "Show Button Text"
enabled. (Bug 32934)
• Adding a new file to a project now correctly puts it in the selected sub-folder. (Bug 66501)
• Fixed bug with snippet insertion failing with unicode chars (Bug 67319:)
• Fixed data loss problem when saving remote files
• Emacs emulation improved on OS X.
• SE Linux installation message downgraded from error to warning if SE is disabled. (Bug
67166)
• Handle backquote-delimited strings in PHP and Ruby parts of RHTML. (Bug 67085)
• Improved error message display when running JavaScript macros. (Bug 67062)
• Fixed bug with interpolations failing in dialogs. (Bug 67494)
Komodo IDE/Edit 4.1 Beta 1 (March 6, 2007)
Enhancements
• Vi registers: Added numbered and named registers similar to those in Vim.
• Tab Stops: Special markers for use in snippets and templates.
Bug Fixes
Komodo IDE/Edit 4.1 Beta 1 (March 6, 2007)
43
Komodo User Guide
• Fixed scrolling selection to top or middle of screen so it takes folded lines into account. (Bug
35063)
• Perl: color scalar and array variables inside interpolating strings. (Bug 34374)
• Fixed confusing exit dialog when prompted to save files on shutdown. (Bug 35770)
• Preserve selection when converting EOLs. (Bug 34776)
• Fixed Lua syntax highlighting. (Bug 66107)
• Fixed a group of Emacs emulation issues. (Bug 33211)
• Added here-documents to PHP. (Bug 54667)
• Added ability to define here-document syntax in UDL-based languages. (Bug 66712)
• Fixed Ctrl+F1 and Shift+F1 in the interactive shell. (Bug 37203)
• Added content to "Samples/Python" sample template. (Bug 32715)
• Added '.lsp' extension for Lisp files. (Bug 32681)
• Greater-than chars are allowed in SGML/XML quoted attribute strings. (Bug 67019)
• Offer to save macro when the contents are modified. (Bug 63577)
• vi emulation: add "tT;," find-character-in-line (Bug 67045)
• vi emulation: fix bug with '.' (repeat) (Bug 65945)
• vi emulation: fix bug of repeat last change/insert text not recording tab keypress (Bug
65963)
• vi emulation: fix some delete/change with direction commands. (Bug 65841, 65842)
• vi emulation: search history includes history from UI as well. (Bug 65639)
• vi emulation: support for Alt/Ctrl Tab window-switching while in visual mode. (Bug 67058)
• Removed 'url' attribute from project elements that don't have one. For snippets, macros, and
commands Komodo was raising a "file_added" notifification that contained "None" as part of
the string. (Bug 67574)
• Fixed SCC exceptions occurring due to SCC trying to check status of virtual files. (Bug
67583)
• Hover tips containing high-bit data while debugging now show up with Unicode characters,
not raw utf-8, or high-bit characters in the wrong encoding (such as programs that
manipulate Cyrillic text with a global cp1251 encoding). (Bug 40317)
• Diff windows now read-only. (Bug 27910)
Komodo IDE/Edit 4.0.2 (February 13, 2007)
Enhancements
• JavaScript completion for function return types.
• Some support for .rxml and .rjs Ruby Files.
• Komodo IDE and Edit can now be run at the same time.
• New File dialog textboxes support some autocompletion.
• Komodo Resources toolbar.
Bug Fixes
• Added True/False keyword highlighting to Python. (Bug 66484)
• Fixed some cgi emulation problems in PHP. (Bug 41537)
• Fixed renaming of virtual folders in projects/toolbox. (Bug 66101)
• Fixed a problem causing focus to switch to another application when dialogs are closed in
Komodo. (Bug 51068)
• Fixed PHP codeintel problem with heredocs. (Bug 66638)
Komodo IDE/Edit 4.0.2 (February 13, 2007)
44
Komodo User Guide
• Changed "PHP does not support debugging" message when PHP is not configured (Bug
66529)
• Fixed error importing package (.kpz) files (Bug 66676)
• Fixed problems opening a large hash/arrays in debugging variable viewers. (Bug 66681)
• Fixed some sorting problem in the toolbox (Bug 66697)
• Fixed problem with "New File..." for remote project folders. (Bug 66595)
• Fixed connection issues in the JavaScript debugger. (Bug 66147)
• Fixed mapped URI support in JavaScript debugger. (Bug 66511)
• luddite.py can now handle filepaths containing spaces. (FCSs) (Bug 66520)
• Fixed problem with jslib File.open() creating a zero byte file. (Bug 66512)
• Fixed space-based path handling for TCLLIBPATH env setting (Bug 66474)
• Fixed a problem opening remote files via FTP. (Bug 66125)
• Fixed a bug causing projects to disappear when deleting many files or expanding a node.
(Bug 41718)
Komodo IDE 4.0.1 (January 29, 2007)
Enhancements
• "New File" dialog revisions: added access keys to the Filename, Directory, Local, and
Remote buttons.
Bug Fixes
• Limited the verbosity of HTML syntax errors and warnings. (Bug 66207)
• Fixed error saving project template. (Bug 66183)
• Fixed a problem with DOM viewer emptying and throwing an exception (Bug 66166)
• Better property-value handling in CSS. (Bug 65994, 65995)
• Completion for HTML attributes with a fixed set of values. (Bug 66149)
• Komodo 3.5 projects with remote files can now be properly upgraded to 4.0 projects. (Bug
66125)
• Fixed trial licence problem on Windows XP with FAT32 filesystems. (Bug 66111)
• Fixed a bug that causes Komodo IDE 4.0.0 to throw an exception on the trial expiry day.
(Bug 66121)
Komodo IDE 4.0, Edit 4.0 Beta 5 (January 22, 2007)
Enhancements
• Improved code completion for Perl.
• "Go to Definition" in Perl
Bug Fixes
• Tabs: Tab order is now properly reset at startup.
• Projects: Restore open/close state of projects at startup.
• Projects: Restore the sorting order of projects at startup.
• Projects: Stop projects from sometimes disappearing after update/deletion.
• Autoindent: Better handling of and bug fixes for HTML/XML auto-indenting.
Komodo IDE 4.0.1 (January 29, 2007)
45
Komodo User Guide
• Codeintel: Now works when some extensions are disabled.
• Codeintel: The Code Intelligence system now honours "Additional Directories" settings in
Project preferences.
• Editor: Improved handling for opening encoded filenames.
• Debugging: Sort list of local/global variables.
• Mac OS X: Fixed crash caused by running mouse across menus.
• Vi emulation: Fix visual line mode to copy/paste correctly.
Komodo 4.0 Beta 4 (January 11, 2007)
Enhancements
• A new "Go to Definition" option for quickly jumping to the definition of a code object (e.g. a
variable, a subroutine, a module, etc.) under your cursor.
• A Vim-like visual mode for text selection.
• Perl autocompletion.
• Ruby on Rails "peer" module autocompletion.
• JavaScript autocompletion shows completion for files in same directory or for directories
defined in global or project preferences.
• PHP autocompletion shows completion for directories defined in global or project
preferences, as well as those defined in php.ini.
• Improved JavaScript debugging workflow.
Bug Fixes
• Remote files: Connections now timeout properly.
• Remote files: Support for working with remote files with a different encoding.
• The PHP XDebug extension has been updated (includes crash bug fixes).
• Perl debugging over iterators now works correctly.
• The style of PHP commenting to use can now be set in Preferences.
• Tab ordering, and window sizing now restored on startup.
• PDK extension fixes and support for the recent PDK Beta.
• PHP completion has partial support for use of DEFINES in include/require statements.
• Improved support for encodings in remote filenames.
• Various Vi emulation fixes.
• Over 100 additional bug fixes since Beta 3.
Komodo 4.0 Beta 3 (December 14, 2006)
Enhancements
• JavaScript catalog selection in preferences. Autocompletion available for several popular
JavaScript libraries.
• Basic Rails autocompletion for the default Rails APIs. Autocompletion for custom application
code not yet implemented.
• XPI support for Code intelligence catalogs.
Bug Fixes
Komodo IDE 4.0, Edit 4.0 Beta 5 (January 22, 2007)
46
Komodo User Guide
• Codeintel (autocomplete/calltips) fixes and improvements in JavaScript, XML/HTML, PHP,
and Ruby.
• Samba support for Live Folders.
• Project level debugging preferences/dialogs fixed.
• Changing the include/exclude preferences for folders fixed.
• Some template loading errors have been fixed.
• HTTP Inspector UI cleanup.
• Remote files under 4K in size are now read properly.
• Fixes for opening remote files.
• Vi emulation mode pasting fixes.
• Better support for HTML fragements in DOM Viewer.
• Search improvements in DOM Viewer.
Komodo 4.0 Beta 2 (November 27, 2006)
Enhancements
• Ruby completion improvements
• PHP completion improvements (notably recursive include/require support)
• Python completion improvements (notably TKinter support improved)
• JavaScript completion improvements, including completion support for JavaScript libraries.
Beta 2 includes support for the Yahoo YUI library.
• HTML completion and DOM Viewer improvements
• Default DTD/Namespace support. The DTD default can be set globally, default namespace
can be set in current file settings dialog.
• Preloading of codeintel data to provide faster response in completion.
• xdebug binaries for PHP 5.2.
• Updated Mozilla code base (now the same as Firefox 2).
• Middle-click closing for editor tabs.
Bug Fixes
• Syntax highlighting configuration fixes.
• Fixed repeat support in VI Emulation.
• Fixed a problem causing crashes when using unicode characters in buffers.
• PHP syntax highlighting fixes.
• JavaScript debugger extension now installs properly into Firefox 2.
• Fixed issues with opening files via SFTP.
• Fixed problem with changing preferences in current file settings.
• Various Preferences fixes.
• Various fixes in the DOMViewer.
• Fixed file reload problem in "dirty" files.
• Drag and drop support in toolbox fixes.
• Various cosmetic fixes.
• Python interactive shell fixes.
• Various code browser/completion fixes for multi-language buffers.
• DocBook DTD files are now parsed properly.
• Fixed leaks in plugin and PyXPCOM layers.
• Project template fixes.
Komodo 4.0 Beta 3 (December 14, 2006)
47
Komodo User Guide
Komodo 4.0 Beta 1 (October 31, 2006)
Enhancements
• Feature complete for 4.0.0
• PHP Zero Configuration
• Code Intel backend redesigned for performance and scalability
• Multilanguage Autocomplete/Calltips
• JavaScript Autocomplete/Calltips
Komodo 4.0 Alpha 7 (October 24, 2006)
• Redesign of Code Intelligence backend
♦ Ruby, Python, JavaScript and PHP reimplemented
♦ Perl and Tcl code intel not working -- back in Beta 1
• Multi language file support (autocomplete, help, commenting, etc.)
• XML/DTD Catalog support for adding new DTD/RelaxNG Schemas
• PHP Zero Configuration
• Project Debugger support
• Project File Management (Delete/Rename/Show in File Manager)
• Project import from remote file system
• Project New File support
• New Icons for most UI buttons
• SCC History now shows branch information as well.
• Project and DOM Viewer performance work
• Project preferences updates
• Live folder/project fixes
• Project Templates changed to packages
• Preferences now upgrade correctly
• Subversion no longer contacts server unless user requests via "refresh"
• more Vi keybindings and fixes
• new "Bright" and "Medium" syntax coloring schemes
• syntax check delay is configurable in prefs
• Pref added to ignore the reload prompt when a file is changed/removed.
Komodo 4.0 Alpha 6 (September 19, 2006)
• XML/HTML Autocomplete/Calltip support:
♦ based on DTD or RelaxNG Schema
♦ SGML Catalog and XML Catalog support
Komodo 4.0 Alpha 5 (September 1, 2006)
• More luddite languages
• Projects: Deployment
• Multilanguage code intel
• JavaScript DBGP event-based breakpoints (eg. onclick)
Komodo 4.0 Beta 1 (October 31, 2006)
48
Komodo User Guide
Komodo 4.0 Alpha 4 (August 24, 2006)
• CSS autocomplete/calltips
• HTTP Inspector rules and filters
• Projects: live folder/projects improvements, performance improvements
• Vi Bindings: new features and improvements
• JavaScript: Interactive Shell and debugging improvements
• Misc. other bug fixes
Komodo 4.0 Alpha 3 (July 25, 2006)
• HTTP Inspector
• More project work (project prefs, more prevalent live folders)
• JavaScript Interactive Shell
Komodo 4.0 Alpha 2 (July 11, 2006)
• SFTP/SCP support in remote files system
• JavaScript debugging improvements (crashes, breakpoints, etc.)
• SCC History
• Vi Bindings
Komodo 4.0 Alpha 1 (June 26, 2006)
• JS debugging in Firefox via the JS DBGP XPI.
• Live Folders in the project viewer (backed by new file notification system)
• UDL/Luddite lexing framework to support RHTML syntax coloring.
Komodo 3.5.3 (May 4, 2006)
• Fixed some xpcom registration issues on startup
• Some minor unicode issues on non-English systems fixed
Komodo 3.5.3 Beta 1 (March, 2006)
• [Mac OS X] Now have a build of Komodo for Mac OS X on Intel.
• [Solaris] Once again have a Komodo for Solaris build.
• Numerous locale and encoding bugs have been fixed.
• Numerous keybinding bugs have been fixed.
• Minor FTP-support improvements to speed up browsing in the "Open Remote File" dialog.
• Improvements in the Diff Windows to properly support context, unified and plain diff styles.
• A full list of bug fixes can be obtained on http://bugs.ActiveState.com/.
Komodo 3.5.2 (December 6, 2005)
• [Windows] Fix AltGr+<number> keybindings for international keyboard layouts on
Windows. See bug 43021 for details. One side effect of this fix is that the keyboard shortcut
Komodo 4.0 Alpha 4 (August 24, 2006)
49
Komodo User Guide
for "View Line Numbers" had to be changed from Ctrl+Shift+6 to Ctrl+Shift+4.
• [Windows] Fix XSLT autocomplete (bug 41898).
• Perl syntax checking default setting change to not use taint mode. See this komodo-discuss
thread for details.
• [Windows] Fix setting of Windows File associations (bug 42107). Due to the nature of the
bug it may be necessary to first remove all your file associations in the Windows Integration
panel, press "Re-apply settings to system", then reset all your file associations before they
will be setup properly.
• [Linux] Fix SELinux issues that would prevent Komodo from starting on Linux machines with
SELinux kernel extensions installed and enforcing -- the default on Fedora Core 4. (Bug
43260)
• Various bug fixes.
Komodo 3.5.1 (November, 2005)
• Added a Ruby Interactive Shell.
• Various bug fixes, especially for Ruby support, IME, and Mac OS X keybinding issues.
Komodo 3.5 (November 2, 2005)
• Komodo has been ported to Mac OS X
• Ruby support has been added, including debugging, code intelligence (including Code
Browser support, Object Browser support, AutoComplete and CallTips), syntax checking,
syntax highlighting, and code folding.
• Komodo's Mozilla source base has been upgraded to the 1.8 tree (same as Firefox 1.5).
• The embedded Python has been updated to version 2.4.
• Multilingual Input Method Editor (IME) support.
Komodo 3.1 (February, 2005)
Key Features
• Subversion support has been added to the Source Code Control system. Support for
Subversion is limited to the same features and capabilities available for CVS and Perforce.
For more information, see Source Code Control
• Perl AutoComplete and CallTips support is available in this release. See AutoComplete and
CallTips for more information.
• The Python debugger has been rewritten into a regular Python package, and now includes
an extension written in C to provide performance boosts for large applications, or
applications using various GUI toolsets (eg. wxPython).
• PDK 6 support is now built into the distribution and does not require a separate step to
enable.
Enhancements
• Syntax coloring for many new languages, including APDL, Asn1, AutoIt, Asm, Avenue,
Bash, CLW, EScript, Erlang, Forth, Gui4Cli, Kix, Lout, Metapost, MMIXAL, Lot, MSSQL,
Nsis, PowerBasic, PostScript, POV-Ray, Scriptol, Specman, TeX, Verilog, and YAML.
• Unicode and locale support has been enhanced.
Komodo 3.5.2 (December 6, 2005)
50
Komodo User Guide
• Performance of the UI components has been improved.
• Markers that show line wrapping when the editor is in wrap mode
• Better column select support. Use 'Shift'+'Alt'+ arrow keys for selection.
• TrueType fonts are available on Linux.
• Anti-aliased fonts are available on Linux.
• Support for copying, pasting as well as dragging and dropping has been improved on Linux.
Komodo 3.1 Beta 2 (January, 2005)
Bug Fixes
• Win9x startup and runtime problems in Beta 1 (bugs 34939, 36202, 36207, 36208)
• WinNT startup problems in Beta 1 (bug 36211)
• AutoComplete: Inherited methods of HTTP::Request not suggested (bug 35769)
• AutoComplete: perlcile gets stuck scanning WWW::Mechanize (bug 35788)
• AutoComplete: PHP AutoComplete for parent:: includes class members for the current class
(bug 36104)
• AutoComplete: Code intelligence doesn't supply methods for an instance of an object. (bug
36128)
• Code Browser: "Go to Definition" error with code folding (bug 33495)
• Code Browser: Perl file is shown twice in the Code Browser (bug 33665)
• Debugger: Remote Python debugging hangs on non-existent file (bug 36247)
• Debugger: Last line not recognized in remote dbg (bug 36265)
• Documentation: Wording change to Perl remote debugging setup docs (bug 33067)
• Documentation: K3.1 Solaris may require OS patches (for Mozilla) (bug 35873)
• Documentation: Fixes to Tutorial docs (bugs 36073, 36077, 36080)
• Editor: "updateBreakpointsFromMarkers" traceback during save (bug 33150)
• Editor: Komodo does not notice that mailexport.xml has changed (bug 36078)
• Macros: Some macro triggers don't work (bug 36084)
• Object Browser: HTTP::Date.time2str looks odd (bug 35786)
• Source Code Control: Offer to save file on SCC diff when the file is dirty (bug 36067)
To view the complete list of bugs fixed in this release, see http://bugs.activestate.com.
Komodo 3.1 Beta 1 (January, 2005)
Bug Fixes
• Solaris builds available
• Subversion documentation added
• Further performance improvements in Python debugger
• Perl Code Intelligence improvements
• Perl .xs file extension mapped to C++ lexer
• * Perl .PL file extension mapped to Perl lexer
• Fixes to Watch variables tab (bug 35808)
• Duplicate variable names in PHP completion fixed (bug 34795)
• Advanced debugger preferences added for customizing amount of data returned from
debug sessions for variable viewers
• Previously, projects could not import/open files with colon in the filename (bug 35783)
Komodo 3.1 (February, 2005)
51
Komodo User Guide
• Permission denied on one item in import prevented importing any files/dirs (bug 30188)
• Support extends and implements for AutoComplete in PHP ( bug 35881)
• Fixed PHP completion for remote files (bug 34745)
• Support self keyword for PHP completion (bug 35042)
• Python -E caused debugging/shell to fail (bug 35114)
• Source Code Control add/delete status in projects was broken (bug 35919)
• Source Code Control edit command was available when it shouldn't have been (bug 35927)
• Source Code Control folder/container commands were not available (bug 35925)
• Fixed using locally installed PyDBGP
To view the complete list of bugs fixed in this release, see http://bugs.activestate.com.
Komodo 3.1 Alpha 4 (December, 2004)
Bug Fixes and Enhancements
• Editor: Column select key bindings now 'Alt'+'Shift' rather than 'Ctrl'+'Alt'+'Shift'
• Debugger: No tooltips/hints for variables when debugging Perl script (32875)
• Debugger: Only 100 children of an array shown in debugger variable panes (33702)
• Python: Extreme slowness debugging large python applications (33140, see new features
above)
• Python: wxPython crashes resolved (33112, see new features above)
• Python: Stepping into execfile within a method fails (34767)
• Python: Eval fails to debug (32657)
• Python: Can't set breakpoints in Python threads (34803)
• Python: Debugger fails to display Python sets ( 34796)
• Python: Interactive shell hangs
• Perl: Log file path does not expand tilde (34711)
• Perl: Debugger stops execution in extraneous .pm files (34699)
• Perl: Various remote debugger issues fixed
• Perl: NEW break support added
• Perl: $1 not preserved in Perl interactive shell session (34528)
• Perl: Single-quoted multi-line string failure (34967)
• PHP: Incorrect line numbers used in code browsing (32499)
• PHP: Completion of functions from include files is faulty (34865)
• PHP: Preferences report debugging is not configured (34703)
• PHP: Updated xdebug extension
• TCL: Support for debugging incrtcl code
• default extensions for new languages (34708)
• Incorrect tooltip in search toolbar (33347)
• Using tab key to indent deletes characters (34695)
• Komodo version does not show in name in Add/Remove Programs (34797)
• 'View as language', display does not update syntax coloring (34689)
• Perl: Syntax color issues (34087)
• Completion drop-down is clipped by scintilla window (34392)
• dragging/dropping multiple files fails to work (34891)
• Rectangle (column) selection failed on windows (34042)
• Print selection with tabs prints incorrect selection (34739)
• Better cvs version parsing (35428)
Komodo 3.1 Beta 1 (January, 2005)
52
Komodo User Guide
Komodo 3.1 Alpha 3 (November, 2004)
Bug Fixes
• fixed startup bug on Linux when using NFS mounts for home directories (34041)
• MOZ_PLUGIN_PATH would cause Komodo startup failure (34779)
• wxPython crash when debugging (33112)
• Perl debugger uri fix (34714)
Komodo 3.1 Alpha 2 (October, 2004)
Bug Fixes
• fixed startup bug on Windows
• Perl Interactive Shell: a few refinements relating to handling of special variables ($1 .. $9,
$`, $', @_)
• Perl debugger: perl debugger fails if logfile setting has spaces in the path (bug 34192)
• Unix install script: fix expansion of "~" directories
• VPM: fix startup failure
Komodo 3.1 Alpha 1 (October, 2004)
Bug Fixes
• Overload support for the Perl debugger (33367)
• Fixed CVS support for less used protocols or protocols available with CVSNT
• Minor fixes in Perforce support (33683)
• "Find" functionality improvements (33698)
• Debugger's HTML view now handles images properly (33619)
• Cyrillic (and other) keyboard support fixed (34028)
• Perl syntax coloring improvements (34087
• General debugger improvements (32645)
• Debugging of Tcl incrtcl classes now possible (34090)
• Breakpoint failures addressed for Tcl debugging (34079)
• File|Revert command was previously never available (33335)
• "Repeat next" key binding ('Ctrl'+'K', 'Ctrl'+'U') now stops repeating when it should (33960)
• On Linux, dragging and dropping a file onto an open file in the Editor Pane caused the
name of the added file to be pasted into the already-open file (32341)
• Deleting a single custom menu from the Toolbox removed all custom menus from the main
menu (33202)
• Comparing files with different line endings caused Komodo to hang (32932)
• Breakpoints in remote files were ignored (33636)
• The Python remote debugger failed when debugging local files (33079)
• Perl Debugger - fixed "Bizarre copy of ARRAY"
• Opening files with 'Enter' key had unintended side effects (33433)
• Non-ASCII Characters were not displayed properly in the RX Toolkit (33054)
• Remote debugger always searched for local files (33116)
• Breakpoints didn't work for filenames with parentheses when debugging Perl (33968)
• Temporary files were created and not removed when debugging Perl (34308)
Komodo 3.1 Alpha 3 (November, 2004)
53
Komodo User Guide
• Module dependencies are now handled better during Perl debugging (33771, 33255)
• Breakpoints are now reset after saving a file for Perl debugging (34267)
To view the complete list of bugs fixed in this release, see http://bugs.activestate.com.
Komodo 3.0.1 (August, 2004)
• On Windows, CPU usage spiked to 100% from the debugger proxy at end of a debug
session.
• Custom menus disappeared when dragging macros into them.
• The "Your Toolbox has changed outside Komodo" alert was being displayed unnecessarily.
• Komodo was unable to "Save As" files in 8bit encodings on Linux platforms.
• Files could not be opened while using ShiftJIS or cp936 system default encodings.
• The debugger was hanging with a Prototype Error when debugging Perl on Linux.
• Usage of the "System defined default browser" was incorrect in some cases.
• CVS integration did not work with some versions of CVS.
• The code intelligence scanning engine hung on certain file access errors.
• Some failures with non-ascii characters in filenames on Linux (such as the inability to use
CVS or failures in the auto-save feature) were fixed.
• Some failures when converting document encodings were fixed.
To view the complete list of bugs fixed in this release, see http://bugs.activestate.com.
Komodo 3.0 (July, 2004)
Code Intelligence
Komodo's Code Intelligence system is a set of tools that supports multiple languages. The Code
Intelligence tools include the Code Browser, Object Browser and Python AutoComplete and
CallTips. All Code Intelligence tools require a Code Intelligence database to operate fully.
The Object Browser is a graphical browser that searches the Code Intelligence database for
specified code symbols and modules. Use the Object Browser's preview pane to view code
snippets containing the search criteria.
The Code Browser displays on the Code tab next to the Projects tab in the Left Pane. The Code
Browser displays a hierarchical tree view of all code constructs (for example, variables, methods,
imports) in all open files. For Python, instance attributes are all displayed. The code tree, which can
be navigated using either the keyboard or mouse, includes the following features:
• Double-click a node to jump to that point in the code.
• When the cursor is positioned in the Editor Pane, clicking the Locate current scope button
on the Code Toolbar or pressing 'Ctrl'+'K', 'Ctrl'+'L' causes Komodo to jump to the node in
the code tree that most closely matches the current point in the program. Additionally, a
Scope Indicator, located in the status bar, displays the current scope of a selected code
construct. Double-click the Scope Indicator to open the tree hierarchy to the code construct.
• When the focus is in the Code Browser tree, pressing the 'Tab' key causes Komodo to shift
to the Filter text box. Typing any string in this text box causes the Code Browser to display
all of the nodes matching that string. Pressing 'Tab' again shifts the focus back to the tree.
Komodo 3.1 Alpha 1 (October, 2004)
54
Komodo User Guide
Clearing the Filter text box returns the tree to its original state. Note that all matching nodes
are shown, even those that are invisible because their parents were not "expanded".
• The Sort menu on the Code Toolbar lets you toggle whether the nodes at each level of the
tree are sorted in alphabetical order or according to the order they occur in the file.
• The Code Description pane, located in the lower part of the Code Browser, displays
additional documentation (when available) on various program components.
Python AutoComplete and CallTips are enhanced with the Code Intelligence database.
Interactive Shell
The interactive shell is an implementation of Perl, Python and Tcl's interactive shell within Komodo.
The interactive shell supports, AutoComplete, CallTips, debugging functions, customization and
history recall.
Debugging
• A debugger proxy is available that enables multiple users to debug with Komodo on the
same machine.
• The Breakpoints tab in the Bottom Pane of the Komodo workspace is designed for
convenient management of breakpoints and Tcl spawnpoints. This tab displays enabled and
disabled breakpoints and spawnpoints. Double-clicking an enabled or disabled breakpoint
on the Breakpoints tab opens the related file in the Editor Pane and shifts focus to the line
in the program associated with that breakpoint.
• Komodo now handles multi-session debugging. Komodo can debug multiple programs,
regardless of the supported languages used in the applications being concurrently
debugged.
• The Bottom Pane of the Komodo workspace (previously the Output Pane) has been
reorganized and enhanced. The new Debug tab is displayed whenever a Komodo
debugging session is launched.
• A Debug Toolbar is available on the Debug tab in the Bottom Pane of the Komodo
workspace. It includes additional controls for detaching from a new debugging session and
forcing a break.
• New remote debugging features include the ability to listen for remote debugger sessions
continuously, set remote debugger preferences, and check the listener status of the current
configuration.
• The new debugger properties dialog box supports multiple 'configurations' to be saved per
file.
• The new Debugger dialog box (displayed when a debug session is invoked) supports
configurable interpreter arguments.
• The Disable Output Buffering and Enable Implicit Flush options for PHP debugging have
no effect when Simulate CGI Environment is selected. To disable output buffering in CGI
emulation mode, manually comment out the output_buffering setting in php.ini with a ";"
character, or set it to "off".
Rx Toolkit
The Rx Toolkit has been completely overhauled. New features include:
• Match Type buttons that set the match mode for the regular expression. The buttons
Code Intelligence
55
Komodo User Guide
represent functions that let you Match, Match All, Split, Replace and Replace All.
• For Python regular expressions, there are two new modifiers: Unicode and Locale.
Multi-User Features
• A Shared Toolbox with functionality similar to the standard Toolbox makes it possible for
multiple users to share items such as run commands and code snippets. The Shared
Toolbox is enabled via a check box on the Shared Support page of Komodo Preferences.
• Users can accept a default Common Data Directory or specify a custom location via the
new Shared Support page in Komodo Preferences.
• Multiple users can share .tip, .pcx and .pdx files and preferences.
Enhanced Search Functionality
• The new Open/Find Toolbar makes it easier to open files and search for strings in currently
open files.
• A Find in Files dialog box is used to search for files that are not currently open.
Macro Enhancements
• A Macro Toolbar provides a quick and easy way to record, pause, play, stop and save
macros.
• Macros are no longer stored as separate files (as they were in 2.x). Because macro content
is now included in a macro item, it is easier to share macros between multiple users.
• The Properties dialog box for macros contains a window in which macros can be coded in
either JavaScript or Python.
• Triggers can be set so that macros execute as a result of specific Komodo events.
• The documentation includes a macro API.
Custom Toolbars, Menus and Icons
Create Custom Toolbars and Menus for frequently used components. Custom Toolbars are
displayed beneath the existing toolbars; custom menus are added to Komodo's top-level menu,
between the Tools and Windows menus. Custom icons can be assigned to components like run
commands, snippets, etc.
Editing Enhancements
• Reflow Paragraph
• Join Lines
• Enter Next Character as Raw Literal
• Repeat Next Keystroke N Times
• Emacs-style "marks"
• Clean Line Endings on save
Miscellaneous
• PHP 5 is supported.
• Support for Web services has been deprecated. Note that this will not prevent the use of
Web services in applications developed in Komodo.
Code Intelligence
56
Komodo User Guide
• Users familiar with the Emacs editor can configure Komodo to use Emacs key bindings and
set a File Associations preference so that Komodo checks for an embedded Emacs mode
specification.
• Support for Tcl has been improved to include more detailed logging and additional syntax
checking options.
• Two new interpolation shortcuts (%L and %P) can now be used in the Run Command
dialog box.
• Users now have the option to assign custom icons to Komodo components (snippets, run
commands, etc).
• Printing features for specifying line wrapping and font scaling have been added to the
Printing page in Komodo Preferences. This page is now also accessible by clicking Print
Settings on the File menu.
• Components from Projects or the Toolbox can be exported to a self-contained archive for
distribution to other users. The import and export wizards are invoked via the right-click
context menu in the Project or Toolbox tab, or from the Toolbox menu.
• Perl, Python and Tcl preferences include the ability to specify import directories.
• On the Editor|Key Bindings preference page, the key bindings list can be filtered.
Documentation
• The new Feature Showcases are quick demos of Komodo features.
• Komodo Help now displays in a selected web browser.
• Improved search capabilities, including phrase search and result ranking, make it easier to
locate specific information.
• The documentation includes an index.
• Context-sensitive Help buttons have been added throughout the Komodo workspace.
• The documentation includes a macro API.
Komodo 3.0 Beta 4 (June, 2004)
Komodo 3.0 Beta 3 (May, 2004)
Komodo 3.0 Beta 2 (May, 2004)
Komodo 3.0 Beta 1 (May, 2004)
Komodo 2.5.2 (January, 2004)
This release contains bug fixes for Komodo 2.5 and 2.5.1, including:
• Intermittent crashes were occurring on Linux, caused by the autosave feature.
• On Linux, the Internationalization dialog in Komodo's Preferences was generating an error.
• Perl's Visual Package Manager was not always reporting a startup failure to the user.
• AutoComplete for Perl and Python did not work.
• Intermittently, the variable type indicator (i.e., $, @, %) was not being selected when
double-clicking on a variable in the editor pane.
• Umlaut characters were causing file contents to be lost on save.
• CVS source code control integration functions were not available on directories or projects.
• The Tcl statement source file was not finding the specified file.
Code Intelligence
57
Komodo User Guide
• There were errors in Tcl syntax checking.
• CVS source code control integration was generating errors on Solaris.
• There were debugging errors when working with Tcl scripts on Solaris.
• When adding template items to a project or the Komodo Toolbox, it was not possible to
cancel the file selection operation.
• The CVS source code control integration now supports use of a local repository.
• The update function in Komodo's source code control integration was not functioning under
certain circumstances.
• On Solaris, it was not possible to create a file on an NFS-mounted disk.
• Regardless of the setting for line endings, new files were created with DOS/Windows line
terminators.
• Perl brace matching could cause Komodo to lock up under certain circumstances.
• XML AutoComplete could cause Komodo to lock up.
• During a workspace restoration, if multiple files contained breakpoints, the breakpoints were
not being written to Komodo's breakpoint manager and would have to be manually re-set.
• After debugging, debugger arrows were still active on files that had been stepped into.
• Files names that included spaces could not be added to projects.
• Under certain circumstances, Komodo would not start on Red Hat version 8.
• Autosave functionality is now more robust.
• Under certain circumstances, opening files resulted in a blank page in the editor pane.
• On Linux, the debug session would occasionally hang due to problems with the remote
debug listener.
Komodo 2.5.1 (October, 2003)
This release contained bug fixes for Komodo 2.5. The only user-visible changes were:
• When clickable links are displayed in the Output Pane, you must double-click (rather than
single click) to follow the link. This allows for portions of the link to be selected via
single-clicks. The link is no longer underlined.
• The default Perl remote debugging port has changed from 9010 to 9011 (due to a conflict
with the XIM server on UNIX). To use the new port, alter the PERLDB_OPTS setting on the
remote machine. If you are invoking the Komodo debugger via the Perl Dev Kit's -debug
switch, ensure that the specified port number matches the Komodo's port number.
• The menu link for the Start Page has been moved from the Help menu to the Windows
menu.
• The Close All menu option no longer closes the Start Page.
• The Internationalization preference page for language encodings has changed.
Programming-language specific encodings are now used for existing files, as well as new
files.
The following major bugs were fixed:
• The highlighting of selected text was not released if the mouse pointer moved outside of the
editor pane.
• Komodo Personal failed to start up properly if the Show Button Text option was enabled.
• Background syntax checking would cease to function.
• Saving of remote files failed for long editing sessions.
• Remote debugging didn't honor Perl breakpoints.
• The Rx window could hang.
Komodo 2.5.2 (January, 2004)
58
Komodo User Guide
• Hotspots in the Output pane were generated for spurious lines and the dialog was hard to
dismiss.
• Installing web services for Perl 5.8 is fixed.
• The Build Standalone Perl Application dialog didn't deal well with scripts with UNC
filenames (\\machine\drive\...).
• Printing collapsed whitespace in the middle of lines.
• The ability to show diffs in an editor tab wasn't working.
Komodo 2.5 for Windows, Linux (September, 2003)
General
• Komodo's speed has been boosted through re-engineering, resulting in quicker times for
startup, tab-switching, loading of dialogs, as well as overall performance gains.
• Menus have been re-organized, and new items have been added. Every Komodo feature
can now be accessed through the top-level menus.
• The Preferences pages and a number of existing dialogs have been improved and
reorganized for ease-of-use. Changed dialogs include those associated with current file
settings, templates, source code control, remote files, and the Perl Dev Kit.
• Templates can now use the same interpolation shortcuts as commands and snippets. Prior
to Komodo Version 2.5, a set of variables could be used to embed the current date and time
in files created from custom templates. The old codes have been deprecated and will be
removed in the next Komodo release.
• The Show Unsaved Changes command, previously exclusive to the Editor context menu,
has been added to the File menu.
• A new Compare Files feature on the Tools menu provides a quick and easy way to locate
and "diff" two files.
• A Word Wrap command has been added to the View menu.
• A Tcl tutorial has been added to Komodo's set of language tutorials. Another new tutorial,
the Komodo Tour, provides an introduction to the program's key features.
• ASPN Cookbook integration is no longer supported.
Workspace
• Changes have been made to make more efficient use of the Komodo workspace:
♦ A Full Screen command has been added to the View menu.
♦ The Toolbox and Project Manager, which previously appeared in separate panes,
are now contained in single pane. You can select Projects/Toolbox Pane from the
View menu to show or hide this pane.
♦ Toolbar button text is not displayed by default. Hiding the button text makes it
possible for the toolbars to share a single row.
• The functionality of Komodo's ancillary windows has been enhanced. The Debug Output,
Command Output, and SCC Output tabs in the Output Pane offer context menus with
access to a subset of the top-level View menu. There are key bindings for each of the
context menu items. The same context menu is available in the "diff" window, which is
invoked by either the Show Unsaved Changes command or the Compare Files command.
The ancillary windows also support "hot-spotting". If Komodo detects a file reference, it will
create a hot spot that links to the file itself.
• Interpreter errors displayed in the Output Pane are now hyperlinks to the relevant line.
Komodo 2.5.1 (October, 2003)
59
Komodo User Guide
• 'Ctrl'+'Tab' functionality is now supported in all of the panes in the Komodo workspace.
Earlier versions of Komodo supported tab-switching in the Editor Pane only.
• The Output tab and the Variables tab are now known as the Debug Output tab and Debug
Variables tab, respectively.
• The "grippies" used to show and hide the panes in the Komodo workspace have been
abandoned in favor of "x" close buttons.
Project Manager and Toolbox
• The new Toolbox menu provides functionality for importing and exporting items, along with
other commands that were previously exclusive to the Toolbox context menu. The
Projects/Toolbox Pane contains the Projects tab and the Toolbox tab. You can show or hide
the Projects and Toolbox tabs by pressing 'Ctrl'+'Shift'+'P' and 'Ctrl'+'Shift'+'T',
respectively.
Editor
• Additions to the Window menu offer new display options for the Editor Pane. Selecting
Split View divides the Editor Pane in two, so that you can preview files (e.g., HTML or XML)
or compare two files. Select Rotate Tab Groups to toggle vertical and horizontal variations
of the split view.
• The View As Language item on the View menu now has a submenu item called Reset to
best guess. Select this item to ignore the user preference, and analyze the file in an
attempt to determine its language.
• Change the language of an open file by right-clicking the name of the language on the
status bar and selecting a language from the pop-up menu.
• A new Smart Editing preference gives you the choice of configuring the 'Tab' key instead of
'Ctrl'+'Space' to trigger Komodo's word-completion feature.
• The Go To Line dialog box now supports entries that are relative to the current line. For
example, instead of entering a specific line number, you can enter "+10" or "-10" to move
ten lines forward or back.
• There are some changes to the default key bindings. For a complete listing of default key
bindings, select Help|List Key Bindings.
• The Ignore Hidden Text option has been removed from the Find dialog box.
• Komodo now supports editing with non-English characters, based on the locale specified in
the regional settings for Windows. See Customizing International Encodings for more
information.
Web and Browser
• A Preview in Browser command is now available through the View menu and the main
toolbar. Depending on how the Web and Browser preferences are configured, this
command will display a preview in one of three ways:
♦ in the Editor Pane
♦ side-by-side with the source code in a split view of the Editor Pane
♦ in a separate window
GUI Builder
• GUI Builder functionality has been extended to include language-specific widget palettes
Komodo 2.5 for Windows, Linux (September, 2003)
60
Komodo User Guide
that are displayed according to the initial language selection. In addition, a greater variety of
widgets is available.
• The new Dialog tab displays an interactive organizational map that makes it easier to plan
and manage the structure of dialogs.
• The new Menu tab is used to create drop-down menus. The Menu tab features an
additional widget set used to create standard menu commands, as well as commands with
check box or radiobutton behavior.
Printing
• The new Page Setup options used to set orientation, margins, and headers and footers can
now be accessed from the File menu.
• A new Print Preview command has also been added to the File menu. In addition to
navigation buttons for viewing multi-page print jobs, the preview window offers access to
Page Setup options. As a result, printing preferences available in Komodo 2.3, including
Print Line Wrap Markers, Characters per line and Font Size Adjustment, have been
removed.
• Selecting the Print to HTML command now opens the generated file.
Fonts and Colors
• The Fonts and Colors preferences have been streamlined to make managing these settings
easier. You can create new font and color schemes based on the default scheme. In
addition to Language-Specific Coloring, you can now set Common Syntax Coloring to
specify the settings for elements used in multiple languages.
Debugging
• A Run Without Debugging item has been added to the Debug menu, providing a faster
way to run scripts in Komodo.
• A new debugging preference, Try to find files on the local system when remote
debugging, has been added. When this preference is turned on, Komodo will search for
the debugger file on the local system instead of automatically opening a read-only version
of the file retrieved from the debug engine.
• Komodo now offers full support for Tcl debugging. In addition, runtime Tcl syntax checking
no longer requires the Tcl Dev Kit.
Source Code Control
• The Automatically check out before save option has been moved from "General Source
Code Control Preferences" to "Perforce" Preferences, where it appears as Automatically
open files for edit before save.
Komodo 2.5 Technology Preview 1 for Solaris (August, 2003)
Komodo 2.5 Beta 1 for Windows, Linux (August, 2003)
Komodo 2.5 Technology Preview 1 for Solaris (August, 2003)
61
Komodo User Guide
Komodo 2.5 Alpha 2 (July, 2003)
Komodo 2.3 (February, 2003)
General
• Compatibility issues with ActivePerl 5.8 (VPM), PHP 4.3 (syntax checking) and Python
2.2.2+ (debugging) have been resolved.
• The XSLT engine has been upgraded to Xerces 2.1 and Xalan 1.4, and includes built-in
extensions for that version. (Refer to http://xml.apache.org/xalan-c/extensionslib.html for
information about extension support.)
• The new Windows Integration page in the Komodo Preferences is used to configure
system-wide file associations.
• The Projects and Workspace page in Komodo can be used to have Komodo prompt you to
open recent files and projects when you start the program.
• The configuration of the Komodo workspace is restored after closing and re-opening
Komodo.
PHP Configuration Wizard
• The PHP Configuration Wizard simplifies the previously cumbersome process of configuring
PHP debugging extensions in Komodo.
Run Command
• The Run Command function has been enhanced, and a new Run Command Tutorial has
been added.
Toolbox
• Snippets now support shortcut codes. To view the supported shortcuts, right-click a snippet,
select Properties, and click the arrow button in the Properties dialog.
• The new Add "Open..." Shortcut... item on the Toolbox menu is used to create shortcut
links in the Toolbox to directories. Key bindings can be assigned to these links.
• Items can be exported from the Toolbox. Select the desired items, then right-click and
select Export as Project File....
• Exported Toolbox items can be imported using the Import into Toolbox... menu item,
accessible from the Toolbox menu.
• The new Compare File With... item on the file context menus in the Toolbox and Project
Manager is used to compare the selected file with another file selected via a file picker
dialog.
Project Manager
• Projects load much faster than in previous versions.
• Snippets now support shortcut codes. To view the supported shortcuts, right-click a snippet,
select Properties, and click the arrow button in the Properties dialog.
• The new Add "Open..." Shortcut... item on the Project Manager menu is used to create
shortcut links in the Project Manager to directories and URLs. Key bindings can be
assigned to these links.
Komodo 2.5 Alpha 2 (July, 2003)
62
Komodo User Guide
• The new Compare File With... item on the Project Manager menu is used to compare the
selected file with another file selected via a file picker dialog.
• When a project has been changed, it can be reverted to its last saved state using the
Revert Project menu item.
• Many settings now persist in Komodo's projects, including debugging options and Import
from File System settings.
• The Import from Filesystem function prompts if you want to install all the files in a
filesystem, and allows you to deselect desired files.
• After using the Import from Filesystem function, if you attempt to import the same
filesystem location into the same project, only files that are new since the last import will be
imported.
SCC Integration
• If you are using Komodo's Perforce integration, you can now specify an external "diff" tool.
• The "diff" window displays the original content and the new content in different colors.
• The "diff" window supports function keys to navigate to changes in the file.
Editor
• Select Show Unsaved Changes from the Editor context menu to view the differences
between the version of the file currently displayed in the Editor Pane and the last saved
version of the file.
• Breakpoints and code folding information is stored with the file, and therefore does not need
to be reconfigured when the file is closed and re-opened.
• There is a new automatic indentation style ("Indent to first non-empty column") that can be
configured using Komodo's Indentation preferences.
• The symbols used to indicate folded sections of code (and sections of code that can be
folded) can be configured on the Editor|Indentation page of the Komodo Preferences.
• You can change Read Only status of a file in the file's preferences. Access the file
preferences by right-clicking the file in the Editor Pane and selecting Properties and
Settings.
• If you change and save a file with a Read Only status, you will be given the option to "force"
the write. This will remove the Read Only flag, save the changes, then reset the Read Only
flag.
• You can specify the language association for an open file in the file's preferences. Access
the preferences for the current file by right-clicking the file in the Editor Pane and selecting
Properties and Settings. Use the Reset button to reassert the language associated with
the file type.
• Various editor bugs have been fixed, including intermittent failure of the paste function,
periodic hanging when large projects were being opened, Perl syntax checking problems
and lost code folding after tab switching.
GUI Builder
• In Komodo's Preferences, you can specify the preferred port that the GUI Builder will use.
• There are now no constraints for user code added to Python files generated by the GUI
Builder.
PDK Support
Komodo 2.3 (February, 2003)
63
Komodo User Guide
• Komodo 2.3 supports version 5 of the Perl Dev Kit, including the new PerlNET and PerlTray
components.
• Support for all the Perl Dev Kit tools has been enhanced.
• When the Build Standalone Perl Application function is used, settings in the dialog are
stored with the file.
Komodo 2.3 beta 2 (February, 2003)
Komodo 2.3 beta 1 (January, 2003)
Komodo 2.0.1 for Linux (November, 2002)
• See Komodo 2.0 for Windows for a list of 2.0 features included in version 2.0.1 for Linux.
• International Encoding support now works with European and Cyrillic character sets.
Configure encoding support on the Internationalization page of Komodo Preferences.
• a new Web Preferences page, used to specify the default browser
• additional Run Command Shortcuts
Komodo 2.0.1 for Windows (October, 2002)
Komodo 2.0 beta 3 for Linux (October, 2002)
Komodo 2.0 beta 2 for Linux (September, 2002)
Komodo 2.0 for Windows (September, 2002)
• Project Manager
♦ add Run commands to projects
♦ add GUI dialogs to projects (Komodo Pro)
♦ add Web services to projects
♦ add macros to projects
♦ add code snippets to projects
♦ organize objects into folders
♦ import groups of files from the filesystem
♦ organize the order of objects in projects
♦ drag items to and from the Project Manager to the Toolbox and Editor
• Toolbox
♦ add Run commands to the Toolbox
♦ add GUI dialogs to the Toolbox (Komodo Pro)
♦ add Web services to the Toolbox
♦ add macros to the Toolbox
♦ add code snippets to the Toolbox
♦ add code snippets to the Toolbox
♦ organize objects into folders
♦ drag items to and from the Toolbox to the Project Manager and Editor
• Customizable Key Bindings for standard Komodo functions, and for macros and Run
commands
• Source Code Control integration for CVS and Perforce (Komodo Pro)
Komodo 2.3 beta 2 (February, 2003)
64
Komodo User Guide
• Visual Package Manager integration (Komodo Pro)
• GUI Builder for building graphical applications (Komodo Pro)
• Macros for recording and repeating common keystroke sequences
• Create code snippets by selecting code in the Editor Pane and dropping it into the Project
Manager or Toolbox
• Enhanced "Run" Command
♦ save run command to the Toolbox
♦ new shortcuts, including escaped % symbol, URL-escaped selection, etc
♦ specify starting directory for command
♦ specify run location (output window, new console, no console)
♦ specify environment variables
♦ save advanced options (such as environment variables) as Run command defaults
• Function Search to quickly find Perl packages and subs, Python or PHP classes and
functions, and Tcl procs
• Incremental Search
• HTML Preview Tab
• Customizable Language Help
• Customizable Cursor, Current Line, Selection and Background Colors
• "Mark All" option in Find dialog
• "Remove All Bookmarks" command
• Printing enhancements
• Background Syntax Checking
♦ hover mouse over icon for total number of errors and warnings
♦ double-click icon to move the editing cursor to the next error or warning
• Tip of the Day
• 'Ctrl'+'Tab' switches between the two most recently opened or edited files
• Ability to re-order open files by dragging-and-dropping file tabs in the Editor Pane
• File tab context menu with common file tasks, such as saving and accessing source code
control commands
• 'Ctrl'+'X' and 'Ctrl'+'C' take entire lines if no text is selected, and will continue to accumulate
lines
• 'Ctrl'+'Shift'+'V' pastes and selects the pasted text
• Improved word wrapping
• Partial word movement
• Overtype / insert toggle support
• Search through the document for the word under the cursor
• Web service proxies in Perl programs
• Brace matching
• Transposing characters
• Literal characters
Komodo 2.0 beta 2 for Windows (September, 2002)
Komodo 2.0 beta 1 for Linux (September, 2002)
Komodo 2.0 beta 1 for Windows (August, 2002)
Komodo 2.0 for Windows (September, 2002)
65
Komodo User Guide
Komodo 1.2.9 (July, 2002)
The following issues were addressed in Komodo 1.2.x releases:
Editor
• (Windows only) Syntax checking now works properly for files located on a network.
• (Tcl, Perl and PHP) Double-clicking variables now selects the variable prefix.
• When dragging and dropping text into the Editor Pane, Komodo no longer attempts to open
a new file.
• When dragging and dropping text from the Editor Pane to other parts of Komodo, Komodo
was crashing. This has been fixed.
• When CallTips are displayed, tip highlighting now progresses as statement components are
entered in the editor.
• When opening large HTML files in the editor, Komodo no longer displays a syntax error
warning.
• Search and replace strings containing backslashes are now handled properly.
• The error regarding invalid regular expressions during search and replace has been fixed.
• Templates in language directories are now correctly included in the language categories.
General Debugging
• Watched variables can be manipulated regardless of whether the debugger is running.
• When the debugger is running, use 'Ctrl'+'F10' to run the debugger to the current cursor
position.
• When the debugger is running, the current line is now highlighted. The highlighting is
dimmed when a stack other than the current stack is selected.
• The debugger now positions the current line in the middle of the Editor Pane.
Perl Editing and Debugging
• Socket errors in Perl debugger connections have been fixed by the addition of a new
configuration item. Select Edit|Preferences|Debugger, and enter the socket port in the Perl
Listener Port field. The "CallKomodo" configuration of the PERLDB_OPTS is no longer
used, and can be removed. See Debugging Perl Remotely for more information.
• Support for the overload.pm module has been added.
• Evals in included files no longer fail when stepping into the included file.
• "Here" doc styling is now supported.
• When debugging Perl, the Komodo debugger does not step over "require" statements.
PHP Editing and Debugging
• Komodo now fails gracefully if the php.ini file does not exist in the specified location.
• AutoComplete is now available inside strings.
• The icon on the Komodo start page now correctly shows when PHP has been enabled.
• AutoComplete no longer fails inside certain string elements.
• Syntax checking now functions on large PHP files.
• PHP configuration is correctly reloaded if it is changed.
• AutoComplete now picks up changes in the php.ini file.
Komodo 1.2.9 (July, 2002)
66
Komodo User Guide
• The PHP 4.1 / 4.2 debugger extension is included with the Komodo distribution. Note that
the 4.1 debugger extension functions with PHP version 4.2.
Tcl Editing and Debugging
• Breakpoints can now be set in included files.
• For Tcl Dev Kit users, Prowrap was being incorrectly called, rather than Procheck.
Other
• PDK version 4.0 is now supported.
• The Rx Toolkit has better font styling.
• To speed initial startup, sample Web services are no longer added to the Komodo
Preferences.
Web Services
• When parsing WSDLs, there is now schema support for complex types (however, not all
schema is supported).
• The WSDL parser now parses all XMethods.com WSDL files.
Komodo 1.2.7 RC1 for Windows and Linux (March, 2002)
Komodo 1.2 for Windows and Linux (December, 2001)
Web Service Consumption
Komodo provides Web service support, bookmarks; quickly add Web services to Perl, Python or
PHP files (including automatic language support like CallTips and AutoCompletion for Web service
objects); browse your Web service bookmark library in the Komodo User Guide.
Share Recipes with the ASPN Cookbook
Komodo provides a fast, easy way to share recipes. Submit your favorite Perl regular expression or
Python, Tcl or XSLT code snippet to the ASPN Cookbook.
Enhanced Editing
The Komodo editor detects files that have changed on disk, and gives you the option to reload.
Komodo also remembers the "state" of each file in the Most Recently Used list, including cursor
position, bookmarks, fold points, language association, and whitespace preference. Undo changes
to a file using the Revert File function. Quickly select blocks of code when performing editing
functions; configure text to auto-wrap in the editor and to auto-save at the interval you prefer.
Keyboard Shortcuts
New keyboard shortcuts include 'Ctrl'+Insert' (copy), 'Shift'+'Delete' (cut), 'Shift'+'Insert' (paste) and
'Ctrl'+<debug command> (suppress Debug Options dialog). Note that you can also use the 'Ctrl'
key in conjunction with the Debugging Toolbar buttons to suppress display of the Debugging
Options dialog box.
Komodo 1.2.7 RC1 for Windows and Linux (March, 2002)
67
Komodo User Guide
Find and Replace
Search and / or Replace a word or phrase in all documents open in the Komodo editor. Use the
new tab on the Output Pane to view all results from Find or Replace operations.
Templates and Macros
Code faster with language-specific templates. Create custom templates, and embed variables for
date and time stamps.
Perl Dev Kit Support
Use Komodo in conjunction with the Perl Dev Kit to build Windows executables, services and
controls written in Perl.
Tcl Support
With a membership to ASPN Tcl, use Komodo's syntax checking and debugging with Tcl.
FTP Support
Edit remote files on FTP servers; add remote files to projects; save files to remote FTP servers.
Use Komodo's Preferences to configure connection information for servers you use frequently.
Komodo User Guide
Search the User Guide or find a word or phrase in the current page; navigate using the Table of
Contents; change the font size. Take a visual tour of the Komodo Workspace, the Komodo
Debugger, the Komodo Editor or the Rx Toolkit.
Komodo Tutorials
Learn about new languages and language-specific Komodo features in the Tutorials.
PHP
Now supports AutoCompletion.
Fonts and Colors
Customize the display of fonts and colors for elements of every language supported by Komodo.
CGI Debugging Emulation
Emulate a CGI environment while debugging on your local machine by configuring server
environment variables and form input.
Enhanced Debugging
Expanded Debugging Options remember your debug settings from one session to another; view
Komodo 1.2 for Windows and Linux (December, 2001)
68
Komodo User Guide
HTML output on the Output tab; configure the Remote Debugging Listener Port; enter program
input on the Output tab.
Run Commands
Interact with the command line using the Run Commands function.
Internationalization
Set the default encoding for files in Komodo's Preferences. While Komodo does not yet support
editing outside of the English character set, non-English characters in existing files will be
preserved.
Komodo 1.2 beta 1 for Linux (November, 2001)
Komodo 1.2 beta 2 for Windows (November, 2001)
Komodo 1.2 beta 1 for Windows (October, 2001)
Komodo 1.1 (June, 2001)
PHP Debugging Enjoy PHP syntax checking and debugging with Komodo. You can configure
Komodo to debug PHP files locally or within a Web server environment. For more information, see
Debugging Programs in the Online Help.
XSLT Debugging - This release supports XSLT debugging. You can view your XSLT file, your
XML input file, and your output simultaneously. You can even open an XML file on your Web server
and transform the file while you debug your XSLT program. We've also improved the sample XSLT
file in our Sample Project. For more information on XSLT debugging, see Debugging Programs in
the Online Help.
Tcl support - You can now use Komodo to edit your Tcl files, including syntax coloring, code
folding, AutoComplete and CallTips. We added a Tcl file to our Sample Project. If you have Tcl Dev
Kit, you can enjoy Tcl syntax checking within Komodo. We plan to include stand-alone syntax
checking that does not require Tcl Dev Kit in an upcoming release. Komodo does not yet support
Tcl debugging.
Improved Performance - This release is based on the latest Mozilla tree, which includes an
optimized code base. Performance improvements include faster installation and startup and faster
response while you type or change files. Komodo responds much faster during debugging, when
opening files and switching between files, and when loading the File Associations pane in the
Preferences dialog.
Support for more languages - You can now use Komodo to edit Ruby and other languages, such
as VB and SQL.
Improvements for Komodo on Linux - You can now resize the Komodo workspace, you can use
fixed-width fonts, and you can debug Perl scripts if you have Perl 5.6 installed and configured.
Komodo 1.2 beta 1 for Linux (November, 2001)
69
Komodo User Guide
XML AutoComplete - Komodo now features AutoComplete for your XML files. When you type an
open angle-bracket "<", Komodo lists the elements in your file. Komodo XML AutoComplete also
lists tag attributes and suggests attribute values for certain values. XML AutoComplete also helps
you close your tags.
Expanded Find and Replace dialog - You can now use regular expressions in your find and
replace strings, you can search through folded text, and more.
Partial Unicode support - Komodo supports ASCII, Latin-1 and Unicode (UTF-8, UCS-2 or
UCS-4) encoding. If you use Komodo to edit a file that has a different character encoding than
those mentioned above, non-English characters may be removed when you save the file.
Komodo 1.0 (April, 2001)
Komodo .1 (November, 2000)
Komodo 1.1 (June, 2001)
70
License and Copyrights
Copyright © 2006 ActiveState Software Inc. All Rights Reserved.
ActiveState is a registered trademark of ActiveState Software Inc. Komodo, the Perl Dev Kit, the
Tcl Dev Kit, ActivePerl, ActivePython, ActiveTcl and ASPN are trademarks of ActiveState
Software Inc.
All other products mentioned are trademarks or registered trademarks of their respective
companies.
Some of the icons in Komodo are used under Creative Commons license from Mark James, and
some are the work of Bright Creative. We are grateful to Mark James and Dave Shea for their great
creative work. Some SCC icons are derived from those in the TortoiseSVN project and used under
the TortoiseSVN Icon License.
The Komodo documentation is licensed under a Creative Commons
Attribution-Noncommercial-Share Alike 2.5 Canada License. Users are encouraged to make
translations or add content and share them with other users on the Komodo community site.
Suggested corrections should be submitted to the Komodo Bug Database.
ActiveState Komodo licenses are issued on a per-user basis. A Komodo license may be installed
on more than one system or platform, as long as the licensee is the sole user of the software.
Komodo License
ActiveState Test Agreement
IMPORTANT! READ THIS LICENSE AGREEMENT BEFORE INSTALLING, OR ELECTRONICALLY
DOWNLOADING THE ACTIVESTATE TEST SOFTWARE ("PRODUCT"). ANY OF THE ABOVE
ACTIONS INDICATE ACCEPTANCE OF, AND LEGALLY BINDS YOU ("LICENSEE"), AND
ACTIVESTATE CORPORATION ("ACTIVESTATE") TO THE TERMS AND CONDITIONS SET
FORTH BELOW. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, THEN DO NOT
TAKE ANY OF THE ABOVE ACTIONS OR USE OR COPY THE PRODUCT.
By participating in the ActiveState Test Program, Licensee gains access to
the Product prior to public release, and has the opportunity to provide
feedback to ActiveState with suggested changes to the release. The purpose
of this Agreement is to acknowledge the conditions whereby Licensee is
authorized to test the Product.
ActiveState hereby grants to Licensee a non-exclusive, non-transferable
license (the "License") to use the Product only for the purpose of testing
the Product. The following conditions will apply to the test program for the
Product:
1. The test period will begin upon electronic download of the Product,
and may be terminated at any time by either Licensee or by ActiveState, by
providing written notification of such intent.
2. The duration of the test period ends on the date when the Product is
announced by ActiveState as being commercially released, or six months from
acceptance of this Agreement, whichever comes first.
3. In the event of any such termination or expiration referred to in
License and Copyrights
71
Komodo User Guide
sections 1 and 2 above, Licensee agrees to immediately destroy and/or erase
the original and all copies of the Product, together with any accompanying
License Keys, and to discontinue their use.
4. During the test period, there may be additional releases of the
Product, which will be provided to Licensee for installation by Licensee.
5. As a normal part of the test program, Licensee agrees to provide
timely feedback to ActiveState representatives on the progress of the test.
This may include bug reports, correspondence with ActiveState
representatives, Product surveys, or written evaluations of Product.
Feedback and other information which is provided by Licensee to ActiveState
in connection with the Product or this Agreement may be used by ActiveState
to improve or enhance its products and, accordingly, ActiveState shall have
a non-exclusive, perpetual, irrevocable, royalty-free, worldwide right and
license to use, reproduce, disclose, sublicense, distribute, modify, and
otherwise exploit such feedback and information without restriction.
6. LICENSEE RECOGNIZES THAT ALL PRODUCT AND OTHER ITEMS PROVIDED TO
LICENSEE HEREUNDER ARE DELIVERED "AS IS." LICENSEE ASSUMES THE ENTIRE RISK
AS TO THE QUALITY AND PERFORMANCE OF PRODUCT. NO WARRANTIES ARE GIVEN,
WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, WITHOUT LIMITATION,
IMPLIED WARRANTIES OF FITNESS FOR PARTICULAR PURPOSE OR MERCHANTABILITY OR
ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. IN NO EVENT WILL
ACTIVESTATE BE LIABLE FOR ANY SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
OR FOR ANY LIABILITY IN TORT, NEGLIGENCE, OR ANY OTHER LIABILITY INCURRED BY
OR UNDER OR IN CONNECTION WITH THIS AGREEMENT. WITHOUT LIMITING THE
GENERALITY OF THE FOREGOING, ACTIVESTATE DOES NOT WARRANT THAT THE USE OF
THE PRODUCT, OR OF ANY INFORMATION CONTAINED IN OR RELATED TO THE PRODUCT,
WILL NOT INFRINGE ANY PATENT, COPYRIGHT, OR TRADEMARK OF ANY THIRD PERSON,
OR THAT THE PRODUCT OR ANY PARTICULAR FEATURES OR FUNCTION CONTAINED IN IT
WILL EVER BE ANNOUNCED AS A GENERALLY COMMERCIALLY AVAILABLE PRODUCT.
7. Licensee shall not modify, reverse engineer, disassemble, reverse
compile, distribute, rent, lease, assign or transfer the Product, nor shall
Licensee create any derivative works of the Product. To the extent that the
Product includes run time or other components licensed by ActiveState from
third parties, Licensee shall not create any software program that links,
embeds or makes direct function calls to such components. Licensee shall not
copy the Product except as reasonably required for backup or archival
purposes, and shall include ActiveState's and its licensors' copyright,
patent, trademark and other proprietary rights notices on all such copies.
The Product shall remain the exclusive property of ActiveState or its
Licensors, and ActiveState reserves all rights not expressly granted to
Licensee.
8. This Agreement sets forth the entire understanding between the parties
with respect to the matters set forth herein and supersedes all prior
representations, understandings, or agreements, whether written or oral,
express or implied, with respect to this transaction.
Komodo License
72
Sending Feedback
We welcome your feedback, suggestions, feature requests and bug reports.
Comments and Feature Requests
If you tried Komodo and you would like to see a certain feature, or you would like to tell us how
Komodo met or didn't meet your coding needs, send us an email.
Please send suggestions and feature requests to [email protected]
Reporting Bugs
If you have found a bug, we'd like to know about it. First, view our on-line bug database and see if
your bug has already been reported. If you can't find your issue, you can submit a bug report.
To view our bug database and submit a bug report:
1. Go to our on-line bug database at http://bugs.ActiveState.com/Komodo/query.cgi
or
From the Komodo Workspace, go to the Help menu and select Komodo Bug Database.
2. Click View Bugs. You can apply filters and then sort the result by column.
3. If necessary, click Search and enter a keyword for your bug.
4. If you can't see your bug, click Submit a bug.
5. Complete the on-line form with as much detail as possible. This helps us identify the
problem.
6. Click Submit Bug Report.
If you make a mistake, click Reset.
Your bug will be assigned an ID and you can monitor the progress of your bug on this Web site. We
will email you when your bug is resolved.
Sending Feedback
73
Working with Projects
Komodo projects are containers for files, folders, templates, macros, run
commands, snippets and links specific to a particular software project or
website. There are two types of Komodo projects:
• Live Projects: A live project does a Live Import of the directory
where the project is created, thereby including all the files and
sub-directories of that directory. This becomes the live project's
base directory. Changes in the filesystem are reflected in the
project, and deleting files from the project gives you the option to
delete them from the filesystem (the "Move to Trash" option). This
kind of project is essentially a top-level live folder.
• Static Projects: Static projects are virtual containers for project
components, similar to virtual folders. They can, however, contain
live folders.
Feature Showcases
• create a custom
toolbar
• create a
directory
shortcut
• export and
import a
package
• assign a
custom
keybinding to a
component
• store a template
in a project
By default, new Komodo projects are "live". This can be changed with the
Live Import preference.
Komodo projects are XML files stored on disk with a ".kpf" extension. If you manually edit the
project file, make a backup copy first; invalid project files will not load.
Components can be dragged and dropped between projects and the Toolbox. Context menus are
available for the various components and a Project drop-down menu. New items can be added via
the Add item drop-down menu in the project tab's toolbar.
Displaying the Project Tab
The Project tab is displayed in the left pane of the Komodo workspace. It is displayed or hidden via:
• View|Tabs|Projects: Opens the left pane with the Project tab in the foreground.
• Key Binding: The default key binding for opening and closing the left pane is
'Ctrl'+'Shift'+'P'. See Configuring Key Bindings to alter or view the current assignment.
• Workspace Toolbar: If the Workspace Toolbar is displayed, click the Show/Hide Left
Pane button. (Select View|Toolbars|Workspace to display the toolbar.) Alternatively, click
the Show Specific Tab button and select Projects.
Creating Projects
To create a Project, use one of the following methods:
• File Menu: On the File menu, select New|New Project.
• File Menu: On the File menu, select New|New Project From Template..., select the
desired project template and click Open.
• Project Menu: On the Project menu, click New Project.
• Project Menu: On the Project menu, click New Project From Template..., select the
desired project template and click Open.
• Project Tab: New Project Button: On the Projects tab, click the
New Project button.
Working with Projects
74
Komodo User Guide
When creating a new project, you are prompted to select a directory where the project file is stored.
The project filename becomes the project name displayed in the Project Tab (without the ".kpf"
extension). "Live" projects will automatically import the files and sub-directories in this directory.
Live Import
The Live Import option in Project Properties and Settings (set globally in Komodo under
Edit|Preferences|Directory Import) makes the project behave as a Live Folder. A project created
with Live Import enabled is a live project.
Opening Projects
Existing projects are opened by any of the following methods:
• File|Open Menu: Select File|Open|Project.
• Project Menu: Select Project|Open Project
• Project Tab: On the Projects tab, click the Open Project button.
Recently opened projects can be accessed from the Komodo Start Page, or from the File|Recent
Projects menu. (The number of recently opened projects is determined by the Most Recently Used
preference.)
The project name and associated files are displayed on the Projects tab. By default, opening a
project only opens the project file, not the components associated with the project. The Opening
and Closing Projects preferences can change this behavior to automatically open recent project
files (and close them when the project is closed).
Setting the Active Project
Multiple projects can be open at the same time. Components in any open project can be used.
However, only one project at a time is "active". The active project is displayed in bold text. When
the Add Component button in the Project Tab is invoked, the component is added to the active
project, regardless of the project that is currently highlighted.
Knowing which project is currently active is important because file preferences can be stored in
projects. Komodo chooses a location for saved preferences based on the following criteria:
• When debugging a file in the active project, preferences are stored in the active project.
• When debugging a file in a project which is open but not active, preferences are stored in
the first project found containing that file.
• When debugging a file that is not in an open project, preferences are saved as a 'global'
preference for that file.
To set the active project, right-click the desired project name and select Make Active Project, or
select Project|Make Active Project from the drop-down menu.
Creating Projects
75
Komodo User Guide
Adding Components to Projects
Projects are organization containers for "components". Components are items like files, folders,
snippets, macros, etc. For information about individual components, refer to the relevant section of
the documentation for the specific component.
Filesystem-based components consists of items that exist as entities on the disk: files and
templates. Komodo-specific components exist only in Komodo, and are not stored as external disk
entities. Komodo-specific components include open shortcuts, folders, snippets, run commands,
URL shortcuts, macros and custom menus and toolbars.
Within projects, filesytem-based components are merely references; they cannot be moved or
deleted from within Komodo; moving them between projects and the Toolbox, or deleting them from
projects or the Toolbox, has no effect on their actual disk-based location or their contents. On the
other hand, Komodo-specific components (such as macros and snippets) do not exist outside of
Komodo; therefore, they can be moved and copied (for example, from the Toolbox to the Project
Tab) and deleted independently of the filesystem.
For example, when a snippet (a Komodo-specific component) is copied from the Project Tab to the
Toolbox, a new copy of the snippet is created; the original version still exists in the original location.
Subsequent modifications of the snippet in the Toolbox do not change the version of the snippet
stored in a project. On the other hand, when the contents of a file (a filesystem-based component)
are changed, the changes apply regardless of the location from which the file is invoked.
To add a component to a project:
• Project|Add: Use the Project drop-down menu. If multiple projects are open, the
component is added to the project that is currently active.
• Project|Add|project_name: When a project name is selected in the Project Tab, the
selected project's name is also displayed in the Project drop-down menu. Components can
be added directly to that project.
• Add Button: Use the Add
button on the Project tab. If multiple projects are open, the
component will be added to the project that is currently selected.
• Context Menu: Right-click a project name and select Add|component.
• Drag and Drop: Drag and drop components from:
♦ Drag-and-Drop-Aware Applications: Filenames can be dragged from
drag-and-drop applications (such as Windows Explorer).
♦ Project Tab or Toolbox: Components can be dragged between projects, the
Toolbox and container components (such as folders).
♦ Editor File Name Tabs: When a file is open in the editor pane, drag and drop from
the tab that displays the filename to a project.
• Import from Filesystem: Right-click a project and select Import from File System.
• Cut/Copy/Paste: All components have a right-click menu that includes the options Cut,
Copy and Paste. Use these options to move components between projects, the Toolbox
and container components.
Some components have special component-specific mechanisms for being added to projects. For
example, snippets can be created and added to a project in one step by selecting a block of text in
the Editor Pane and dragging it onto a project. URL shortcuts are created by dragging and dropping
a URL from a browser address bar or from the Editor Pane onto a project. Refer to the specific
Adding Components to Projects
76
Komodo User Guide
component sections for more information about these options.
To remove a component from a project, click the desired component and press 'Delete', or
right-click the component and select Delete from the context menu.
Komodo-specific components (such as run commands, macros, etc) are permanently deleted.
Filesystem-based components (such as files and dialog projects) are not; only the reference to the
component within the project is removed.
Project Display Settings
Use the button on the top right of the Project Tab to select the fields that are displayed in the
Project Tab. Click the column headings to organize the items according to the contents of any
column.
Column contents depend on the type of component. For example, the Status and Depot Rev
display options only have contents if the component is part of a source code control repository.
The following columns can be displayed:
• Date: The date from the filesystem when the component was last saved.
• Size: The filesystem size of the component.
• Status: The source code control status of the component.
• Rev: When a component is part of a source code control repository, this column displays
the revision number of the local version of the file.
• Depot Rev: When a component is part of a source code control repository, this column
displays the revision number of the repository version of the file.
• Action: When a component is part of a source code control repository, this column displays
the current action (if any) being performed on the file. For example, if a file is currently
opened for editing, the action is "edit".
• Name: The name of the component. For filesystem-based components (such as files and
dialog projects), the name is equivalent to the filename. For Komodo-specific components
(such as macros and run commands), the name is the user-defined name assigned to the
component.
Saving Projects
If an asterisk is displayed beside the project name, the project has changed since it was opened or
last saved. This happens not only when components are added, edited or removed in the Project
Pane, but also when debugging options are changed for files in the project. To save a project:
• File Menu: On the File menu, click Save Project.
• Project Menu: On the Project menu, click Save Project. This saves the active project. If a
project name is currently highlighted in the Project Tab, the Project menu contains an
option for saving the selected project (Project|project_name|Save Project).
• Project Tab: Save Project Button: On the Projects tab, click the Save Project button.
• Project Context Menu: Right-click the desired project and select Save Project.
The mechanisms described above can also be used to save a project to a new project file by
Project Display Settings
77
Komodo User Guide
selecting Save Project As... rather than Save. Filesystem-based components (such as files and
dialog boxes) are relative references rather than actual entities; in the new project, the reference to
the location of the component is preserved. Komodo-specific components (such as macros and run
commands) are copied to the new project; there are independent versions of the component in the
original project and in the new project.
Refreshing Project Status
The Refresh Status option checks read/write disk status for the project file and for
filesystem-based components (such as files and dialog projects) within the project. If the project
contains files of a language for which "code intelligence" is supported and enabled (as configured in
the Code Intelligence Preferences), Refresh Status also updates the code intelligence database
with the contents of those files.
If the project or its components are stored in a source code control system, Refresh Status also
checks the repository status of the file. Komodo determines whether a file is contained in an SCC
repository by the following methods:
• Perforce: query of the P4 repository (with the current user's client spec)
• CVS: analysis of the CVS control directories
• Subversion: analysis of the subversion control files
Importing and Exporting Projects via Packages
Entire projects (including all the components contained in a project) can be exported to a "package"
file for distribution to other Komodo users or for the sake of archiving. Packages are compressed
archive files that contain the project from which the Export Package option was invoked. The
Export Package option differs from the Export as Project File option (provided for project
components) in that Export Package creates a self-contained archive file that contains copies of
all the filesystem-based components (such as files and dialogs). Export as Project File, on the
other hand, only contains Komodo-specific components (such as snippets and run commands).
To export a project and its contents to an archive, select Project|project_name|Export Package
from the drop-down menu, or right-click the project and select Export Package.
The Package Export Wizard prompts for a Package Name and a Export Location. The Package
Name is the file in which the package is stored; it will have the extension ".kpz", and can be opened
by any archiving utility that supports libz (for example WinZip).
Exported packages can only be imported into "container" objects in Komodo, such as projects, the
Toolbox, and folders within projects and the Toolbox.
To import the contents of a package into a project, right-click the project to which you want to
import the package, and click Import Package. The Package Import Wizard prompts for the name
of the package and the location on disk where the files will be extracted. Click Next and then click
Finish to complete the import.
For information about importing packages to the Toolbox or a folder, see Toolbox - Import Package
and Folders - Import Package for more information.
Saving Projects
78
Komodo User Guide
Importing Files from the File System
This option creates files within a project based on the directory structure and file contents of a local
or network filesystem. File references within the project are created for imported files; folders are
created for directories (depending on the configuration of the import options). To import a
filesystem into a project:
• Project Menu: On the Project menu, click Import from File System. This imports the
specified filesystem (according to the criteria described below) into the current active
project. If a project name is currently highlighted in the Project Tab, the Project menu
contains an option for importing into the selected project (Project|project_name|Import
from File System).
• Project Context Menu: Right-click the desired project and select Import from File
System.
Configure the following import options:
• Directory to import from: Specify the directory from which you want to import files. Use the
Browse button to navigate the file system.
• Browse for directory location: Choose Locally... to browse the local filesystem or
Remotely... to browse a remote filesystem.
• Files to include: Specify the filenames to include. Use wildcards ("*" and "?") to specify
groups of files. Separate multiple file specifications with semicolons. If the field is left blank,
all files in the specified directory are imported.
• Files and directories to exclude: Specify the file and directory names to exclude. Use
wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with
semicolons. If the field is left blank, no files in the specified directory are excluded.
• Import Subdirectories Recursively: Select this check box to import directories (and files
contained in those directories) located beneath the directory specified in the Directory to
import from field. This check box must be checked in order to specify the "Import Directory
Structure" option as the Type of folder structure to create.
• Type of folder structure to create:
♦ Import directory structure: If the Import Subdirectories Recursively box is
selected and this option is selected, Komodo creates folders within the project that
represent imported directories. Thus, the directory structure is preserved within the
project.
♦ Make a folder per language: If this option is selected, imported files are organized
into folders according to the language indicated by file pattern in the filename. File
associations are configured in the Komodo Preferences. Each folder is named after
the associated language, for example, "Perl files", "XML files", etc. Files that don't
correspond to a known file pattern are stored in a folder called "Other files".
♦ Make one flat list: If this option is selected, all the imported files are placed directly
under the project from which the Import from File System command was invoked.
Source Code ControlKomodo IDE only
Source code control refers to projects and/or components stored in a source code control depot
(such as a CVS or Perforce repository). There are two aspects to source code control within
projects: source code control on the project file itself, and source code control on components
Importing Files from the File System
79
Komodo User Guide
contained in projects.
When Komodo integration with a source code control system is configured, icons in the Project
Manager display the SCC status of the project file and components contained in the project. See
file status icons in the source code control documentation for more information about these icons.
Source code control functions (such as adding files to an SCC repository, or opening files
contained in a repository for editing) can be performed both on the project file, and on the
components contained in the project. To access SCC commands for a project file:
• Project Menu: Click the project name in the Project Manager, then select
Project|project_name|Source Control).
• Project Context Menu: Right-click the desired project and select Source Control.
To access SCC commands for the components contained in a project:
• Project Menu: Click the project name in the Project Manager, then select
Project|project_name|Source Control on Contents).
• Project Context Menu: Right-click the desired project and select Source Control on
Contents.
See Source Code Control Commands for a description of each of the commands.
Reverting Projects
If a project has been altered but has not been saved, use the Revert Project option to undo the
changes. To access the Revert Project option:
• Project Context Menu: Right-click the desired project and select Revert Project.
• Project Menu: Select Project|Revert Project or Project|project_name|Revert Project.
Project|Revert Project reverts the active project. If a project name is currently highlighted
in the Project Tab, the Project menu contains an option for reverting the selected project
(Project|project_name|Revert Project).
Closing Projects
Closing a project removes it from the Project Tab. To close a project:
• File Menu: On the File menu, click Close Project.
• Project Menu: On the Project menu, click Close Project. This closes the active project. If
a project name is currently highlighted in the Project Tab, the Project menu contains an
option for closing the selected project (Project|project_name|Close Project).
• Project Context Menu: Right-click the desired project and select Close Project.
If the project has changed since it was last saved, you are prompted to save it. If files contained in
the project are open in the editor, you are asked if you wish to close them.
Source Code ControlKomodo IDE only
80
Komodo User Guide
Deleting Projects
When a project is deleted, the project file is deleted from disk; Komodo-specific components (such
as run commands and macros) stored in the project are also deleted. Filesystem-based
components (such as files and dialog projects) are not deleted. To delete a project, delete the
project file from the filesystem.
Project Properties and Settings
The Project Properties and Settings dialog box contains information about the project file, such as
its size, its location on disk, its directory import settings, its source code control status, and
project-specific language settings.
To access the Project Properties dialog box, right-click the desired project name and select
Properties, or click the desired project and select Project|project_name|Properties from the
drop-down menu.
The following categories are available:
• Properties: Displays the name, size, and location of the project; the date and time it was
created, last modified and last accessed; and indicates if the project is read-only.
• Source Code Control: Displays SCC status as applicable (SCC System, Status, Depot
Revision, and My Revision).
• Debugging: Displays a subset of the settings available in the Debugging Options dialog
box. These settings will take precedence over the default debugging settings for files in the
project.
• Directory Import: Defines how Komodo dynamically imports files and directories into the
project. These settings override those configured in Komodo's global Directory Import
preferences. Select the Live Import check box to keep the imported directories and files
current with the file system via Live Folders.
• Languages: Allows you to add additional directories to a language's path for Komodo to
use when debugging, syntax checking, or in the interactive shell. Komodo will also scan
these directories for autocomplete and calltip information.
Project Templates
Project templates are useful if you find yourself repeatedly creating the same types of projects. See
the Project Templates documentation for information on using Komodo's sample project templates,
and saving your own.
Deleting Projects
81
Using the Toolbox
The Komodo Toolbox stores components that are frequently used. The
Toolbox is similar to a persistent project; however, rather than storing
components that are specific to a particular project, it stores components
that are used for a variety of tasks.
The Projects Manager and the Toolbox share a common set of
components. Components are of two types: Komodo-specific components
(such as macros, run commands and custom menus) and
filesystem-based components (such as files and dialog projects).
Components within the Projects tab and the Toolbox are manipulated
using an intuitive drag-and-drop interface, by context menus, or via the
Project and Toolbox drop-down menus. Component options are
accessed via the drop-down menus, or via right-click context menus.
Feature Showcases
• create a custom
toolbar
• create a
directory
shortcut
• import a
filesystem
• assign a
custom
keybinding to a
component
• store a template
in a project
Displaying the Toolbox
The Toolbox is displayed on a "tab" in the Right Pane of the Komodo workspace. It is displayed or
hidden via any of the following methods:
• View|Tabs|Toolbox: Use the View drop-down menu to modify Komodo's display
characteristics.
• Key Binding: The default key binding (in the default key binding scheme) for opening and
closing the Toolbox tab is 'Ctrl'+'Shift'+'T'. See Configuring Key Bindings to alter or view the
current key assignment.
• Workspace Toolbar: If the Workspace Toolbar is displayed, click the "Show/Hide Right
Pane" button. (Select View|Toolbars|Workspace to display the toolbar.) Alternatively, click
the "Show Specific Tab" button and select Toolbox.
Adding Components to the Toolbox
The Toolbox is an organizational container for frequently used "components". Components are
items like files, folders, snippets, macros, etc. For information about individual components, refer to
the relevant section of the documentation.
Filesystem-based components consists of items that exist as entities on the disk: files and
templates. Komodo-specific components exist only in Komodo, and are not stored as external disk
entities. Komodo-specific components include open shortcuts, folders, snippets, run commands,
URL shortcuts, macros and custom menus and toolbars.
Within the toolbox, filesytem-based components are merely references; they cannot be moved or
deleted from within Komodo; moving them between projects and the Toolbox, or deleting them from
projects or the Toolbox, has no effect on their actual disk-based location or their contents. On the
other hand, Komodo-specific components do not exist outside of Komodo; therefore, they can be
moved and copied (for example, from the Toolbox to the Projects tab) and deleted independently of
the filesystem.
Using the Toolbox
82
Komodo User Guide
For example, when a snippet (a Komodo-specific component) is copied from the Projects tab to the
Toolbox, a new copy of the snippet is created; the original version still exists in the original location.
Subsequent modifications of the snippet in the Toolbox do not change the version of the snippet
stored in the Projects tab. On the other hand, when the contents of a file (a filesystem-based
component) are changed, the changes apply regardless of the location from which the file is
invoked.
To add a component to the Toolbox:
• Toolbox|Add: Use the Toolbox drop-down menu.
• Toolbox|Add|folder_name: When a folder name is selected in the Toolbox, the selected
folder's name is also displayed on the Toolbox drop-down menu. Components can be
added directly to that folder.
• Add Button: Use the Add
button on the Toolbox tab.
• Drag and Drop: Drag and drop components from:
♦ Drag-and-Drop-Aware Applications: Filenames can be dragged from
drag-and-drop applications (such as Windows Explorer).
♦ Projects tab or Toolbox: Components can be dragged between projects, the
Toolbox and container components (such as folders).
♦ Editor Filename Tabs: When a file is open in the Editor Pane, drag and drop from
the tab that displays the filename to the Toolbox.
• Import from Filesystem: Right-click a folder and select Import from File System.
• Cut/Copy/Paste: All components have a right-click menu that includes the options Cut,
Copy and Paste. Use these options to move components between projects, the Toolbox
and container components (such as folders).
Some components have special component-specific mechanisms for being added to projects. For
example, snippets can be created and added to the Toolbox in one step by selecting a block of text
in the Editor Pane and dragging it into the Toolbox. URL shortcuts are created by dragging and
dropping a URL from a browser address bar or from the Editor Pane into the Toolbox. Refer to the
specific component sections for more information about these options.
To remove a component from the Toolbox, right-click the desired item and select Delete.
Alternatively, click the desired component and press 'Delete', or right-click the component and
select Delete.
Komodo-specific components (run commands, macros, etc) are permanently deleted.
Filesystem-based components (files, dialog boxes) are not; only the reference to the component
within the project is removed.
Exporting and Importing Toolbox Contents
The Toolbox has commands for exporting and importing the contents of the Toolbox as a package.
Packages, which are stored with a ".kpz" extension, are compressed archive files, and can be
opened by any archiving utility that supports libz (for example WinZip). The Export Package
option differs from the Export as Project File option in that copies of filesystem-based components
(such as files and dialog projects) are included in the archive. Conversely, Export as Project File
creates a project with a reference to the component's original location and does not create copies
of the components.
Adding Components to the Toolbox
83
Komodo User Guide
Both Komodo-specific components (such as run commands and snippets) and filesystem-based
components (such as files and dialog projects) can be included. The exported file can subsequently
be loaded as a project or imported into the Toolbox. This provides a mechanism for sharing a
Toolbox among multiple Komodo users; another mechanism is described in the "Shared Toolbox"
section below.
To export the contents of the Toolbox to a project file:
1. From the Toolbox menu, select Export.
2. In the Export Package dialog box, choose the destination directory and enter a filename.
3. Click Save.
To import a previously exported Toolbox:
1. From the Toolbox menu, select Import.
2. In the Import Package dialog box, select the project file containing the item(s) that you
want to import.
3. Click Open.
Sharing Toolboxes
A Shared Toolbox is a single Toolbox shared by multiple Komodo users. When a Shared Toolbox
is enabled, a second tab called Shared Toolbox is displayed beside the Toolbox tab in the Right
Pane. This tab displays the contents of the toolbox.kpf file, located in the Common Data
Directory specified in Komodo's Shared Toolbox preference.
The functionality of the Shared Toolbox is determined by the user's access rights to the
toolbox.kpf file. All users with "read" rights to the file are able to use items from the Toolbox. To
prevent users from altering the shared toolbox, ensure that they only have "read" (and not "write")
access to the file.
The Shared Toolbox is populated by the same methods described in Adding Components to the
Toolbox.
Exporting and Importing Toolbox Contents
84
Working with Files
Komodo provides a variety of methods for accessing and editing files. While files can be opened
and edited individually, they can also be stored in projects or the Toolbox as components.
If Komodo is configured to integrate with a source code control system (SCC), status icons beside
the filenames indicate the file's current SCC status, and SCC options are available from the File
menu and the right-click context menus. This integration is described in detail in the Source Code
Control section of the Komodo documentation.
Files are manipulated in various ways: via the File menu, via context menus in the editor, via
context menus on the file tab (above the editor), and as components within projects and the
Toolbox.
This document describes file functionality, such as opening, printing, and saving files. See the
Editing page for information about editing files.
Creating Files
To create a new file, click the "New File" button on the standard toolbar. (To display the standard
toolbar, click View|Toolbars|Standard.) A new file with the default file extension for the file type is
created and opened in the Komodo editor. Use the New Files page in Komodo's Preferences to
specify the default file extension for new files.
Creating Files from Templates
New files can be created based on pre-defined templates that contain default content for specific
file types. See the Templates documentation for information about configuring custom templates.
To create a new file from a template, select File|New|File. The New File dialog box contains
numerous pre-defined templates organized into categories. Select the desired category, then select
the desired template within that category.
Click Open to create a file with the contents of the template file. The file is loaded in the editor.
The File|New|File menu displays a list of the most recently accessed templates. To alter the
number of template files displayed, refer to the New Files page in Komodo's Preferences.
To add a template to the Toolbox for quick access, select the desired template and click Add to
Toolbox.
Storing Files within a Project or the Toolbox
Files can be stored in a project, in the Toolbox, or within folders in a project or the Toolbox. Storing
a file within a project or the Toolbox creates a reference to the actual file located on the disk; it
does not affect the file itself. Therefore, the same file can be stored in multiple projects and folders,
both in projects and within the Toolbox; changes to the original source file apply regardless of the
source of the file reference; deleting a file from a project or the Toolbox does not delete the file from
Working with Files
85
Komodo User Guide
the filesystem.
While most file options (such as source code control commands, viewing unsaved changes, and
refreshing the file status) are accessible regardless or whether or not the file is contained in a
project or the Toolbox, some commands are specific to the project/Toolbox environment. These
commands are described below.
Creating an Open Shortcut to the Current File Location
Open... shortcuts, stored within a project or the Toolbox, are references to filesystem directories.
When an open shortcut is invoked, the standard Open File dialog box is displayed with the contents
of the directory.
Open shortcuts can be created using a specific file as the context. Right-click a file in a project or
the Toolbox and select Make "Open..." Shortcut. This creates an open shortcut to the directory
where the file is stored.
Exporting Files as Projects
The Export as Project File option is used to create a new project file containing the file from which
the option was invoked. To access this option, the file must be stored in a project or the Toolbox.
Right-click the desired file name and select Export as Project File. You are prompted to provide
the name of the new project file and the directory where it will be stored.
To open the new project file, select File|Open|Project.
Exporting Files to a Package
Files can be archived and distributed among multiple Komodo users via "packages". Packages are
compressed archive files that contain the file from which the Export Package option was invoked.
Packages are stored in files with a ".kpz" extension, and can be opened by any archiving utility that
supports libz (for example WinZip). The Export Package option differs from the Export as
Project File option in that copies of filesystem-based components (such as files and dialog
projects) are included in the archive. Conversely, Export as Project File creates a project with a
reference to the component's original location and does not create copies of the components.
When Export Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as projects, the
Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting and Importing
Toolbox Contents, Projects - Importing and Exporting Projects via Packages, or Folders - Import
Contents from Package for more information.
Opening Files
There are numerous methods for opening files in Komodo. These include:
• Command-Line Argument: When Komodo is invoked from the command line, files can be
specified as open arguments. See Starting on Windows, Starting on OSX, or Starting on
Linux for more information.
Storing Files within a Project or the Toolbox
86
Komodo User Guide
• File|Open: Use the File|Open menu option.
• Projects tab or Toolbox: Double-click, drag and drop, or use the file's right-click context
menu to open a file contained in a project or the Toolbox.
• Open/Find Toolbar: Use the Open/Find Toolbar. To display the Open/Find Toolbar, select
View|Toolbars|Open/Find.
• Most Recently Used List: The most recently opened files are displayed on Komodo's Start
Page. This list is also accessible from the File|Recent Files menu. The number of files in
the most recently used list is determined by the Appearance preference.
• Drag and Drop: Drag and drop one or more files from another drag-and-drop application
(such as Windows Explorer) onto the Komodo editor.
Opening Files with the Open/Find Toolbar
The Open/Find Toolbar provides quick access for opening files and finding strings. The toolbar is
displayed in Komodo by default. To hide or show the toolbar, select View|Toolbars|Open/Find.
Use the Open field on the Open/Find Toolbar to open one or more files in the filesystem. The
Open field generates a drop-down list of files and directories as you navigate the hierarchy. To
open a file, enter the file path and name, and then press 'Enter'.
For example, to open a file named "debug.txt" in the directory C:\temp\log on a machine running
Windows, enter C:\tmp\log\debug.txt in the Open field and then press 'Enter'. As you enter each
backslash, a drop-down list displays the files and directories beneath the current directory.
Enter "./" or ".\" in the Open field to display a list of files and directories in the "current" directory.
The current directory is determined as follows:
1. Current File: If a file is open in the editor, the directory where the file is stored is the current
directory. If multiple files are open, the file that is currently displayed is the current file.
2. HOME Variable: If no files are open, Komodo checks if the system has a defined HOME
environment variable. If so, the directory specified in that variable's value is the current
directory.
3. Filesystem Root: If neither of the above conditions is met, the system's root directory is
used ("C:\" is the default on Windows, and "/" is the default on Linux and Mac OS X).
To narrow the results in the list box, enter one or more characters in the name of the file or
directory you wish to open or view. (The search is case-sensitive.) Alternatively, use the arrow keys
to navigate the drop-down list. The contents of the Open field are updated as you move up and
down the list with the arrow keys.
Note that you can use standard directory navigation syntax to change directories. For example, if
the current directory is /home/fred/tmp/foo, change to the /home/fred/tmp/bar directory by entering
../bar.
To open a file, press 'Enter' when the file name is displayed in the Open field. To continue
navigating the directory structure, append a frontslash or backslash to the directory name displayed
in the Open field; the drop-down list is updated with the list of files and directories that exist under
the current location.
Opening Files
87
Komodo User Guide
To open multiple files, specify a wildcard ("*" for a file name segment, "?" for a specific character).
For example, to open all the files with the extension ".tcl" in the directory /home/fred/tmp, enter
/home/fred/tmp/*.tcl.
At any time, press the 'Escape' key to return focus to the Komodo editor.
Opening Remote Files
Komodo can open files located on remote machines, providing that the remote machine is
configured for FTP, SFTP, or SCP access. To quickly access frequently used servers, create an
entry in the Server Preferences (Edit|Preferences|Servers).
To open a file located on a remote server, select File|Open|Remote File.
Connecting to a remote Server
• Pre-Configured Server Connection: If remote servers have been configured in Komodo's
Preferences, select the name of the configuration from the Server drop-down list. Access
the Server Configuration dialog box by clicking the Accounts button to the right of the
Server field.
• Manual Server Connection: Enter the server's fully qualified hostname in the Server field.
Press 'Enter'. You are prompted to enter a name and password for the server. If the server
is configured for anonymous access, select Anonymous login. To store the login name
and password for the server, click Remember these values.
Navigating the Remote File System
After establishing a connection to the remote server, a list of files and directories is displayed.
These files and directories exist under the directory specified in the Look in field. Double-click a
directory (indicated by a file folder icon) to navigate the directory structure. Use the navigation
buttons in the top right corner of the dialog box to navigate the remote filesystem.
To open a single file, double-click the filename. To open multiple files, hold down the 'Ctrl' key while
clicking multiple files, then click Open.
The buttons in the top right corner of the dialog box perform various file and directory manipulation
functions. Hover your mouse pointer over the buttons for a description of their functions. To delete
or rename a file on the remote server, right-click the filename and, with the left mouse button,
select the desired command on the context menu.
Storing Remote Files in Projects or the Toolbox
When remote files are added to a project or the Toolbox, or to container components within a
project or the Toolbox, they are accessed and organized in the same manner as local files
(double-clicking a file opens it in the editor; right-clicking a file accesses file option, etc). Remote
files can only be added to projects or the Toolbox by connecting to the remote server.
Login authentication is processed when the remote file is opened, or when it is added to the
Toolbox or a project. For the duration of the Komodo session, the user name and password are
remembered; closing and opening the file uses the same authentication information as the first time
Opening Files with the Open/Find Toolbar
88
Komodo User Guide
the file was opened. If authentication fails, you are prompted to enter a user name and password.
After closing and re-opening Komodo, the authentication information stored in the Servers
preference is checked again. Thus, changes to the user name or password stored in the server
configuration do not take effect until Komodo is closed and re-opened. If no authentication
information is stored in the server configuration, you are prompted to supply it when you open the
file.
See Adding Components to Projects or Adding Components to the Toolbox for instructions on
adding remote files to the Toolbox or to projects.
To open a remote file, double-click the file name, use the assigned key binding, or right-click the file
and select Open File.
Opening Mapped URIs
Mapped URIs can be opened by dragging a mapped link from a browser into Komodo. For
example, if you mapped the URL http://www.example.org/ to the local directory /var/www/, you
could drag a link like http://www.example.org/projects/test.html from a browser into Komodo, which
would open the local file /var/www/projects/test.html
This feature also works with URIs mapped to remote filesystems (via FTP, SFTP or SCP), which in
turn can be configured for automatic authentication under Edit|Preferences|Servers.
Switching Between Files
To switch between open files in the editor:
• Key Binding: Use the associated key binding.
• Editor Tabs: Click the tab with the desired filename.
• Window Menu: On the Window menu, select Next File or Previous File to move from left
to right (or right to left) across the file tabs. Alternatively, select the desired file from the list
of files currently open in the editor.
• Project or Toolbox: Double-click the filename.
If more files are opened than can be displayed by file tabs, click the right and left arrow buttons
located in the top right corner of the editor to view the tabs of all open files.
To re-order the position of the file tabs, drag and drop the tabs into the desired positions.
For more information about working with the editor tabs, see Editor Tab Display in the editor
documentation.
Comparing Files
Komodo includes a "diff" mechanism used to compare files. To compare two files using Komodo's
"diff" window:
1. Select Tools|Compare Files.
Opening Remote Files
89
Komodo User Guide
2. By default, the path and file name of the file currently displayed in the editor is the first file
for comparison. As desired, alter this selection by entering an alternate path and file, or
browse for the desired file using Browse button. Use the same mechanism to specify the
second file.
3. Click Compare Files. The contents of both files are displayed in the "diff" window.
If the file is stored in a project or the Toolbox, this function can also be invoked by right-clicking the
file and selecting Compare File With.
The unique characteristics of each file are displayed in different colors (red and blue by default);
common characteristics are displayed in a third color (black by default). To configure custom colors
for the "diff" window, alter the Language-Specific Coloring setting for the Other|Diff language in
the Fonts and Colors preference.
The following key bindings are available in the "diff" window:
• F8: Jump to the next change.
• F7: Jump to the previous change.
• F9: Jump to corresponding line. Opens and/or shifts focus to the original file in the Editor
Pane. If viewing a diff in an editor tab, right-click and select Jump to Corresponding Line
(or select Code|Jump to Corresponding Line) to shift focus to the editor tab containing
the source code. Selecting this option opens the source code tab in the Editor Pane if it is
not already open and/or shifts focus to the original file in the Editor Pane. (If viewing a diff in
an editor tab, right-click and select Jump to Corresponding Line.)
• Esc: close the window
Refreshing File Status
The Refresh Status option checks the read/write disk status for the component. If the file is of a
language for which "code intelligence" is supported and enabled (as configured in the Code
Intelligence Preferences), Refresh Status also updates the code intelligence database with the
contents of the file.
If the component is stored in a source code control system, Refresh Status also checks the
repository status of the file. Komodo determines whether a file is contained in an SCC repository by
the following methods:
• Perforce: analysis of the client configuration
• CVS: analysis of the CVS control directories
To refresh the file status of the current file, right-click the file tab or right-click within the editor and
select Refresh Status. The same option is available on the right-click context menu of files in
projects or within the Toolbox.
Source Code Control
Komodo provides source code control support for files stored in CVS or Perforce repositories.
Source code control support (including SCC configuration, status icons and specific commands) is
described in detail in the Source Code Control section of the documentation. To access source
Comparing Files
90
Komodo User Guide
code control commands:
• Editor Context Menu: Right-click a file in the editor and select Source Control.
• File Tab Context Menu: Right-click a file tab above the editor and select Source Control.
• Toolbox or Project Context Menu: Right-click a file in the Toolbox or Projects tab and
select Source Control.
• Toolbox or Project Menu: If a file is currently selected in the Toolbox or Projects tab, use
the menu to access source code control commands for the selected file.
File Properties and Settings
In addition to the Komodo's global Preferences, some preferences can also be configured on a
per-file basis. These settings override the global and project level preferences. To access the
Properties and Settings dialog box for a file:
• Edit Menu: On the Edit menu, click Current File Settings.
• Editor Context Menu: Right-click in the editor and select Properties and Settings from the
context menu.
• File Tab Context Menu: Right-click the tab above the editor that displays the filename, and
select Properties and Settings.
File Properties
The Properties category in the Properties and Settings dialog box displays general information
about the file, such as the directory where it is stored, the size and creation and modification dates.
The following file characteristics can be modified on this tab:
• Attributes: Toggle the file's status between writable and read-only.
• Language: This field displays the current language association (which affects
language-specific options like syntax coloring and AutoComplete) for the current file. To
change the language association, select another language from the drop-down list. To set
the language association to the Komodo default (as configured in the File Association
Preference, click Reset.
• Encoding: Use this field to set the International Encoding for the current file. Select Use
signature (BOM) to use the byte order mark (a Unicode character at the top of the file
which indicates the encoding) if present.
• Line Endings: Use this field to set the desired line endings for the current file. By default,
Komodo preserves the line endings contained in a file when the file is opened. (Default line
endings for new files are configured in the New Files preference.) If you select Preserve
existing line endings, new lines are assigned the end-of-line character selected in the
drop-down list, but existing lines are not be altered.
For HTML and XML documents, two additional settings are available:
• Default DOCTYPE
• Default Namespace
Komodo tries to determine these values from the document's XML declaration. If the document
does not have one, the DOCTYPE and namespace can be manually set here, enabling appropriate
XML autocompletion. XHTML 1.1 is the default if no delaration or settings are present.
Source Code Control
91
Komodo User Guide
File Source Control Settings
If Komodo is configured to work in conjunction with a Source Code Control system, the Source
Code Control category displays the current SCC status and settings.
File Editor Settings
The options on this tab are a subset of the General Editor and Smart Editing preferences. Refer to
those sections of the Preferences documentation for information about individual options.
Indentation Tab
The options on this tab are a subset of the Indentation Preferences. Refer to that section of the
Preferences documentation for information about individual options.
Browser Preview
This option configures the behavior of the Preview in Browser function. When the Preview in
Browser function is invoked, you are prompted to specify the file or URL used to preview the
current file. (For example, when previewing a CSS file, specify an HTML file to use for the preview.)
The Preview in Browser dialog box has an option for remembering the specification. If that option is
enabled, the file or URL specified is displayed in the Preview field. Click Change to alter the
preview file.
Printing Files
To print the file that is currently displayed in the editor, use one of the following methods. These
methods invoke the standard system dialog box for printer selection and configuration. Advanced
print functions are described below.
• File|Print|Print: Invoke the print function from the File menu.
• Standard Toolbar: On the Standard Toolbar, click the Print button.
• Editor Context Menu: Right-click the file and select Print.
Printing style is configured on the Printing page in Komodo's Preferences. Alternatively, select
File|Print|Print Settings to display the Printing preferences page.
To display a preview of the printed output, select File|Print|Print Preview.
Select File|Print|Print Preview contains features for setting the scale and orientation of a print job.
Use the arrow buttons to move forward or backward in a multi-page print job, or enter a specific
page number in the field provided. Click the Page Setup button to access the complete set of print
features in the Page Setup dialog box.
To print a selection of text rather than the entire file, select the desired text in the editor, then select
File|Print|Print Selected Text.
File Source Control Settings
92
Komodo User Guide
Page Setup
Manage the format of print jobs using the options available in the Page Setup dialog box. Select
File|Page Setup to access these options.
Format and Options
• Orientation: Select whether the printed output should have a portrait or landscape
orientation.
• Scale: If the Shrink To Fit Page Width check box is not selected, use this field to manually
enter a percentage.
• Shrink To Fit Page Width: Select this check box to make the print job fit the paper size
selected for the default printer.
• Print Background (colors & images): Select this check box to include background colors
and graphics (e.g., on a web page) in a print job.
Margins and Header/Footer
• Margins: Use the fields provided to enter the size of the margins in inches.
• Headers and Footers: Use the drop-down lists to select the type of information that
appears in the headers and/or footers, and to determine their position on the page. The top
row of lists contains the header options, and the bottom row contains the footer options.
Choose from options such as "Title", "URL" and "Page #". Select the "Custom" option from
any of the drop-down lists to enter custom header information. To print without headers and
footers, select the "blank" option in each of the drop-down lists.
Print to HTML File
To generate an HTML file from the file currently active in the editor:
1. On the File menu, click Print to HTML File. You are prompted to name the output file.
2. Enter the file location in the field provided. Click OK. The HTML file opens in the editor.
To print a selection of text to an HTML file (rather than the entire file), select the desired text in the
editor, then select File|Print|Print to HTML File.
Saving Files
Komodo is "intelligent" about saving files. For example, Komodo prompts to save unsaved files on
close. Attempting to save changes to a file that is set to read-only displays a dialog box where you
are given the option to change the status or to "force" the save (which makes the file writable,
saves the changes, then sets the file back to read-only). In addition, Komodo can be configured to
automatically save a backup copy of files open in the editor. To configure Komodo's save
functionality, use the Save Options preference page.
To save a file with its current name, do one of the following:
• Key Binding: Use the associated key binding.
• File|Save: Use the File|Save menu option to save the file that is currently displayed in the
Page Setup
93
Komodo User Guide
editor. To save the file to a different name, select File|Save As. To save all open files,
select File|Save All
• Standard Toolbar: Click the Save button on the Standard toolbar. To save all open files,
click the Save All button.
• File Tab Context Menu: Right-click the file tab and select Save. To save the file to a
different name, select File|Save As.
Saving Files Remotely
To save a copy of the current file to a remote server, select File|Save Remotely As. The Remote
File dialog box is displayed. When editing files located on a remote server (including remote files
stored in a project or the Toolbox), saving the file automatically saves it to the remote location.
Show Unsaved Changes
Before saving a file, view the changes in the file since it was last saved by using the Show
Unsaved Changes option. To invoke this option, right-click within the editor (or on the file tab
above the editor) and select Show Unsaved Changes. An external window displays the
differences between the current version of the file and the disk version (e.g., the version that was
last saved).
The unique characteristics of each file are displayed in different colors (red and blue by default);
common characteristics are displayed in a third color (black by default). To configure custom colors
for the "diff" window, alter the Language-Specific Coloring setting for the Other|Diff language in
the Fonts and Colors preference.
Reverting Files
To abandon changes made to a file since it was last saved, but leave the file open in the editor,
select File|Revert.
Closing Files
To close one or more files, use one of the following methods:
• File Menu: Select File|Close or Window|Close. To close all open files, select
Windows|Close All.
• Key Binding: Use the associated key binding.
• File Tab Context Menu: Right-click the file tab and select Close.
• Editor: Click the "x" in the top right corner of the editor to close the current file.
Saving Files
94
Searching
Feature Showcases
Komodo provides a variety of methods for searching and replacing text,
both within files open in the editor and within files on the filesystem. While
Komodo has standard search and replace functionality, it also features
unique search mechanisms like searching for the work under the cursor,
incremental searching and function search.
• fast string
finder
• incremental
search
• Open/Find
Toolbar
Searching for Strings
Searching Within Open Files: Find Dialog
The Find dialog box is used to search for words or phrases in the current document. To open the
Find dialog box, from the Edit menu, select Find, or use the associated key binding.
Enter the text you wish to find in the Find what field.
The following search options can be configured:
• Match Case: To find matches of the search string regardless of case, select No. To find
matches only when the search string matches the case of the occurrence, select Yes. To
find exact case matches only when the search string contains mixed case, select Yes, if
search string contains capital letters. For example, if you enter "mystring" in the Find
what field and select Yes, if search string contains capital letters, both "mystring" and
"myString" will match. However, if you enter "myString" in the Find what field, only
"myString" will match.
• Use: Choose Plain Text to exactly match the search string. Regular Expressions will
interpret the search string as a Python regular expression, and perform the search
accordingly; Wildcards will interpret asterisk and question mark characters as glob-style
wildcards. The option specified (Plain Text, Regular Expressions (Python), Wildcards)
becomes the default search type used for the Open/Find Toolbar.
• Match whole word: If this box is checked, matches in the document will only be found if
whitespace occurs on either side of the search string. For example, if the search string is
"edit" and "Match whole word" is selected, only occurrences of the word "edit" will be found
as matches. However, if "Match whole word" is not selected, "editing", "editor", "editorial"
and "edited" will also be found as matches.
• Search up: This performs the search from the cursor position to the top of the file, rather
than from the cursor position to the bottom of the file. (The default functionality is to search
down from the cursor position.)
• Display results in Find Results 2: Komodo supports two Find Results tabs in the Bottom
Pane. Check this box to display the search results in the second, rather than the first, Find
Results tab. If this box is not checked, the first Find Results tab is used to display the
results of the search.
The Open/Find toolbar uses the settings from the Find in Files and Find dialog boxes as default
search parameters. For example, if you configure the Find dialog box to search using wildcards,
Searching
95
Komodo User Guide
the Open/Find toolbar will also perform wildcard searches.
Specify where Komodo should search for the text. In the "Search in" section, select one of the
following:
• Current document: This searches the document that is currently in focus in the editor for
occurrences of the search string.
• Selection only: will only search the highlighted area of the document that is in focus in the
editor. (If you search a selected section, the highlighting of the selected section will be
temporarily turned off in order to display highlighted results of the Find function.)
• All open documents: Search for the string in all documents currently open in the editor.
Invoke the search by clicking the desired search command button:
• Find Next: Finds consecutive occurrences of the search string in your file or selection. As
matches are found, the text will be highlighted. The Find dialog box remains in focus. To
keep the focus in your file, close the Find dialog box, then use the associated key binding.
• Find All: Locates all occurrences of the search string in your file or selection. The matches
will be displayed in the Find Results tab in the Bottom Pane.
• Mark All: Inserts a bookmark on each line that contains the search string. To move the
editing cursor to a bookmarked line, press F2.
To display the results of a previous search, click the relevant Find Results tab in the Bottom Pane.
If the Bottom Pane is not displayed, select View|Tabs|Find Results.
Replacing Within Open Files: Replace Dialog
The Replace dialog box is used to search for and replace words or phrases in the current
document. To open the Replace dialog box, from the Edit menu, select Replace, or use the
associated key binding.
Enter what to find and replace with:
• Find what: Enter the search string you want to find.
• Replace with: Enter the replacement characters.
The following replace options can be configured:
• Match Case: To find matches of the search string regardless of case, select Never. To find
matches only when the search string matches the case of the occurrence, select Always.
To find exact case matches only when the search string contains upper-case letters, select
"If Search String Contains Capital Letters". For example, if you enter "function" in the Find
what field and select "If Search String Contains Capital Letters", both "function" and
"Function" will match. However, if you enter "Function" in the Find what field, only
"Function" will match.
• Use:
♦ Plain Text: Match the exact search string.
♦ Regular Expressions Interprets the search string as a Python regular expression.
Expressions and strings can be enclosed in parentheses to retain the matched
substring for use in the Replace with field. Use the "\num" syntax to insert the
Searching Within Open Files: Find Dialog
96
Komodo User Guide
results of the match into the replacement (i.e. "\1" for the first "(...)" group, "\2" for the
second group, etc.).
♦ Wildcards Interprets the asterisk and question mark characters as wildcards for
simple "glob" matching.
• Match whole word: If this box is checked, matches in the document will only be found if
whitespace occurs on either side of the search string. For example, if the search string is
"edit" and "Match whole word" is selected, only occurrences of the word "edit" will be found
as matches. However, if "Match whole word" is not selected, "editing", "editor", "editorial"
and "edited" will also be found as matches.
• Search up: Performs the search from the cursor position to the top of the file, rather than
from the cursor position to the bottom of the file.
• Show "Replace All" Results: Displays the number of replacements in the status bar at the
bottom left of the Komodo Workspace. Details of each change, complete with the line
number, will appear on the Find Results tab in the Bottom Pane.
• Display in Find Results 2: Komodo supports two Find Results tabs in the Bottom Pane.
Check this box to display the search results in the second, rather than the first, Find
Results tab. If this box is not checked, the first Find Results tab is used to display the
results of the search.
Specify where Komodo should replace the specified text. In the "Replace in" section, select one of
the following:
• Current document: Searches the document that is currently in focus in the editor for
occurrences of the search string.
• Selection only: Only searches the highlighted area of the document that is in focus in the
editor. (If you search a selected section, the highlighting of the selected section will be
temporarily turned off in order to display highlighted results of the Find function.)
• All open documents: Searches for the string in all documents currently open in the editor.
Invoke the search by clicking the desired search command button:
• Find Next: Finds consecutive occurrences of the search string in your file or selection. As
matches are found, the text is highlighted. Click Replace to replace the highlighted text with
the replacement string.
• Replace: Highlights the next occurrence of the search string; if you click Replace again, the
highlighted text will be replaced with the replacement string and the next occurrence of the
search string will be highlighted.
• Replace All: Replaces all occurrences of the search string in the document or selection
without prompting for confirmation. All replacements will be displayed on the Find Results
tab of the Bottom Pane.
Searching for the Word Under the Cursor
When the editing cursor is within (or adjacent to) a word, you can quickly search for other
occurrences of the same word within the current document. If you are using the default key binding
scheme, press 'Ctrl'+'F3' to select the word; continue pressing 'Ctrl'+'F3' to step through each
occurrence in the document. ('Meta'+'F3' for Mac OS X users.)
Replacing Within Open Files: Replace Dialog
97
Komodo User Guide
Incremental Search
Incremental search is used to look through the current file in the Editor Pane for a group of
incrementing characters. That is, as you continue to type in search characters, Komodo will find the
next occurrence of the search string. After all the search characters have been entered, you can
move through each occurrence of the search string within the current file.
To start an incremental search select Edit|Incremental Search, or use the associated key
binding. (If you are using the default key binding scheme, the key binding is 'Ctrl'+'I' on Windows
and Linux and 'Meta'+'I' on Mac OS X.) The status bar (in the bottom left corner of the Komodo
workspace) will display the text "Incremental Search:". Begin typing the characters you want to find;
as you type characters, the editing cursor will move to the first match beneath the current cursor
position within the current file, and the search string will be displayed in the status bar.
To change the search string based on the characters surrounding the editing cursor, use the
associated key binding. If the default key binding scheme is in effect, the key combination is
'Shift'+'Right Arrow' (to add one or more characters to the right of the editing cursor) or 'Shift'+'Left
Arrow' (to remove one or more characters to the left of the editing cursor). On Mac OS X the key
bindings are 'Meta'+'Right Arrow' and 'Meta'+'Left Arrow'.
For example, if you entered "fo" as the search string, and the next occurrence of these characters
was in the word "foo", you could use the 'Shift'+'Right Arrow' key combination to extend the search
string to "foo". Conversely, you could use the 'Shift'+'Left Arrow' key combination to reduce the
search string to "f".
To search through the file for the search string press 'Ctrl'+'I' to find subsequent occurrences of
the search string within the current file (On Mac OS X, press 'Meta'+'I'). Continue pressing 'Ctrl'+'I'
to cycle through all occurrences. When the search reaches the bottom of the file, it will continue
from the top of the file. 'Ctrl'+'Shift'+'I' will search backwards from the current cursor positon (On
Mac OS X, press 'Meta'+'Shift'+'I').
To cancel the incremental search press any key except the key bindings assigned to the
incremental search functions.
Searching All Files: Find in Files Dialog
The Find in Files dialog box complements the Find dialog box by providing the ability to search for
text in files that are not currently opened in Komodo. Select Edit|Find in Files (or use the
associated key binding) to open the new dialog box.
The Find in Files dialog box consists of the following options:
• Find what: Enter the search string.
• Match Case: To find matches of the search string regardless of case, select No. To find
matches only when the search string matches the case of the occurrence, select Yes. To
find exact case matches only when the search string contains mixed case, select Yes, if
search string contains capital letters. For example, if you enter "mystring" in the Find
what field and select Yes, if search string contains capital letters, both "mystring" and
"myString" will match. However, if you enter "myString" in the Find what field, only
"myString" will match.
Incremental Search
98
Komodo User Guide
• Match whole word: If this box is checked, matches in the document will only be found if
whitespace occurs on either side of the search string. For example, if the search string is
"edit" and "Match whole word" is selected, only occurrences of the word "edit" will be found
as matches. However, if "Match whole word" is not selected, "editing", "editor", "editorial"
and "edited" will also be found as matches.
• Use: Choose Plain Text to exactly match the search string. Regular Expressions will
interpret the search string as a Python regular expression and perform the search
accordingly; Wildcards interpret asterisk and question mark characters as wildcards.
• Search in: By default, the Search in field is populated with a period, which indicates that
the "current" directory will be searched. (If no file is open, the current directory is the value
specified in the HOME environment variable; if the HOME variable is not defined, the current
directory is "C:\" on Windows and "/" on OS X and Linux. If one or more files are open, the
location of the file that is displayed in the Editor Pane is the current directory.) To search
directories other than the current, either specify an absolute path, or specify a relative path
from the current directory. For example, if the current directory is /home/fred/tmp/foo, you
could search the /home/fred/tmp/bar directory by entering ../bar. Manually enter one or
more directories; multiple directories are separated by semicolons. Alternatively, click the
browse button to the right of the field to display a directory browser dialog box. (Directories
already specified in the Search in field will be displayed in this dialog box.) Use the
directory browser to navigate the filesystem, specify one or more search directories, and/or
alter the order in which the directories are searched.
• Search in subfolders: If this box is checked, subdirectories beneath the directories
specified in the Search in field are also searched.
• Include: To specify one or more file types that should be searched, enter the file extensions
preceded by a wildcard. For example, to search files with ".pl" and ".tcl" extensions, enter
*.pl;*.tcl. (Note that multiple file extensions are separated by any combination of
semicolons, spaces, colons, and commas.)
• Exclude: To specify one or more file types that should be excluded from the search, enter
the file extensions preceded by a wildcard. For example, to exclude files with ".exe" and
".doc" extensions, enter *.exe;*.doc. (Note that multiple file extensions are separated by
any combination of semicolons, spaces, colons, and commas.) If both the Include and
Exclude fields are blank, all file types are searched.
• Display results in Find Results 2: Komodo supports two Find Results tabs in the Bottom
Pane. Select this check box to display the search results in the second, rather than the first,
Find Results tab. If this box is not checked, the first Find Results tab is used to display the
results of the search.
After clicking Find All, the Find Results 1 or Find Results 2 tab (depending on the setting of the
Display results in Find Results 2 check box) are displayed in Bottom Pane. Depending on the
number of files that are being searched, it may take some time to generate results. (The search
status is displayed on the top line of the Find Results tab. The results include the file in which the
search string is found, the line number in the file where the search string occurs, and the context
surrounding the search string. Double-click a search result (or click the arrow button at the top right
of the pane) to open the file in the editor and place the editing cursor on the selected occurrence.
Fast Search: Open/Find Toolbar
The Open/Find toolbar provides quick access for opening files and finding strings. Find strings in
files currently displayed in the editor or in files not currently open in Komodo but located on the
filesystem. The toolbar is displayed by default; to close or open the toolbar, select
Searching All Files: Find in Files Dialog
99
Komodo User Guide
View|Toolbars|Open/Find.
The Open/Find toolbar also provides fast access to find functionality. The Find and in fields are
used to perform searches on files in Komodo or elsewhere in the filesystem. Both fields have a list
of the most recently entered strings and file specifications. Use the in field browse button, located
to the right of the in field, to populate this field with the directory, folders, or files you want to
search.
Enter the string that you wish to search in the Find field. The Find toolbar uses the settings from
the Find in Files and Find dialog boxes as default search parameters. For example, if you configure
the Find dialog box to search using wildcards, the Find toolbar will also perform wildcard searches.
Specify the files that should be searched in the in field. The in field uses the same logic as the
Open field to determine the current directory. (If no file is open, the current directory is the value
specified in the HOME environment variable; if the HOME variable is not defined, the current directory
is "C:\" on Windows and "/" on OS X and Linux. If one or more files are open, the location of the file
that is displayed in the Editor Pane is the current directory.)
To search directories other than the current, either specify an absolute path, or specify a relative
path from the current directory. For example, if the current directory is /home/fred/tmp/foo, you
could search the /home/fred/tmp/bar directory by entering ../bar. Alternatively, use the in field
browse button to locate and populate this field with the directory, folders, or files you want to
search.
The in field accepts wildcards; use "*" for a file name segment and "?" for a specific character.
Separate multiple directories with semicolons. If nothing is specified in the in field, the search will
be performed against the file that is currently displayed in the Editor Pane (if applicable), and the
next occurrence of the search string is highlighted.
For example, to search for occurrences of the string "error" in all files located in the directory
/tmp/output, enter error in the Find field and /tmp/output/* in the in field.
If files are specified in the in field, matches will be displayed in the Find Results tab.
At any time, press the Escape key to return focus to the Komodo editor. The Find field can be
accessed via the associated key binding.
For example, to search for occurrences of the string "debug" in all files located in the directory
/tmp/log on a machine running Linux, enter debug in the Find field. Enter /tmp/log/* in the in field,
or use the "browse" button to locate this directory on your filesystem. For more information on
searching using the Open/Find Toolbar, see Finding Strings.
Find Results Tabs
The Find Results 1 tab (located in the Bottom Pane) displays all matches that result when the
Find All function in the Find dialog box is used. The Find Results 1 tab displays the line number on
which the match occurred and the line that contains the match. Double-click a line in the Find
Results tab to display the line in the Editor Pane.
Fast Search: Open/Find Toolbar
100
Komodo User Guide
The Find All function in the Find and Replace dialog box, and the Find in Files dialog box
(Edit|Find in Files) both make use of the Find Results tab, which displays the result of the search
on the Command Output tab. Komodo includes a second output tab that can be specified by
checking the Display results in Find Results 2 check box. By using both tabs, search results are
not overwritten every time a new search is invoked.
Finding Functions: Function Search
The Function Search looks through the current document for the following constructs:
• Perl programs: sub and package statements.
• Python programs: class and def statements.
• PHP programs: class and function statements.
• Ruby programs: module, class and def statements.
• Tcl programs: proc statements.
Moving Between Functions
To search forward from the current cursor position, select Code|Find Next Function, or use the
associated key binding. To search backwards from the current cursor position, select Code|Find
Previous Function, or use the associated key binding.
Displaying a List of Functions
To find all instances of functions within the current document, select Code|Find All Functions, or
use the associated key binding. The list of functions in the current document will be displayed on
the Find Results tab located in the Bottom Pane of the Komodo Workspace. Double-click a
specific construct on the Find Results tab to highlight the relevant line in the Editor Pane.
Find Results Tabs
101
Editing
Komodo's editor has extensive code intelligence features for JavaScript,
HTML, XML, XSLT, Perl, PHP, Python, Ruby, and Tcl. and provides
syntax highlighting and common editor features for most other
programming languages. Many of these features can be customized in
Komodo's editor preferences.
Right-clicking in the editor pane brings up a context menu with common
editing functions. In addition to standard Cut, Copy, Paste, Select All, and
Print commands, the following options are available:
Feature Showcases
• previewing css
in a browser
• storing a code
fragment for
reuse
• Add as Snippet in Toolbox: Stores the selected code in the
Toolbox.
• Disable/Enable Breakpoint: Toggles a breakpoint between
enabled, disabled, or deleted states. (Komodo IDE only).
• Add/Edit Breakpoint: Adds or edits a conditional breakpoint.
(Komodo IDE only).
• Add/Edit Spawnpoint: Adds or edits a Tcl spawnpoint on the line
where the cursor is positioned (Komodo IDE only).
• Go to Definition: Jumps to the corresponding definition of the
code object currently under the cursor. See Go to Definition.
• Jump to Corresponding Line: When viewing changes in a diff
file, jump from the current line in the diff to the corresponding line
in the the source code.
• Toggle Bookmark: Insert or remove a bookmark.
• Show Unsaved Changes: Opens a window showing changes
made to the file since the last time it was saved (in unified diff
format). Press F8 to jump to the next change, F7 to jump to the
previous change, F9 jump to a highlighted change in the original
file, and Esc to close the window.
• Refresh Status: Refresh the current file's status. See
Customizing File Settings for more information.
• Source Control: Opens a sub-menu with source sode control
commands. Available only for files under version control (Komodo
IDE only).
• Properties and Settings: Select to adjust the properties and
settings of the current file.
Language Support
Syntax Coloring and Indentation
The Komodo editor is language-sensitive. When you open a file in a supported language, Komodo
will color the syntax, format indentation, and provide indentation guides.
Editing
102
Komodo User Guide
More Information:
• Customizing Fonts and Colors
• File Associations
• Viewing the Current File as Another Language
• Customizing Indentation
Background Syntax Checking
As you write code in the editor, Komodo periodically checks for syntax errors. Syntax errors are
underlined with a red wavy line; syntax warnings are underlined with a green wavy line. Komodo
uses the language interpreter's own error-checking functions, so there may be slight differences in
the way that syntax errors are detected and displayed depending on the version of the interpreter.
The syntax checking icon in the status bar displays the syntax status of the current file displayed in
the Editor Pane:
• A green check mark over the icon indicates that the language interpreter does not detect
any warnings or errors in the program.
• A red exclamation mark over the icon indicates one or more errors. To see the number of
errors and warnings contained in the program, hover your mouse pointer over the syntax
checking icon. A pop-up tool tip will display the total number of errors and warnings.
• An hourglass over the icon indicates that syntax analysis is in progress.
You can view the error message from the interpreter in the status bar if the editing cursor is on the
same line as the error. If it is not, hover the mouse pointer over the error and the interpreter error
will be displayed in a pop-up tool tip.
To move the editing cursor to the line containing the error or warning, double-click the syntax
checking icon. If there are multiple errors or warnings, each time you double-click the icon, the
editing cursor will move to the next error.
If background syntax checking is disabled in Preferences, shift-click on the syntax checking icon to
check the syntax of the file.
Right-clicking on the syntax checking icon brings up the context menu.
• Check syntax now (same as shift-click)
• Jump to next result (same as double-click)
• Clear warning/error squigglies
Komodo supports background syntax checking for the following languages:
Syntax Coloring and Indentation
103
Komodo User Guide
• HTML
• JavaScript
• Perl *
• PHP **
• Python
• Tcl
• XML
• XSLT
* requires ActivePerl build
623 or higher
** requires PHP version 4.05
or greater
More Information:
• Preferences | Editor | Smart Editing
AutoComplete and CallTips
Autocomplete and calltips are two related features to help you write code more efficiently.
Autocomplete presents a pop-up list of relevant choices at certain trigger points as you are editing
a document. Autocomplete functionality varies according to language; for example, Python
autocomplete lists object methods when you type the '.' (period) trigger character, Perl
autocomplete lists available sub-packages when you type the '::' trigger string in a "use" statement,
and XSLT autocomplete lists appropriate element and attribute names when starting XML tags.
Use the arrow keys to scroll through the list; use the 'Tab' or 'Enter' key to insert the currently
selected item into your document; use the 'Esc' key to cancel the pop-up list.
A calltip presents you with a call signature for, and possibly a short description of, a function or
method call.
Generally, a calltip is opened when you enter the open parenthesis, "(", of a function call. However,
this varies according to language. Use the 'Esc' key to close the calltip.
Komodo includes autocomplete and calltip support for several languages. Language-specific
functionality for each supported language is described below.
More Information:
• Enabling and Disabling AutoComplete and CallTips
Background Syntax Checking
104
Komodo User Guide
Perl AutoComplete and CallTips
Komodo supports the following types of Perl autocomplete and calltips:
• Autocomplete for sub-modules in use statements: Available sub-modules are listed
upon entering "::" in use and require statements. For example:
use LWP::|
• Autocomplete for sub-modules, subroutines, and variables: Sub-modules, subroutines,
and variables are listed upon entering "::" in a fully qualified Perl name. For example:
use LWP;
$HTTP::Request::|
• Autocomplete for module subroutines: Subroutines are listed upon entering "->" after a
module name. For example:
use LWP;
LWP::UserAgent->|
• Autocomplete for object methods: Object methods are listed upon entering "->" after an
object reference. For example:
use Data::Dumper;
my $d = Data::Dumper->new($foo);
$d->|
• Calltips for subroutine calls: A calltip is shown for subroutine and object method calls
upon entering "(" after a sub-routine name, if information is available for that subroutine.
Note: Perl supports subroutine calls without the parentheses. Komodo only triggers a calltip
without the parentheses for certain built-in Perl functions such as, "chdir", "split", "join", etc.
A Perl autocomplete list or calltip can also be explicitly initiated by typing 'Ctrl'+'J' ('Meta'+'J' on Mac
OS X).
Perl autocomplete and calltips are driven by Komodo's Code Intelligence system. See Building the
Code Intelligence Database for information on pre-building the database that Komodo uses for Perl
autocomplete and calltips. Pre-building the Code Intelligence Database is not necessary, but can
improve performance of this feature.
Python AutoComplete and CallTips
Komodo supports the following types of Python autocomplete and calltips:
• Autocomplete for object methods and attributes: Object methods and attributes are
listed upon entering "." after an object reference. For example:
import sys
sys.|
• Calltips for function calls: A calltip will be shown for function and object method calls upon
entering "(" after the function name -- if information is available for that function.
AutoComplete and CallTips
105
Komodo User Guide
A Python autocomplete list or calltip can also be explicitly initiated by typing 'Ctrl'+'J' ('Meta'+'J' on
Mac OS X).
Python autocomplete and calltips are driven by Komodo's Code Intelligence system. See Building
the Code Intelligence Database for information on pre-building the database that Komodo's uses
for Python autocomplete and calltips. Pre-building the Code Intelligence Database is not
necessary, but can improve performance of this feature.
Ruby AutoComplete and CallTips
Komodo supports the following types of Ruby autocomplete and calltips:
• Autocomplete for require statements: Available Ruby libraries are listed upon entering
the opening quote and for slashes in the quotes. For example:
require '| require 'net/|
• Autocomplete for available attributes on a class or module namespace: Available
methods, constants and sub-modules are listed upon entering "::" in a fully qualified Ruby
name. For example:
class Animal
def initialize(species)
@@species = species
end
def grunt
"ugh"
end
def run
end
end
Animal::|
• Autocomplete for methods on an class instance: Available methods on an instance are
listed upon entering ".". For example:
a = Animal.new("dog")
a.|
• Calltips for method calls: The method signature (and possibly some method
documentation) is shown in a calltip upon entering the "(" for a method call.
a = Animal.new(|"dog")
A Ruby autocomplete list or calltip can also be explicitly initiated by typing 'Ctrl'+'J' ('Meta'+'J' on
Mac OS X).
Ruby autocomplete and calltips are driven by Komodo's Code Intelligence system. See Building the
Code Intelligence Database for information on pre-building the database that Komodo uses for
Ruby autocomplete and calltips. Pre-building the Code Intelligence Database is not necessary, but
can improve performance of this feature.
AutoComplete and CallTips
106
Komodo User Guide
PHP AutoComplete and CallTips
Komodo supports the following types of PHP autocomplete and calltips:
• Classes and Methods: Classes in the current file, and classes in any included files, are
displayed upon entry of the keyword "new". Methods in the class are displayed when you
enter "->".
• Functions: Standard PHP functions and functions defined within the script (and within any
included files) are displayed after you have typed four characters that match one or more
function names.
• Variables: Variables declared in the current file, or in any included files, are displayed when
you enter the symbol "$" followed by a letter. For variables declared within the current file,
only those variables declared above the current line are included in the pop-up list.
Tcl AutoComplete and CallTips
Komodo supports the following types of Tcl autocomplete and calltips:
• Autocomplete for command names: A list of matching Tcl commands is displayed after
you have typed three characters in a command. For example,
str|
• Calltips for command arguments: A calltip is displayed for a Tcl command upon entering '
' (space) after the command name. For example,
string is alpha |
Customizing Tcl AutoComplete
Tcl autocomplete and calltips use the built-in function definitions contained in Tcl .tip files, which
are in the tcl subdirectory of the Komodo installation directory for your platform.
Windows
<komodo-install-directory>\lib\support\tcl
Linux
<komodo-install-directory>/lib/support/tcl
Mac OS X
<komodo-install-directory>/Contents/SharedSupport/tcl
Edit the .tip files to customize or extend Tcl autocomplete and calltips in Komodo. Review the
existing .tip files for examples before editing.
XSLT AutoComplete
Komodo supports the following types of XSLT autocomplete:
AutoComplete and CallTips
107
Komodo User Guide
• Autocomplete for XSLT elements: A list of appropriate elements in the XSL-namespace
for the current context is supplied upon entering "<" to start a tag.
• Autocomplete for XSLT attributes: A list of appropriate attributes in the XSL-namespace
for the current element is supplied upon entering ' ' (space) in a tag.
• Autocomplete for end-tags: A one item list containing the appropriate closing tag for the
current position is supplied upon entering '</'.
• Autocomplete for output: A list of elements and attributes for HTML or XML output (as
defined in the method attribute of the xsl:output element) is supplied upon entering "<"
within xsl:template blocks. If the output method is a specific dialect of XML, specifying
the publicId or systemId of that dialect in the doctype-public or doctype-system
(respectively) enables autocompletion appropriate to that dialect.
XML AutoComplete and CallTips
Komodo supports XML autocomplete and calltips for basic XML as well as a a number of XML
dialects, including:
• HTML
• VXML
• XML Schema
• XHTML
• SVG
• Atom
• SGML
• MathML
• Dublin Core
• RELAX
• XBL
• DocBook
• RELAX NG
• XUL
• WAP
• RDF
• XML Catalog
• XSLT
• MXML
Support for additional XML dialects can be configured by adding an XML Catalog for the dialect in
the SGML/XML Catalogs section of the Code Intelligence Preferences.
Komodo supports the following types of XML autocomplete:
• Autocomplete for elements: A list of elements available in the current namespace is
supplied upon entering "<". If the current document's XML dialect is not recognized (i.e. it is
not in the above list or in a configured catalog), the completion list is drawn from elements
used in the document.
• Autocomplete for attributes: A list of attributes available within in the current element is
supplied upon entering a space after the element name.
• Autocomplete for end-tags: A list (of length one) to close the current tag is supplied upon
entering '</'.
If the document does not have an XML declaration, autocomplete will default to XHTML 1.1. The
DOCTYPE and namespace can be manually set under File Properties.
Viewing the Current File as Another Language
Komodo's syntax coloring, background syntax checking, and indentation are language-specific.
However, Komodo provides the option to view a file as another language. This is useful when you
open, for example, a Perl file that has no extension. You can select the Perl language option, then
edit the file as a regular Perl file. Komodo's File Associations do not allow you to set a language
association with a file that doesn't have an extension.
AutoComplete and CallTips
108
Komodo User Guide
To view the current file as another language:
1. On the View menu, select View as Language.
2. From the list, select the desired language.
If you have opened a file that does not have a file association specified in the Preferences dialog
box, Komodo displays the file as text. You can select to view the file as another language, but
Komodo does not remember again. If you will be working with a new type of file, it is recommended
that you specify a file association.
For example, if you open a DocBook (*.docb) file in Komodo, it does not have XML syntax coloring.
Specify a file association to tell Komodo to open *.docb files as XML files. For more information on
specifying file associations, see Customizing File Associations.
If you choose to view a file in a different language and then save the file, the original language will
not be restored when you re-open the file. If you are unsure of the original language, you can select
View|View As Language|Reset to best guess. Komodo will ignore the user preference, and
analyze the file in an attempt to determine its language.
Commenting Blocks of Code
The commenting function is used to convert a single line or a group of lines into a comment, with
the syntax appropriate for the file's language. Komodo supports commenting for the following
languages:
More Information:
• Commenting and Un-commenting Lines or Blocks of Code
Manipulating Code
Automatically Repeating Keystrokes
Komodo can repeat a single keystroke for a given number of characters. To have Komodo repeat a
key sequence a specified number of times:
1. Select Code|Repeat Next Keystroke N Times. The status bar at the bottom of the
Komodo workspace prompts you for the number of times the keystroke will be repeated.
2. Type a number using only numeric characters.
3. Enter the keystroke. The results of the sequence are displayed in the Editor Pane the
specified number of times.
Indenting and Un-indenting Lines of Code
To indent a single line or a selected block of code:
• Single Line: Position the cursor at the start of the text on the desired line. Press Tab, or
select Code|Increase Line Indent.
Viewing the Current File as Another Language
109
Komodo User Guide
• Multiple Lines: Select the desired lines by clicking and dragging in the Editor Pane. Press
Tab, or select Code|Increase Line Indent.
To un-indent a single line or a selected block of code:
• Single Line: Position the cursor at the start of the text on the desired line. Select
Code|Decrease Line Indent or use the associated key binding.
• Multiple Lines: Select the desired lines by clicking and dragging in the Editor Pane. Select
Code|Decrease Line Indent, or use the associated key binding.
Specify the number of spaces per tab in the Indentation Editor Preferences
(Edit|Preferences|Editor|Indentation).
Reflowing Paragraphs
To reformat a section of code so that it is left-aligned and displays within the Edge line column,
select the section of code to be reflowed, and then select Code|Reflow Paragraph. Alternatively,
use the associated key binding.
Joining Lines
To cause two lines of code to display on the same line, position the cursor in the first of the two
lines, and select Code|Join Lines. The second line is joined with the first line.
Converting between Uppercase and Lowercase
To convert a selection of text from uppercase to lowercase (or vice-versa), from the Code menu,
select Make Uppercase or Make Lowercase
, or use the associated key binding.
Transposing Characters
To reverse the position of the two characters to the left of the editing cursor, use the associated key
binding.
Literal Characters
To insert literal characters into the editor, select Code|Enter Next Character as Raw Literal, and
then enter the key or key combination representing the literal character. (Alternatively, use the
associated key binding.) For example, to insert a form feed, enter 'Ctrl'+'L'. The following characters
are common:
• Ctrl+L: Form Feed (shown as "FF")
• Esc: Escape character (shown as "ESC")
• Return or Ctrl+M: Carriage Return (shown as "CR")
• Ctrl+J: Line Feed (shown as "LF")
• Tab or Ctrl+I: Tab (shown as "---->")
Indenting and Un-indenting Lines of Code
110
Komodo User Guide
Commenting and Un-commenting Lines or Blocks of Code
To comment a single line of code, place the cursor on the desired line, then, from the Code menu,
select Comment Region. Alternatively, use the associated key binding.
To un-comment a line of code, place the cursor is on the desired line, then, from the Code menu,
select Uncomment Region. Alternatively, use the associated key binding.
To comment a block of code, select the lines you wish to comment by clicking and dragging the
mouse in the Editor Pane. Then, from the Code menu, select Comment Region. Alternatively, use
the associated key binding.
To un-comment a line of code, place your cursor is on the desired line, then, from the Code menu,
select Uncomment Region, or use the associated key binding.
Cleaning Line Endings
If a file contains line endings for more than one platform, you can replace the unwanted line
endings with the line endings specified in file's Properties and Settings dialog box.
1. On the View menu, click View EOL Markers to show line endings.
2. Select the line(s) for which you want to replace the endings.
3. On the Code menu, click Clean Line Endings. The line endings are replaced with the line
endings specified in the file's settings.
Tabifying and Untabifying Regions
"Tabifying" a region converts leading spaces to tabs. If you select a line of code that has some
leading spaces and you choose to tabify the region, you convert all the leading spaces into Tab
characters. The Tabify region dialog box sets the ratio of space characters to Tab characters. If you
select 8, then each 8 space characters will be represented as 1 Tab character.
To tabify a region:
1. From the Code menu, select Tabify Region.
2. In the dialog box, set the number of spaces, from 1 to 16, to apply to a tab.
Click OK or press Enter.
To untabify a region:
1. From the Code menu, select Untabify Region.
2. In the dialog box, set the number of spaces, from 1 to 16, to apply to a tab.
3. Click OK or press Enter.
To illustrate tabifying, follow this procedure:
1. Open the sample_project.kpf.
2. Open perl_sample.pl.
3. Turn on the Line Numbers.
4. Turn on the Whitespace characters.
Commenting and Un-commenting Lines or Blocks of Code
111
Komodo User Guide
5. Find the following line: $sum += $prices[$i]; There are four leading spaces on this
line. You can tabify this line and convert each space character into one Tab character.
6. Tabify this line. Set the number of spaces to 1. This means each space character will be
converted to one Tab character.
7. Now this line has four Tab characters, represented as right arrows, preceding print $sum
+= $prices[$i];. This causes the line to be indented too far.
8. Untabify this line. Set the number of spaces to 1. This returns the line to the original state.
Now look at another line with 8 leading spaces.
1. Open python_sample.py
2. Find the following line: print "element %s is a string" % element. There are 8
leading spaces on this line.
3. Tabify this line. Set the number of spaces to 8. This means the 8 spaces will be converted
to one Tab character.
4. Now this line has one Tab character, represented as a right arrow, preceding print
"element %s is a string" % element;. This does not change the line's
indentation.
5. Untabify this line. Set the number of spaces to 8. This returns the line to the original state.
You can set the width of Tab characters in the Preferences dialog box. The default value is 8.
Selecting Columns or Blocks
Select columns of text in Komodo by pressing the 'Alt' key and then dragging with the mouse. This
feature, often called block selection, is particularly useful when you want to easily move code and
data that is arranged in columns. Once the column of text has been selected, use the keyboard or
the Edit menu to delete it or move it to another location.
Completing Words
The Komodo editor maintains an index of words in the current file. Rather than re-entering words
that already exist in the current file, use the Complete Word feature to finish words.
Enter one or more characters, then select Code|Complete Word, or use the associated key
binding. Words are completed based on the most recent occurrence in the current file. For
example, if you type "pr", Komodo searches backward from the insertion point to find the first
instance of a word that begins with "pr". Continue pressing the spacebar while holding down the
'Ctrl' ('Meta' on Mac OS X) key to cycle through all possible completions for the word. The
Complete Word feature is case sensitive.
Selecting Blocks of Code
Quickly select blocks of code using Komodo's Select Block function (Code|Select Block, or use
the associated key binding). This function uses the Code Folding logic.
When the Select Block function is invoked, Komodo analyzes the cursor position relevant to the
blocks of code in the document. If the cursor is within a block, the entire block will be selected. (If
the cursor is within a nested block, only the current sub-block will be selected, not the block that
contains the entire nested structure.) If the cursor is not inside a block, the entire document will be
Tabifying and Untabifying Regions
112
Komodo User Guide
selected.
Editor Display Characteristics
Toggling Whitespace On and Off
Whitespace is any space in a file not taken up by text. Line breaks, spaces, and tabs are
considered whitespace.
To toggle whitespace on and off, select View|View Whitespace, or use the associated key binding.
To set a default for whitespace display, see Customizing Editor Features for more information.
Toggling Indentation Guides On and Off
Indentation guides display vertical lines in the Editor Pane that indicate the number of whitespace
indents. The width of indentation guides is determined by the value in the Indentation Width
preference. See Customizing Indentation for more information.
To toggle indentation guides on and off, select View|View Indentation Guides, or use the
associated key binding.
Toggling Line Numbers On and Off
Line numbers can help orient you when working in a long file.
To toggle line numbers on and off, select View|View Line Numbers, or use the associated key
binding.
To set this option globally, see Customizing General Editor Features for more information.
Toggling EOL (end of line) Markers On and Off
End-of-line markers indicate where and how a line ends, such as by a hard return or another key. If
you use Enter to end a line, the EOL marker could be CR or CR+LF.
To toggle EOL markers on and off, select View|View EOL markers, or use the associated key
binding.
To set this option globally, see Customizing General Editor Features for more information.
Increasing and Decreasing the Code Font Size
To increase the font size in the Editor Pane, select View|Font, and then Increase or Decrease.
Alternatively, use the associated key binding. Repeat until the font size is appropriate. The size
specification applies to all files open in the Editor Pane.
When you save a file, the new font size is saved.
Selecting Blocks of Code
113
Komodo User Guide
Toggling Fixed and Non-Fixed Width Fonts
In Komodo, you can use fixed width or non-fixed width fonts for editing. You can also toggle
between these settings. The default font is non-fixed width. Note that this setting does not persist. If
you toggle to a different setting, the next time you open the file it will restore the width specified on
the Fonts tab of the Fonts and Colors page in Komodo Preferences.
To toggle between fixed and non-fixed width font:
1. On the View menu, select Font, then Toggle Fixed/Proportional Fonts. This changes the
font to fixed width.
2. Repeat to reverse.
Folding and Unfolding Code
Code folding symbols appear in the left margin of the Editor Pane immediately left of the line of
code that is or can be folded. Minus signs indicate the beginning of a block of code that can be
collapsed or folded. Plus signs indicate the beginning of a block of code that can be expanded or
unfolded. This line of code is also underlined.
Either specific code blocks or all code blocks can be folded.
To collapse or fold a single block of code:
• Click the minus sign immediately to the left of a block of code
or
• On the View menu, select Fold, then Collapse
or
• Use the associated key binding.
To collapse or fold all foldable blocks of code:
• On the View menu, select Fold, then Collapse All
All foldable blocks of code collapse and the minus signs all become plus signs.
To expand or unfold a single block of code:
• Click the plus sign immediately to the left of a block of code
or
• On the View menu, select Fold, then Expand
or
• Use the associated key binding.
To expand or unfold all foldable blocks of code:
• On the View menu, select Fold, then Expand All
All foldable blocks of code expand and the plus signs all become minus signs.
Toggling Fixed and Non-Fixed Width Fonts
114
Komodo User Guide
Navigating Within Files
Moving to a Specific Line
While editing, you can move to a specific line number as follows:
1. On the View menu, select Goto Line.
2. In the dialog box, enter the line number, or, to move backward or forward from the current
line enter "+" or "-" in front of the number. For example, enter "+5" to move five lines ahead.
3. Click Goto Line or press Enter.
Go to Definition
You can jump to the definition of a code object under your cursor (e.g. a variable, a subroutine, a
module, etc.) in any of the following ways:
• Select Code|Go to Definition
• Right-click to bring up the context menu and select Go to Definition
• Typing 'Ctrl'+'K','Ctrl'+'G'
Alternatively, double-click the symbol node for the object in the Code Browser tree.
Objects defined within the file, in user-defined modules, and in the site library are accessible in this
way; objects defined in a language's standard library are not.
In Rails applications, you can also jump to symbol definitions in models from controller files.
Setting and Moving to Bookmarks and Marks
Bookmarks are points of interest in a file. Komodo displays blue triangles on the left margin beside
bookmarked lines. Marks, which are derived from the Emacs editor, are similar to bookmarks. The
key difference is that marks have no graphical representation in Komodo. Marks make it possible to
create an invisible reminder of previously visited locations in a file.
Bookmarks
• To set or unset a bookmark: Position the editing cursor on the line of interest. Select
Code|Marks|Toggle Bookmark or use the associated key binding to bookmark the line. If
the line is already bookmarked, the bookmark will be removed.
• To move to the next bookmark: Select Code|Marks|Next Bookmark or use the
associated key binding.
• To move to the previous bookmark: Select Code|Marks|Previous Bookmark or use the
associated key binding.
• To clear all bookmarks: Select Code|Marks|Remove All Bookmarks or use the
associated key binding.
Marks
Navigating Within Files
115
Komodo User Guide
• To set a mark: Position the cursor on the line of interest. Select Code|Marks|Set
Transient Mark. The status bar at the bottom of the Komodo workspace indicates that a
transient mark is set at the current line. If the default Emacs key binding scheme is in effect,
execute this command using 'Ctrl'+'Space'.
• To move from a position to a mark: Select Code|Marks|Exchange Position and Mark to
move from the cursor location (or "position") back to the associated mark. Conversely, if the
cursor is located at the mark, selecting this option will move the cursor back to the previous
position. If the default Emacs key binding scheme is in effect, execute this command using
'Ctrl'+'X', 'Ctrl'+'X'.
• To move to the previous mark: Select Code|Marks|Move to Previous Mark to move
from the current mark to the previous mark or from the current cursor location to the
previous mark. If the default Emacs key binding scheme is in effect, execute this command
using 'Ctrl'+'U', 'Ctrl'+'Space'.
Matching Braces
Use the Matching Brace functions to quickly jump between opening and closing braces and
parentheses. Notice that when the editing cursor is adjacent to a brace or parenthesis, the brace is
displayed in bold red. The associated closing or opening brace is also displayed in bold red.
To jump to the matching brace, select Code|Jump to Matching Brace, or use the associated key
binding. To select the braces and the contents they contain, select Code|Select to Matching
Brace.
Detecting Changed Files
Komodo can be configured to monitor the status of files that are opened in the editor. If the file is
changed on disk, you will be prompted to reload the latest version under the following
circumstances:
• when you change between tabs in the editor
• when you switch back to Komodo from another application
• when you save a file
Use Komodo's Preferences to enable or disable this function.
Preview in Browser
You can configure Komodo to preview a variety of file types in your default browser, or in the Editor
Pane. The Preview in Browser feature is particularly useful when working with HTML or XML files.
The browser preview will be displayed in a separate window, in the Editor Pane, or in a split view of
the Editor Pane, depending on which preference has been set.
The context menu in the Editor Pane is only available when the "source" tab is in focus. If Komodo
does not support previewing of a specific file type, the Preview in Browser option will not be
available from either the toolbar or the View menu.
To preview a file with the Preview in Browser feature:
Setting and Moving to Bookmarks and Marks
116
Komodo User Guide
1. Open the file in the Komodo Editor Pane. Or, if the file is already open, make sure it is the
selected tab in the Editor Pane.
2. Select View|Preview in Browser. A dialog box will appear, prompting you to choose which
file to preview.
3. If you want to preview the current file, select Preview with this file, or, if you want to
preview using another file that includes the current file (e.g., use an HTML file to preview a
CSS file), select Preview with another file or URL, then click Browse to navigate to the
desired file location. If you do not want to be prompted each time you preview a specific file,
select Remember this selection for this file. If you later decide that you want to specify a
different preview selection, change the Browser Preview file or URL in the current file's
Properties and Settings.
4. Click Preview. The file will be displayed in the Editor Pane or in a separate window,
depending on which preference has been set.
Editor Tab Display
Use the following commands on the Window menu to manage the way previews and tab groups
are displayed in the Editor Pane:
• Move to Other Tab Group: Splits the Editor Pane (if not already split) and moves the active
file to the other tab group.
• Split View: Splits the Editor Pane (if not already split) and displays the active file in both tab
groups.
• Rotate Tab Groups: If two tab groups are displayed, this option switches between a
horizontal and vertical split.
If displayed in the Editor Pane, previews include a toolbar with basic Web browser functionality,
including (from left to right) "Back", "Forward" "Reload", and "Stop" buttons.
Preview in Browser
117
Working with Folders
Komodo has two distinct types of folders that can be used in projects or in
the Toolbox:
• Live Folders correspond to actual directories on the filesystem.
The directory tree view displays the current contents of the
corresponding filesystem directory.
• Virtual Folders do not directly correspond to directories on the
filesystem. They are multi-purpose containers; any component
that can be added to a project or the Toolbox can be stored in
these folders.
Feature Showcase
• import a
filesystem
layout
When you Import from File System, the virtual project or Toolbox
folders are created with the same names as the imported
directories, but modifying the name of the folder within Komodo
has no effect on the directory's name in the file system. See
Adding Components to Projects or Adding Components to the
Toolbox for instructions on adding folders.
Double-click a folder to display its contents. Double-click again to collapse
a folder and hide its contents. Alternatively, click the plus and minus
icons.
Folder Options
To access options for the selected folder, do one of the following:
• Toolbox or Project|component_name|option: When a component is selected in the
Project Tab or Toolbox, use the Project or Toolbox drop-down menus to access the list of
options. The name of the component that is currently selected in a project or the Toolbox is
displayed in the drop-down menu.
• Context Menu: Right-click an existing component in a project or the Toolbox and select the
desired option.
The following options are available for folders:
Import from File System
This option imports the files and directories from a local or network filesystem into a Virtual Folder.
Depending on the configuration of the options below, file and directory references are created in
the same hierarchical structure as the filesystem. (Alternatively, all the file references in a recursive
directory structure can be located at the same level within a folder.)
Use the following options on the Import from File System dialog box to configure the import:
• Directory to import from: Specify the directory from which you want to import files. Use the
Browse button to navigate the file system.
• Files to include: Specify the filenames to include. Use wildcards ("*" and "?") to specify
groups of files. Separate multiple file specifications with semicolons. If the field is left blank,
Working with Folders
118
Komodo User Guide
all files in the specified directory are imported.
• Files and directories to exclude: Specify the file and directory names to exclude. Use
wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with
semicolons. If the field is left blank, no files in the specified directory are excluded.
• Import Subdirectories Recursively: Check this box to import directories (and files
contained in those directories) located beneath the directory specified in the Directory to
import from field. This box must be checked in order to specify the "Import Directory
Structure" option as the Type of folder structure to create.
• Type of folder structure to create:
♦ Import directory structure: If the Import Subdirectories Recursively box is
checked and this option is selected, Komodo creates folders within the project that
represent imported directories. Thus, the directory structure is preserved within the
project.
♦ Make a folder per language: If this option is selected, imported files are organized
into folders according to the language indicated by file pattern in the filename. File
associations are configured in the Komodo Preferences. Each folder is named after
the associated language, for example, "Perl files", "XML files", etc. Files that don't
correspond to a known file pattern are stored in a folder called "Other files".
♦ Make one flat list: If this option is selected, all the imported files are placed directly
under the project or folder from which the Import from File System command was
invoked.
After importing from the file system, you are prompted to confirm the addition of the files that match
the specified criteria. You may remove one or more files from the import. Click OK to proceed with
the import.
After using the Import from File System feature, if you attempt to re-import the same file system
location into the same project, only files that are new since the last import are imported.
Export Contents to Package
Folders can be archived and distributed among multiple Komodo users via Packages. Packages
are compressed archive files that contain the folder from which the Export Package option was
invoked, as well as the folder's contents. Packages are stored in files with a ".kpz" extension, and
can be opened by any archiving utility that supports libz (for example WinZip). The Export
Package option differs from the Export to Project option in that a copy of filesystem-based
components (such as files and dialog projects) is included in the archive. Conversely, Export to
Project creates a project with a reference to the component's original location and does not create
a copy of the component.
To export the contents of a folder to a package:
1. In the Project Tab or Toolbox, right-click the folder containing the item(s) to be exported to a
package and select Export Package.
2. In the Package Export Wizard, enter the Package Name and Export Location. Click Next.
3. Click Finish.
Import from File System
119
Komodo User Guide
Import Contents from Package
Exported packages can only be imported into "container" objects in Komodo, such as projects, the
Toolbox, and folders within projects and the Toolbox.
To import the contents of a package to a folder:
1. In the Project Tab or Toolbox, right-click the folder and select Import Package.
2. In the Package Import Wizard, enter the name of the package and the location on disk
where files (as opposed to internal components like snippets and run commands) will be
extracted. Click Next.
3. Click Finish.
Refresh Folder Contents Status
The Refresh Status option checks read/write disk status for filesystem-based components (such
as files and dialogs) contained within the folder. If a file is of a language for which "code
intelligence" is supported and enabled (as configured in the Code Intelligence Preferences),
Refresh Status will also update the code intelligence database with the contents of the file.
If the component is stored in a source code control system, Refresh Status also checks the
repository status of the component. Komodo determines whether a file is contained in an SCC
repository by the following methods:
• Perforce: analysis of the client configuration
• CVS: analysis of the CVS control directories
Adding Components to Folders
Use this option to add components to the selected folder. All components can be added to folders,
in the same manner they are added to projects. Refer to the individual component documentation,
or the topics Adding Components to Projects or Adding Components to the Toolbox for more
information.
Use the cut/copy/paste options to remove folders from a project or the Toolbox, or to move folders
between the project and the Toolbox, between projects, or between folders.
Exporting Contents as Project File
When this option is invoked, a new project file is created that contains the folder (and its contents)
from which the option is invoked. You are prompted to provide the name of the new project file and
the directory where it will be stored. To open the new project file, select File|Open|Project.
Renaming Folders
To change the name of a folder, select this option and enter a new name.
Import Contents from Package
120
Komodo User Guide
Source Control on Folder Contents
Source Control on Contents refreshes the source code control status of all the files contained
within the folder. A subset of Komodo's Source Code Control functions can be performed. See
Source Code Control for a description of specific options.
Deleting Folders
To remove a folder from a project or the Toolbox, select the Delete option. Deleting a Komodo
folder has no effect on the actual filesystem contents. The folder is removed from the project or
Toolbox, but not deleted from the disk.
Source Control on Folder Contents
121
Snippets
Snippets are frequently used strings that can be quickly inserted into the
current document. For example, repetitive sections of code or standard
comments can be stored within a snippet. Snippets have advanced
properties; they support the use of Tab Stops and Interpolation Shortcuts,
can be assigned to Key Bindings, and allow for the specification of
indentation context and cursor position.
Snippets are stored in the Projects tab or the Toolbox.
Feature Showcases
• a snippet that
prompts for
input
• a snippet
containing a
code fragment
Creating Snippets
To create a code snippet, select the desired block of text in the Editor Pane. Then drag and drop
the selected section onto the Toolbox tab or into a project on the Projects tab.
Alternatively, select the desired text, then right-click and select Add as Snippet in the Toolbox.
Alternatively, right-click a folder in the Toolbox or on a project or folder name on the Projects tab,
and select New Snippet. If you use this method, you must manually enter the contents of the
snippet; text selected in the Editor Pane is not automatically added to the Snippet dialog box.
Configuring Snippets
To configure snippet properties, right-click the snippet on either the Toolbox tab or the Projects tab,
and select Properties. The following configuration properties are available:
• Snippet Name: Enter the text that should display in the Projects tab or Toolbox for this
code snippet. If the snippet was created by dragging a text selection from the Editor Pane,
the snippet is named after the text in the snippet.
• Snippet Contents: If the snippet was created by dragging a text selection from the Editor
Pane, the contents of the selected text are displayed in the Snippet Contents field.
Otherwise, enter the contents of the snippet manually. Add or edit snippet content as
desired.
• Snippet Shortcuts: Add Interpolation Shortcuts or Tab Stop/Replace markers to a snippet
by clicking the arrow button to the right of the Snippets Contents field, and selecting a
shortcut from the drop-down menu. Interpolation shortcuts in snippets are not executed
when the snippet is inserted in the Editor Pane via dragging and dropping.
• Maintain selected text or cursor position after insertion: Within the snippet contents
field, either select a portion of the snippet (by dragging the mouse pointer over the desired
selection) or position the editing cursor within the string. If this check box is selected, when
the snippet is inserted into the Editor Pane, the selected text or the cursor position is
displayed in the same manner.
• Maintain indentation context after insertion: If the snippet is inserted into the Editor Pane
when the editing cursor is in an indented position, select this check box to use the
indentation point as an indentation "prefix". The indentation structure of the snippet is
preserved at the position of insertion.
Snippets
122
Komodo User Guide
Using Snippets
To insert the contents of a snippet at the current cursor position in the Editor Pane, double-click it,
or right-click the snippet and select Insert Snippet.
Although you can also drag and drop snippets onto the Editor Pane, the cursor position and
indentation check box options explained above in Configuring Snippets will only take effect if the
snippet is added using the double-click or Insert Snippet method.
Snippet Options
To access options for the selected snippet, do one of the following:
• Toolbox|snippet_name|option or Project|snippet_name|option: When a snippet is
selected in the Project Manager or Toolbox tab, use the Project or Toolbox drop-down
menus to access the list of options. The name of the snippet currently selected in a project
or the Toolbox is displayed on the drop-down menu.
• Context Menu: Right-click a snippet in a project or the Toolbox and select the desired
option.
The following options are available:
• Insert Snippet: Use this option to insert the snippet at the current cursor position in the
editor, as described above in Using Snippets.
• Cut/Copy/Paste: These options are used to remove the snippet from a project or the
Toolbox, or to move snippets between the project and the Toolbox (and vice versa).
• Export as Project File: When this option is invoked, a new project file is created that
contains the snippet from which the option is invoked. You are prompted to provide the
name of the new project file and the directory where it will be stored. To open the new
project file, select File|Open|Project.
• Export Package: Snippets can be archived and distributed among multiple Komodo users
via Packages. Packages are compressed archive files that contain the snippet from which
the Export Package option was invoked. Packages are stored in files with a ".kpz"
extension, and can be opened by any archiving utility that supports libz (for example
WinZip). The Export Package option differs from the Export as Project File option in that
copies of filesystem-based components (such as files and dialog projects) are included in
the archive. Conversely, Export as Project File creates a project with a reference to the
component's original location and does not create copies of the components. When Export
Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as
projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting
and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages,
or Folders - Import Contents from Package for more information.
• Rename: To change the name of a snippet, select this option and enter a new name.
• Delete: To remove a snippet from a project or the Toolbox, select this option. The snippet is
permanently deleted.
Using Snippets
123
Komodo User Guide
Snippet Properties
Snippet properties are used to alter or rename snippets (as described in Configuring Snippets,
above). The Properties dialog box is also used to assign a custom icon to a snippet or to assign a
custom key binding. To access the Properties dialog box, right-click the snippet and select
Properties.
Assigning Custom Icons to Snippets
The default snippet icons can be replaced with custom icons. Komodo includes more than 600
icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel
images for best results).
To assign a custom icon to a snippet:
1. On the Projects tab or Toolbox tab, right-click the desired snippet and select Properties.
Alternatively, click the icon in the Projects tab or Toolbox tab, then select
Projects|snippet_name|Properties or Toolboxsnippet_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the Properties dialog box for the snippet, click OK. The custom icon is displayed next to
the snippet.
To revert to the default icon for a selected snippet:
1. On the Projects tab or Toolbox tab, right-click the desired snippet and select Properties.
2. Click Reset, then click OK. The default icon is displayed next to the snippet.
Snippet Key Bindings
To assign a key binding to a snippet, right-click the snippet on either the Toolbox tab or the Projects
tab, and select Properties. Select the Key Bindings tab, and configure the desired binding. See
Key Bindings for Custom Components for more information.
Snippet Properties
124
Macros
A macro consists of keystroke sequences that are recorded, saved, and executed either manually,
via a key binding, or with an event trigger. When the macro is invoked, the recorded keystrokes and
instructions execute. Only keystrokes (not mouse movements) are recorded within macros. Note
that, with the exception of the Find dialog box, macros that call external dialog boxes are not
supported. Macros are stored in projects or the Toolbox. Custom key bindings can be assigned to
macros.
The Macros toolbar provides quick access for recording, running, and saving macros. To open or
close the toolbar, select View|Toolbars|Macros. Alternatively, select Tools|Macros.
Creating Macros
Macros can be created via recording keystrokes, or by programming macro commands in the
Macros properties dialog. For information about programming macros, refer to the Macro API.
Recording Macros
Recording is a simple method for creating a macro. Recording a macro requires typing a series of
keystrokes in the Editor Pane. To record a macro:
1. Select Tools|Macros|Start Recording. The Komodo status bar displays "Recording
Macro".
2. In the Editor Pane, enter the keystrokes to store in the macro. While entering keystrokes,
pause recording by selecting Tools|Macros|Pause Recording. Select Start Recording
when ready to resume macro creation.
3. To end macro recording, select Tools|Macros|Stop Recording. The status bar displays
"Macro Recorded".
Alternatively, use the Macros Toolbar to invoke the commands.
Saving Recorded Macros
To save the most recent macro:
1. Select Tools|Macros|Save to Toolbox, or click Macro: Save to Toolbox on the Macro
Toolbar.
2. Give the new macro a unique name in the Enter name for new macro field. A reference to
the macro is automatically added to the Toolbox.
Programming Macros
Use the "New Macro" Properties dialog box to program macros in either Python or JavaScript.
Additionally, use this dialog box to specify macro key bindings and Komodo triggers that invoke the
macro automatically.
To add a macro:
Macros
125
Komodo User Guide
1. Select Toolbox|Add|New Macro... or Project|Add|New Macro.... Alternatively, use the
Add buttons within the Project or Toolbox tab, or right-click a project or folder name and
select Add.
2. On the Macro tab, configure the following options:
♦ New Macro: Enter the name of the macro (displayed in the Toolbox and Projects
tab) in the field.
♦ Change Icon: Click to select a custom icon to associate with this macro.
♦ Reset: Clears the icon choice.
♦ Language: Specify the language (Python or JavaScript) in which to program the
macro.
3. Program the macro in the Language editor field.
4. Click OK.
Refer to the Macro API for information about programming macros.
Running Macros
To run the most recently recorded macro, select Tools|Macros|Execute Last Macro, or use the
associated key binding. If the Macro Toolbar is open (View|Toolbars|Macro), click Macro: Run
Last Macro.
To run a macro that has been saved to a file and assigned to a project or to the Toolbox,
double-click the macro, or use the key binding assigned to the macro. Alternatively, right-click the
macro in the Projects tab or the Toolbox and select Execute Macro from the context menu.
Specifying Macro Triggers
Macros can be configured to execute based on certain Komodo events or triggers. When an event
occurs (for example, a file is opened in Komodo), the macro is triggered and then executes. A
macro that triggers "editor" functions or modifies open files should run in the foreground to block
user access to the editor. Macros running in the foreground run and "block" until they return. This
prevents the user from moving the cursor and disrupting the macro currently in progress.
Macro Return Values
Use the Macros Properties dialog box to specify a macro return value. Entering return 1; is
syntactically valid as a true value in either Python or JavaScript. Macros that return true and invoke
before a Komodo event can interrupt the process under execution. For example, a macro can
prevent a file from being saved if true is returned. If a macro returns "None" in JavaScript, or "Null"
in Python, it evaluates to false and does not interrupt the Komodo event in progress.
Note: Be sure to enable macro triggers via the Projects and Workspace Preferences in Komodo's
preferences. In the Triggering Macros area, select Enable triggering of macros on Komodo
events, and then click OK.
To add a trigger to a macro:
1. Right-click the macro in the Toolbox and select Properties.
2. Select the Triggers tab on the Macro Properties dialog box to access the following options:
Programming Macros
126
Komodo User Guide
♦ Macro should trigger on a Komodo event: Select the check box to access the
trigger events.
♦ Select the event you want to trigger the macro:
◊ At the tail end of the Komodo startup process
◊ After a file is opened
◊ Before a file is saved
◊ After a file is saved
◊ Before a file is closed
◊ After a file is closed
◊ Before Komodo shuts down (as part of File/Exit)
♦ Rank: Enter a numerical rank for the macro. For example, if three macros all invoke
"After a file is opened", a macro executes first (100), second (101), or third (102).
The default is 100 to provide room for macros to run before the default (1-99). Note
that if two macros trigger on the same event with the same rank, both execute in
indeterminate order.
3. Click Apply.
Running Macros in the Background
If a macro is not associated with a Komodo event, it can run either in the foreground or in the
background. Depending on the use case, some macros should run in the background while others
are more suitable for running in the foreground. Macros that invoke and do not affect the current file
are best run in the background to minimize interference with Komodo responsiveness. Macros that
perform "editor" functions or modify open files should always run in the foreground to "block" and
prevent user interference. This prevents the user from moving the cursor and disrupting the macro
currently in progress. Macros that run in the background are run in threads in Python, or in a
timeout in JavaScript.
To run a macro in the background:
1. Right-click the macro in the Toolbox and select Properties.
2. Select the Run in Background option.
3. Click Apply.
Storing Macros in Projects or the Toolbox
Macros are added to the Toolbox via the Tools|Macros|Save to Toolbox option. However, you
can manually add macros to the Toolbox, or to a project in the Projects tab.
To add a new macro to a project or the Toolbox:
1. Right-click the name of the project, or the name of a folder within a project or the Toolbox,
and select Add|New Macro from the context menu. Alternatively, select Project|Add|New
Macro or Toolbox|Add|New Macro from the drop-down menu, or select New Macro from
the Add button in the Project or Toolbox tab.
2. Follow the instructions in the Programming Macros section.
3. Click OK.
Alternatively, existing macros can be dragged and dropped between the Toolbox and the Projects
tab.
Specifying Macro Triggers
127
Komodo User Guide
Macro Options
To access macro options, right-click the macro name in a project or the Toolbox and select the
desired option.
• Execute Macro: Use this option to run the selected macro.
• Cut/Copy/Paste: These options are used to remove the macro from a project or the
Toolbox, or to move macros between the project and the Toolbox (and vice versa).
• Export as Project File: When this option is invoked, a new project file is created that
contains the macro from which the option is invoked. You are prompted to provide the name
of the new project file and the directory where it will be stored. To open the new project file,
select File|Open|Project.
• Export Package: Macros can be archived and distributed among multiple Komodo users
via "packages". Packages are compressed archive files that contain the macro from which
the Export Package option was invoked. Packages are stored in files with a ".kpz"
extension, and can be opened by any archiving utility that supports libz (for example
WinZip). The Export Package option differs from the Export as Project File option in that
copies of filesystem-based components (such as files and dialog projects) are included in
the archive. Conversely, Export as Project File creates a project with a reference to the
component's original location and does not create copies of the components. When Export
Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as
projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting
and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages,
Folders - Import Contents from Package for more information.
• Rename: To change the name of a macro, select this option and enter a new name.
• Delete: To remove a macro from a project or the Toolbox, select this option. The macro is
permanently deleted.
Assigning Custom Icons to Macros
The default macro icon can be replaced with custom icons. Komodo includes more than 600 icons;
alternatively, select a custom image stored on a local or network drive (use 16x16-pixel images for
best results).
To assign a custom icon to a macro:
1. In the project or in the Toolbox, right-click the desired macro and select Properties.
Alternatively, click the macro in the Projects tab or Toolbox tab, then select
Projects|macro_name|Properties or Toolboxmacro_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the properties dialog box for the macro, click OK. The custom icon is displayed next to
the macro.
To revert to the default icon for a selected macro:
1. On the Projects tab or Toolbox tab, right-click the desired macro and select Properties.
2. Click Reset, then click OK. The default icon is displayed next to the macro.
Macro Options
128
Komodo User Guide
Assigning Key Bindings to Macros
Custom key bindings can be assigned to macros stored in the Toolbox or in a Project. Use the Key
Binding tab in the macro's Properties to specify the keystrokes that invoke the macro. See Key
Bindings for Custom Components for more information.
Vi Command Mode Macros
Komodo's Vi emulation offers a command-line mode. Entering ':' opens a text box for entering
commands. You can add additional commands by creating a Toolbox folder named Vi Commands,
then creating Macros with the name of the desired command. The macro is executed when you
type it's name in the Vi command text box. For example, to create a macro that replicates the
behavior of the 'ZZ' command in Vi:
1. record or write a macro that saves and closes the current file
2. save the macro to the Toolbox with the name 'ZZ'
3. move the ZZ macro into the Vi Commands folder.
Assigning Key Bindings to Macros
129
Macro API
Introduction to the Komodo Macro API
Komodo macros can be written in either JavaScript or Python. As much as possible, the API calls
are the same regardless of the language. Exceptions are noted where appropriate.
In both Python and JavaScript, there is a top-level komodo object that contains both variables and
utility functions. These are:
• The editor object for manipulation of code buffers.
• The document object for manipulation of documents in memory.
• The file type, corresponding to files on disk.
• The doCommand(...) function to execute Komodo "commands".
• The openURI(...) function to open a local or remote file using a URI.
• The findPart(...) function to find other components (snippets, run commands, other macros,
etc).
• The interpolate(...) function for evaluation of interpolation codes.
• The getWordUnderCursor() function to retrieve the word under the editing cursor.
Warning
The macro system is a powerful mechanism by which Komodo users can execute arbitrary code
inside the Komodo process. It is easy for novices to write macros that can significantly disrupt
Komodo's behavior, leading to instability and data loss. We encourage users to experiment with
macros when not working with important files.
Of particular note:
• Macros that never terminate (for example, due to infinite loops) can hang Komodo.
• Macros that modify the buffer should never be run in the background, as multiple threads
accessing the editor object could cause crashes.
• Macros that modify the editor object should be written with care, to avoid data loss
.
Feedback
Komodo 3.0 was the first release of Komodo with a published macro API. We expect the API to
change in response to customer feedback. As such, the API described below may change in future
releases (we will of course try to minimize backwards-incompatible changes). Questions and
feedback on the API are encouraged via the komodo-discuss mailing list.
The editor Object
The komodo.editor object corresponds to the main text editing widget that contains and
manipulates files in the Editor Pane. It is a thin wrapper around the Scintilla widget, an open-source
component written by Neil Hodgson (www.scintilla.org).
Macro API
130
Komodo User Guide
The Scintilla API is large, complex and subject to change. This document only contains the calls
most relevant to Komodo, and notes some common patterns of use relevant to changing the editor
widget.
editor Attributes
int currentPos
The location (in character units) of the caret.
int anchor
The location (in character units) of the selection anchor.
string text
The contents of the buffer.
string selText
The contents of the selection (readonly).
long scrollWidth
The width of the scroll area (in pixels).
long xOffset
The horizontal scroll position (in pixels) of the start of the text view.
boolean viewEOL
Whether to show end-of-line markers or not.
long viewWS
Whether to show whitespace characters (0: no, 1: yes).
long eOLMode
The characters that are inserted when the user presses 'Enter': either 'CRLF' (0 - the default
on Windows), 'CR' (1) or 'LF' (2 - the default on Linux).
long tabWidth
The size of a tab as a multiple of the size of a space character.
long indent
The size of indentation in terms of the width of a space.
boolean useTabs
Whether indentation should be created out of a mixture of tabs and spaces (1) or be based
purely on spaces (0).
boolean indentationGuides
Whether to show indentation guides or not.
readonly long firstVisibleLine
The line number of the first visible line in the text view.
long lineCount
The number of lines in the text view.
long textLength
The length of the current buffer in characters.
long targetStart
The start of the target region; see replaceTarget.
long targetEnd
The end of the target region; see replaceTarget.
long linesOnScreen
The number of complete lines visible on the screen.
The editor Object
131
Komodo User Guide
komodo.editor Methods
void emptyUndoBuffer()
Empty the undo buffer.
void undo()
Undo the last action.
void cut()
Cut current selection (komodo.doCommand('cmdCut') is the preferred method).
void copy()
Copy current current selection.
void paste()
Replace current selection with the clipboard contents.
void clear()
Clear current selection.
long replaceTarget(in long length, in string text)
Replace the target text with the argument text. Text is counted so it can contain NULs.
Returns the length of the replacement text..
string getTextRange(in long min, in long max)
Return a range of characters from the current buffer.
void insertText(in long pos, in string text)
Insert text at a specified position.
void colourise(in long start, in long end)
Force the re-coloring of the specified range.
wchar getWCharAt(in long pos)
Get the (Unicode) character at the specified position.
void addText(in long length, in string text)
Add text to the end of the current buffer.
void selectAll()
Select the entire buffer.
void gotoLine(in long line)
Jump to the specified line.
void gotoPos(in long pos)
Jump to the specified position in the buffer.
void deleteBack()
Delete the character to the left of the cursor.
void newLine()
Add a newline (note: this is a less 'smart' newline than can be obtained using
komodo.doCommand('cmd_newlineExtra').
void redo()
Redo the last action.
boolean canRedo()
There is an action that can be redone.
void beginUndoAction()
Begin an undo block (see note).
void endUndoAction()
End an undo block (see note).
long getColumn(in long pos)
Get the column (0-based) of the specified position.
long getLineEndPosition(in long line)
komodo.editor Methods
132
Komodo User Guide
Get the position corresponding to the last character on the specified line (not including EOL
characters).
void setSel(in long start, in long end)
Make selection start at start and end at end.
long lineFromPosition(in long pos)
Get the line number (0-indexed) from character position pos.
long positionFromLine(in long line)
Get character position which begins the specified line.
void lineScroll(in long columns, in long lines)
This will attempt to scroll the display by the number of columns and lines that you specify.
Positive line values increase the line number at the top of the screen (i.e. they move the text
upwards as far as the user is concerned). Negative line values do the reverse.
void scrollCaret()
If the current position (this is the caret if there is no selection) is not visible, the view is
scrolled to make it visible.
long lineLength(in long line)
Return the length of the current line.
void replaceSel(string)
Replace current selection with the text in the string.
void lineDown()
Move cursor down one line.
void lineDownExtend()
Extend selection down one line.
void lineUp()
Move cursor up one line.
void lineUpExtend()
Extend selection up one line.
void charLeft()
Move cursor one character to the left.
void charLeftExtend()
Extend selection one character to the left.
void charRight()
Move cursor one character to the right.
void charRightExtend()
Extend selection one character to the right.
void wordLeft()
Move cursor one word to the left.
void wordLeftExtend()
Extend selection one word to the left.
void wordRight()
Move cursor one word to the right.
void wordRightExtend()
Extend selection one word to the right.
void home()
Move cursor to the Home position.
void homeExtend()
Extend selection to the Home position.
void lineEnd()
Move cursor to the end of the line.
void lineEndExtend()
komodo.editor Methods
133
Komodo User Guide
Extend selection to the end of the line.
void documentStart()
Move cursor to the start of the document.
void documentStartExtend()
Extend selection to the start of the document.
void documentEnd()
Move cursor to the end of the document.
void documentEndExtend()
Extend selection to the end of the document.
void pageUp()
Page up.
void pageUpExtend()
Extend selection one page up.
void pageDown()
Page down.
void pageDownExtend()
Extend selection one page down.
void editToggleOvertype()
Toggle overtype mode.
void vCHome()
Move cursor to the first non-whitespace character on a line or, if none, the beginning of a
line.
void vCHomeExtend()
Extend the selection to the first non-whitespace character on a line or, if none, the
beginning of a line.
void zoomIn()
Increase font size.
void zoomOut()
Decrease font size.
void delWordLeft()
Delete word to the left of the cursor.
void delWordRight()
Delete word to the right of the cursor.
void lineCopy()
Copy line at the cursor.
void lineCut()
Cut line at the cursor.
void lineDelete()
Delete line at the cursor.
void lineTranspose()
Transpose current line and previous line.
void lineDuplicate()
Duplicate current line.
void lowerCase()
Convert selection to lower case.
void upperCase()
Convert selection to upper case.
void lineScrollDown()
Scroll display down one line.
void lineScrollUp()
komodo.editor Methods
134
Komodo User Guide
Scroll display up one line.
void deleteBackNotLine()
Delete last character except if at beginning of line.
void homeDisplay()
Move cursor to Home position for the current display line (as opposed to the buffer line
when word wrap is enabled).
void homeDisplayExtend()
Extend selection to the Home position for the current display line (as opposed to the buffer
line when word wrap is enabled).
void lineEndDisplay()
Move cursor to end of the current display line (as opposed to the buffer line when word
wrap is enabled).
void lineEndDisplayExtend()
Extend selection to the end of the current display line (as opposed to the buffer line when
word wrap is enabled).
void wordPartLeft()
Move cursor a word segment to the left. Word segments are marked by capitalization
(aCamelCaseIdentifier) or underscores (an_under_bar_ident).
void wordPartLeftExtend()
Extend selection a word segment (as described in void wordPartLeft()) to the left.
void wordPartRight()
Move cursor a word segment (as described in void wordPartLeft()) to the right.
void wordPartRightExtend()
Extend selection a word segment (as described in void wordPartLeft()) to the right.
void delLineLeft()
Delete to beginning of line.
void delLineRight()
Delete to end of line.
void paraDown()
Move cursor one paragraph down.
void paraDownExtend()
Extend selection one paragraph down.
void paraUp()
Move cursor one paragraph up.
void paraUpExtend()
Extend selection one paragraph up.
editor Object Notes
Invalid Parameters: The Scintilla API assumes that users of the API do their own error-checking.
Passing arguments that are out of bounds or otherwise erroneous can result in Komodo crashing.
The Undo Stack: Scintilla manages the "undo" stack. To treat a sequence of operations as a single
operation for the sake of Undo/Redo, wrap these operations in a beginUndoAction /
endUndoAction pair. The endUndoAction must be called even in the case of an exception in
the code. Otherwise, the undo stack will be corrupted and might lose data.
For example, for JavaScript:
komodo.editor.beginUndoAction()
try {
editor Object Notes
135
Komodo User Guide
... // do your sequence here
} finally {
komodo.editor.endUndoAction()
}
For Python:
komodo.editor.beginUndoAction()
try:
... # do your sequence here
finally:
komodo.editor.endUndoAction()
The document Object
The komodo.document object refers to the current document. A document contains the contents
of the file being edited. These contents will be different than those of the file on disk if the file is
unsaved or "dirty".
document Attributes
string baseName
The basename of the document (e.g. "myfile.txt").
string displayPath
The display path of the document (e.g. "C:\Code\myfile.txt").
file
The file object corresponding to the document (null if the document is unsaved).
string buffer
The contents of the document (Unicode string).
boolean isDirty
Whether there are unsaved changes to the document.
boolean isUntitled
Whether the document has never been saved.
string language
The language that this document is viewed as ("Python", "Perl", etc.
The file Object
The file object is an attribute of document objects, and corresponds to a wrapper object around
the file object.
file attributes
string URI
The URI to the file (e.g. "file:///C:/Code/myfile.txt").
string displayPath
The display path of the file (e.g. "C:\Code\myfile.txt"), or the URI if the URI is not of
the file:// scheme.
string baseName
The base name of the file (e.g. "myfile.txt").
The document Object
136
Komodo User Guide
string dirName
The directory of the file (e.g. "C:\Code").
The komodo.doCommand Function
Signature:
komodo.doCommand(commandId)
Execute the internal Komodo command specified by commandId.
Command IDs and their corresponding functions are available in the Command ID reference.
Most editor-related commands require that the Editor Pane be in focus. To ensure focus before
invoking doCommand, set the focus explicitly as follows:
komodo.view.setFocus()
The komodo.openURI Function
Signature:
komodo.openURI(uri_string#line_number)
Open the file specified by the URI string and move the cursor to the line number specified after '#'
(if any).
All file access protocols used by Komodo are valid. For example:
komodo.openURI("file:///home/user/example.txt#33");
komodo.openURI("ftp://example.org/pub/example.xml");
komodo.openURI("scp:///host.example.org/home/user/file.txt#11");
The komodo.findPart Function
Signature:
komodo.findPart(type, name, where) -> part
Find a "part" (the internal name for a component such as a snippet, another macro, a run
command, etc) in the Toolbox or a project.
• type: The type of component to search for. It can be one of:
♦ "snippet"
♦ "command"
♦ "macro"
♦ "file"
♦ "folder"
♦ "dialog"
♦ "URL"
file attributes
137
Komodo User Guide
♦ "template"
♦ "DirectoryShortcut"
• name: The component's name.
• where: A string corresponding to the component container that should be searched.
Supported values are:
"toolbox"
search in the Toolbox
"shared toolbox"
search in the Shared Toolbox (if enabled)
"toolboxes"
search in both the Toolbox and the Shared Toolbox
"container"
search the project or Toolbox that contains the current macro
"*"
search all of the above
The komodo.interpolate Function
Signature:
komodo.interpolate(s[, bracketed]) -> string
Evaluate interpolation shortcuts in the given string.
• s: The string to interpolate.
• bracketed: An optional boolean value indicating whether plain (e.g. %F) or bracketed (e.g.
[[%F]]) syntax is being used. If not specified, plain interpolation is used (i.e.
bracketed=false)
The komodo.findPart Function
138
Komodo Command Id List
Breakpoint Manager
Add Breakpoint
cmd_breakpoint_add
Add Tcl Spawnpoint
cmd_spawnpoint_add
Delete All Breakpoints
cmd_breakpoint_delete_all
Delete Breakpoint
cmd_breakpoint_delete
Edit Breakpoint
cmd_breakpoint_properties
Enable/Disable All Breakpoints
cmd_breakpoint_toggle_all
Enable/Disable Breakpoint
cmd_breakpoint_toggle
Show Breakpoint
cmd_breakpoint_goto
Code Browser
Go to Definition
cmd_codeBrowserGoToDefinition
Locate current scope...
cmd_codeBrowserLocate
Debugger
Add Watch Variable
cmd_dbgAddVariable
Add/Edit Breakpoint...
cmd_dbgBreakpointAddOrEdit
Add/Edit Spawnpoint...
cmd_dbgSpawnpointAddOrEdit
Break Now
cmd_dbgBreakNow
Clear All Breakpoints
cmd_dbgBreakpointClearAllInURI
Delete Selected Variable
cmd_dbgDeleteVariable
Detach
cmd_dbgDetach
Disable/Enable Breakpoint
cmd_dbgBreakpointToggle
Edit Selected Variable Name
cmd_dbgWatchedVariable
Edit Selected Variable Value
cmd_dbgEditVariable
Interactive Debugger Shell Clear Buffer
cmd_dbgInteractiveClearBuffer
Interactive Debugger Shell
cmd_dbgInteractive
Listen for Debugger Connections
cmd_debuggerListener
Load HTML Preview
cmd_dbgViewAsHTML
Make Selection a Watched Variable
cmd_dbgMakeWatchedVariable
New Session
cmd_dbgNewSession
Run Script
cmd_dbgRun
Run to Cursor
cmd_dbgStepCursor
Komodo Command Id List
139
Komodo User Guide
Show Current Statement
cmd_dbgShowCurrentStatement
Show Hidden Variables
cmd_dbgShowHiddenVars
Start Default Interactive Shell
cmd_startInteractiveShell
Start Perl Interactive Shell
cmd_startPerlInteractiveShell
Start Python Interactive Shell
cmd_startPythonInteractiveShell
Start Tcl Interactive Shell
cmd_startTclInteractiveShell
Start
cmd_dbgGo
Start/Find/Hide Default Interactive Shell
cmd_toggleInteractiveShell
Step Forward
cmd_dbgStepForward
Step In
cmd_dbgStepIn
Step Out
cmd_dbgStepOut
Step Over
cmd_dbgStepOver
Stop
cmd_dbgStop
Editor
Add as Snippet to Toolbox
cmd_makeSnippetFromSelection
Back
cmd_back
Backspace
cmd_backSmart
Beginning of Line (first char/first column)
cmd_home
Cancel AutoComplete
cmd_cancel
Compare with file on disk
cmd_showUnsavedChanges
Copy
cmd_copy
Current File Settings
cmd_editPrefsCurrent
Cut Line
cmd_lineCut
Cut Region
cmd_cutRegion
Cut rest of line
cmd_killLine
Cut
cmd_cut
Decrease Line Indent
cmd_dedent
Delete Line
cmd_lineDelete
Delete Word Left
cmd_deleteWordLeft
Delete Word Right
cmd_deleteWordRight
Delete
cmd_delete
End of Line
cmd_end
Exchange Current Point and Mark
cmd_transientMarkExchangeWithPoint
Go to Beginning of word
cmd_beginningOfWord
Go to End of Document
Debugger
140
Komodo User Guide
cmd_documentEnd
Go to End of word
cmd_endOfWord
Go to Line...
cmd_gotoLine
Go to Next Bookmark
cmd_bookmarkGotoNext
Go to Next Line
cmd_lineNext
Go to Previous Bookmark
cmd_bookmarkGotoPrevious
Go to Previous Line
cmd_linePrevious
Go to Top of Document
cmd_documentHome
Increase Line Indent
cmd_indent
Insert Newline (align with current line)
cmd_newlineSame
Insert Newline (continue comments)
cmd_newlineExtra
Insert Newline (no favors)
cmd_newlineBare
Insert Newline
cmd_newline
Insert Next Key as Literal Character
cmd_rawKey
Join current and next lines
cmd_join
Move Back Part of Word
cmd_wordPartRight
Move Forward Part of Word
cmd_wordPartLeft
Move Left One Character
cmd_left
Move One Character Right
cmd_right
Move One Word Left
cmd_wordLeft
Move One Word Right
cmd_wordRight
Move to previous mark in mark ring
cmd_transientMarkMoveBack
Page Down
cmd_pageDown
Page Up
cmd_pageUp
Paste and Select
cmd_pasteAndSelect
Paste
cmd_paste
Redo
cmd_redo
Reflow paragraph(s)
cmd_editReflow
Remove All Bookmarks
cmd_bookmarkRemoveAll
Repeat next keystroke N times
cmd_repeatNextCommandBy
Reset language to best guess
cmd_viewAsGuessedLanguage
Scroll One Line Down
cmd_lineScrollDown
Scroll One Line Up
cmd_lineScrollUp
Scroll current line to center of screen
cmd_editCenterVertically
Scroll current line to top of screen
cmd_editMoveCurrentLineToTop
Editor
141
Komodo User Guide
Select All
cmd_selectAll
Select Next Character
cmd_selectCharNext
Select Next Part of Word
cmd_wordPartRightExtend
Select Next Word
cmd_selectWordRight
Select Page Down
cmd_selectPageDown
Select Page Up
cmd_selectPageUp
Select Previous Character
cmd_selectCharPrevious
Select Previous Part of Word
cmd_wordPartLeftExtend
Select Previous Word
cmd_selectWordLeft
Select to Beginning of Line (first char/first
column)
cmd_selectHome
Select to Beginning of word
cmd_beginningOfWordExtend
Select to End of Document
cmd_selectDocumentEnd
Select to End of Line
cmd_selectEnd
Select to End of word
cmd_endOfWordExtend
Select to Next Line
cmd_selectLineNext
Select to Previous Line
cmd_selectLinePrevious
Select to Top of Document
cmd_selectDocumentHome
Set Mark
cmd_transientMarkSet
Toggle Bookmark
cmd_bookmarkToggle
Toggle Overtype/Insert Mode
cmd_toggleOvertype
Transpose Current and Previous Characters
cmd_transpose
Transpose Current and Previous Lines
cmd_lineTranspose
Transpose Current and Previous Words
cmd_transposeWords
Trigger preceding autocomplete list or calltip
cmd_triggerPrecedingCompletion
Undo
cmd_undo
Zoom Font Size Down
cmd_fontZoomOut
Zoom Font Size Up
cmd_fontZoomIn
Find
Find Next Result
cmd_findNextResult
Find Next Selected
cmd_findNextSelected
Find Next
cmd_findNext
Find Previous
cmd_findPrevious
Find in Files...
cmd_findInFiles
Find...
cmd_find
Find
142
Komodo User Guide
Incremental Search Backwards
cmd_startIncrementalSearchBackwards
Incremental Search
cmd_startIncrementalSearch
Replace...
cmd_replace
General
Close All Windows
cmd_closeAll
Close Project
cmd_closeProject
Close Window
cmd_bufferClose
Edit Properties
cmd_editProperties
Export Selection as HTML...
cmd_exportHTMLSelection
Export as HTML...
cmd_exportHTML
Import From File System into Current Project
cmd_importFromFS_Project
Least Recently Viewed File
cmd_bufferNextLeastRecent
Most Recently Viewed File
cmd_bufferNextMostRecent
New File (default type)
cmd_new
New File...
cmd_newTemplate
New Project...
cmd_newProject
Next File
cmd_bufferNext
Open File...
cmd_open
Open Project...
cmd_openProject
Open Remote File...
cmd_open_remote
Open Template...
cmd_openTemplate
Open URL...
cmd_openURL
Preferences...
cmd_editPrefs
Previous File
cmd_bufferPrevious
Print Preview
cmd_printPreview
Print Selection...
cmd_printSelection
Print Setup...
cmd_printSetup
Print...
cmd_print
Quit
cmd_quit
Refresh Status
cmd_refreshStatus
Revert Project
cmd_revertProject
Revert
cmd_revert
Save All
cmd_saveAll
Save As Remote...
cmd_saveAs_remote
Save As Template
General
143
Komodo User Guide
cmd_saveAsTemplate
Save As...
cmd_saveAs
Save Project As...
cmd_saveProjectAs
Save Project
cmd_saveProject
Save
cmd_save
Help
About Komodo
cmd_helpAbout
ActiveState Programmer Network
cmd_helpASPN
ActiveState Support
cmd_helpSupport
ActiveState Website
cmd_helpActiveState
Alternate Help on Selection
cmd_helpLanguageAlternate
Help...
cmd_helpHelp
Komodo Bug Database
cmd_helpViewBugs
Language-Specific Help on Selection
cmd_helpLanguage
PHP Mailing Lists
cmd_helpPHPMailingLists
PHP Reference (Web)
cmd_helpPHPRef_Web
Perl Mailing Lists
cmd_helpPerlMailingLists
Perl Reference (Local)
cmd_helpPerlRef_Local
Perl Reference (Web)
cmd_helpPerlRef_Web
Python Mailing Lists
cmd_helpPythonMailingLists
Python Reference (Local)
cmd_helpPythonRef_Local
Python Reference (Web)
cmd_helpPythonRef_Web
Show Keybindings...
cmd_helpShowKeybindings
Software Updates
cmd_helpUpdates
Start Page
cmd_openStartPage
Tcl Mailing Lists
cmd_helpTclMailingLists
Tcl Reference (Local)
cmd_helpTclRef_Local
Tcl Reference (Web)
cmd_helpTclRef_Web
Tip of the Day...
cmd_helpTipOfTheDay
XSLT Mailing Lists
cmd_helpXSLTMailingLists
Macro
End Recording
cmd_stopMacroMode
Execute Last Macro
cmd_executeLastMacro
Pause Recording
cmd_pauseMacroMode
Help
144
Komodo User Guide
Save to Toolbox
cmd_saveMacroToToolbox
Start/Resume Recording
cmd_startMacroMode
Projects/Toolbox
Add New Folder...
cmd_addFolderPart
Add Remote File...
cmd_addRemoteFilePart
Source Code
Clean Line Endings
cmd_cleanLineEndings
Collapse All Folds
cmd_foldCollapseAll
Collapse Fold
cmd_foldCollapse
Comment Region
cmd_comment
Complete Word (backwards)
cmd_completeWordBack
Complete Word
cmd_completeWord
Convert Selection to Lower Case
cmd_convertLowerCase
Convert Selection to Upper Case
cmd_convertUpperCase
Expand All Folds
cmd_foldExpandAll
Expand Fold
cmd_foldExpand
Find All Functions
cmd_findAllFunctions
Find Next Function
cmd_findNextFunction
Find Previous Function
cmd_findPreviousFunction
Jump to Matching Brace
cmd_jumpToMatchingBrace
Jump to corresponding line
cmd_jumpToCorrespondingLine
Match Braces
cmd_braceMatch
Next Syntax Error/Warning
cmd_nextLintResult
Select Block
cmd_blockSelect
Select to Matching Brace
cmd_selectToMatchingBrace
Tabify Region...
cmd_tabify
Un-comment Region
cmd_uncomment
Un-tabify Region...
cmd_untabify
Source Control
Add File
cmd_SCCadd
Add Folder
cmd_SCCadd_folder
Commit Changes in Folder
cmd_SCCcommit_folder
Commit Changes
cmd_SCCcommit
Macro
145
Komodo User Guide
Compare Files in Folder
cmd_SCCdiff_folder
Compare
cmd_SCCdiff
Edit
cmd_SCCedit
Remove File
cmd_SCCremove
Revert Changes in Folder
cmd_SCCrevert_folder
Revert Changes
cmd_SCCrevert
Update Folder
cmd_SCCupdate_folder
Update
cmd_SCCupdate
Toolbox
Export Package
cmd_toolboxExportPackage
Tools
Build Standalone Perl Application...
cmd_toolsBuildPerlAppCommand
Run Command...
cmd_toolsRunCommand
Rx Toolkit
cmd_toolsRx
Watch File...
cmd_toolsWatchFile
User Interface
Browser Preview
cmd_browserPreview
Focus on Bottom Pane
cmd_focusBottomPane
Focus on Editor
cmd_focusEditor
Focus on Projects Pane
cmd_focusProjectPane
Focus on Toolbox Pane
cmd_focusToolboxPane
Move tab to another tab window
cmd_movetab
Show/Hide Code Browser Tab
cmd_viewCodeBrowser
Show/Hide Debug Toolbar
cmd_viewdebugtoolbar
Show/Hide End of Lines
cmd_viewEOL
Show/Hide Macros Toolbar
cmd_viewmacrotoolbar
Show/Hide Open/Find Toolbar
cmd_viewfindtoolbar
Show/Hide Output Pane
cmd_viewBottomPane
Show/Hide Projects Pane
cmd_viewLeftPane
Show/Hide Projects Tab
cmd_viewProjects
Show/Hide SCC Toolbar
cmd_viewscctoolbar
Show/Hide Standard Toolbar
cmd_viewedittoolbar
Show/Hide Toolbar Button Text
cmd_toggleButtonText
Source Control
146
Komodo User Guide
Show/Hide Toolbox Pane
cmd_viewRightPane
Show/Hide Toolbox Tab
cmd_viewToolbox
Show/Hide Tools Toolbar
cmd_viewtoolstoolbar
Show/Hide Whitespace
cmd_viewWhitespace
Show/Hide Workspace Toolbar
cmd_viewworkspacetoolbar
Split view of tab
cmd_splittab
Toggle splitter orientation
cmd_rotateSplitter
Use Fixed/Proportional Font
cmd_fontFixed
View Source
cmd_focusSource
View/Hide Indentation Guides
cmd_viewIndentationGuides
View/Hide Line Numbers
cmd_viewLineNumbers
Word-wrap long lines
cmd_wordWrap
User Interface
147
Komodo JavaScript API
ko
Classes
class objectTimer
Constructor
objectTimer(instance, func, args)
Class variables
args - args
func - func
instance - instance
interval - window.setInterval()
running - Boolean
timeout - window.setTimeout()
timer - Number
Class functions
free()
monitor()
startInterval(timer)
startTimeout(timer)
stop(timer)
stopInterval()
stopTimeout()
Komodo JavaScript API
148
Komodo User Guide
ko.browse
Functions
about()
show our about dialog XXX DEPRECATE, this should be dialog.about or ko.about
aspnMailingList(topic)
show mailing list archives on ASPN that are related to the topic
Arguments
topic - String
browseTag(tag)
browse to a predefined url on activestate.com see tag2uri in ko.browse
localHelp(app)
show the url defined in "localHelpFile" in an instance of koIAppInfoEx
Arguments
app - String
the app identifier from the CID of a koIAppInfoEx implementation (eg.
@activestate.com/koAppInfoEx?app=Perl)
openUrlInDefaultBrowser(url, browser)
open the given url or complain appropriately
Arguments
url - String
browser - String
optional, retreived from prefs if not used
showCommandIds()
show a list of command id's in the browser
showKeybindings()
ko.browse
149
Komodo User Guide
show a list of keybindings in the browser
updateHelpLanguagesPopup()
Hide or show the local help entries in the Help->Languages popup depending on whether an
actually help file to launch can be found.
webHelp(app)
show the url defined in "webHelpURL" in an instance of koIAppInfoEx
Arguments
app - String
the app identifier from the CID of a koIAppInfoEx implementation (eg.
@activestate.com/koAppInfoEx?app=Perl)
ko.commands
Functions
doCode(cmdId, code)
doCodeAsync(cmdId, code)
doCommand(command)
Returns - rc
doCommandAsync(command, event)
Arguments
event - Event
Returns - Boolean
setCommandEnabled(id, node, supported, enabled)
updateCommand(command, commandNode, controller)
Returns - found
updateCommandset(commandset)
ko.dialogs
Functions
150
Komodo User Guide
Variables
alert - parent.opener.ko.dialogs.alert
yesNo - parent.opener.ko.dialogs.yesNo
yesNo()
Functions
alert(prompt, text, title, doNotAskPref, options)
authenticate(title, message, loginname, allowAnonymous, allowPersist)
Returns - ko.dialogs.authenticate2()
authenticate2(prompt, server, username, allowAnonymous, title, login)
Returns - Object
customButtons(prompt, buttons, response, text, title, doNotAskPref, style)
Returns - obj.response
editEnvVar(name, value, title, mruName, interpolateValues)
handleEnterKey()
internalError(error, text)
okCancel(prompt, response, text, title, doNotAskPref)
Returns - obj.response
pickIcon()
pickPreview(url, language, mode)
Returns - Object
progress(processor, prompt, title, is_cancellable, cancel_warning, modal)
prompt(prompt, label, value, title, mruName, validator, multiline, screenX, screenY, tacType,
tacParam, tacShowCommentColumn)
prompt2(prompt, label1, value1, label2, value2, title, mruName1, mruName2, validator, multiline1,
multiline2, screenX, screenY)
selectFromList(title, prompt, items, selectionCondition, stringifier, doNotAskPref, yesNoCancel,
buttonNames)
yesNo(prompt, response, text, title, doNotAskPref)
Returns - obj.response
Variables
151
Komodo User Guide
yesNoCancel(prompt, response, text, title, doNotAskPref, style)
Returns - obj.response
ko.dragDrop
Functions
unpackData(flavourData, ret)
ko.dragDrop.dragObserver
Variables
canHandleMultipleItems - Boolean
Functions
canDrop(event, session)
Arguments
event - Event
Returns - Boolean
doDragOverEvent(event)
Arguments
event - Event
doDropEvent(event)
Arguments
event - Event
focusWindow()
getSupportedFlavours()
Returns - flavours
onDragOver(event, flavour, session)
Arguments
event - Event
Returns - Boolean
Functions
152
Komodo User Guide
onDrop(event, transferDataSet, dragSession)
Arguments
event - Event
ko.eggs
Functions
boing()
ko.filepicker
Functions
browseForDir(textbox)
A dialog to pick a directory, and put the directory path into a XUL textbox.
Arguments
textbox - Element
browseForRemoteDir(textbox)
A dialog to pick a remote directory and put the path into a XUL textbox.
Arguments
textbox - Element
getFolder(defaultDirectory, prompt)
Pick a directory/folder.
Returns - String
openExeFile(defaultDirectory, defaultFilename, title)
Pick an executable file for open.
Returns - String
openFile(defaultDirectory, defaultFilename, title, defaultFilterName, filterNames)
Pick a file for open.
Functions
153
Komodo User Guide
Returns - String
openFiles(defaultDirectory, defaultFilename, title, defaultFilterName, filterNames)
Pick multiple files for open.
Returns - Array
openRemoteFiles(defaultUrl, defaultFilename, defaultFilterName, filterNames)
Open remote file(s) Same parameters meanings as "filepicker_remoteFileBrowser" (above) Returns
nothing. Note: The files will be opened through this function call
remoteFileBrowser(defaultUrl, defaultFilename, mode, title, defaultFilterName, filterNames,
helpTag)
Browse for remote file(s)
Returns - Object
saveAsRemoteFiles(defaultUrl, defaultFilename, defaultFilterName, filterNames)
Choose remote filename to save as Same parameters meanings as "filepicker_remoteFileBrowser"
(above) Returns the remote url of the selected file, or null if the dialog is cancelled.
saveFile(defaultDirectory, defaultFilename, title, defaultFilterName, filterNames)
Pick a file for save.
Returns - String
ko.fileutils
Functions
showDiffs(fname1, fname2)
ko.help
Functions
alternate()
alternate uses the alternate help preference
DEPRECATED_getTag(tag)
getTag old help open method, DEPRECATED
Functions
154
Komodo User Guide
Returns - tag
DEPRECATED_openTag(tag)
openTag old help open method, DEPRECATED
language()
language open language specific help for the current buffer.
open(page)
open open Komodo help window
Arguments
page - String
a page tag as defined in toc.xml
tutorialProject(tutorial)
tutorialProject used by the help system to open KPF files associated with a tutorial
Arguments
tutorial - String
name of tutorial to open
tutorials(tutorial)
tutorials Open the Tutorial in the help browser "tutorial" can optionally be used to specify a particular
tutorial to start with. Currently valid values are "perl", "python", "php", "xslt", and null (to go to
Tutorial home page).
Arguments
tutorial - String
name of tutorial to open
ko.inputBuffer
Input buffering When you need to capture user input while a slow XUL window is loading you can
use the input buffer. Usage: - in some JS code: ko.inputBuffer.start() // open XUL window - in slow
XUL window onload handler: var contents = ko.inputBuffer.finish(); // use the contents somehow
Functions
155
Komodo User Guide
Variables
id - String
Functions
finish()
Returns - contents
focus(event)
Arguments
event - Event
start()
ko.interpolate
Utility methods to easily use the KoIInterpolationService from JavaScript. Basically you can use the
ko.interpolate.interpolate() method to iterpolation special '%'-escape codes in a given list of strings.
See koInterpolationService.py (or play around with "run commands") for an authoritative description
of available escape codes. How to interpolate a couple of strings (mystringa, mystringb). You can
do as many strings as you want. var imystringa = null; var imystringb = null; try { var istrings =
ko.interpolate.interpolate( <ref-to-komodo.xul>, [mystringa, mystringb], // codes are not bracketed
[mystringc, mystringd], // codes are bracketed <optional-query-title>); imystringaForUse = istrings[0];
imystringaForDisplay = istrings[1]; imystringbForUse = istrings[2]; imystringbForDisplay = istrings[3];
imystringcForUse = istrings[4]; imystringcForDisplay = istrings[5]; imystringdForUse = istrings[6];
imystringcForDisplay = istrings[7]; } catch (ex) { var errno = lastErrorSvc.getLastErrorCode(); if
(errno == Components.results.NS_ERROR_ABORT) { // Command was cancelled. } else if (errno
== Components.results.NS_ERROR_INVALID_ARG) { var errmsg =
lastErrorSvc.getLastErrorMessage(); alert("Could not interpolate:" + errmsg); } else { log.error(ex);
alert("There was an unexpected error: " + ex); } }
Functions
activeProjectPath()
Returns - projectFile
currentFilePath()
Returns - String
currentFileProjectPath()
Returns - projectFile
getBlockOffsets(s, bracketed)
Variables
156
Komodo User Guide
Return a list of start and end offsets of interpolation code blocks into the given strings "s".
Returns - offsets
getViewData(editor, viewData)
A utility function to retrieving specific view data required by Interpolate_interpolate(). "editor" is a
reference to the komodo.xul window. "viewData" (optional) is a object possibly containing overriding
values for some of the view data.
Returns - viewData
getWordUnderCursor(scimoz)
Returns - scimoz.getTextRange()
interpolate(editor, strings, bracketedStrings, queryTitle, viewData)
Interpolate '%'-escape codes in the given list(s) of strings. "editor" is a reference the komodo.xul
window. "strings" is a list of raw strings to interpolate. "bracketedStrings" is a list of raw strings to
interpolate, using the bracketed form "queryTitle" (optional) is a title for the possible query dialog
raised during interpolation. "viewData" (optional) allows one to override specific view data used for
interpolation. By default view data is retrieved from the current view. This may not always be
appropriate. It may be an object with one or more of the following attributes: "fileName" is the
filename of the current file (null, if N/A); "lineNum" is the current line number (0, if N/A); "word" is the
current word under cursor (null if none); "selection" is the current selection (null if none). On
success, this function returns a *double* list of interpolated strings: For each string in "strings" and
"bracketedStrings" two strings are returned. The first is the interpolated string for use and the
second for *display*. In most cases these are the same but they may differ, for example, if a
password query response was interpolated into the string which should not be displayed in the
Komodo UI. Otherwise an exception is raised and an error set on the last error service: koILastError
errno reason ----------------------- ----------------------------------------- NS_ERROR_ABORT User cancelled
the query dialog. NS_ERROR_INVALID_ARG A normal interpolation failure because of invalid
interp code usage.
Returns - istrings
isWordCharacter(ch)
ko.isearch
Variables
controller - ISController
ko.isearch.controller
Functions
157
Komodo User Guide
Variables
inRepeatCounterAccumulation - Boolean
repeatCounter - Number
ko.keybindings
Variables
keylabel2keysequence - keylabel2keysequence
keysequence2keylabel - keysequence2keylabel
Functions
onload()
Classes
class manager
Constructor
manager()
Class variables
_commandParams - Object
_configDirty - Boolean
_configKeyTree - cloneObject()
_configUnsaved - Boolean
_keyPressCaptureWindow - window
_knownconfigs - Array
activeCommands - Object
command2key - Object
commanditems - Array
Variables
158
Komodo User Guide
commandnames - Array
constructor
currentConfiguration - gPrefSvc.prefs.getStringPref()
currentPrefixMap - this.keyTree
currentPrefixString - String
currentScheme - this.keybindingSchemeService.getScheme()
data - lines.join()
document - document
inPrefixCapture - Boolean
key2command - Object
keybindingSchemeService
keyDownLabels
keynames - Array
keyTree - Object
lastcategory - String
prefset - gPrefSvc.prefs
rownum - Number
Class functions
_addRow(category, desc, keys)
Returns - String
_clearActiveBindings()
_configKnown(newconfigname)
Returns - Boolean
_getKeyTreeRoot(keysequence)
Returns - root
Class variables
159
Komodo User Guide
_saveKnownConfigs()
_usedbys(root, remainingsequence, sofarsequence, usedbys)
applyCurrentConfiguration()
assignKey(commandId, keysequence, parameter)
cancelPrefix(why)
clearBinding(commandId, commandParam, restore)
clearBindings()
clearSequence(commandId, keylabel, restore)
clearUsedBys(commandId, keysequence)
command2keylabel(commandId)
Returns - keysequence2keylabel()
command2keysequences(commandId, commandParam)
Returns - seqs
commandId2desc(commandname, param, label)
Returns - commanddesc
commandId2parameter(commandname, label)
Returns - String
commandId2shortdesc(commandname, param)
Returns - commanddesc
commandId2tabledesc(commandname, param)
Returns - commanddesc
configurationWriteable(configname)
Returns - scheme.writeable
deleteConfiguration(configname, prefset)
evalCommand(event, commandname, keylabel)
Arguments
event - Event
Returns - Boolean
Class functions
160
Komodo User Guide
event2keylabel(event, useShift)
Arguments
event - Event
Returns - data.join()
eventBindings(event)
Arguments
event - Event
Returns - possible
getConfigurations()
Returns - this._knownconfigs
getKey(keyname)
keypressHandler(event)
Arguments
event - Event
learnParameter(commandId, parameter, keylabel)
loadConfiguration(configName, forceReload)
makeCommandIdTable()
Returns - String
makeCurrentKeyBindingTable()
Returns - String
makeDirty()
makeKeyActive(commandId, keysequence)
makeNewConfiguration(newconfigname, prefset)
Returns - newconfigname
mergeSchemeConfiguration(configName, forceReload)
observe(part, topic, partId)
offerToSave()
Class functions
161
Komodo User Guide
parseConfiguration(data, forceReload, ignoreCommandPrefix)
Parse the keybinding configuration file data into commands. Acitivate the keybinding commands.
parseGlobalData()
removeCommandsWithPrefix(prefix)
revertToPref(configname)
saveAndApply(prefset)
saveCurrentConfiguration()
setKeyBinding(keysequence, commandId, commandKey)
Returns - key
startPrefixCapture()
stashIn(vessel, keylabel)
switchConfiguration(newconfigname)
Returns - Boolean
unsetKey(keylabel)
unsetKeyBinding(commandId)
usedBy(sequence)
Returns - usedbys
walk_and_apply(root, keysequence)
ko.launch
Functions
checkForUpdates()
Opens the update manager and checks for updates to the application. From
http://plow/source/xref/mozilla/1.8/browser/base/content/utilityOverlay.js#452
diff(diff, title, message)
diff open the diff dialog, you must provide the diff
ko.launch
162
Komodo User Guide
Arguments
diff - String
title - String
message - String
Returns - window.openDialog()
find(searchTerm)
Open the Find dialog.
Arguments
searchTerm - String
findInFiles(searchTerm, folders)
Open Find in Files dialog.
Arguments
searchTerm - String
folders - String
httpInspector()
httpInspector open the HTTPInspector window
Returns - ko.windowManager.openOrFocusDialog()
openAddonsMgr()
openAddonsMgr open the extension/add ons manager window
Returns - ko.windowManager.openOrFocusDialog()
replace()
Open the Find & Replace dialog. TODO: add searchTerm/replacement arguments.
runCommand()
runCommand open the run command dialog
Returns - window.openDialog()
Functions
163
Komodo User Guide
rxToolkit(mode, regex, replacement, searchText, matchCase, isModal)
Open the rx toolkit.
Arguments
mode - String
One of "match", "match-all", "split", "replace", "replace-all" or null for the default (match-all).
regex - String
The regular expression pattern, or null for the default (the last regex).
replacement - String
searchText - String
matchCase - Boolean
Whether to set the "I" match option.
isModal - Boolean
Whether to open the Rx dialog modally (default is false.
Returns - args
watchLocalFile()
watchLocalFile prompt for a file to watch, then open a new watch window
ko.lint
Functions
clearResults()
doClick(event)
Arguments
event - Event
doRequest()
finalize()
initialize()
ko.lint
164
Komodo User Guide
jumpToNextLintResult()
Classes
class lintBuffer
Constructor
lintBuffer(view)
Class variables
_lastRequestId - Number
_lintTimer - objectTimer
constructor
errorString - request.errorString
lintingEnabled - this.view.prefs.getBooleanPref()
lintResults - request.results
view - view
Class functions
_cancelDelayedRequest()
_clearResults()
_createLintRequest(linterType)
_getLinterCID()
_issueRequest()
_notify()
destructor()
observe(subject, topic, data)
QueryInterface(iid)
Returns - this
Functions
165
Komodo User Guide
reportResults(request)
request(reason)
ko.logging
Variables
LOG_CRITICAL - Number
LOG_DEBUG - Number
LOG_ERROR - Number
LOG_INFO - Number
LOG_NOTSET - Number
LOG_WARN - Number
loggingSvc - Components.interfaces.koILoggingService
Functions
dumpDOM(node, level, recursive)
dumpEvent(event)
Arguments
event - Event
dumpObject(o, name)
dumpObjectTree(o, recurse, compress, level)
dumpView(view)
getLogger(logger_name)
Returns - this.getLoggingMgr().getLogger()
getLoggingMgr()
Returns - _gLoggingMgr
getObjectTree(o, recurse, compress, level)
Returns - s
Class functions
166
Komodo User Guide
getStack()
Returns - str
LoggingMgr()
strObject(o, name)
Returns - s
Classes
class Logger
Constructor
Logger(logger, logger_name)
Class variables
_logger - logger
_logger_name - logger_name
constructor
Class functions
critical(message)
debug(message)
error(message)
exception(e, message)
getEffectiveLevel()
Returns - this._logger.getEffectiveLevel()
info(message)
setLevel(level)
warn(message)
Functions
167
Komodo User Guide
ko.logging.LoggerMap
ko.macros
Variables
eventHandler - MacroEventHandler
recorder - MacroRecorder
Functions
evalAsJavaScript(__code, part)
Returns - Boolean
recordPartInvocation(part)
ko.macros.recorder
Variables
mode - String
ko.main
Functions
addCanQuitHandler(handler, object)
addCanQuitHandler observer for watching the quit-application-requested notification, and easily
handling a response to it.
addUnloadHandler(handler, object)
addUnloadHandler Register a routine to be called on Komodo shutdown. To register a simple
routine do this: ko.main.addUnloadHandler(<routine>) To register an object method do this:
ko.main.addUnloadHandler(this.<method>, this);
addWillQuitHandler(handler, object)
addWillQuitHandler simple observer for watching the quit-application-granted notification
ko.logging.LoggerMap
168
Komodo User Guide
ko.main.window
Functions
onunload()
ko.markers
Variables
MARKERS_MASK_SYMBOLS - Number
MARKNUM_BOOKMARK - Number
MARKNUM_BREAKPOINT_DISABLED - Number
MARKNUM_BREAKPOINT_ENABLED - Number
MARKNUM_CURRENT_LINE_BACKGROUND - Number
MARKNUM_DEBUG_CURRENT_LINE - Number
MARKNUM_INTERACTIVE_PROMPT - Number
MARKNUM_INTERACTIVE_PROMPT_MORE - Number
MARKNUM_SPAWNPOINT_DISABLED - Number
MARKNUM_SPAWNPOINT_ENABLED - Number
MARKNUM_STDERR - Number
MARKNUM_STDIN_PROMPT - Number
MARKNUM_STDOUT - Number
MARKNUM_TRANSIENTMARK - Number
Functions
getPixmap(uri, force)
Read a file from disk, cache and return the contents.
Arguments
uri - String
ko.main.window
169
Komodo User Guide
file uri
force - Boolean
force read from file Note: The file contents are cached by URI. This is used to load pixmaps for
scintilla markers.
Returns - content_cache[uri]
setup(scimoz)
Setup the standard Komodo markers in the given SciMoz instance and return an appropriate mask
for ISciMoz.setMarginMaskN(<n>, <mask>).
Arguments
scimoz - iSciMoz
scimoz plugin instsance
Returns - ko.markers.MARKERS_MASK_SYMBOLS
ko.mozhacks
Functions
pluginContextMenu()
pluginContextMenu Verified still necessary with moz 1.8 branch - SMC For some reason popups
over the plugin are messed up until the first context menu over mozilla is activated. It is apparently
due to popupNode not being initialized, so we do that here. See:
http://www.xulplanet.com/references/elemref/ref_popup.html
ko.mru
Functions
add(prefName, entry, caseSensitive)
addFromACTextbox(widget)
addURL(prefName, url)
del(prefName, index)
finalize()
get(prefName, index)
Functions
170
Komodo User Guide
Returns - retval
getAll(prefName, maxLength)
Returns - retval
initialize()
maxEntries(listPrefName)
Returns - maxEntries
reset(prefName)
ko.open
The open namespace contains functionality to open buffers in komodo
Functions
displayPath(displayPath, viewType)
Open the given path in Komodo.
Arguments
displayPath - String
identifies the path to open. Display path may be the display path of an already open (and possibly
untitled) document.
viewType - String
optional default "editor", the type of view to create for the openned path. It is ignored if the
displayPath indicates an already open view.
filePicker(viewType)
open a file picker, and open the files that the user selects
multipleURIs(urls, viewType)
startPage()
Open Komodo's Start Page
templatePicker(viewType)
open a file picker, and open the templates that the user selects. This allows editing the templates, it
is not for creating new files from templates.
Functions
171
Komodo User Guide
URI(uri, viewType, skipRecentOpenFeature)
function for opening buffers in Komodo tabs
Arguments
uri - String
the path or URI to open
viewType - String
optional default "editor" type of view component to use. Values can be [ "editor", "browser", "diff" ].
skipRecentOpenFeature - Boolean
optional default false, can be used when the URI to open is a project file to specify that the feature
to open files in that project should not be offered.
Returns - DOMElement xul:view
ko.printing
Functions
browserPrint()
browserPrintPreview()
browserPrintPreviewEnter()
browserPrintPreviewExit()
print(view, preview, tofile, selectionOnly)
Returns - Boolean
printPreview(view, preview, tofile, selectionOnly)
ko.projects
Variables
active - ko.toolboxes.user.viewMgr
BaseManager - BaseManager
extensionManager - projectExtensionManager
Functions
172
Komodo User Guide
manager
manager - projectManager
managers - Array
Functions
addCommand(item)
addDirectoryShortcut(dirname, parent)
addFile(parent_item)
Returns - Boolean
addFileWithURL(url, parent)
addFolder(name, parent)
addItem(item, parent)
addLiveFolder(dirname, parent)
addMacro(parent)
addMenu(parent)
addMenuFromPart(part)
addNewFileFromTemplate(parent)
Returns - gViewMgr.newTemplate()
addNewPart(type, partviewerId)
addRemoteFile(item)
Returns - Boolean
addSnippet(parent)
addSnippetFromText(snippettext, parent)
Returns - snippet
addTemplate(parent)
addToolbar(parent)
Variables
173
Komodo User Guide
addToolbarFromPart(part)
addURL(parent)
addURLFromText(URLtext, parent)
commandProperties(item)
editSCCFile(item)
Returns - lastErrorSvc.getLastErrorMessage()
ensureAddMenu(popup)
executeMacro(part)
Returns - Boolean
executeMacroById(id, asynchronous)
Returns - Boolean
exportItems(items)
exportPackageItems(items)
fileProperties(item, view, folder)
Returns - Boolean
findItemsByURL(url)
Returns - items
findPartById(id)
Given a ID, look in the projects and toolboxes until you find the first part with that id (the id allocation
scheme guarantees there will be at most one) and return it. Return null on failure to find such a part.
Returns - gPartSvc.getPartById()
findPartsByURL(url)
Returns - parts
getDefaultDirectory(parent)
getFocusedProjectView()
does the active view have real focus, if so, return it, otherwise null.
getManagerForItem(item)
Returns - ko.projects.active.manager
Functions
174
Komodo User Guide
hasURL(url)
Returns - Boolean
importFromFileSystem(part, baseURL)
Returns - Boolean
importFromPackage(part, filename)
invalidateItem(item)
invokePart(part)
Given a koIPart, invoke it (do it's "double-click" action) through whatever code path is appropriate
for that part -- i.e. snippets get inserted, commands get run, etc.
invokePartById(id)
Given the ID of a part, find it and invoke it.
isToolbarRememberedAsHidden(id)
Returns - Boolean
macroProperties(item)
menuProperties(item, rank)
onload()
open(url, skipRecentOpenFeature)
openDirectoryShortcut(part)
partAcceptsMenuToolbar(part)
Returns - Boolean
refreshStatus(items)
registerExtension(ext)
reimportFromFileSystem(part)
Returns - Boolean
removeImportedVirtualFilesAndFolders(part)
Recursively removes virtual files and folders, but does not remove any folders that have been
added manually or parts that are not files or folders (i.e. snippets, macros, etc...). This function will
also remove any manually added files, that were not added as part of the import process, because
there is not way to tell manually added files and imported files apart.
Functions
175
Komodo User Guide
removeItemsByURL(url, skipDialog)
Returns - items
removeItemsByURLList(urls, skipDialog)
removeToolbarForPart(part)
runCommand(cmdPart)
saveProjectAs(project)
Returns - Boolean
snippetInsert(snippet)
snippetProperties(item)
toggleToolbarHiddenStateInPref(id)
updateToolbarForPart(part)
URLProperties(item)
ko.run
Functions
buildRecentCommandsMenu(popupWidget)
canClose()
Prepare to close Komodo. Return false if cannot yet close Komodo. If there are processes still
running then must wait for or kill them.
Returns - Boolean
registerProcess(command, process)
Keep a list of processes spawned by the RunCommand system. This is necessary to ensure that
there are no hangs when Komodo closes because some process is still running. Before closing
Komodo all process must be terminated.
runCommand(editor, command, cwd, env, insertOutput, operateOnSelection,
doNotOpenOutputWindow, runIn, parseOutput, parseRegex, showParsedOutputList, name,
clearOutputWindow, terminationCallback, saveInMRU, saveInMacro, viewData)
Run the given command.
ko.run
176
Komodo User Guide
Returns - Boolean
runEncodedCommand(editor, encodedCommand, terminationCallback)
Run an "encoded" command. An encoded command is a string that describes the command and
possibly a number of optional arguments. The encoding is defined by koIRunService.Decode().
Returns - Boolean
unregisterZombieProcess()
Remove any processes that have terminated from the list.
ko.run.output
The interface for using the run output window (where run command output goes to, in the bottom
pane of the Komodo workspace). Expected usage: - Someone calls ko.run.output.initialize() at
startup and ko.run.output.finalize() at shutdown. - When a command is to be run in the output
window do this: * announce intention to start session ko.run.output.startSession(...); *... setup and
start running the actual command calling * ko.run.output.getTerminal() and ko.run.output.show() as
needed ko.run.output.setProcessHandle(p); * to allow user to kill process *... setup
ko.run.output.endSession() to be run when the process * terminates.
Functions
endSession(retval)
Complete a terminal session. The command exited with the given value.
finalize()
getTerminal()
Returns - _gTerminalHandler
initialize()
kill(retval)
Kill the process currently running in the output window's terminal, if any.
scintillaOnClick(event)
Arguments
event - Event
setProcessHandle(process)
Pass a koIRunProcess reference to the output window so it can manipulate the process that is
being run in its terminal, if necessary.
Functions
177
Komodo User Guide
show(editor, showParsedOutputList)
Show the command output window. "editor" is the XUL window holding the command output
window. "showParseOutputList" is a boolean indicating whether to show the tree parsed output list.
startSession(command, parseOutput, parseRegex, cwd, filename, clearContent)
Start a terminal session in the output window with the given command. This raises an exception if
the run output window is currently busy. "command" is the command being run (note that this is the
command string *for display* which might be slight different -- passwords obscured -- than the
actual command) "parseOutput" is a boolean indicating whether to parse output lines "parseRegex"
is the regular expression to use to parse output lines "cwd" is the directory in which the command is
being run (note: ditto *for display* subtlety withh "command") "filename" is the current editor
filename (if any) "clearContent" is a boolean indicating whether to clear the output window content
(by default "true", i.e. the window _is_ cleared).
toggleView()
treeOnClick(event)
Arguments
event - Event
treeOnKeyPress(event)
Arguments
event - Event
Returns - Boolean
ko.scc
Functions
warnSSHConfiguration()
ko.scc.logger
Functions
append(text)
clear()
init()
reportResults(actiondescription, actiontext)
Functions
178
Komodo User Guide
show()
ko.statusBar
Functions
AddMessage(msg, category, timeout, highlight, interactive)
AddMessage Post a message to the status bar message area. "msg" is the message string. An
empty string or null indicates that the message (of the given category) should be cleared. "category"
is the message group to which the message belongs. It is an arbitrary string (it must be at least one
character). "timeout" is the amount of time, in milliseconds, that the message should appear. A
value of 0 indicates that the message does not timeout. "highlight" is a boolean indicating whether
the message should be highlighted on the status bar. "interactive" is a boolean indicating whether
the message corresponds to an interactive prompt (such as interactive search). These have higher
'priority' over non-interactive messages in case of conflict. A structure similar to a stack of status
messages is maintained. The latest message is always shown. When/if it timesout then the previous
message is the stack is displayed. There can only be one message per category, so reusing a
category allows for removal of status messages that are no longer appropriate. To add a message
that does not timeout: ko.statusBar.addMessage("hello there", "my_category", 0, false) To remove
that message: ko.statusBar.addMessage(null, "my_category", 0, false) To add a highlighted
message for three seconds: ko.statusBar.addMessage("hello there", "my_category", 3000, true)
Clear()
Clear clear all statusbar elements
ClearCheck()
ClearCheck clear the syntax checking status
dump()
dump dump the current message stack to stdout
ko.stringutils
Functions
bytelength(s)
Returns - _sysUtils.byteLength()
charIndexFromPosition(s, p)
Returns - _sysUtils.charIndexFromPosition()
escapeWhitespace(text)
Functions
179
Komodo User Guide
Returns - String
getSubAttr(value, subattrname)
unescapeWhitespace(text, eol)
Returns - newtext
updateSubAttr(oldValue, subattrname, subattrvalue)
Returns - newValue
ko.toolboxes
Variables
shared
user
user - toolboxManager
Functions
addCommand(command, cwd, env, insertOutput, operateOnSelection, doNotOpenOutputWindow,
runIn, parseOutput, parseRegex, showParsedOutputList, name)
importPackage(filename)
onload()
updateSharedToolbox()
In a discussion btwn DavidA and TrentM it was decided that the shared toolbox behaviour should be
the following (in light of the possibility that the current Komodo user might not have permissions to
write to the shared toolbox location): - If the useSharedToolbox pref is false, then shared toolbox
support is off. - Else if the shared toolbox file exists then shared toolbox support is on. - Else if the
user DOES have access to write to the shared toolbox file location then a blank one is created (as
for the normal Toolbox) and shared toolbox support is on. - Else (useSharedToolbox is true, the
shared toolbox file does not exist and the user does NOT have write access) shared toolbox support
is turned off. Update the shared toolbox state (i.e. enable or disable it).
ko.toolboxes.shared
ko.toolboxes.shared.viewMgr
Functions
180
Komodo User Guide
ko.trace
Functions
get()
Returns - _tracer
Classes
class Trace
Constructor
Trace()
Class variables
constructor
myPerfTimer - Object
perfLog - Number
timelineService - Components.interfaces.nsITimelineService
Class functions
_repeatStr(str, aCount)
Returns - res
enter(text)
indent(text)
leave(text)
mark(text)
markTimer(name, text)
outdent(text)
perfTimer(name, title, reset)
resetTimer(name)
ko.trace
181
Komodo User Guide
startTimer(name)
stopTimer(name)
timestamp(name, title)
ko.uilayout
Functions
buildViewAsLanguageMenu()
ensureOutputPaneShown()
ensurePaneForTabHidden(tabName)
ensurePaneShown(tabs)
ensureTabShown(tabId, focusToo)
focusPane(tabsId)
fullScreen()
isButtonTextShowing()
Returns - _buttonTextShowing
isCodeBrowserTabShown()
Returns - Boolean
isPaneShown(tabs)
Returns - Boolean
leftPaneShown()
newFileFromTemplateOrTrimMRU(templateURI, mruPrefName, mruIndex)
Returns - gViewMgr.doFileNewFromTemplate()
onFullScreen()
onload()
onloadDelayed()
outputPaneShown()
Class functions
182
Komodo User Guide
populatePreviewToolbarButton(popup)
restoreTabSelections()
rightPaneShown()
saveTabSelections()
toggleButtons()
togglePane(splitterId, tabsId, cmdId, force)
toggleSplitter(aCommandID)
toggleTab(tabId, collapseIfFocused)
toggleToolbarVisibility(toolbarId)
unload()
updateFullScreen()
updateMRUMenuIfNecessary(mru)
updateSplitterBroadcasterState(aCommandID)
updateTabpickerMenu(menupopup)
updateTitlebar(view)
updateToolbarArrangement(buttonTextShowing)
updateViewAsMenuIfNecessary()
updateWindowList(popup)
ko.uriparse
ko.uriparse Functions to convert/parse strings representing URLs, files, etc. This is basically a loose
shim around class URIParser in URIlib.py (somewhat obtusely via koIFileEx). Routines:
ko.uriparse.localPathToURI(<localPath>) ko.uriparse.pathToURI(<URI or localPath>)
ko.uriparse.URIToLocalPath(<URI or localPath>) ko.uriparse.displayPath(<localPath or URI>)
ko.uriparse.baseName(<localPath or URI>) ko.uriparse.dirName(<localPath or URI>)
ko.uriparse.ext(<localPath or URI>) ko.uriparse.fixupURI(<URI>) Dev Notes: - This module caches
a single koIFileEx instance to, presumably, speed things up.
Functions
183
Komodo User Guide
Functions
addMappedURI(uri)
Returns - Boolean
baseName(file)
baseName Get the basename (a.k.a. leafName) of the given file. "file" can be a local filename or
URI. Examples: file:///D:/trentm/foo.txt -> foo.txt D:\trentm\foo.txt -> foo.txt
ftp://ftp.activestate.com/ActivePython -> ActivePython
Returns - koFileEx.baseName
dirName(file)
dirName Get the dirname of the given file. "file" can be a local filename or URI referring to a local
file. Examples: file:///D:/trentm/foo.txt -> D:\trentm D:\trentm\foo.txt -> D:\trentm
ftp://ftp.activestate.com/ActivePython -> throws exception
Returns - koFileEx.dirName
displayPath(uri)
displayPath Get an appropriate representation of the given URI for display to the user. "uri",
typically, is a URI, though it can be a local filename as well. Examples: file:///D:/trentm/foo.txt ->
D:\trentm\foo.txt D:\trentm\foo.txt -> D:\trentm\foo.txt ftp://ftp.activestate.com/ActivePython ->
ftp://ftp.activestate.com/ActivePython
Returns - koFileEx.displayPath
ext(file)
ext Get the extension of the given file. "file" can be a local filename or URI
Returns - koFileEx.ext
fixupURI(uri)
fixupURI Fix the URI using Mozilla's URI fixup service. Known fixes: - quotes spaces in the URI
file:///spam and eggs.txt -> file:///spam%20and%20eggs.txt - adds two leading slashes to file URI
with only one file:/foo/bar.txt -> file:///foo/bar.txt NOTE!!! nsIURIFixup will escape wide strings
incorrectly if it does not understand the uri scheme. This was discovered for instance, with koremote
uri's. We currently only fixup file:// uri's, but may also need to fixup http:// uri's at some point.
Returns - uri
getMappedPath(path, prefs)
Returns - mappeduri
Functions
184
Komodo User Guide
getMappedURI(uri, prefs)
Returns - ko.uriparse.pathToURI()
localPathToURI(localPath)
localPathToURI Get the URI representation of the given local file path. "localPath" must be a local
file path. Returns the URI for the given path or raises an exception if "localPath" is not a local path.
Examples: D:\trentm\foo.txt -> file:///D:/trentm/foo.txt \\planer\d\trentm\tmp\foo.txt ->
file://planer/d/trentm/tmp/foo.txt file:///D:/trentm/foo.txt -> throws exception
ftp://ftp.activestate.com/ActivePython -> throws exception
Returns - koFileEx.URI
pathToURI(path)
pathToURI Get the URI representation of the given local file path or URI "path" must be a local file
path or a URI Returns the URI for the given path or the URI if one was passed in. Examples:
D:\trentm\foo.txt -> file:///D:/trentm/foo.txt file:///D:/trentm/foo.txt -> file:///D:/trentm/foo.txt
ftp://ftp.activestate.com/ActivePython -> ftp://ftp.activestate.com/ActivePython
Returns - koFileEx.URI
URIToLocalPath(uri)
URIToLocalPath Get the local file path for the given URI. "uri" may be a URI for a local file or a local
path. Returns the local file path or raises an exception if there is no local file representation for that
URI. Note: I would rather this explicitly raised if "uri" were a local path, but koIFileEx does not work
that way. Examples: D:\trentm\foo.txt -> D:\trentm\foo.txt file:///D:/trentm/foo.txt -> D:\trentm\foo.txt
ftp://ftp.activestate.com/ActivePython -> throws exception
Returns - koFileEx.path
ko.views
Variables
viewManager - viewManager
Functions
onload()
ScimozOffsetFromUCS2Offset(scimoz, pos, delta)
Returns - pos
ko.views
185
Komodo User Guide
Classes
class ViewHistory
view history controller Recently-visited views: The viewhistory object maintains a stack of recently
visited lists. This information can be used to switch to recent views. The semantics of the following
methods are as follows: - .getNextMostRecentView() and .getNextLeastRecentView() are used by
the buffer switching commands to know which views to switch to. - .enterBufferSwitchingSession()
and .exitBufferSwitchingSession() are called by the buffer swiching commands to help
.setMostRecentView() know how to behave (the "recent views" stack is NOT updated during such a
session). Note that .enter...() may be called multiple times for one .exit...() call. .setMostRecentView() is called by the view manager's .selectView() and can be called directly by
the buffer switching commands for proper session handling. NOTE: THIS BEHAVIOR IS TURNED
OFF BY SETTING "handlestctrltab" to false on the tabbed view.
Constructor
ViewHistory()
Class variables
_currentView - subject
_keylistener
_observingCtrlKeyUp - Boolean
_recentViews - Array
_timeout - objectTimer
constructor
inBufferSwitchingSession - Boolean
log - ko.logging.getLogger()
Class functions
_debug_recentViews()
_keylistener(event)
Arguments
event - Event
_setKeyListener()
Classes
186
Komodo User Guide
ctrlup(event)
Arguments
event - Event
doNextLeastRecentView()
doNextMostRecentView()
enterBufferSwitchingSession()
exitBufferSwitchingSession()
getNextLeastRecentView()
Returns - view
getNextMostRecentView()
Returns - view
getState()
Returns - state
observe(subject, topic, data)
removeRecentView(view)
setMostRecentView(view)
setState(state, viewcontainer)
ko.views.manager
ko.views.manager.currentView
Variables
anchor - anchor
currentPos - currentPos
ko.widgets
Class functions
187
Komodo User Guide
Functions
getEncodingPopup(hierarchy, toplevel, action)
Returns - menuitem
ko.window
Functions
checkDiskFiles(event)
view_checkDiskFiles is only called from the window's focus handler, located in komodo.xul. it
handles checking if any files have changed.
Arguments
event - Event
Returns - Boolean
focusedScintilla()
does scintilla have focus? Return the scintilla widget
Returns - Element
focusedView()
does any view widget have focus? return which one does or null
Returns - Element
getCwd()
get the current working directory for the window, which is the directory of the current buffer, or the
home directory of the user
Returns - String
ko.windowManager
Functions
closeAll()
close all open windows, return true if successful. The normal goQuitApplication function in toolkit
does this, but we want to prevent quitting if one of the dialogs prevents shutdown by not closing.
Functions
188
Komodo User Guide
Returns - Boolean
getMainWindow()
return a reference to the main Komodo window
Returns - wm.getMostRecentWindow()
openOrFocusDialog(chromeURI, windowType)
Open a window if no windows of windowType exist. Otherwise, bring the window of windowType to
the front. Parameters for this function are identical to window.openDialog()
Returns - window.openDialog.apply()
ko.workspace
Functions
restoreInProgress()
Returns - _restoreInProgress
restoreWorkspace()
restore all workspace preferences and state, open files and projects
saveWorkspace()
save all workspace preferences and state
Functions
189
Templates
Templates are files that contain the basic structure for new files or
projects. For example, a Perl template might contain the standard "#!"
line, appropriate copyright statements, and use statements calling a
standard set of modules.
Feature Showcase
• store a template
in a project
Komodo includes templates for a number of languages languages, and
lets you create and use your own. Templates can contain Interpolation
Shortcuts or Tab Stops. They can be stored in a project or in the Toolbox
for quick access, and shared via the Common Data Directory.
Creating New Files from Templates
The New File menu option, invoked via File|New|New File, or via the associated key binding,
provides access to numerous templates for creating new files. These templates consist of standard
code that is generally included in programs of the selected type. For example, the Perl template
creates a file with a ".pl" extension that contains the line "use strict;"; the XSLT stylesheet
template creates a file with an ".xsl" extension and an xml version and xsl stylesheet declaration.
To create a new file from a template file, in the New File dialog box, select the category in the Left
Pane, then double-click the template name in the Right Pane. A new file is created in the Komodo
editor using the code stored in the template.
When using the New File button on the Standard Toolbar, the template (if any) associated with the
language in the new files preferences is used to create the new file.
Alternatively, templates can be stored in a project or the Toolbox, and can be associated with a key
binding.
Creating Custom Templates
Custom templates are created in the Komodo editor; on saving the file, it is identified as a template.
1. Create Template File: In Komodo, create a file with the desired contents for the template.
2. Save as Template: Select File|Save As Template.
Custom templates are stored in the "My Templates" folder (as displayed in the Save File dialog
box). Due to a Komodo bug (41829), OS X users must navigate manually to:
<User-home-directory>/Library/Application Support/Komodo/3.x/templates/My Templates
Optionally, create shortcuts (on Windows), aliases (Mac OS X) or symlinks (on Linux or Mac OS X)
in the "My Templates" directory structure that point to files located elsewhere on the system. Files
should have an extension that allows Komodo to correctly detect the language (according to the
settings configured in Komodo's File Associations preference).
If you create a directory alongside My Templates with the same name as a template group that
already exists in Komodo (such as Common or Web), the contents of the two directories are merged.
If files of the same name exist in both directories, the file in the directory at the same level as My
Templates
190
Komodo User Guide
Templates is used.
For example:
templates\
My Templates\
<--directory
MyCGI.pl
<--file in the My Templates directory
TestSystem.tcl
<--file in the My Templates directory
Corporate
<--shortcut/symlink to corporate templates
Common\
<--directory
Python.py
<--file; takes precedence over the Python.py template
MyCGI.pl
<--file; displays in the Common folder
To edit an existing template, select File|Open|Template File. The directory containing the My
Templates directory (and any "merge" directories, as described above) is displayed. Select the
desired template and make the desired changes.
Using Interpolation Shortcuts in Custom Templates
Interpolation shortcuts can be used in templates. When a new file is generated from a template file
containing interpolation shortcuts, the shortcut is converted to its relevant value.
For example, if a template file contains the interpolation shortcut [[%date:%d/%m/%Y
%H:%M:%S]], when a new file is created from that template, the interpolation shortcut is converted
to the current date and time in the following format: 27/06/2004 11:10:21.
Interpolation shortcuts within templates use the bracketed syntax. Refer to the interpolation
shortcut section for a complete description of the code, syntax and usage.
Project Templates
Just as template files contain the basic structure for new files, project templates provide a basic
framework for new projects.
To create a new project from a project template, click File|New|New Project from Template and
choose from one of the available templates.
To save any project as a template select the project and click Project|Create Template From
Project..., or right-click on the project and click Create Template From Project.... in the
context-menu. The project will be exported as a project package and saved in the
project-templates/My Templates sub-directory of the user data directory. Once the project has been
saved as a template, it becomes available via File|New|New Project from Template.
Komodo ships with project templates for, Ruby on Rails, Komodo Extensions, and Firefox
Extensions.
Storing Templates in a Project or the Toolbox
Use the Komodo Projects tab or the Toolbox to store frequently used templates. In addition to the
general methods described in Adding Components to Projects and Adding Components to the
Toolbox, templates can be added to the Toolbox via the New File dialog box. Select Add to
Creating Custom Templates
191
Komodo User Guide
Toolbox to add the selected template to the Toolbox.
Template Options
Right-click a template to access the following options:
• Open Template: Use this option to create a new file from the selected template.
• Cut/Copy/Paste: These options are used to remove the template from a project or the
Toolbox, or to move templates between the project and the Toolbox (and vice versa).
• Export as Project File: When this option is invoked, a new project file is created that
contains the template from which the option is invoked. You are prompted to provide the
name of the new project file and the directory where it will be stored. To open the new
project file, select File|Open|Project.
• Export Package: Templates can be archived and distributed among multiple Komodo users
via "packages". Packages are compressed archive files that contain the template from
which the Export Package option was invoked. Packages are stored in files with a ".kpz"
extension, and can be opened by any archiving utility that supports libz (for example
WinZip). The Export Package option differs from the Export as Project File option in that
copies of filesystem-based components (such as files and dialog projects) are included in
the archive. Conversely, Export as Project File creates a project with a reference to the
component's original location and does not create copies of the components. When Export
Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as
projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting
and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages,
or Folders - Import Contents from Package for more information.
• Rename: To change the name of a template (as displayed in the Projects tab or Toolbox),
select this option and enter a new name.
• Delete: To remove a template from a project or the Toolbox, select this option. The
reference to the template is deleted; the file containing the template is not deleted.
• Properties: Changes the title or the disk location of the template. In addition, the icon and
key binding assigned to the template are accessed via the Properties dialog box. See below
for instructions on altering the template's icon or key binding.
Assigning Custom Icons to Templates
The default template icon can be replaced with custom icons. Komodo includes more than 600
icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel
images for best results).
To assign a custom icon to a template:
1. On the Projects or Toolbox tab, right-click the desired template and select Properties.
Alternatively, click the template in the Projects or Toolbox tab, then select
Projects|template_name|Properties or Toolbox|template_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the Properties dialog box for the template, click OK. The custom icon is displayed next to
the template.
Storing Templates in a Project or the Toolbox
192
Komodo User Guide
To revert to the default icon for a selected template:
1. On the Projects or Toolbox tab, right-click the desired template and select Properties.
2. Click Reset, then click OK. The default icon is displayed next to the template.
Template Key Bindings
Custom key bindings can be assigned to templates stored in the Toolbox or in a Project. Use the
Key Binding tab in the template's Properties to specify the keystrokes that invoke the template.
See Key Bindings for Custom Components for more information.
Assigning Custom Icons to Templates
193
Open Shortcuts
Open shortcuts are references stored in projects or the Toolbox that point
to directories on a local or network drive. When an open shortcut is
invoked, the standard Open File dialog box is displayed with the contents
of the directory. Open shortcuts make it quick to access deep directories
that are frequently used.
Feature Showcase
• create a
directory
shortcut
Refer to Adding Components to Projects or Adding Components to the
Toolbox for instructions on adding components to projects or the Toolbox.
In addition, open shortcuts can be created by right-clicking a file in a
project or the Toolbox and selecting Make "Open..." Shortcut.
Open Shortcut Options
To access options for the selected open shortcut, do one of the following:
• Toolbox|shortcut_name|option or Project|shortcut_name|option: When an open
shortcut is selected in the Projects tab or Toolbox, use the Project or Toolbox drop-down
menus to access the list of options. The name of the open shortcut that is currently selected
in a project or the Toolbox is displayed on the drop-down menu.
• Context Menu: Right-click the open shortcut in a project or the Toolbox and select the
desired option.
The following options are available:
• Open (Shortcut): Use this option to display the contents of the folder specified in the open
shortcut.
• Cut/Copy/Paste: These options are used to remove components from a project or the
Toolbox, or to move components between the Projects tab and the Toolbox.
• Export as Project File: When this option is invoked, a new project file is created that
contains the open shortcut from which the option is invoked. You are prompted to provide
the name of the new project file and the directory where it will be stored. To open the new
project file, select File|Open|Project.
• Export Package: Open shortcuts can be archived and distributed among multiple Komodo
users via "packages". Packages are compressed archive files that contain the open shortcut
from which the Export Package option was invoked. Packages are stored in files with a
".kpz" extension, and can be opened by any archiving utility that supports libz (for
example WinZip). The Export Package option differs from the Export as Project File
option in that copies of filesystem-based components (such as files and dialog projects) are
included in the archive. Conversely, Export as Project File creates a project with a
reference to the component's original location and does not create copies of the
components. When Export Package is invoked, you are prompted for a name and file
location for the package. Exported packages can only be imported into "container" objects
in Komodo, such as projects, the Toolbox, and folders within projects and the Toolbox. See
Toolbox - Exporting and Importing Toolbox Contents, Importing and Exporting Projects via
Packages, or Folders - Import Contents from Package for more information.
• Rename: To change the name of an open shortcut, select this option and enter a new
name.
Open Shortcuts
194
Komodo User Guide
• Delete: To remove an open shortcut from a project or the Toolbox, select this option. The
open shortcut is permanently deleted.
Open Shortcut Properties
Open shortcut properties are used to alter the destination of the shortcut or to change the open
shortcut's name. The Properties dialog box is also used to assign a custom icon to an open
shortcut or to assign a custom key binding. To access the Properties dialog box, right-click the
open shortcut and select Properties.
Assigning Custom Icons to Open Shortcuts
The default open shortcut icon can be replaced with custom icons. Komodo includes more than 600
icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel
images for best results).
To assign a custom icon to an open shortcut:
1. On the Projects tab or Toolbox tab, right-click the desired open shortcut and select
Properties. Alternatively, click the open shortcut in the Projects tab or Toolbox tab, then
select Projects|shortcut_name|Properties or Toolbox|shortcut_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the Properties dialog box for the open shortcut, click OK. The custom icon is displayed
next to the open shortcut.
To revert to the default icon for a selected open shortcut:
1. On the Projects tab or Toolbox tab, right-click the desired open shortcut and select
Properties.
2. Click Reset, then click OK. The default icon is displayed next to the open shortcut.
Open Shortcut Key Bindings
Custom key bindings can be assigned to open shortcuts stored in the Toolbox or in a Project. Use
the Key Binding tab in the open shortcut's Properties to specify the keystrokes that invoke the
open shortcut. See Key Bindings for Custom Components for more information.
Open Shortcut Options
195
URL Shortcuts
URLs are components within a project or the Toolbox that are used to store frequently used URL
addresses. These URL shortcuts can be opened in an external browser (as specified in the Web
and Browser preference) or displayed in a new tab within Komodo.
Refer to Adding Components to Projects or Adding Components to the Toolbox for instructions on
adding components to projects or the Toolbox. In addition, URL shortcuts can be created by
dragging a URL from a browser address bar or from a Komodo tab onto a project or Toolbox. URLs
must be preceded by "http://".
To open a URL, double-click the URL name (which opens the URL in an external browser), use the
assigned key binding, or right-click the URL and select Open URL in browser or Open URL in
tab.
URL Shortcut Options
To access options for the selected URL shortcut, do one of the following:
• Toolbox|shortcut_name|option or Project|shortcut_name|option: When a URL shortcut
is selected in the Projects tab or Toolbox, use the Project or Toolbox drop-down menus to
access the list of options. The name of the URL shortcut that is currently selected in a
project or the Toolbox is displayed on the drop-down menu.
• Context Menu: Right-click the URL shortcut in a project or the Toolbox and select the
desired option.
The following options are available:
• Open URL in browser: Use this option to launch the default web browser (as specified in
the Web and Browser preference) and display the stored URL.
• Open URL in tab: Use this option to display the stored URL in a tab in the Komodo Editor
Pane.
• Cut/Copy/Paste: These options are used to remove the URL shortcut from a project or the
Toolbox, or to move URL shortcuts between the project and the Toolbox (and vice versa).
• Export as Project File: When this option is invoked, a new project file is created that
contains the URL shortcut from which the option is invoked. You are prompted to provide
the name of the new project file and the directory where it will be stored. To open the new
project file, select File|Open|Project.
• Export Package: URLs can be archived and distributed among multiple Komodo users via
"packages". Packages are compressed archive files that contain the URL shortcut from
which the Export Package option was invoked. Packages are stored in files with a ".kpz"
extension, and can be opened by any archiving utility that supports libz (for example
WinZip). The Export Package option differs from the Export as Project File option in that
copies of filesystem-based components (such as files and dialog projects) are included in
the archive. Conversely, Export as Project File creates a project with a reference to the
component's original location and does not create copies of the components. When Export
Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as
projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting
URL Shortcuts
196
Komodo User Guide
and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages,
or Folders - Import Contents from Package for more information.
• Rename: To change the name of a URL shortcut, select this option and enter a new name.
• Delete: To remove a URL shortcut from a project or the Toolbox, select this option. The
URL shortcut is permanently deleted.
URL Shortcut Properties
URL shortcut properties are used to alter the address of the URL or to change the URL shortcut's
name. The Properties dialog box is also used to assign a custom icon to a URL shortcut or to
assign a custom key binding. To access the Properties dialog box, right-click the URL shortcut and
select Properties.
Assigning Custom Icons to URL Shortcuts
The default URL shortcut icon can be replaced with custom icons. Komodo includes more than 600
icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel
images for best results).
To assign a custom icon to a URL shortcut:
1. On the Projects tab or Toolbox tab, right-click the desired URL shortcut and select
Properties. Alternatively, click the URL shortcut in the Projects tab or Toolbox tab, then
select Projects|macro_name|Properties or Toolbox|macro_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the Properties dialog box for the URL shortcut, click OK. The custom icon is displayed
next to the URL shortcut.
To revert to the default icon for a selected URL shortcut:
1. On the Projects tab or Toolbox tab, right-click the desired URL shortcut and select
Properties.
2. Click Reset, then click OK. The default icon is displayed next to the URL shortcut.
URL Shortcut Key Bindings
Custom key bindings can be assigned to URL shortcuts stored in the Toolbox or in a Project. Use
the Key Binding tab in the URL shortcut's Properties to specify the keystrokes that invoke the URL
shortcut. See Key Bindings for Custom Components for more information.
URL Shortcut Options
197
Run Commands
Run commands are operating system commands run from within
Komodo. Use the Run Command dialog box to interact with the system
command line or shell while editing or debugging files in Komodo.
Besides making it easy to run simple and complex custom commands
from within Komodo, the Run Command dialog box can insert the results
of shell commands into a document in the Editor Pane, or pass the
contents of a document to the system command line or shell.
To view examples of run commands, see the "Samples" folder in the
Toolbox.
Tutorial
• Run
Commands
Feature Showcase
• Google Run
Command
Run commands can be stored for re-use in a project or the Toolbox,
where they can be assigned key bindings.
Access the last ten commands executed in the Run Command dialog box
by selecting Tools|Recent Commands. The prefixes [i], [l] and [il]
indicate that Insert output, Pass selection as input or both were
selected with the original command.
Creating Run Commands
To create a run command, select Tools|Run Command. The Run Command dialog box is
displayed. Alternatively, invoke the Run Command dialog box from the Projects tab or the Toolbox
by selecting Add|New Command from the Project or Toolbox menu.
The Run Command dialog box can be toggled between its "simple" or "advanced" form by clicking
the More/Less button.
Simple Run Commands
This section describes the components of the Run Command dialog box that are displayed when
the advanced commands are hidden (via the More/Less button. See Advanced Run Commands
for information about the advanced fields.
• Run: Enter the command to run.
• Interpolation Shortcut: Click the arrow button to the right of the Run field to access a
drop-down list of interpolation shortcuts. When an interpolation shortcut is selected, it is
inserted at the current cursor position in the Run field. Windows users should enclose
shortcuts for files and directories in double quotes (e.g. "%F") to ensure that spaces in the
file name or file path are interpreted correctly.
• Pass selection as input: If this check box is selected, the text currently highlighted in the
editor is passed to the command in the Run field. For example, if the Run field contains
grep myvar, each line containing "myvar" in the text selected in the editor is returned.
• Insert output: If this check box is selected, the results of the command are inserted at the
cursor position in the current document.
• Add to Toolbox: If this check box is selected, the command is saved in the Toolbox.
Run Commands
198
Komodo User Guide
Advanced Run Commands
Click the More button in the Run Command dialog box to display advanced options. The following
options are available:
• Start in: Enter the directory where the command should be run, or click the Browse button
to navigate the filesystem. Click the arrow button to the right of the Start in field to select
interpolation shortcuts pertinent to the Start in setting. Interpolation shortcuts are inserted
at the current cursor position in the Run field.
• Run in: Specify the environment in which the command should be run. The options are:
♦ Command Output Tab: The command is run in Komodo's Bottom Pane.
♦ New Console: The command is run in a new shell or command window.
♦ No Console (GUI Application): The command launches the specified application
without displaying output in a shell or on the Command Output tab.
• Do not open output pane: If this check box is selected, the Bottom Pane containing the
Command Output tab does not automatically open when the command is run. To manually
view the Bottom Pane, select View|Command Output. (This option is only accessible if the
Run in field is set to Command Output tab.)
• Parse output with: If this check box is selected, the field to the right is used to enter a
regular expression that parses the output. See Parsing Command Output in the Run
Command Tutorial for an example. (This option is only accessible if the Run in field is set to
Command Output tab.)
• Show parsed output as list: If output parsing is configured, select Show parsed output
as list to display the output in list format on the Command Output tab. (This option is only
accessible if the Run in field is set to Command Output tab.)
• Environment Variables: Use the Environment Variables section of the dialog box to
configure new environment variables or change the value of existing environment variables
for the duration of the run. To add or alter an environment variable, click New and configure
the following values:
♦ Variable Name: Enter a name for the variable.
♦ Variable Value: Enter a value for the variable.
♦ Interpolation Shortcut: Click the arrow button to the right of the Variable Value
field to insert an interpolation shortcut pertinent to the Variable Value setting. The
interpolation shortcut is inserted at the current cursor position in the Variable Value
field.
♦ Add Path: Click this button to insert a directory as the variable value.
• Save advanced options as defaults: If this check box is selected, the current settings are
stored as the defaults for the Run Command dialog box.
Command Output Tab
By default, the commands run in the Command Output tab on Komodo's Bottom Pane. (Use the
Run in field to run the command in a new shell window, or to run a graphical application without a
console.)
If the command prompts for input, enter it directly on the Command Output tab. Output written to
"stderr" (standard error output) is displayed in red at the top of the tab. Click the Close button at the
top right of the Command Output tab to terminate a running command. Click the Toggle
Raw/Parsed Output View button to jump from parsed results to raw output and vice versa.
(Parsing is enabled and configured via the Parse output with field.)
Advanced Run Commands
199
Komodo User Guide
Note: For more information on parsing command output, see the Parsing Command Output section
of the Run Command Tutorial.
Storing Run Commands in a Project or the Toolbox
To add a run command to the Toolbox, select Add to Toolbox in the Run Command dialog box.
Run commands can also be added to projects or the Toolbox via the methods described in Storing
Run Commands in a Project or the Toolbox.
To run a command stored in the Toolbox or in a project, double-click the run command's name, use
the assigned key binding, or right-click the run command and select Run.
To access run command options for the selected run command, right-click the run command's
name. The options are as follows:
• Run Command: Execute the stored run command.
• Cut/Copy/Paste: These options are used to remove the run command from a project or the
Toolbox, or to move a run command between a project and the Toolbox (and vice versa).
• Export as Project File: When this option is invoked, a new project file is created that
contains the run command from which the option is invoked. You are prompted to provide
the name of the new project file and the directory where it is stored. To open the new
project file, select File|Open|Project.
• Export Package: Run commands can be archived and distributed among multiple Komodo
users via "packages". Packages are compressed archive files that contain the run command
from which the Export Package option was invoked. Packages are stored in files with a
".kpz" extension, and can be opened by any archiving utility that supports libz (for
example WinZip). The Export Package option differs from the Export as Project File
option in that copies of filesystem-based components (such as files and dialog projects) are
included in the archive. Conversely, Export as Project File creates a project with a
reference to the component's original location and does not create copies of the
components. When Export Package is invoked, you are prompted for a name and file
location for the package. Exported packages can only be imported into "container" objects
in Komodo, such as projects, the Toolbox, and folders within projects and the Toolbox. See
Toolbox - Exporting and Importing Toolbox Contents, Projects - Importing and Exporting
Projects via Packages, or Folders - Import Contents from Package for more information.
• Rename: To change the name of a run command, select this option and enter a new name.
• Delete: To remove a run command from a project or the Toolbox, select this option. The run
command is permanently deleted.
Run Command Properties
To access the properties of a run command stored in a project or the Toolbox, right-click the run
command and select Properties. The Properties dialog box contains all the elements of the Run
Command dialog box, and is therefore used for editing stored run commands. In addition, the
Properties dialog box is used to assign a custom icon to the run command, and to assign a custom
key binding.
Command Output Tab
200
Komodo User Guide
Assigning Custom Icons to Run Commands
The default run command icon can be replaced with custom icons. Komodo includes more than
600 icons; alternatively, select a custom image stored on a local or network drive (use 16x16-pixel
images for best results).
To assign a custom icon to a run command:
1. On the Projects tab or Toolbox tab, right-click the desired run command and select
Properties. Alternatively, click the run command in the Projects tab or Toolbox tab, then
select Projects|runcommand_name|Properties or
Toolboxruncommand_name|Properties.
2. In the Properties dialog box, click Change Icon.
3. In the Pick an Icon dialog box, select a new icon and click OK. Alternatively, click Choose
Other, and browse to the desired image file.
4. In the properties dialog box for the run command, click OK. The custom icon is displayed
next to the run command.
To revert to the default icon for a selected run command:
1. On the Projects tab or Toolbox tab, right-click the desired run command and select
Properties.
2. Click Reset, then click OK. The default icon is displayed next to the run command.
Run Command Key Bindings
Custom key bindings can be assigned to run commands stored in the Toolbox or in a Project. Use
the Key Binding tab in the run command's Properties to specify the keystrokes that invoke the run
command. See Key Bindings for Custom Components for more information.
Run Command Properties
201
Custom Toolbars and Menus
Custom toolbars and menus are used to extend Komodo's default menus
and toolbars with menus and toolbars containing custom items. Any
component that can be stored in a project or the Toolbox can be stored in
a custom toolbar or menu. A custom toolbar might contain frequently used
run commands and snippets; a custom menu might contain folders with
the contents of a local filesystem.
Feature Showcase
• create a custom
toolbar
Custom toolbars and menus are created and configured within the Project
Manager and/or the Toolbox. Custom toolbars and menus contained in
projects are only displayed when the projects are open in the Projects tab;
custom toolbars and menus contained in the Toolbox are always
displayed.
Creating Custom Toolbars and Menus
1. On the Project or Toolbox menu, select Add|New Custom Toolbar or Add|New Custom
Menu. Enter a name for the new component.
2. Copy and paste or drag and drop the item(s) to be included on the toolbar or menu onto the
icon created in the previous step. Alternatively, right-click the custom menu or toolbar name
and select Add. For a complete description of adding components to containers (such as
projects and custom menus and toolbars), see the Projects section of the documentation.
New toolbars are displayed alongside the default Komodo toolbars and can be accessed via
the View|Toolbars menu. New menus are displayed to the right of the default Komodo
menus.
Custom Menu and Toolbar Options
To access options for a custom menu or toolbar, do one of the following:
• Toolbox|menuortoolbar_name|option or Project|menuortoolbar_name|option: When a
custom menu or toolbar is selected in the Projects tab or Toolbox, use the Project or
Toolbox menus to access the list of options. The name of the custom menu or toolbar that
is currently selected in a project or the Toolbox is displayed on the menu.
• Context Menu: Right-click the custom menu or toolbar in a project or the Toolbox and
select the desired option.
The following options are available:
• Export as Project File: When this option is invoked, a new project file is created that
contains the custom menu or toolbar from which the option is invoked. You are prompted to
provide the name of the new project file and the directory where it will be stored. To open
the new project file, select File|Open|Project.
• Export Package: Snippets can be archived and distributed among multiple Komodo users
via Packages. Packages are compressed archive files that contain the snippet from which
the Export Package option was invoked. Packages are stored in files with a ".kpz"
extension, and can be opened by any archiving utility that supports libz (for example
WinZip). The Export Package option differs from the Export as Project File option in that
Custom Toolbars and Menus
202
Komodo User Guide
copies of filesystem-based components (such as files and dialog projects) are included in
the archive. Conversely, Export as Project File creates a project with a reference to the
component's original location and does not create copies of the components. When Export
Package is invoked, you are prompted for a name and file location for the package.
Exported packages can only be imported into "container" objects in Komodo, such as
projects, the Toolbox, and folders within projects and the Toolbox. See Toolbox - Exporting
and Importing Toolbox Contents, Projects - Importing and Exporting Projects via Packages,
or Folders - Import Contents from Package for more information.
• Rename: To change the name of a custom menu or toolbar, select this option and enter a
new name.
• Cut/Copy/Paste: These options are used to remove the custom menu or toolbar from a
project or the Toolbox, or to move custom menu or toolbars between the project and the
Toolbox (and vice versa).
• Add: Use this option to add components to the selected custom menu or toolbar. All
components can be added to custom menu or toolbars in the same manner they are added
to projects. Refer to the individual component documentation, or the project documentation
for more information.
• Delete: To remove a custom menu or toolbar from a project or the Toolbox, select this
option. The custom menu or toolbar is permanently deleted.
Custom Menu and Toolbar Properties
Custom menu or toolbar properties are used to alter the name of the custom menu or toolbar, or
change the custom menu or toolbar's display order. To access the Properties dialog box, right-click
the custom menu or toolbar and select Properties.
Custom menus are displayed between the default Tools and Window menus. If multiple custom
menus are in effect, the display order depends on the menu's Priority setting. New menus have a
default priority of 100; alter the priority of custom menus to control the left-to-right order of display.
Custom toolbars are displayed to the right of default Komodo toolbars. If necessary, a new row is
created for their display. If multiple custom toolbars are in effect, the display order depends on the
toolbar's Priority setting. New toolbars have a default priority of 100; alter the priority of custom
toolbars to control the left-to-right order of display.
To assign a letter to be used in combination with the 'Alt' key for menu access, enter a shortcut
letter in the Menu Access Key field. If the letter is already assigned to a Komodo core function,
you are prompted to enter a different letter.
Custom Menu and Toolbar Options
203
Debugging ProgramsKomodo IDE only
The Komodo debugger is a tool for analyzing programs on a line-by-line
basis, monitoring and altering variables, and watching output as it is
generated. Debugging features include:
• breakpoint and spawnpoint control
• remote debugging
• stepping
• watching variables
• viewing the call stack
• sending input
• adding command-line arguments
• interactive shell
The sections that follow contain general information about the debugger that
is applicable to each language. Komodo provides debugging support for
JavaScript, Perl, Python, PHP, XSLT and Tcl. For information about
configuring languages and language-specific debugger functions, see:
Tutorials
• Perl tutorial
• Python tutorial
• PHP tutorial
• Ruby tutorial
• XSLT tutorial
Feature Showcases
• conditional
breakpoints
• XSLT debug
view
• Debugging JavaScript
• Debugging Perl
• Debugging Python
• Debugging PHP
• Debugging Ruby
• Debugging Tcl
• Debugging XSLT
Notes
• Perl Debugging on Windows 98/Me requires ActivePerl Build 623 or
higher. Restart your machine after you install ActivePerl to be sure
that your system's PATH variable is updated with the location of Perl.
• Be sure you meet the software prerequisites for debugging, as
described in the Installation Guide.
Starting the Debugger
To start the debugger, do one of the following:
• Debug Toolbar: Select Go/Continue or Step In.
• Keyboard: Use the associated key binding.
• Debug Menu: Click Go/Continue or Step In.
By default, the Debugging Options dialog box is displayed (unless the debugger preference has been
configured to start without displaying the dialog box). To override the debugger preference on Windows
and Linux systems, hold down the 'Ctrl' key while invoking the key binding for starting the debug session.
(Select Help|List Key Bindings to view the current key bindings; use the key bindings preference to
configure custom key bindings.) Alternatively, the 'Ctrl' key can be used to suppress the display of the
Debugging Options dialog box.
Debugging ProgramsKomodo IDE only
204
Komodo User Guide
If multiple files are open in the Editor Pane, the program that is currently displayed is debugged. If no
breakpoints are set, Go/Continue causes the debugger to run to the end without stopping. Step In
moves through the program one line at a time.
If the Bottom Pane is hidden, Komodo automatically shows it.
To run a program without debugging, do one of the following:
• Debug Menu: Select Run without debugging.
• Keyboard: Use the associated key binding.
To run a program to the current cursor position, do one of the following:
• Debug Menu: Select Run to Cursor.
• Keyboard: Use the associated key binding.
By default, the debugger will break on the first line of executable code when it starts. This is useful for
adding breakpoints if none have been set yet. To change this behavior, set Initial break behavior to
Run to first breakpoint in the debugger preferences (Edit|Preferences|Debugger).
Multi-Session Debugging
Komodo supports the concurrent debugging of multiple applications, or multi-session debugging. With
multi-session debugging, Komodo debugs more than one project at a time, regardless of the supported
languages used in the programs being debugged.
When debugging multiple sessions, each session has a unique Debug tab (located in the Bottom Pane)
for controlling the debug actions specific to that process. A Debug tab is created each time a new
debugger session is started. To close a Debug tab, click the X button at the top right corner.
To start multiple debugging sessions, do one of the following:
• Debug Menu: Click Start New Session.
• Keyboard: Use the associated key binding.
Debugging Options
When the debugger is invoked, the Debugging Options dialog box is displayed. Use this to configure the
system environment, command-line arguments, CGI environment, and other debugging options.
Not all of the debugging options described below apply to all languages. The available tabs and fields
depend on the interpreter used to debug the file. The interpreter is determined by the File Associations
configured for the active file in the Editor Pane.
To suppress the display of the Debugging Options dialog box on Windows and Linux systems, hold down
the 'Ctrl' key while clicking the desired debugging button on the Debug Toolbar, or use the desired
keyboard shortcut. Change the default display by selecting Skip debug options dialog from
Edit|Preferences|Debugger.
Starting the Debugger
205
Komodo User Guide
Global Options
These options are displayed regardless of which configuration tabs are available.
• Language: The language of the file being debugged.
• Simulate CGI Environment: Select this check box to display two additional CGI option tabs CGI Environment and CGI Input.
• Debug in separate console: Select this check box to display the debug process in a separate
console window rather than the Output tab. As applicable, the console window displays program
output and prompts for program input.
General Tab
• Interpreter Arguments: As required, enter command line options and arguments for the
interpreter in this field. Use the Shortcut button to the right of the input field to select common
language-specific options.
• Script: Enter the name of the script to be debugged. By default, this field contains the full path
and name of the program displayed in the Editor pane. When manually specifying a script, UNC
or SMB paths (which identify remote machines on a local area network via the "\\" prefix) are not
supported. Instead, map the network share to a drive letter (Windows) or mount the share on the
filesystem (OS X and Linux). When set as a Project setting, this is the script that Komodo opens
for debugging when a session is started from any file in the project. This is useful when working
in modules which are called by a 'main' program.
• Script Arguments: As required, enter arguments for the script in this field as they would appear
on the command line. Multiple Arguments must be separated with spaces. If the Simulate CGI
Environment box is selected, and CGI Input variables of the type GET are set, the contents of
this field are ignored.
• Directory: Specify the directory to start the program in. If unset, the program starts in the
directory where it resides.
• Select the input XML file: (XSLT only) Specify the name and location of the input XML file.
• Select the interpreter to use for debugging: (PHP and Tcl only) For Tcl programs, select tclsh
or the wish interpreter, depending on whether you are debugging a console or a GUI application.
For PHP programs, select the CLI (Command Line Interface) or CGI (Common Gateway
Interface) interpreter. These selections reference the interpreters configured under
Edit|Preferences... in the Language Configuration section.
• Select the directory that contains the php.ini file: (PHP only) If more than one version of PHP
exists on the system, specify the directory that contains the php.ini file you wish to use.
• Disable Output Buffering (PHP only): Output from the PHP interpreter is not buffered (it is
displayed as it occurs) if this option is enabled. This option has no effect when Simulate CGI
Environment is selected. To disable output buffering in CGI emulation mode, comment out the
output_buffering setting in php.ini with a ";" character, or set it to "off".
• Enable Implicit Flush (PHP only): The PHP output layer flushes itself automatically after every
output block. If this option is not enabled, output is buffered by the operating system and is
flushed periodically by the operating system, or when the application is finished. This option has
no effect when Simulate CGI Environment is selected.
Environment Tab
The Environment tab displays all environment variables set on the system. Use this tab to add new
variables or change the values of existing variables for the duration of the debug session. The Default
Global Options
206
Komodo User Guide
Environment Variables pane displays environment variables that have been declared on your system.
The User Environment Variables pane displays environment variables set in the saved configuration
which override the Default Environment Variables.
Change variables by adding a new variable with the same name and a new value. These changes have
no effect outside of the Komodo debugger and are stored in each saved configuration.
• To Add New Variables: Click New and enter the Variable Name and Variable Value in the
Environment Variable dialog box. To add one or more directories to the Variable Value field, click
Add Path and navigate to the desired directory.
• To Edit Existing Variables: Select the variable, click Edit, then change as desired. This creates
a new variable with the same name and the desired value. (User Environment Variables take
precedence over Default Environment Variables.)
• To Delete a Variable: Select the variable from the User Environment Variables pane and click
Delete. Default Environment Variables cannot be deleted, but can be set to an empty value.
CGI Environment Tab
The CGI Environment tab is only displayed if the Simulate CGI Environment check box is selected on
the General tab. It displays CGI Environment Variables commonly configured on a web server. Use this
tab to alter existing variables and add new variables. Variable changes have no effect outside of the
Komodo debugger and are stored in each saved configuration.
• To Add New Variables: Click New, and enter the Variable Name and Variable Value in the
Environment Variable dialog box. To add one or more directories to the Variable Value field, click
Add Path and navigate to the desired directory.
• To Edit Existing Variables: Select the variable, click Edit, then change as desired. This creates
a new variable with the same name and the desired value. (User CGI Environment Variables
take precedence over Default CGI Environment Variables.)
• To Delete a Variable: Select the variable from the User CGI Environment Variables pane and
click Delete.
CGI Input Tab
The CGI Input tab is only displayed if the Simulate CGI Environment check box is selected on the
Global Options tab. It is used to configure the CGI form type and variables for the purpose of simulating
CGI input. Note that Komodo's CGI emulation does not generate HTTP Request Headers; rather, it
executes the CGI directly by emulating a web server environment.
• Request Method: Select the request method that has been assigned to the form in the CGI
program.
• Post Type: Select the format in which data is sent from the browser to the server.
Use the Request Variable section of the dialog box to create variables that are processed by your CGI
program. These variables are displayed in the Browser Arguments section of the dialog box.
• Type: Specify the type of input associated with the variable (GET, POST, cookie or file).
• Name: Enter the variable name as specified in the CGI program.
• Value: Enter the value for the variable specified in the Name field. To provide a directory path
and file, click the Browse Files button, select the desired file and click Add. (To accommodate
Environment Tab
207
Komodo User Guide
file uploads, select Multipart as the form's POST method.)
To alter variables: Click on the desired variable in the Browser Arguments section of the dialog box,
make changes in the Type, Name and Value fields, then click Update.
To delete variables: click on the desired variable in the Browser Arguments section of the dialog box,
and click Delete.
Storing Debug Configurations
Debugging options can be saved as "named configurations" in the Debug Configuration panel. To save
the current configuration:
1. Click New...
2. Enter a unique Configuration Name.
3. Click OK.
Existing saved configurations can be selected from the drop-down list. If you wish to delete a saved
configuration, select it from the list and click Delete.
If the file being debugged is part of a project that is currently open, these preferences are saved in that
project. If not, this configuration is automatically saved as part of the file's Properties and Settings
(although they cannot be altered via the file's Properties dialog box).
Breakpoints and Tcl Spawnpoints
Breakpoints are set at lines in the program where you want program execution to pause. Enabled
breakpoints appear as solid red circles in the left margin of the Editor pane and are also listed on the
Breakpoints tab during debugging. Disabled breakpoints appear as white circles with a red outline.
Double-clicking on an enabled or disabled breakpoint from the Breakpoints tab opens the associated
file in the Editor Pane and shifts focus to the line number for that break location.
Spawnpoints are set at points in a Tcl script where you want an external application to execute (spawn).
When a spawnpoint is encountered during the debugging process, Komodo configures the spawned
application to start as a new debugger session. Both the initial and spawned debugger sessions run
concurrently. Enabled spawnpoints appear as solid green arrows in the left margin of the Editor pane
and are also listed on the Breakpoints tab during debugging. Disabled spawnpoints appear as white
arrows with a green outline. Double-clicking an enabled or disabled spawnpoint from the Breakpoints
tab opens the associated file in the Editor pane and shifts focus to the line number coinciding with that
spawnpoint location.
Breakpoint and Spawnpoint Management
Breakpoints and spawnpoints can be monitored and managed on the Breakpoints tab in the Bottom
pane (displayed during debugging or invoked by selecting View|Tabs|Command Output). This tab lists
all breakpoints and spawnpoints set in the program. Use the Breakpoints tab to:
• toggle breakpoints
• toggle spawnpoints
CGI Input Tab
208
Komodo User Guide
• go to source code
• set breakpoint properties
Toggling Breakpoints
Breakpoints and Spawnpoints can be toggled between enabled, disabled and deleted. To toggle a
breakpoint, do one of the following:
• Breakpoint Margin: Click on the line you wish to break at once to enable a breakpoint, a second
time to disable it, and a third time to delete it.
• Debug Menu: Click Enable/Disable Breakpoint once to enable a breakpoint on the current line,
a second time to disable it, and a third time to delete it.
• Keyboard: Press 'F9' ('Meta'+'\' on Mac OS X) once to enable a breakpoint on the current line, a
second time to disable it, and a third time to delete it.
To create a new breakpoint in the Breakpoints tab:
1. Click the New button and then select New Breakpoint or right-click in the Breakpoints pane and
select Add|New Breakpoint on the context menu.
2. The following Breakpoint Properties are required:
♦ Language: By default, the language of the program being debugged.
♦ File: The location of the file where the breakpoint is being set.
♦ Line: The line number in the file where the spawnpoint is to be set.
♦ Enable: Select the check box to enable the breakpoint.
3. Click OK.
To delete a breakpoint in the Breakpoints tab, do one of the following:
• Select the breakpoint and click the Delete Breakpoint button
• Right-click on the breakpoint and select Delete.
To clear or remove multiple breakpoints, do one of the following:
• Debug Menu: Click Clear All Breakpoints.
• Breakpoint Tab: Click the Delete All Breakpoints button.
• Keyboard: Use the associated key binding.
To disable or enable all breakpoints:
• On the Breakpoints tab, click the Disable/Enable All Breakpoints button. All breakpoints are
disabled if previously enabled, or enabled if previously disabled.
Toggling Spawnpoints
To add a Tcl spawnpoint, use the Breakpoints tab:
1. Click the New button and then select New Tcl Spawnpoint or right-click in the Breakpoints list
and select Add|New Tcl Spawnpoint on the context menu.
2. The following properties are configurable in the Spawnpoint Properties dialog box:
♦ Language: Tcl
Breakpoint and Spawnpoint Management
209
Komodo User Guide
♦ File: The location of the file where the spawnpoint is to be set (for example,
C:\samples\tcl_sample.tcl).
♦ Line: The line number in the file where the spawnpoint is to be set.
♦ Enable: Select the check box to enable the spawnpoint. Deselect the check box to
disable the spawnpoint.
3. Click OK.
To delete a spawnpoint in the Breakpoints tab, do one of the following:
• Select the spawnpoint and click the Delete Breakpoint button
• Right-click on the spawnpoint and select Delete.
To clear or remove multiple spawnpoints, do one of the following:
• Debug Menu: Click Clear All Breakpoints.
• Breakpoint Tab: Click the Delete All Breakpoints button.
• Keyboard: Use the associated key binding.
To disable or enable all spawnpoints:
• On the Breakpoints tab, click the Disable/Enable All Breakpoints button. All spawnpoints are
disabled if previously enabled, or enabled if previously disabled.
Note: Breakpoints and spawnpoints added or modified while a program is running are not necessarily
updated in the breakpoint manager. To add breakpoints while debugging, interrupt the debugging
session using the Break button to ensure that the new breakpoint is properly updated.
Go to the Source Code
To open the source code in the Editor Pane at the line number where the breakpoint or spawnpoint is
set, do one of the following:
• Breakpoints Tab: Double-click the breakpoint to view the associated source code.
• Breakpoints Tab: Select the desired breakpoint and click the Go to the Source Code button.
Breakpoint Properties
When adding or editing a breakpoint in the Breakpoint tab, a Breakpoint Properties dialog box
appears. This dialog box contains a tab for each available breakpoint type. Change the breakpoint type
by switching to a different tab.
Each tab is split into two parts, separated by a horizontal line. The top section contains configuration
items that are required; the bottom section contains configuration options that are optional. The last item
on this tab is the Enable checkbox.
• Language: The language of the file where the breakpoint is to be set.
• File: The line number on which to break.
• Condition: Evaluate some code and break if it evaluates to true. For example, 0==0, as the
condition would always evaluate to true and cause the debugger to break. The condition should
be specified in the syntax of the language selected in the Language drop-down list.
Breakpoint and Spawnpoint Management
210
Komodo User Guide
• Watch: Break when the value of the specified variable (or expression) is set or changed.
• Function Call: Break after the specified function is called.
• Function Return: Break after the specified function has finished executing.
• Exception: Break when the specified exception is caught.
• Line: Break on the specified line.
• Hit Counts: Break when the condition specified in any of the above has been met a certain
number of times. Each time the debugger engine reaches a breakpoint, it adds one to the count.
It then looks at the hit count setting to see if the evaluation allows for a break at that moment.
There are two configuration items related to hit counts, the condition and the count. There are
three types of conditions:
♦ Break when hit count is greater than or equal to
♦ Break when hit count is equal to
♦ Break when hit count is a multiple of
For example:
1. Set a breakpoint on line 2 of a script.
for 1 in range(256):
print 'hello'
2. Define a hit condition 'Break when hit count is a multiple of'.
3. Enter the value 5. The debugger breaks every 5th time it passes the line with the print
statement.
Not all breakpoint types are supported for all languages. The following table shows breakpoint support by
language:
Type
Tcl
Perl PHP XSLT Python
Line Number
Yes Yes
Yes
Yes
Yes
Function Call
No
Yes
Yes
Yes
Yes
Function Return No
Yes
Yes
Yes
Yes
Exception
No
No
No
No
Yes
Conditional
Yes Yes
No
Yes
Yes
Watch
Yes Yes
No
No
Yes
Forcing a Break
Use the Break Now function to stop debugging an application at the current execution point, and then
continue debugging from that point. For example, use this control when debugging applications running
long processes. To force a break while debugging an application, do one of the following:
• Debug Menu: Select Break Now.
• Debug Toolbar: Click the Break Now button.
Breakpoint and Spawnpoint Management
211
Komodo User Guide
Remote Debugging
Remote debugging is the process of debugging programs locally while they execute on remote
machines. This is useful for debugging applications in the environments where they would normally be
run (e.g. CGI programs in a live web server setting), and for systems built using client/server
architecture.
Komodo can be set to Listen for Debugger Connections continuously. Additionally, you can set remote
debugger preferences and check listener status of the current listener configuration. For instructions on
configuring specific languages for remote debugging, see:
• Debugging Perl
• Debugging Python
• Debugging PHP
• Debugging XSLT
• Debugging Tcl
Listen for Debugger Connections
To toggle continuous listening for remote debugging, do one of the following:
• Debug Menu: select Listen for Debugger Connections.
• Keyboard: Use the associated key binding.
Note: A check mark appears when Listen for Debugger Connections is enabled. Otherwise, this
feature is disabled.
Check Listener Status
To check the status and current configuration of the Komodo debugger:
1. On the Debug menu, select Listener Status. The Debugger Listener status screen appears.
2. Click OK after reviewing listener status, or use the associated key binding.
Multi-User Debugging
When multiple users are running Komodo session, configure Komodo's Debugger Connection Options
to listen for debug connections on port "0" (see Set Debugger Preferences). The system provides
Komodo with a unique port each time Komodo is started, allowing multiple users on the system to debug
applications simultaneously. In remote debugging, this requires the remote debugger application to be
manually set to connect on the system-allocated port unless the Debugger Proxy is used.
Debugger Proxy
Remote debugger processes can communicate with Komodo through the DBGP proxy (debugger
protocol proxy). The proxy allows Komodo to use a system-allocated listener port for debugging without
the user having to manually configure the same port number on the remote debugger. This is useful for
running multiple remote debugging sessions and on networks where a remote debugging process can
not connect to Komodo directly. The proxy can run on the local machine, the remote machine, or a
Remote Debugging
212
Komodo User Guide
separate machine.
A typical DBGP Proxy connection is established as follows:
1. Komodo contacts the DBGP proxy and identifies itself with:
2.
♦ Hostname or IP: The hostname or IP address of the machine Komodo is running on. This
is set to localhost or 127.0.0.1 if the debugger is running locally.
♦ Port Number: The port configured in Preferences|Debugger or the system-assigned
port.
♦ Proxy Key: The Proxy Key configured in Preferences|Debugger. If unset, Komodo will
use the USER or USERNAME environment variable value.
3. The DBGP Proxy stores this information.
4. The remote debugging process contacts the DBGP Proxy, providing an IDE Key which
corresponds to the Proxy Key specified in Komodo. By default, this connection happens on port
9000 but can be configured to use another port (see language-specific debugging instructions
and "-d" option below).
5. DBGP Proxy uses the IDE Key value to match the connection to the appropriate instance of
Komodo.
6. The remote debugger connects to Komodo on the system-assigned or user-specified port.
To start the proxy on Windows:
set PYTHONPATH="<Komodo install directory>\lib\support\dbgp\pythonlib;%PYTHONPATH%"
cd <Komodo install directory>\lib\support\dbgp\bin
pydbgpproxy
To start the proxy on Linux (requires Python 2.2 or later):
export PYTHONPATH=<Komodo install directory>/lib/support/dbgp/pythonlib;$PYTHONPATH
cd <Komodo install directory>/lib/support/dbgp/bin
python pydbgpproxy
To start the proxy on OS X:
export PYTHONPATH=<Komodo install directory>/Contents/SharedSupport/dbgp/pythonlib;$PYTHONPATH
cd <Komodo install directory>/Contents/SharedSupport/dbgp/bin
python pydbgpproxy
The following options are available:
• -d <hostname:port>: Listener port for debugger processes.
• -i <hostname:port>: Listener port for Komodo instances.
• -l <log_level>: Logging level. Logging is dumped to stout and can be set to CRITICAL,
ERROR, WARN, INFO or DEBUG.
Example
If you are debugging scripts on a remote web server that cannot connect to Komodo directly because of
a firewall, you can run dbgpProxy on an intermediary server (e.g. a gateway) which can connect to
Komodo and the web server on specified ports. The three servers in this example are:
1. workstation: The machine running Komodo. The following preferences are set:
Debugger Proxy
213
Komodo User Guide
♦ Listen for Debugger Connections is enabled.
♦ Enable Debugger Proxy is selected.
♦ Listen for debug connections on port is set to '0' (use system-assigned port)
♦ Proxy Listener Address is set to gateway:9001
♦ Proxy Key is set to "jdoe"
Debug|Listener Status displays a system-assigned Host Port of 37016.
2. gateway: A gateway server with access to the internal and external networks. The proxy is
running with the following options:
dbgpProxy -i gateway:9001 -d gateway:9000
3. webserver: The machine running a Python CGI script called test.py.
The debugging process on 'webserver' is launched with the following command:
python dbgpClient.py -d gateway:9000 -k "jdoe" test.py
The remote debugger running on 'webserver' (dbgpClient.py in this case) connects to the proxy
(dbgpProxy.py) running on 'gateway'. The proxy uses the IDE Key "jdoe" to connect the debugger
process to the Komodo instance listening with a Proxy Key of "jdoe". The proxy continues to
communicate with the remote debugger on port 9000, but routes the debugging session to Komodo on
port 37016.
Sending Input to the Program
When a program prompts for input, enter the desired input in the console window or Output tab
(depending on the Debugging Options configuration), and press Enter to continue.
Using Debugger Commands
Debugger Command Description
This table lists common tasks and their Komodo commands.
To do this
Press this
Run a program
The debugger runs until the program ends.
• Debug Menu: Select Run Without
Debugging
• Windows/Linux Keyboard: Press 'F7'
• Mac OS X Keyboard: Press
'Meta'+'Ctrl'+'R'
Start the debugger
The debugger runs until it encounters a
breakpoint, or until the program ends.
Sending Input to the Program
• Debug Menu: Select Go/Continue
• Windows/Linux Keyboard: Press 'F5'
• Mac OS X Keyboard: Press 'Meta'+'>'
• Debug Toolbar: Click the Go/Continue
button
214
Komodo User Guide
Step In
The debugger executes the next unit of code,
and then stops at the subsequent line.
• Debug Menu: Select Step In
• Windows/Linux Keyboard: Press 'F11'
• Mac OS X Keyboard: Press
'Meta'+'Shift'+'I'
• Debug Toolbar: Click the Step In
button
Step Over
Like Step In, Step Over executes the next unit
of code. However, if the next unit contains a
function call, Step Over executes the entire
function then stops at the first unit outside of
the function.
• Debug Menu: Select Step Over
• Windows/Linux Keyboard: Press 'F10'
• Mac OS X Keyboard: Press
'Meta'+'Shift'+'O'
• Debug Toolbar: Click the Step Over
button
Step Out
The debugger executes the remainder of the
current function and then stops at the first unit
outside of the function.
• Debug Menu: Select Step Out
• Windows/Linux Keyboard: Press
'Shift'+'F11'
• Mac OS X Keyboard: Press
'Meta'+'Shift'+'T'
• Debug Toolbar: Click the Step Out
button
Run to Cursor
The debugger runs until it reaches the line
where the cursor is currently located.
• Debug Menu: Select Run to Cursor.
• Windows/Linux Keyboard: Press
'Shift'+'F10'
• Mac OS X Keyboard: Press
'Meta'+'Ctrl'+'I'
Break Now
Pause debugging an application at the current
execution point. Go/Continue continues
debugging from that point.
• Debug Menu: Select Break Now
• Debug Toolbar: Click the Break Now
button
Stop
Stop the debugging session. Go/Continue
restarts debugging from the beginning of the
program.
• Debug Menu: Select Stop
• Windows/Linux Keyboard: Press
'Shift'+'F5'
• OS X Keyboard: Press 'Meta'+'Ctrl'+'P'
• Debug Toolbar: Click the Stop button
Toggle breakpoint
Enables, disables, or deletes a breakpoint on
the current line.
• Debug Menu: Select Disable/Enable
Breakpoint
• Windows/Linux Keyboard: Press 'F9'
• Mac OS X Keyboard: Press 'Meta'+'\'
Show Current Statement
Debugger Command Description
215
Komodo User Guide
Moves the editing cursor from any position in
the file to the statement at which the debugger
is stopped.
• Debug Menu: Select Show Current
Statement
• Windows/Linux Keyboard: 'Alt'+'*'
• Mac OS X Keyboard: 'Alt'+'*'
Detach
Stop the debugging process but continue
application process execution.
• Debug Menu: Select Detach
• Debug Toolbar: Click the Detach
button
Debugger Stepping Behavior
Instead of running to the end of a program or to the next breakpoint, the debugger can also step through
code one statement at a time. The following Debug menu items and toolbar buttons control stepping
behavior:
• Step In: Executes the current statement and pauses at the following statement.
• Step Over: Executes the current statement. If the line of code calls a function or method, the
function or method is executed in the background and the debugger pauses at the statement that
follows the original one.
• Step Out: When the debugger is within a function or method, Step Out will execute the code
without stepping through the code line by line. The debugger will stop on the line of code
following the function or method call in the calling program.
When stepping through a program which calls a function or method from an external program (e.g. a
module or package) the debugger steps into the external program at the point where the function or
method is called, opening it in a new tab. Stepping continues in the external program until the function
call is completed.
Note: Perl operators sort, map, and grep behave like other looping constructs with respect to stepping
behavior in the debugger. When Komodo has stopped at one of these operators, Step Over stops at the
first statement or expression used within the first argument of these operators.
For example, if the debugger steps over a statement containing a foreach, while, map, grep, or sort
looping construct that evaluates its body five times, the debugger remains inside that loop for five
iterations. When it steps over on the sixth iteration, the debugger exits the loop and stops at the next
statement.
To skip execution of such looping constructs, set a breakpoint on the statement following the construct,
and continue until Komodo reaches that breakpoint.
Viewing the Debugging Session
When the Komodo debugger is started, the Debug tab opens in the Bottom Pane. This tab consolidates
views of the debugger output, call stack, program variables (local and global), and watch variables. The
Debug tab also contains a Debug Toolbar for stepping in, out, over, and running functions while
debugging.
Debugger Stepping Behavior
216
Komodo User Guide
When debugging more than one session at a time (multi-session debugging), a Debug tab for each
session is accessible in the Bottom Pane. The Debug tab selected is the session currently being
debugged. To change to another debug session, select the Debug tab for that session (identified by the
filename of the program). When a new session is started, a new Debug tab is created and Komodo
automatically switches to that new session.
The Debug tab is divided into two sub-panes, which have tabs of their own. The right sub-pane contains
the Output, Call Stack, and HTML Preview tabs. The left sub-pane contains variable tabs.
Viewing Variables
The variables section of the Debug tab is divided into tabs that vary according to the language of the
program being debugged. (Language variations are described below.) Variables with multiple values
(such as arrays) are indicated by plus and minus symbols to the left of the variable name.
To Expand or Collapse Variables: Plus symbols indicate variables with multiple values that can be
expanded; minus symbols indicate variables that can be collapsed. Click on the plus or minus symbol to
expand or collapse the variable list.
To Change Variable Values: Double-click in the variable's Value field and enter the desired value. (The
value of nodes in XML documents cannot be changed.)
Python Variables and Objects
While debugging Python programs, variables and objects are displayed on the Locals, Globals, and
Code Objects tabs:
• Locals: Displays variables referenced within the current function. If the program is currently
outside of a function, all variables are displayed.
• Globals: Displays all used program variables.
• Code Objects: Displays an expandable tree view of all classes, functions, and their attributes.
During Python debugging sessions, click the Show Hidden Variables
button to display special
Python variables prefixed with double underscores, such as __doc__, __dict__, etc.
PHP and Tcl Variables
While debugging PHP and Tcl programs, variables are displayed on the Locals and Globals tabs:
• Locals: Displays variables referenced within the current function. If the program is currently
outside of a function, all variables are displayed.
• Globals: Displays all used program variables. Note: PHP "Super Globals" ($_POST, $_GET,
etc.) are hidden by default. The Show Hidden Variables button will toggle them on and off.
Perl Variables
While debugging Perl programs, Argument and Special tabs are displayed in addition to the Locals and
Globals tabs listed above.
• Argument: Displays parameters for the current subroutine (i.e. @_).
Viewing the Debugging Session
217
Komodo User Guide
• Special: Displays current Perl special variables (i.e. @ARGV, %ENV, @INC, $0, etc.)
XSLT Variables
While debugging XSLT programs, data nodes and variables are displayed on the Locals and Globals
tabs:
• Locals: Displays data nodes from the input XML document. Only nodes contained in the context
of the template specified in the Call Stack are displayed.
• Globals: Displays xsl:param and xsl:variable elements declared at the top level of the
program.
Setting Watched Variables
The Watch variable tab monitors selected variables and expressions. Use the Watch variable tab to
watch variables, or expressions based on variables, by typing expressions, dragging and dropping
expressions from an editor, or selecting variables from one of the other variable tabs. Also, use the
Watch tab to change the value of a variable or remove a variable from the Watch tab.
Watched variables can be added, manipulated and removed regardless of whether the debugger is
currently running.
To watch one or more variables during program execution:
• Click the Add button on the Watch variables tab and type a variable name in the dialog box
• Select the variable in the editor (or any other drag-and-drop aware application), then drag and
drop the variable into the Watch tab
• Right-click a variable in one of the other variable tabs and select Add to Watch from the context
menu.
The Watch variable tab supports viewing the results of expressions made with watched variables. For
example, in a Perl program with scalar variables $base and $height the following expression could be
entered:
($base / 2) * $height
To enter arbitrary expressions on the Watch variable tab:
1. Click the Add button above the Watch variable tab.
2. Enter an arbitrary expression in the dialog box.
3. Click OK.
To change the values of variables:
• Double-click the variable on the Watch variable tab and specify a value. Currently, only the
values of simple variables can be changed. For example, values of variables such as 'a.b[3]' (in
Python) or '$a{b}->[3]' (in Perl) cannot be changed.
Note: This function is not available for arbitrary expressions.
Viewing Variables
218
Komodo User Guide
• Double-click the variable on the Locals or Globals pane and specify a value in the dialog box.
To remove a variable from the Watch variable tab, select the variable and click Delete on the bottom
right toolbar. Alternatively, right-click the desired variable and select Remove Watch on the context
menu.
Output Tab
The Output tab is used to view program output and to send input to the program being debugged. The
following standard data streams are handled in the Output tab:
• stderr: program output
• stderr: errors
• stdin: program input (not supported for Perl or PHP during remote debugging)
When debugging Tcl and Python, if stdin is requested by the program, a red percent character is
shown in the margin of the Output tab.
HTML Preview Tab
If the program produces HTML output, select the HTML tab to preview the rendered output. Unlike the
Output tab, the HTML preview is not constantly updated. Use the Reload HTML View button in the
bottom-pane toolbar to update the preview.
Viewing the Call Stack
The call stack is a data area or buffer used for storing requests that need to be handled by the program.
Komodo's stack stores temporary data such as variables and parameters and operates as a push-down
list. New data moves to the top of the stack and pushes the older data down in a "last-in, first-out"
arrangement.
To view the call stack in a current debugging session, select the Call Stack tab in the right pane of the
Debug tab.
There is one line in this tab per stack frame at any point in the execution of a program. The calling frame
contains the information about a function call, including the filename, the line number, and any
parameters or local variables.
Watching Files
When debugging a program that writes output to another file, or when watching programs execute, you
can watch the output or the log file using Komodo's File Watcher.
The Watch File tool shows a file as the file is being updated on disk. It has no relationship with variable
viewing, except that, while debugging, it is often useful to watch variables change state and files change
content.
To use the File Watcher:
Setting Watched Variables
219
Komodo User Guide
1. On the Tools menu, select Watch File.
2. Browse to the desired file and click OK.
3. Run the program.
Detaching the Debugger
Use the Detach control to stop the debugging process but continue running the application. When
application execution is detached from the debugging process, output continues to print on the Debug
tab until the application finishes running.
To detach application execution from the debugging process, do one of the following:
• Debug Menu: Select Detach.
• Debug Toolbar: Click the Detach button.
Stopping the Debugger
To stop the Komodo debugger, do one of the following:
• Debug Menu: Select Stop.
• Keyboard: Use the associated key binding.
• Debug Toolbar: Click the Stop button.
The debug session ends.
Watching Files
220
Debugging JavaScriptKomodo IDE only
Komodo can debug local or remote JavaScript programs. Unlike other
dynamic language debugging, Komodo uses uses the Firefox browser as
its JavaScript runtime environment. JavaScript enabled pages are loaded,
viewed and controlled in Firefox, and the debugging information is passed
to Komodo via the Komodo JavaScript Debugger extension.
The instructions below describe how JavaScript debugging works in
Komodo, and how to configure Komodo and Firefox for debugging. For
general information about using the Komodo debugger, see Komodo
Debugger Functions.
Understanding JavaScript Debugging
JavaScript debugging using Firefox and Komodo is different in a few important ways from
debugging in other languages. As JavaScript programs are generally run and controlled from a
browser window, limitations in the browser's JavaScript library (in this case, Mozilla's jsLib) affect
how code is handled in the debugging process.
Pretty Print
In certain situations, the JavaScript library returns compiled code objects rather than the original
JavaScript source. Komodo is unable to display meaningful information without decompiling and
visually reformatting the code object first. This view of the code object is called Pretty Print.
The Pretty Print Debug toolbar button and menu option allows for manual toggling of this view.
This option is important in two cases:
• JavaScript in an HTML element: When JavaScript is used within an HTML element, the
Komodo JavaScript Debugger currently returns a code object without the HTML context. For
example:
<p><a onclick="javascript:alert('This is an alert!');">Click me.</a><p>
If this construct were on line 200 of an HTML file, the debugger would not open the HTML
file at line 200, but automatically display the following in Pretty Print mode:
function onclick(event) {
javascript:
alert("This is an alert!");
}
• eval(): As JavaScript does not have a 'use' statement to pull in modules, eval() is often
used to dynamically load JavaScript code (common in various JavaScript web toolkits).
When stepping through the contents of an eval() it will often be helpful to switch to Pretty
Print mode.
In the following example the string being evaluated is actually JavaScript code defined in
the code variable.
<script language="javascript" type="text/javascript">
Debugging JavaScriptKomodo IDE only
221
Komodo User Guide
var code = "var i = 1; \n" +
"var j = 2; \n" +
"alert('i + j = ' + (i + j)); \n";
function runIt() {
eval(code);
}
runIt();
</script>
When stepping through this code in normal mode, Komodo will spend several extra steps
on the eval(code) line without jumping up to the embedded code in the var code
section. In more complex JavaScript, or in eval() instances that call external files or
dynamically generated code, this would be quite uninformative.
In Pretty Print mode, the code objects are returned individually, each in a new editor tab, as
you step through the code. When the eval(code) line is encountered, a new tab will open
up displaying the embedded JavaScript from the var code section.
When debugging these JavaScript constructs, you may find that the line numbers displayed in the
Call Stack are wrong, sometimes even specifying a line number beyond the last line of the file.
This is a side-effect of the JavaScript library constraints mentioned earlier, and an indicator that you
should switch to Pretty Print mode (if Komodo has not done this automatically).
Configuring the JavaScript Debugger
1. If you have not already done so, download and install the Firefox browser for your operating
system / platform.
2. In Komodo, on the Edit menu, click Preferences
3. In the Preferences dialog box under Languages, click JavaScript.
4. Click Install/Upgrade 'Komodo JavaScript Debugger' Firefox extension.
5. Follow the steps in the Firefox Software Installation dialog box to install jslib.xpi and
komodo_javascript_debugger.xpi.
Alternatively, launch Firefox and navigate to the /lib/support/modules/ subdirectory of your Komodo
installation and open the xpi files.
Once these extensions have been installed, the Komodo JavaScript Debugger extension must be
configured to communicate with Komodo. In Firefox:
• Click the Properties button in the new Komodo JavaScript Debugger toolbar or,
• Click Tools | Komodo JavaScript Debugger | Configure
The following configuration options are available:
• Host: This is set to 127.0.0.1 (localhost) by default and should not normally need to be
changed. If Firefox is running on a different host, or if you are using a DBGP Proxy, set the
appropriate IP address here.
• Port: This should be set to the same value that is set in Komodo's Debugger preferences.
This port setting can also be checked by clicking Debug | Listener Status.
• Use Proxy: Select this option if you are connecting to Komodo via a DBGP Proxy.
Pretty Print
222
Komodo User Guide
• Proxy Key: If Use Proxy is selected, this should be set to the same value configured in
Komodo's Debugger preferences.
When debugging JavaScript, Komodo attempts to fetch the code from the URI used in the browser
unless otherwise specified. If you want to actually edit the file while debugging, you will need to
map the URI to a local or remote filesystem directory. Specify these mappings in Mapped URIs
under File | Preferences....
Debugging JavaScript
To begin a JavaScript debugging session:
1. Click Debug | Listen for Debugger Connections in Komodo if it is not already selected.
2. Open the web page or local file you wish to debug in Firefox.
3. In Firefox, click Connect to Komodo Debugger in the Komodo JavaScript Debugger
toolbar or click Tools | Komodo JavaScript Debugger | Connect to Komodo Debugger.
4. In Firefox, click or mouse over a JavaScript control or, if your page contains one, wait for a
JavaScript timer event.
At this point the New Remote Debugger Connection dialog box may appear asking if you want to
accept the debugger session. Click Yes to open the program in a new editor tab. Select "Don't ask
me again." to automatically accept all remote debugging sessions in future.
Breakpoints can now be set and the program can be interactively debugged in Komodo. See
Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.
Configuring the JavaScript Debugger
223
Debugging PerlKomodo IDE only
Komodo can debug Perl programs locally or remotely, including debugging
in CGI and mod_perl environments. The instructions below describe how to
configure Komodo and Perl for debugging. For general information about
using the Komodo debugger, see Komodo Debugger Functions.
Tutorial
• Perl Tutorial
Debugger commands can be accessed from the Debug menu, by shortcut
keys, or from the Debug Toolbar. For a summary of debugger commands,
see the Debugger Command List.
Configuring the Perl Debugger
To specify which Perl interpreter Komodo uses to debug and run Perl programs:
1. On the Edit menu, click Preferences.
2. In the Preferences dialog box under Languages, click Perl. Komodo searches for Perl
interpreters on your system and displays them in the drop-down list.
3. If the preferred interpreter is in this list, click to select it. If not, click Browse to locate it.
4. Click OK.
To start a local Perl debugging session:
On the Debug menu or Debug Toolbar, click Go/Continue or Step In to invoke the debugging
session. See Komodo Debugger Functions for full instructions on using Komodo's debugging
functionality.
Enabling "Break Now"
By default, the Break Now function is disabled for Perl debugging because some programs and
modules (e.g. LWP and WWW::Mechanize) are not compatible with asynchronous breaking.
To enable Break Now, include the setting 'async=1' in the PERLDB_OPTS environment variable. This
can be done in Komodo's Environment preferences (Edit|Preferences...|Environment).
Debugging Perl Remotely
When debugging a Perl program remotely, the program is executed on the remote system and the
debug output is sent to Komodo. Komodo controls the debugging session (e.g. stepping and
breakpoints) once the session starts on the remote system.
Perl remote debugging works on any system that can run the version of perl5db.pl distributed with
Komodo. ActivePerl and most other distributions of Perl (version 5.6 or greater) will work.
Note: If you have the ActiveState Perl Development Kit (PDK) installed, follow the instructions for PDK
users to disable the PDK debugger before continuing.
To debug Perl programs remotely:
Debugging PerlKomodo IDE only
224
Komodo User Guide
Step One: Configure the Remote Machine
1. Copy Komodo's perl debugger and its associated libraries to the remote machine by copying
the entire dbgp/perllib sub-directory of the Komodo installation to the new machine, or
download a package from the Komodo Remote Debugging page.
Note: Do not copy perl5db.pl to the standard "lib" directory of the Perl installation on the
remote machine, as this will overwrite the standard perl5db.pl file.
2. On the remote machine, set the PERL5LIB environment variable to the location of the new
perl5db.pl and its libraries. For example, if the remote machine is running Windows and perllib
directory was copied to C:\misc\perllib, set the variable as follows:
set PERL5LIB=C:\misc\perllib
For example, if the remote machine is running Linux or Mac OS X and perllib was copied to the
/home/me/perl/komodo_perl_debugging directory, set the variable as follows:
export PERL5LIB=/home/me/perl/komodo_perl_debugging/perllib
3. On the remote machine, set the PERLDB_OPTS and DBGP_IDEKEY variables. This tells the
Perl interpreter on the remote machine where to connect to Komodo or the DBGP Proxy and
how to identify itself.
PERLDB_OPTS=RemotePort=<hostname>:<port>
DBGP_IDEKEY=<ide_key>
♦ The port number must match the port number specified in
Edit|Preferences|Debugger. Click Debug|Listener Status to check the current port.
♦ Replace <hostname> with the name or IP address of the machine running Komodo.
♦ If DBGP_IDEKEY is unset, the USER or USERNAME environment variable is used as
the IDE Key.
♦ The variable definitions must be on one line.
For example:
Windows 2000, NT, XP
set PERLDB_OPTS=RemotePort=127.0.0.1:9000
set DBGP_IDEKEY=jdoe
Windows Me
Use the MSCONFIG utility (Start|Run|MSCONFIG). Select the Environment tab, and create a
new variable with the Variable Name of PERLDB_OPTS, and the Variable Value of
RemotePort=127.0.0.1:9000.
Linux and Mac OS X Systems
Debugging Perl Remotely
225
Komodo User Guide
export PERLDB_OPTS="RemotePort=127.0.0.1:9000"
export DBGP_IDEKEY="jdoe"
Note: As with local debugging, the Break Now function is disabled by default. To enable this
button and functionality, add the option 'async=1' to the PERLDB_OPTS environment variable.
For example, on Windows:
set PERLDB_OPTS=RemotePort=127.0.0.1:9000 async=1
Step Two: Listen for Debugger Connections
In Komodo, on the Debug menu, click Listen for Debugger Connections.
Step Three: Start the Perl Program on the Remote Machine
Start the debugging process using the "-d" flag:
perl -d program_name.pl
A Perl Debug tab is displayed in Komodo.
Step Four: Debug the Perl Program using Komodo
Click Step In, or Go/Continue to run to the first breakpoint. See Komodo Debugger Functions for full
instructions on using Komodo's debugging functionality.
Disabling and Enabling the Perl Dev Kit (PDK) Debugger
If you have installed the ActiveState Perl Development Kit (PDK) on the remote machine, the system
may be configured to use the PDK debugger when a Perl debug session (perl -d) is launched. To
use Komodo's debugger, disable the PDK debugger on the remote machine first. If necessary, you
can re-enable the PDK debugger on the remote machine later.
Disabling the PDK Debugger on the Remote Machine
To disable the PDK debugger on the remote machine, perform one of the following procedures:
Option 1:
At the command shell, enter the following command:
Windows
set PERL5DB=BEGIN { require 'perl5db.pl'; }
set PERLDB_OPTS=
Linux
export PERLDB_OPTS=
To re-enable the PDK debugger, set the PERL5DB variable to an empty string.
Disabling and Enabling the Perl Dev Kit (PDK) Debugger
226
Komodo User Guide
Option 2: (Windows)
1. Open System Properties:
♦ On Windows 9x/NT/2000, right-click the My Computer icon and select Properties.
♦ On Windows XP, click Start | Control Panel | System
◊ Click the Advanced tab.
◊ Click Environment Variables.
◊ In the System variables section, click New.
◊ Set the Variable Name field to PERL5DB.
◊ Set the Variable Value field to BEGIN { require 'perl5db.pl'}.
◊ Select the PERLDB_OPTS variable, click Edit.
◊ Delete the contents of the Variable Value field.
◊ Click OK three times to exit.
These changes take effect in new Command Prompt windows. To re-enable the PDK debugger,
delete the PERL5DB variable, and change the PERLDB_OPTS variable back to it's original value.
Configuring Perl for CGI Debugging
Debugging CGI programs on live production servers can seriously impair performance. We
recommend using a test server for CGI debugging. Instructions for configuring Microsoft IIS and
Apache servers are shown below; for other web servers, use these examples and the web server
software documentation as a guide for modifying the server environment.
The settings and paths listed are examples only. Substitute these with the specific paths, hostnames
and port numbers of your server as necessary
Configuring a Microsoft IIS Web Server
• Modify the Server's Environment Variables: Right-click the My Computer icon on the
desktop, and select Properties. On the Advanced tab, click the Environment Variables
button. Add the following items to the System Variables pane:
PERL5LIB="C:\Program Files\ActiveState Komodo x.x\lib\support\dbgp\perllib"
PERLDB_OPTS=RemotePort=<hostname>:<port>
DBGP_IDEKEY="<ide_key>"
Note: The path for the PERL5LIB directory shown above is the correct path in a default
installation. That path must be changed if you have installed Komodo in a different location.
Also, the debugger doesn't seem to be able to find the libraries if any directories in the path
contain spaces. You should copy the perllib directory to another location in which there are no
spaces in the path to overcome this problem and use that path in the PERL5LIB system
variable described above.
• Modify the Internet Information Services Configuration: A "-d" option must be added to the
Executable Path for the Perl CGI script mapping.
♦ IIS 4 and 5:
1. Open the Internet Information Services manager.
2. Select one web site or the entire Web Sites node as desired.
3. Click Action|Properties
4. On the Home Directory tab, click the Configuration button.
Disabling the PDK Debugger on the Remote Machine
227
Komodo User Guide
5. Add (or modify) an entry for Perl with the following characteristics:
Extension = .pl
Executable Path = c:\perl\bin\perl.exe -d "%s" %s
♦ IIS 6:
1. Open the Internet Information Services manager.
2. Select the Web Service Extensions node.
3. Add (or modify) the Web Service Extension for Perl CGI as above.
• Restart the Service: You must restart IIS for the changes to take effect.
Configuring an Apache Web Server
Ensure that Perl CGI scripts are operating correctly on the Apache server before proceeding with CGI
debugger configuration. If you are running Apache under Windows, disable the
ScriptInterpreterSource registry in the httpd.conf file. Use a stand-alone Perl interpreter for
remote debugging.
• Modify the httpd.conf file: The following values can be configured for a specific virtual host or
all hosts. Add the following values in the appropriate sections:
SetEnv PERL5LIB "C:\Program Files\ActiveState Komodo x.x\lib\support\dbgp\perllib"
SetEnv PERLDB_OPTS "RemotePort=<hostname>:<port>"
SetEnv DBGP_IDEKEY "<ide_key>"
Note: You must enable the mod_env Apache module (see
httpd.apache.org/docs/mod/mod_env.html) for the SetEnv directive to function.
• Modify the Perl Script: Add the "-d" flag to the "shebang" line:
#!/perl/bin/perl -d
Starting a CGI Debugging Session
After the configuration is complete, debug programs as follows:
• In Komodo, on the Debug menu, click Listen for Debugger Connections.
• Using a web browser, access your CGI script.
• A Perl Debug tab is displayed in Komodo. See Komodo Debugger Functions for full
instructions on using Komodo's debugging functionality.
Debugging mod_perl
Debugging mod_perl handlers is similar to debugging any Perl program remotely (see Debugging Perl
Remotely to familiarize yourself with the terminology). Debugging mod_perl is different in that you'll
typically invoke the code indirectly with a web browser, and that the Perl code is running inside an
Apache web server.
To configure Komodo debugging in mod_perl:
1. Copy the entire dbgp/perllib sub-directory of the Komodo installation to a convenient directory
Configuring a Microsoft IIS Web Server
228
Komodo User Guide
on the server, or download and unpack the Perl Remote Debugging package from the Komodo
Remote Debugging page. If you are running Apache on your local workstation, you can use
Komodo's copy directly (e.g. <Komodo-install-dir>/lib/support/dbgp/perllib ) for the following
steps. Note: Do not copy perl5db.pl to the standard "lib" directory of the Perl installation on the
remote machine, as this will overwrite the standard perl5db.pl file.
2. In the directory containing perl5db.pl, create a new directory called Apache. For example:
$ cd Komodo/lib/support/dbgp/perllib
$ mkdir Apache
3. Create a symlink or shortcut to perl5db.pl within the new Apache directory. For example:
$ cd Apache
$ ln -s ../perl5db.pl .
4. Install the Apache::DB perl module on the server:
$ cpan Apache::DB
5. Add the following snippet to your httpd.conf file (replace "/path/to/dbgp/perllib" with the full path
to the directory containing perl5db.pl):
<Perl>
use ModPerl::Registry;
use lib qw(/path/to/dbgp/perllib);
$ENV{PERLDB_OPTS} = "RemotePort=localhost:9000 LogFile=stderr";
use Apache::DB ();
Apache::DB->init;
</Perl>
Make sure that RemotePort is set to the hostname and port Komodo using to listen for
debugger connections (see the PERLDB_OPTS setting in the "Configure the Remote
Machine" section of Debugging Perl Remotely).
6. You will probably already have a <Location> section in httpd.conf (or apache.conf) for your
perl scripts. Add the following line to that section:
PerlFixupHandler Apache::DB
For example:
<Location /perl-bin>
SetHandler perl-script
PerlHandler ModPerl::Registry
Options +ExecCGI
PerlOptions +ParseHeaders
PerlFixupHandler Apache::DB
</Location>
7. Restart Apache in debug mode (e.g. apache -X), and open the page you wish to debug in a
browser.
%U" referer LogFormat "%{User-agent}i" agent <IfModule mod_alias.c> ScriptAlias /cgi-bin/
"C:/apps/apache-1-3-33/Apache/cgi-bin/" <Directory "C:/apps/apache-1-3-33/Apache/cgi-bin">
AllowOverride None Options None Order allow,deny Allow from all </Directory> </IfModule> #
mod_perl setup Alias /mod_perl/ "c:/apps/apache-1-3-33/Apache/mod_perl/" <Location /mod_perl>
SetHandler perl-script PerlHandler Apache::Registry Options +ExecCGI allow from all
Debugging mod_perl
229
Komodo User Guide
PerlSendHeader On </Location> # mod_perl debugging setup <IfDefine PERLDB> <Perl> use
Apache::DB (); Apache::DB->init; </Perl> <Location /> PerlFixupHandler Apache::DB </Location>
</IfDefine> <Location /perl-status> PerlHandler Apache::Status SetHandler perl-script </Location>
Debugging mod_perl on Windows
For this example, there are two files (test.pl and printenv.pl) in the mod_perl directory
(c:/apps/apache-1-3-33/Apache/mod_perl/):
• test.pl:
use strict;
our $counter;
$counter = defined $counter ? $counter + 1 : 0;
my $r = shift;
$r->send_http_header('text/plain');
$r->print("" . localtime(time()) . ", counter=$counter\n");
print "This is written with a plain print stmt -- the others use \$r->print\n";
• printenv.pl:
#!c:/perl/bin/perl.exe
## printenv.pl -- demo CGI program which just prints its environment -*- perl -*##
use strict;
print "Content-type: text/html\n\n";
print "<HTML><BODY><H3>Environment variables</H3>";
$a = '' . localtime(time());
print "<h3>Date: $a</h3>\n";
print "<UL>";
foreach (sort keys %ENV) {
my $val = $ENV{$_};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "<LI>$_ = \"${val}\"</LI>\n";
}
print "</UL></BODY></HTML>";
You will start by debugging a standard CGI Perl script, which is running with Apache::Registry to
benefit from mod_perl's code-caching. Complete the following steps to debug test.pl. Use the same
procedure to debug printenv.pl.
1. Navigate to the directory containing Apache.exe, and start the server with this command,
ensuring that no other server is running on the same port:
Apache.exe -f conf/mp1.conf -X -D PERLDB
2. Start Komodo, listening on port 2345.
3. Load test.pl with this URL in the web browser's address bar:
http://localhost/mod_perl/test.pl
The Komodo debugger stops at the first line of the handler sub in Apache/Registry.pm.
4. Step into the code. Do this by finding the eval line that evaluates the compiled script code and
setting a breakpoint there. It will look similar to this:
Debugging mod_perl on Windows
230
Komodo User Guide
eval { &{$cv}($r, @_) } if $r->seqno;
5. Click Go/Continue to continue to that point, and then click Step In three times. Notice that
instead of stepping into test.pl, Komodo has stepped into a similar buffer with a Perl "(eval...)"
name. This is the code that Apache::Registry generates from the original script and then
runs. You can set breakpoints in this code, and examine and modify variables just as if you
were debugging a standalone Perl file. The difference is that, when you reach the end of the
outer handler, you must instruct Komodo to stop debugging.
6. Click the Stop button. When you try debugging test.pl again by, for example, refreshing the
browser, Komodo will stop at a line in IO::Handle.pm. This is a bug.
7. Click Go/Continue, followed by Stop, and refresh the browser again. Komodo returns to the
Apache::Registry handler.
8. Click Go/Continue to move to the breakpoint where your own handler is entered, and step into
it.The $counter variable value is preserved from the previous call, and is incremented from 1
to 2. An entry was added to debug a mod_perl handler outside Apache::Registry. This
time enter http://localhost/perl-status in the browser address bar. Barring an extra
step through IO::Handle::DESTROY (that same bug), the debugger stops at the first line of
the handler sub in Apache::Status. Again, you can continue to step through, examine and
modify variables as in any other debug session.
Troubleshooting
If the debugger doesn't launch, add logging to the session by adding something like
LogFile=stderr with this setting:
set PERLDB_OPTS=RemotePort=localhost:2345 LogFile=stderr
These strings will be written to Apache's error.log file. If you haven't already, install cygwin or google
for another implementation of tail so you can watch this file easily in another window.
If the debugger is working (you'll see many messages in error.log referring to breakpoints if it is),
you might need to clear all the breakpoints from Komodo and restart it, especially if there are
breakpoints pointing to eval-type buffers that no longer exist. This is another bug in Komodo.
Debugging mod_perl on Linux and Mac OS X
Perform the following procedures to configure and execute mod_perl debugging on Linux and Mac OS
X.
Configuring mod_perl Debugging on Linux and Mac OS X
If your system meets the requirements outlined at the beginning of this section, you are ready to build
your own version of Apache with mod_perl.
1. Use the "All-In-One" installation technique described in the mod_perl documentation. This
example assumes use of Apache 1.3.33 and mod_perl 1.29, with the following settings:
$ cat makepl_args.mod_perl
DO_HTTPD=1
APACHE_SRC=../apache_1.3.33/src
EVERYTHING=1
ALL_HOOKS=1
USE_APACI=1
Debugging mod_perl on Windows
231
Komodo User Guide
APACI_ARGS=--prefix=/usr/local/httpd_perl
2. Set the following environment variables in the command window you'll be launching Apache
from. Users of csh and tcsh can make the usual substitutions for setting environment variables.
export PERL5DB='BEGIN { require q(/home/me/perl/komodo_perl_debugging/perllib/perl5db.pl)
export PERL5LIB="/home/me/perl/komodo_perl_debugging/perllib"
export PERLDB_OPTS="RemotePort=localhost:2345"
Note: For verbose logging output from the debugger, add a LogFile directive to the
PERLDB_OPTS variable. For example:
set PERLDB_OPTS=RemotePort=localhost:2345 LogFile=stderr
3. Set up the configuration file mp1.conf (with Apache installed in /usr/local/httpd_perl/bin) as
follows:
ServerType standalone
ServerRoot "/usr/local/httpd_perl/"
PidFile logs/httpd.pid
Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 15
MaxRequestsPerChild 0
ThreadsPerChild 50
Port 80
ServerAdmin [email protected]
ServerName server.example.com
DocumentRoot "/usr/local/httpd_perl/htdocs/mp1"
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory "/usr/local/httpd_perl/htdocs/mp1">
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>
PerlPassEnv PERL5DB
PerlPassEnv PERL5LIB
PerlPassEnv PERLDB_OPTS
ErrorLog logs/error.log
LogLevel warn
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent
<IfModule mod_alias.c>
ScriptAlias /cgi-bin/ "/usr/local/httpd_perl/cgi-bin/"
<Directory "/usr/local/httpd_perl/cgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
Debugging mod_perl on Linux and Mac OS X
232
Komodo User Guide
</Directory>
</IfModule>
# mod_perl setup
Alias /mod_perl/ "/usr/local/httpd_perl/mod_perl/"
<Location /mod_perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
allow from all
PerlSendHeader On
</Location>
# mod_perl debugging setup
<IfDefine PERLDB>
<Perl>
use Apache::DB ();
Apache::DB->init;
</Perl>
<Location />
PerlFixupHandler Apache::DB
</Location>
</IfDefine>
<Location /perl-status>
PerlHandler Apache::Status
SetHandler perl-script
</Location>
Debugging mod_perl on Linux and Mac OS X
For this example, there are two files in the mod_perl directory (/usr/local/httpd_perl/mod_perl/):
• test.pl:
use strict;
our $counter;
$counter = defined $counter ? $counter + 1 : 0;
my $r = shift;
$r->send_http_header('text/plain');
$r->print("" . localtime(time()) . ", counter=$counter\n");
print "This is written with a plain print stmt -- the others use \$r->print\n";
$r->post_connection(sub {$r->child_terminate});
• printenv.pl:
#!/usr/local/bin/perl
## printenv.pl -- demo CGI program which just prints its environment -*- perl -*##
use strict;
print "Content-type: text/html\n\n";
print "<HTML><BODY><H3>Environment variables</H3>";
$a = '' . localtime(time());
Debugging mod_perl on Linux and Mac OS X
233
Komodo User Guide
print "<h3>Date: $a</h3>\n";
print "<UL>";
foreach (sort keys %ENV) {
my $val = $ENV{$_};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "<LI>$_ = \"${val}\"</LI>\n";
}
print "</UL></BODY></HTML>";
If you compare this section of the documentation with the same section of the mod_perl debugging
instructions for Windows, you'll notice that the Linux/OS X version of test.pl contains an extra line:
$r->post_connection(sub {$r->child_terminate});
There are different ways to run Perl in Apache. In this example, you will debug the scripts in two
different environments. First, debug the printenv.pl snippet with Apache running in single-process
mode. Then, debug the test.pl program in a more standard mode, where Apache spawns child
processes.
To debug printenv.pl:
1. Start Komodo, listening on port 2345.
2. Move to the server root and start the server with this command:
bin/httpd -f conf/mp1.conf -D PERLDB -X
3. In the browser, go to http://localhost/mod_perl/printenv.pl. The Komodo
debugger should now be at the first line of the handler sub in Apache/Registry.pm.
4. Step into the code. Do this by finding the eval line that evaluates the compiled script code and
setting a breakpoint there. It should look something like this:
eval { &{$cv}($r, @_) } if $r->seqno;
5. Set a breakpoint there, click Go/Continue, and then click Step In. Notice that instead of
stepping into test.pl, Komodo has stepped into a similar buffer with a Perl "(eval...)" name. This
is the code that Apache::Registry generates from the original script, and then runs. You
can step through the wrapped code for printenv.pl and return to
Apache::Registry::handler, or click Go/Continue. Notice that the Komodo debug
session ends.
As with Windows, the combination of Komodo, mod_perl in debugging mode, and Apache in
single-server mode tends to break down unpredicatably after each single debug session, and you
must restart both Komodo and Apache.
By adding the one line to end child requests, this tells Komodo when to end a debug session, and
you'll get more iterations.
For the second part of this example, you will debug test.pl.
1. Start Apache with this command:
bin/httpd -f conf/mp1.conf -D PERLDB
2. In the browser, go to http://localhost/mod_perl/test.pl.-->
Debugging mod_perl on Linux and Mac OS X
234
Debugging PythonKomodo IDE only
Komodo can be used to debug Python programs locally or remotely,
including debugging in CGI environments. The instructions below
describe how to configure Komodo and Python for debugging. For
general information about using the Komodo debugger, see Komodo
Debugger Functions.
Tutorial
• Python Tutorial
Debugger commands can be accessed from the Debug menu, by
shortcut keys, or from the Debug Toolbar. For a summary of debugger
commands, see the Debugger Command List.
Configuring the Python Debugger
To specify which Python interpreter Komodo should use to debug and run Python programs locally:
1. On the Edit menu, click Preferences.
2. In the Preferences dialog box under Languages, click Python. Komodo searches for
Python interpreters on your system and displays them in the drop-down list.
3. If the preferred interpreter is in this list, click to select the interpreter. If not, click Browse to
locate it.
4. Click OK.
On the Debug menu or Debug Toolbar, click Go/Continue or Step In to invoke the debugging
session. See Komodo Debugger Functions for full instructions on using Komodo's debugging
functionality.
Using the Python Remote Debugger
When debugging a Python program remotely, the program is executed on the remote machine, and
the debug output is sent to Komodo. Komodo controls the debugging session once the session
starts on the remote machine.
Installing the Python Remote Debugger on the Remote Machine
To debug a Python program remotely, the Python debugger client package must be installed on the
remote machine. Packages are available for download from the Komodo Remote Debugging page.
Alternatively, if your remote machine uses the same platform as the machine on which you installed
Komodo, you can get the Python debugger client files from the pythonlib and bin subdirectories of
the Komodo installation directory for your platform. The locations are as follows:
Windows
<komodo-install-directory>\lib\support\dbgp\pythonlib\
<komodo-install-directory>\lib\support\dbgp\bin
Linux
<komodo-install-directory>/lib/support/dbgp/pythonlib/
<komodo-install-directory>/lib/support/dbgp/bin
Debugging PythonKomodo IDE only
235
Komodo User Guide
Mac OS X
<komodo-install-directory>/Contents/SharedSupport/dbgp/pythonlib/
<komodo-install-directory>/Contents/SharedSupport/dbgp/bin
To install the Python Remote Debugger:
1. The Python remote debugging package requires the logging package, which is included
in Python 2.3 and later. However, if you have an earlier version of Python, you must
download and install the logging package. To verify that the logging package is installed
correctly, run the following command:
python -c "import logging; print 'ok'"
If this command prints the word "ok", you can move to the next step. If this command results
in an ImportError, you need to resolve the error before continuing.
2. Download and unzip the Komodo-PythonRemoteDebugging package for your platform and
Komodo version from the Komodo Remote Debugging page.
3. Set up your Python installation so the dbgp Python package is on your PythonPath. You
can do this by copying the dbgp directory to the site-packages directory of your Python
installation. Alternatively, you can copy the dbgp directory to a convenient location, and then
add that directory to your PYTHONPATH environment variable. For example, on Windows,
if you copied the files to a directory called C:\debugger, enter the following at the command
line:
set PYTHONPATH=%PYTHONPATH%;C:\debugger
To verify that the setup is correct, run the following command:
python -c "import dbgp.client; print 'ok'"
If this command prints the word "ok", you can move to the next step. If this command results
in an ImportError then you need to resolve the error before continuing.
4. Put the bin\pydbgp.py script (bin/pydbgp on Linux and Mac OS X) somewhere convenient.
This is the main script that you run to start a remote debugging session.
Tip: Placing the pydbgp.py script in a directory that is on your PATH environment variable, makes
the script easier to run. On Windows, also make sure that your PATHEXT environment variable
includes .py. On Linux and Mac OS X, ensure that the pydbgp script is executable by running this
command:
chmod u+x path/to/pydbgp
Now try running this command:
pydbgp --help
If the setup is correct, the internal help documentation for running pydbgp is displayed.
Note: The debugging client relies on certain core python library files (e.g. sys, os, getopt,
socket, types). If you have added custom modules to your python site-packages, PYTHONPATH
or sys.path with the same name as those imported by pydbgp, the debugger may not work
Installing the Python Remote Debugger on the Remote Machine
236
Komodo User Guide
properly.
Invoking the Python Remote Debugger
Python remote debugging sessions are started in one of three ways:
• Running the pydbgp.py driver script.
• Calling dbgp.client.brk() directly from within your Python program code.
• An exception reaches the top-level in a Python script that is set up for just-in-time
debugging.
All methods require that the Python remote debugger client package is installed on the remote
machine (see Installing the Python Remote Debugger).
Running pydbgp.py from the Command Line
To start a Python remote debugging session from the command line:
1. On the Debug menu, ensure that Listen for Debugger Connections is checked.
2. Log in to the remote machine. (Note: the "remote" machine can be the same machine on
which Komodo is running.)
3. On the remote machine, run the pydbgp.py driver program with the appropriate options:
python -S path/to/pydbgp.py -d host:port your-script.py
where host:port identifies the port on which Komodo is listening. By default, Komodo listens
for remote debugger connections on port 9000. For example, if the "remote" machine is the
same machine on which Komodo is running, start a debugging session with this command:
python -S path/to/pydbgp.py -d localhost:9000 your-script.py
Other options for using the pydbgp.py driver are available by running:
python -S path/to/pydbgp.py --help
If you are connecting to a DBGP Proxy, you must specify an ide_key value with the -k
option to pydbgp.py. Listener port and DBGP Proxy settings are configurable via
Edit|Preferences|Debugger. Select Debug|Listener Status to view the current settings.
Note: If your application requires that sitecustomize.py is loaded, you must run Python with the -S
argument. The debugger will load site.py at the appropriate time. Komodo is unable to debug
sitecustomize.py due to how Python handles loading of that file.
Note: If you followed the tip described in Installing the Python Remote Debugger the basic
command is:
pydbgp -d host:port your-script.py
Invoking the Python Remote Debugger
237
Komodo User Guide
Calling dbgp.client.brk() in your Python Programs
To break into a remote debugging session directly from within your Python code:
1. On the Debug menu, ensure that Listen for Debugger Connections is checked
2. Import and use the brk() function in the dbgp.client module to set a hard breakpoint.
For example, the following simple Python script will break into a debugging session when
execution reaches the brk() call:
from dbgp.client import brk
def foo():
print "Hello, World!"
brk(host="mybox", port=9000)
print "Goodbye."
3. Run your Python program.
The brk() function supports the following arguments:
• host: machine running Komodo or the DBGP Proxy (uses localhost if unspecified)
• port: port to connect on (uses 9000 if unspecified)
• idekey: key used to identify the debugging session to Komodo or the DBGP Proxy (uses
the value of the USER or USERNAME environment variable if unspecified)
Just-in-Time Debugging
"Just-in-time debugging" allows the remote debugger to connect to Komodo if an uncaught
exception occurs during execution (i.e. if a Python exception reaches the top level of your Python
program). By adding the following lines of code to the beginning of your script, you can trap and
explore the execution state of your Python program when an exception reaches the top level:
from dbgp.client import brkOnExcept
brkOnExcept(host='mybox', port=9000)
If and when an exception reaches the top level of your Python program, a post-mortem debugging
session is started in Komodo at the line at which the exception is raised. The debug session is
automatically placed in interactive mode so that you can inspect the current program environment,
exactly like a Python interactive shell.
The brkOnExcept() function takes the same arguments as brk(). As with brk(),
brkOnExcept() attempts to connect to localhost on port 9000 with an idekey of USER or
USERNAME if no arguments are specified.
CGI Debugging
To debug CGI applications written in Python:
• Configure Python to be used as the CGI (or embedded extension) for your Web server. For
information on configuring Python, refer to the Python documentation.
• Follow the steps outlined in Using dbgp.client Functions in Python Programs to call the
Python remote debugger from within the application. Start the remote application through a
web browser instead of running it from the command line.
Invoking the Python Remote Debugger
238
Komodo User Guide
CGI Debugging
239
Debugging PHPKomodo IDE only
Komodo can be used to debug PHP programs locally or remotely.
Remote PHP debugging encompases all types of PHP debugging not
initiated from within Komodo, including debugging PHP scripts running
under a local web server.
Tutorial
• PHP Tutorial
The instructions below describe how to configure Komodo and PHP for
debugging. For general information about using the Komodo debugger,
see Komodo Debugger Functions.
Debugger commands can be accessed from the Debug menu, by
shortcut keys, or from the Debug Toolbar. For a summary of debugger
commands, see the Debugger Command List.
Komodo uses a PHP debugger extension called Xdebug that must be
installed for Komodo to debug PHP scripts. This can be done manually or
with the PHP Configuration Wizard. Pre-built binaries named
"php_xdebug.dll" (for Windows) or "xdebug.so" (for Linux and Mac OS X)
are provided with Komodo and are also available for download from the
Komodo Remote Debugging page.
See www.xdebug.org/install.php for instructions on compiling Xdebug
from source on other platforms.
Installing PHP
PHP debugging in Komodo will work with PHP 4.3.10 or later, with the exception of versions 5.0.0
through 5.0.2. If you are using PHP 5.0, you will need at least 5.0.3 or greater. Download PHP from
http://www.php.net/downloads.php.
Refer to the PHP website for detailed information on installing PHP.
To debug PHP scripts in a web environment, be sure PHP is operating correctly with your web
server before configuring the debugger extension. Consult the PHP documentation for details on
configuring PHP with various web servers.
Windows
If you are unfamiliar with the installation of PHP, we recommend using the Windows InstallShield
package. To install the PHP executable or SAPI module manually, see the PHP website. Be sure
that the PHP directory is included in your system's PATH.
Linux
Your Linux system may already have PHP installed. Login and type 'php -v' to determine the
version of your current PHP interpreter. If it is earlier than version 4.3.1 (or 5.0.0 through 5.0.2) you
must upgrade. PHP must also support loading dynamic extensions (the default for PHP under
Linux). If it does not, reinstall PHP as per the instructions on the PHP website.
Debugging PHPKomodo IDE only
240
Komodo User Guide
• RPMs are available for Red Hat from www.redhat.com/apps/support/updates.html
• RPMs for for other distributions are available from http://rpmfind.net/.
When installing PHP to a non-default directory, you must add the following argument to the
./configure command:
--with-config-file-path=/path/to/php.ini
where /path/to/php.ini is the full path to the directory where the php.ini file is located.
Mac OS X
Although both the Jaguar and Tiger releases of OS X include a version of PHP, it is recommended
that you obtain a more recent version. Either build from source code, or download a PHP module
for OS X's Apache web server from www.entropy.ch/software/macosx/php/.
Local PHP Debugging
In local debugging mode, Komodo executes PHP directly. While this is convenient for quickly
debugging a PHP script, if your script depends on the availability of a web server, use Remote PHP
Debugging even if the script is running on the same machine as Komodo. This makes it possible to
test the script in its true environment.
When debugging locally, certain environment variables are not available, such as those provided
by the CGI environment. However, it is possible to simulate a CGI environment by specifying CGI
environment variables and CGI input in the Debugging Options dialog box. It is is not necessary to
install a web server to use Komodo's local debugging features. Once you have configured PHP to
use the debugger extension as described below, you can debug your scripts by opening a PHP file
and using Komodo Debugger Functions.
If you receive an error message when attempting to debug a PHP script, check the PHP
troubleshooting section of the Komodo FAQ.
Configuring Local PHP Debugging
Komodo configures itself automatically for local PHP debugging by launching the default PHP
interpreter (i.e. the first in your PATH) and attempting to load the Xdebug extension
(php_xdebug.dll or xdebug.so). If this is successful, a new copy of php.ini is created
automatically with debugging enabled which Komodo will use when debugging PHP scripts locally.
PHP Debugger Config Wizard
If the automatic configuration of PHP debugging is not successful, try configuring PHP debugging
manually using the PHP Configuration Wizard.
To start the wizard:
1. On the Edit menu, click Preferences.
2. Under Languages, select PHP.
Linux
241
Komodo User Guide
3. Click the Debugger Configuration Wizard button to display the wizard's introductory
window.
4. Click Next to begin configuring PHP for debugging.
The wizard will guide you through the steps necessary to configure the debugging extension.
1. Choose Installation:
The first step assumes that you have already installed PHP. If you have more than one
version of PHP installed, choose the version to configure. Browse to the directory containing
the PHP executable or enter the directory path in the Set up this installation field, and
then click Next.
2. Choose PHP INI Path:
Next, choose the php.ini file to be copied and its destination directory. Subsequent changes
to the original file will not be available in the new copy. Modify the new file directly, or rerun
the wizard to copy the changes. Click Next.
♦ On Windows, the php.ini file is generally located in c:\windows, or c:\winnt,
depending on your operating system. It may also be located in the same directory as
your php.exe executable.
♦ On Linux, the default location is /usr/local/lib. It may also be located in the
same directory as your PHP executable.
3. Choose PHP Extension Directory:
Many PHP installations already include a default "extensions" directory. This is where the
debugger extension should be installed. If you have specified an extensions directory in the
.ini file, you do not need to change the path that appears in the Use this extensions
directory field. It is important that the extensions are installed in the same directory as your
PHP installation. If you choose a different location, some extensions may not work. Once
the desired path is set, click Next.
4. Ready to Install:
The final window in the wizard displays the installation options. Confirm that the selections
are correct and click Next. To change any of the selections, click Back.
The PHP Configuration Wizard is only used to configure local debugging. To debug PHP remotely
on a web server, see Configuring Remote PHP Debugging.
If the wizard does not successfully enable local PHP debugging, refer to Configuring Remote PHP
Debugging for more information on manual configuration and Common Local PHP Debugging
Problems for information on common problems.
Starting and Stopping a PHP Local Debugging Session
To step through the script, from Debug menu, select Step In.
To run the script to the first breakpoint, from the Debug menu, select Go/Continue.
Configuring Local PHP Debugging
242
Komodo User Guide
To stop the debugger, from the Debug menu, select Stop.
See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.
Remote PHP Debugging
Remote PHP debugging encompases all types of PHP debugging not initiated from within Komodo,
including debugging PHP scripts running under a local web server.
When a PHP script is run through a web browser, the web server uses the PHP interpreter to
execute the script. If PHP is configured for remote debugging, the server contacts Komodo to start
a debugging session. Komodo controls the debugging (e.g. stepping and breakpoints) once the
session starts. CGI variables are available, as are all other variables that are available when
running PHP under a web server.
Though remote PHP debugging allows PHP scripts to be run in their true environment, it may be
slower than local PHP debugging.
Configuring Remote PHP Debugging
Remote debugging of PHP in Komodo is set up differently depending on how many people will be
debugging scripts on the same web server:
Single User Remote PHP Debugging: In single user remote debugging, PHP is configured to
always look for a specific instance of Komodo on a specific machine. This configuration requires no
changes to the PHP script. Your web server and your instance of Komodo can be on one machine
or two machines
Multi-User Remote PHP Debugging: When multiple users need to debug PHP scripts on a single
web server, use the DBGP Proxy with the remote PHP debugging instructions below. While it is
possible to configure Apache with Virtual Hosting, it is easier to configure multi-user remote PHP
debugging with the proxy.
Remote PHP debugging must be configured manually. The following procedure assumes that you
have already installed PHP.
Step 1 - Copy the Debugging Extension to the Web Server
Before debugging PHP scripts in Komodo, PHP must be configured to use the Xdebug extension
(php_xdebug.dll or xdebug.so).
Find the appropriate extension for the version of PHP you are running and manually copy it into a
directory on the server that the PHP interpreter and web server can access. The Xdebug files can
be found in the php sub-directory of the Komodo installation. For example:
Windows
• File required: php_xdebug.dll
• Source location:
<komodo-install-directory>\lib\support\php\debugging\<PHP-version>
Starting and Stopping a PHP Local Debugging Session
243
Komodo User Guide
or the Komodo Remote Debugging page.
• Destination: the extension_dir as defined in the php.ini file.
Linux
• File required: xdebug.so
• Source location:
<komodo-install-directory>/lib/support/php/debugging/<PHP-version>/
or the Komodo Remote Debugging page.
• Destination: the extension_dir as defined in the php.ini file.
Mac OS X
• File required: xdebug.so
• Source location:
<komodo-install-directory>/Contents/SharedSupport/lib/support/php/debuggin
or the Komodo Remote Debugging page.
• Destination: the extension_dir as defined in the php.ini file.
In the downloadable packages, the extensions are found in version-specific subdirectories of the
unpacked archive.
We recommend installing Xdebug in the existing PHP extensions directory on the web server
(specified by the extension_dir variable in the php.ini file). If you are installing PHP for the first
time, the extension_dir may be set to "./". You should change this to a full, direct path, such as
C:\php\extensions under Windows, or /usr/local/lib/php/extensions under Linux and
Mac OS X.
Step 2 - Edit the Web Server's PHP Configuration
Open the php.ini configuration file on the web server. In the "Dynamic Extension" section, add
the lines specified below.
Note: Xdebug is incompatible with the Zend Optimizer
and Zend Studio Debugger extensions. These extensions
should be commented out in php.ini when configuring PHP
for remote debugging with Komodo.
• Windows
; xdebug config for Windows
zend_extension_ts=c:\path\to\php_xdebug.dll
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.idekey=<idekey>
The php.ini configuration file should be in your operating system directory (e.g.
C:\WINDOWS or C:\WINNT), or in the same directory as php.exe (e.g. C:\PHP). If you
used the PHP Windows installer, this file should be in the correct location.
Configuring Remote PHP Debugging
244
Komodo User Guide
• Linux and Mac OS X
; xdebug config for Linux and Mac OS X
zend_extension=/path/to/xdebug.so
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.idekey=<idekey>
Set remote_port to the same value as the debugging listener port configured in
Edit|Preferences|Debugger (or the system assigned Host Port displayed under Debug|Listener
Status). If Komodo is not running on the same machine as the web server, you also need to set
remote_host to the correct IP address for Komodo.
Restart the web server to load the new configuration.
Step 3 - Verify the Web Server's PHP Configuration
Once the php.ini file is updated, verify that Xdebug is configured by running the following
command:
php -m
If your command-line PHP interpreter uses a different php.ini file (this is often the case) or if you're
not sure which file it uses, create a phpinfo.php file containting the line '<?php phpinfo(); ?>'
in a web server directory to display the configuration in a web browser.
Make sure Xdebug appears in both the PHP and Zend module lists.
Note: Recent versions of PHP are set to buffer program output by default. While debugging, it is
useful to disable output buffering so that results of print and echo statements can be seen
immediately when stepping through code. To disable output buffering, comment out the
output_buffering setting in php.ini with a ";" character, or set it to "off".
Starting and Stopping a PHP Remote Debugging Session
Once remote PHP debugging is configured, the PHP interpreter can contact Komodo and initiate a
remote debugging session when a PHP script is executed on the web server.
To initiate remote debugging from a web browser:
1. Ensure you have configured PHP for your web server, have it properly working, and have
configured PHP and Komodo as described in Configuring Remote PHP Debugging.
2. On the Debug menu, click Listen for Debugger Connections.
3. Open your web browser and access the script you want to debug. Append
"?XDEBUG_SESSION_START=<idekey>" to the end of the URL as a GET argument. The
IDE Key should match the Proxy Key value shown in Debug|Listener Status. For
example:
http://example.org/sample.php?XDEBUG_SESSION_START=jdoe
Configuring Remote PHP Debugging
245
Komodo User Guide
Note: This is only required for the first request. After that, Xdebug tracks the debugging
session with a cookie. For more information on how this works, see
www.xdebug.org/docs-debugger.php#browser_session
4. A PHP debugging session starts in Komodo. On the Debug menu, click Step In or
Go/Continue to run to the first breakpoint.
It is also possible to call XDEBUG_SESSION_START by adding it in an input element of an HTML
form. For example:
<input type="hidden" name="XDEBUG_SESSION_START" value="jdoe" />
To initiate remote debugging from the command line:
1. On the Debug menu, click Listen for Debugger Connections.
2. Set the XDEBUG_CONFIG environment variable. Use the port specified in
Edit|Preferences|Debugger or listed in Debug|Listener Status.
On Windows:
set XDEBUG_CONFIG=remote_port=9000 remote_enable=1
On Linux/Mac OS X:
export XDEBUG_CONFIG="remote_port=9000 remote_enable=1"
3. Run the script using the PHP interpreter:
php -f sample.php
4. A PHP debugging session will start in Komodo. Click Step In to start stepping through the
script or Go/Continue to run to the first breakpoint.
To initiate remote debugging using the DBGP Proxy:
1. From the Debug menu, select Listen for Debugger Connections.
2. Set the XDEBUG_CONFIG environment variable as above. Use the port specified in
Edit|Preferences|Debugger or listed in Debug|Listener Status. Add an IDE Key value to
the XDEBUG_CONFIG environment variable that matches the Proxy Key value shown in
Debug|Listener Status.
On Windows:
$set XDEBUG_CONFIG=remote_port=9000 remote_enable=1 idekey=<USERNAME>
On Linux/Mac OS X:
export XDEBUG_CONFIG="remote_port=9000 remote_enable=1 idekey=<USER>"
3. Run the script using the PHP interpreter:
php -f sample.php
4. A PHP debugging session will start in Komodo. On the Debug menu, Click Step In to start
stepping through the script or Go/Continue to run to the first breakpoint.
Starting and Stopping a PHP Remote Debugging Session
246
Komodo User Guide
Output from the debug session appears in the Bottom Pane of the Komodo Workspace. Komodo
does not support a console for remote debugging. The browser will not show the script output until
debugging is complete.
To stop the debugger:
On the Debug menu, select Stop or pass the XDEBUG_SESSION_STOP variable by appending it to
the URL or adding it to a form (as with XDEBUG_SESSION_START above).
See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.
If you receive an error message while debugging a PHP script that is not caused by the errors in
the script itself, check the PHP troubleshooting section of the Komodo FAQ.
Using xdebug_break()
The xdebug_break() function is used to hard-code a break in a PHP program. It can be used
instead of a Komodo breakpoint. For example:
<?php
echo "<p>Breaks after this line.</p>";
xdebug_break();
echo "<p>Breaks before this line.<p>";
?>
This function breaks the code during a debugging session but will not initiate a new session. Use
xdebug_break() in conjunction with the methods described above for starting debugging
sessions.
Xdebug Logging
To log xdebug sessions on the server, add the following line to the xdebug config section of the
php.ini configuration file:
xdebug.remote_log=/tmp/xdebug.log
...or add remote_log to the XDEBUG_CONFIG environment variable. For example:
export XDEBUG_CONFIG="remote_port=9000 remote_enable=1 remote_log=/tmp/xdebug.org"
You can replace "/tmp/xdebug.org" with any writable directory and the filename of your choice.
Common PHP Debugging Problems
Debugging PHP on OS X
The version of PHP supplied with Mac OS X is not complied with loadable extension support, so it
is not compatible with Komodo's debugger (Xdebug). For PHP debugging on OS X, either build
PHP from source with loadable extension support or use binaries from
http://www.entropy.ch/software/macosx/php/. The 4.3.11 or 5.0.4 for Apache 1 packages have
Using xdebug_break()
247
Komodo User Guide
been found to work well with Komodo PHP debugging.
Debugging PHP on 64-bit Linux
The version of xdebug.so for Linux provided by Komodo is not compatible with 64-bit versions of
PHP. To configure PHP debugging on 64-bit Linux systems, compile Xdebug from source, replace
Komodo-<version>/lib/support/php/debugging/<PHP version>/xdebug.so with the new 64-bit
version, and run the PHP Configuration Wizard.
Zend Optimizer and Zend Studio Debugger
Xdebug is incompatible with the Zend Optimizer and Zend Studio Debugger extensions. If these
extensions are enabled in php.ini, they will not be imported into the copy created by Komodo for
debugging. When configuring Remote PHP Debugging, these extensions should be manually
commented out in php.ini.
Debugging PHP on OS X
248
Debugging RubyKomodo IDE only
Komodo can debug Ruby programs locally or remotely. The instructions
below describe how to configure Komodo and Ruby for debugging. For
general information about using the Komodo debugger, see Komodo
Debugger Functions.
Tutorial
• Ruby Tutorial
Debugger commands can be accessed from the Debug menu, by
shortcut keys, or from the Debug Toolbar. For a summary of debugger
commands, see the Debugger Command List.
Configuring the Ruby Debugger
To specify which Ruby interpreter Komodo uses to debug and run Perl programs:
1. Select Edit|Preferences (OS X: Komodo|Preferences).
2. In the Preferences dialog box under Languages, click Ruby. Komodo searches for Ruby
interpreters on your system and displays them in the drop-down list.
3. If the preferred interpreter is in this list, click to select it. If not, click Browse to locate it.
4. Click OK.
To start a local Ruby debugging session:
On the Debug menu or Debug Toolbar, click Go/Continue or Step In to invoke the debugging
session. See Komodo Debugger Functions for full instructions on using Komodo's debugging
functionality.
Note: Linux users on x86_64 systems will need to install a 64 bit version of the ruby-debug
library (see the Komodo FAQ entry for more information).
Debugging Ruby Remotely
When debugging a Ruby program remotely, the program is executed on the remote system and the
debug output is sent to Komodo. Komodo controls the debugging session (e.g. stepping and
breakpoints) once the session starts on the remote system.
1. Install the Ruby debugger application and associated files on the remote machine. All of
these files are included in /lib/support/dbgp/rubylib beneath the Komodo installation
directory (/Contents/SharedSupport/dbgp/rubylib on ac OS X). Copy rdbgp.rb and the
contents of the DB directory to a convenient location on the remote machine. Note:Some of
these files are shared library files (.so), which are platform specific. If your Komodo
installation is on a different platform, download the Komodo-PythonRemoteDebugging
package for the appropriate platform and Komodo version from the Komodo Remote
Debugging page.
2. Start Komodo on the local machine.
3. On the remote machine, set the dbgdir variable to specify the location of the remote
mahcine directory where you copied rdbgp.rb and its associated files.
Windows
Debugging RubyKomodo IDE only
249
Komodo User Guide
set dbgdir=<Path_To_rbdbgp.rb>
Linux/Mac OS X
dbgdir=<Path_To_rbdbgp.rb>
4. On the remote machine, set the RUBYDB_OPTS variable his supplies the Ruby interpreter
with the information that is necessary to connect to the Komodo application running on the
local machine.
Windows
set RUBYDB_OPTS=remoteport=<ServerName>:<Port>
set RUBYOPT=
Linux/Mac OS X
export RUBYDB_OPTS=remoteport=<Server_Name>:<Port>
unset RUBYOPT
5. Start the debugger and open the program that you want to debug.
Windows
ruby -I%dbgdir% -r %dbgdir%\rdbgp.rb <Program_To_Debug.rb>
Linux/Mac OS X
ruby -I"$dbgdir" -r "$dbgdir"/rdbgp.rb <Program_To_Debug.rb>
The remote file will open in Komodo with the debugger stopped at the first line of executable code.
A yellow arrow indicates the current position. You can now set breakpoints in this file, step through,
and use other Komodo debugging features as if it were a local file. However, you cannot modify the
file.
Setting a Break in your Ruby Code
To break into a remote debugging session directly from within your Ruby code, insert the following:
ENV['RUBYDB_OPTS'] = 'remoteport=<Server_Name>:<Port>'
$:.push('<Path_To_rdbgp.rb>')
require 'rdbgp'
The first two lines set up the environment for remote debugging (similar to steps three and four
above). The third line loads the debugger which breaks immediately by default.
Once the debugger has been loaded, subsequent breaks can be specified in the program with the
Debugger.current_context.stop_next function. It's a good idea to wrap this function in a
begin ... end block in case the module wasn't loaded:
begin;
Debugger.current_context.stop_next = 1;
rescue Exception;
end
Debugging Ruby Remotely
250
Komodo User Guide
These in-code breakpoints can be easily toggled by changing the boolean value (i.e. 1 = enabled, 0
= disabled).
Rubygems and RUBYOPT
Rubygems is the most commonly used framework for managing third-party Ruby modules.
Rubygems is included with the One-Click Installer (available at
http://rubyforge.org/projects/rubyinstaller/). This installer adds the environment variable
RUBYOPT=rubygems to the list of system variables. This is usually correct behavior, as it
automatically enables all your Ruby scripts to use rubygems to find modules. However, it will cause
the Ruby debugger to always step into a file called ubygems.rb (a simple wrapper around
rubygems.rb) when debugging.
There are three ways to avoid this:
• Set a breakpoint on the first line of the main file, and start the debugger with Go instead of
the Step Into.
• In Komodo's Environment preferences, set the RUBYOPT environment variable an empty
string.
• When you start the debugger, choose the Environment tab in the Debugging Options
dialog box, add a new entry for RUBYOPT in the User Environment Variables box, and
leave its value empty.
Debugging Rails Applications
Ruby on Rails applications can be debugged locally or remotely just like any other ruby application.
However, since much of the Rails framework has to run within the debugger, the process is
normally slower than with a standalone ruby program.
Local Rails Debugging
1. Load the pertinent app or controllers files in Komodo.
2. Set breakpoints in the methods where you want to stop.
3. Load the script/server file that you would normally run from the command-line.
4. In the Debugging Configuration dialog, set the Directory field to the top-level directory
containing the apps folder.
5. With the script/server file active, start the debugger.
Remote Rails Debugging
1. Follow the steps described above in Debugging Ruby Remotely to install the ruby debugger
and set the environment variables dbgdir and RUBYDB_OPTS.
2. Start the Rails script/server with the ruby debugger from the top-level directory containing
the apps folder:
Windows
ruby -I%dbgdir% -r %dbgdir%\rdbgp.rb script/server
Setting a Break in your Ruby Code
251
Komodo User Guide
Linux/Mac OS X
ruby -I"$dbgdir" -r "$dbgdir"/rdbgp.rb script/server
The remote files will open in Komodo with the debugger stopped at the first line of executable code.
A yellow arrow indicates the current position. You can now set breakpoints in this file, step through,
and use other Komodo debugging features as if it were a local file. However, you cannot modify the
file.
Remote Rails Debugging
252
Debugging TclKomodo IDE only
Komodo can be used to debug Tcl programs locally or remotely. The
following instructions describe how to configure Tcl debugging. For
general information about using the Komodo debugger, see Komodo
Debugger Functions.
Tutorial
• Tcl Tutorial
Debugger commands can be accessed from the Debug menu, by
shortcut keys, or from the Debug Toolbar. For a summary of debugger
commands, see the Debugger Command List.
Configuring Local Tcl Debugging
Specify the Tcl interpreter Komodo uses to debug and run Tcl programs:
1. On the Edit menu, select Preferences.
2. In the Preferences dialog box under Languages, click Tcl. Komodo searches for Tcl
interpreters in the system PATH and lists all tclsh and wish interpreters available in
separate drop-down lists. If no Tcl interpreters are displayed in the list, check that the
location of the interpreters is specified in your PATH environment variable.
3. If the preferred interpreters are in these lists, click to select them. If they are not, click
Browse to locate them.
4. Click OK.
To start a local Tcl debugging session, click Go/Continue or Step In on the Debugger menu or
toolbar. See Komodo Debugger Functions for full instructions on using Komodo's debugging
functionality.
Remote Tcl Debugging
When debugging a Tcl program remotely, the program is executed on the remote machine and the
debug output is sent to Komodo. Komodo controls the debugging session (e.g. stepping,
breakpoints, and spawnpoints) once the session has been started on the remote machine.
Installing the Tcl Debugger Application on a Remote Machine
To debug a Tcl program remotely, the Tcl debugger application, dbgp_tcldebug.exe (Windows) or
dbgp_tcldebug (Linux and OS X), must be installed on the remote machine. This file is installed in
the tcl subdirectory of the Komodo installation directory for your platform.
Windows
<komodo-install-directory>\lib\support\tcl
Linux
<komodo-install-directory>/lib/support/tcl
Mac OS X
Debugging TclKomodo IDE only
253
Komodo User Guide
<komodo-install-directory>/Contents/SharedSupport/tcl
This application is also available for download from the Komodo Remote Debugging page.
To install the Tcl debugger application on the remote machine:
• If necessary, install a Komodo license.
• Copy the dbgp_tcldebug executable to any convenient directory.
Invoking the Tcl Debugger Application
To debug a Tcl script on a remote machine:
1. In Komodo, select Listen for Debugger Connections from the Debug menu.
2. Log in to the remote machine.
3. On the remote machine, run the dbgp_tcldebug executable from the command line. To
specify command line arguments for the script that you are debugging, simply add those
arguments to the end of the command, after the dbgp_tcldebug arguments.
dbgp_tcldebug -dbgp <komodo_host:port>
-app-file <tcl_program>
-app-shell </path/to/tclsh_or_wish>
The following options are available:
♦ -dbgp: Sets the hostname (or IP address) and port where Komodo or the DBGP
Proxy is running. In Komodo, select Debug|Listener Status to check the current
port setting.
♦ -app-file: Specifies the Tcl program to debug. Program arguments should follow a
"--" delimiter after the Tcl program name (e.g. ... -app-file test.tcl -arg_0 arg_1).
♦ -app-shell: Sets the path to the Tcl interpreter (tclsh or wish).
♦ -help: Displays a complete list of options.
4. A Tcl Debug tab opens in Komodo. Click Step In, or Go/Continue) to run to the first
breakpoint (see Komodo Debugger Functions for full instructions).
Example
Remote Machine (Windows):
• The file dbgp_tcldebug.exe has been copied into the C:\remote_debug directory.
• The Tcl file to be debugged is called test.tcl and is located in the current working
directory.
• The Tcl interpreter is C:\Tcl\bin\wish.exe.
Local Machine:
• The hostname is "mybox".
• The Komodo remote debugging listener port is set to 9000.
In this scenario, the following command is entered on the remote machine:
Installing the Tcl Debugger Application on a Remote Machine
254
Komodo User Guide
C:\remote_debug\dbgp_tcldebug.exe -dbgp mybox:9000
-app-file test.tcl -app-shell C:\Tcl\bin\wish.exe
Invoking the Tcl Debugger Application
255
Debugging XSLTKomodo IDE only
Komodo does not need to be manually configured for local XSLT
debugging. It uses the libxslt and libxml libraries directly to transform
XML documents into HTML, text, or other XML document types. See
www.libxml.org for more information on this XML C parser and toolkit.
Tutorial
• XSLT Tutorial
For general information about debugging with Komodo, see General
Debugger Functions. Debugger commands can be accessed from the
Debug menu, by shortcut keys, or from the Debug Toolbar. For a
summary of debugger commands, see the Debugger Command List.
Using the XSLT Debugger
To debug an XSLT file:
1. Open the XSLT file and set breakpoints.
2. Start the debugger by clicking Go/Continue or Step In on the Debug Toolbar.
3. In the Debugging Options dialog, Select the input XML file
4. Click OK to start the debugger.
The XSLT program, the input XML file, and the results of the transformation appear simultaneously.
By default, Komodo splits the Editor pane horizontally.
• The XSLT program continues to appear in the top tab group.
• The XML input file appears in a new tab below the XSLT program.
• The results of the transformation are displayed in the Output tab.
A yellow arrow on the breakpoint margin shows the current line of execution in both the XSLT and
XML file. Breakpoints can be set in the both files before starting the debugging session, or while
stepping through the code.
Using a Remote XML Input File
To debug using an XML file on a remote server, enter the full URL to the file in the Select the input
XML file field (for example, http://www.example.org/input_file.xml).
XSLT Stepping Behavior
Stepping behavior in the XSLT file is similar to the standard stepping behavior described in
Debugger Stepping Behavior, but the terminology for describing XSLT is slightly different than that
used for scripting languages.
• Step In: Executes the current XSL element or template line and pauses at the following line.
• Step Over: Not applicable. Behaves the same as Step In.
• Step Out: When the debugger is within an XSL element, Step Out will execute the entire
block without stepping through the code line by line. The debugger will stop on the line
following the closing tag of the element.
Debugging XSLTKomodo IDE only
256
Komodo User Guide
Though the current line is highlighted in both the XSLT and XML files, the stepping behavior is only
applicable to the XSLT file.
XSLT Stepping Behavior
257
HTTP InspectorKomodo IDE only
The HTTP Inspector is used to examine HTTP requests and responses as they happen. It runs a
local proxy service to intercepts HTTP traffic and display each transaction.
Transactions highlighted in the Transaction table are displayed in detail in the Request and
Response panes below.
Starting the HTTP Inspector
The HTTP Inspector runs a local proxy for intercepting HTTP traffic. Start the proxy by opening the
HTTP Inspector (Tools|HTTP Inspector) and selecting the Start button on the Inspector toolbar.
Alternatively, set Komodo to start the HTTP Inspector proxy automatically at startup. Under
Preferences|HTTP Inspector, select Run HTTP Inspector in the background when Komodo
starts up. If you want to run the Inspector on a port other than 8080 (the default) specify it in the
Listen on port field.
If you are working behind a web proxy (i.e. at your network gateway) you can specify the hostname
and port of the proxy for the HTTP Inspector to forward connections through. Select Enable proxy
forwarding and enter the hostname and port (e.g. host.example.org:18080) of the proxy. If
no port is specified Komodo will attempt to use port 8080.
Connecting the Browser
Once the HTTP Inspector is running, your browser must be configured to connect to it. Set the
browser's internet connection settings to point to the HTTP proxy on localhost:8080 (default). If
you've set the Inspector to use a different port, use the port specified above in Preferences|HTTP
Inspector. If you are running the browser on a different machine, specify the hostname of the
system running Komodo.
Debugging HTTP connections may require you to switch back and forth from using the Inspector to
making a direct connection to the internet. If this is the case you may find it useful to configure a
separate browser for debugging HTTP, or use a browser plugin (e.g. SwitchProxy Tool for Firefox)
that allows you to change your proxy configuration quickly.
Note: The HTTP Inspector does not unencrypt HTTPS (encrypted) sessions.
Inspecting the HTTP Data
Once Komodo and your browser have been configured to debug HTTP sessions, load the page
you are trying to analyze:
1. If it is not already running, start the HTTP Inspector
2. Load the page in the browser
3. Watch the HTTP transactions (request/response pairs).
4. Select a transaction to view details in the Request and Response panes. A data dump of
the transactions can be seen in the data buffer panes below.
HTTP InspectorKomodo IDE only
258
Komodo User Guide
By default, the Transaction table shows the following columns:
• State: This appears blank for an uninterrupted transaction. If a Break on Request/Response
has been selected, an icon will appear in this column indicating the break state of the
current transaction (Request or Response).
• Time: Time of the transaction.
• Duration: How long the transaction took.
• Method: HTTP method used (GET, POST, etc.)
• Status: Status returned by the server.
• Size: Amount of data transferred in bytes (content-length.
• Content: MIME content-type.
• URL: Full URL of the target.
Break on Request/Response
Selecting Break on every Request
or Break on every Response
in the toolbar will stop on
the appropriate part of the next transaction. The request or response can then be edited before
being submitted. The current break state of the transaction will appear in the State column in the
main Inspector window.
Editing a Request/Response
All fields, headers and data buffers in the Request and Response panes are editable in the
relevant break state.
If the response is returned in a compressed format (i.e. the response headers contain a "gzip"
content-encoding) the unzipped data will be displayed in the data buffer. If any modifications are
made, the data will be re-compressed before being passed back to the browser.
When modifying request or response data, the content-length header will be automatically modified
to match the length of data in the corresponding data buffer.
Rules
Rules perform specified actions when a certain HTTP request or response is detected. They can be
created (New...), edited (Edit...), removed (Delete) and ordered (Move Up and Move Down). The
order of the rules can be important as all matching rules are processed sequentially.
The following parameters can be set for each rule:
• Rule Name: Arbitrary name for the rule.
• Rule Type: Match on a request, a response, or either one.
• Tests: The match criteria for triggering a rule.
♦ Match on all|any of the following: One or more match criteria can be set. This
option selects whether the match should apply to all or any of the match criteria.
♦ Request/Response part to match: The rule can match against the URL, Method,
Status, Version, Header or Data fields of an HTTP Request or Response.
♦ Match type: Use contains for a substring match or regex for a regular expresion
pattern (Python syntax)
Inspecting the HTTP Data
259
Komodo User Guide
♦ Match string: The string or pattern which triggers the rule.
• Actions: Specifies one or more actions to be taken once a rule is triggered. The following
actions are available:
♦ Break: Breaks at the point the rule is triggered. The HTTP Inspector window must
be open for the break to occur.
♦ Delay: Delays the request or response by a specified number of seconds. Use up to
three decimal places to specify milliseconds (e.g. 0.001 = 1 ms). Use literal to
specify the exact value, or random to set a range.
♦ Timeout: Wait for the HTTP timeout.
♦ Modify Field: Change the value of a Method, URL, Client IP, Status or Data.
♦ Set Header: Add a new header or change the value of an existing one.
♦ Remove Header: Remove a named header.
Rules
260
Interactive ShellKomodo IDE only
Komodo's interactive shell implements individual language shells within
Komodo. Shells are used to directly communicate with the specified
language interpreter. Statements, expressions, and code fragments can
be entered independent of program files. The shell can be used as a
stand-alone interactive tool or as a shell that interacts from within a
debugging session.
Tutorial
• Python Tutorial
Feature Showcase
• interactive shell
Stand-Alone Interactive Shell
When the interactive shell is started as a stand-alone tool, use the shell to help test modules and
experiment with new languages or programs. Other uses for a stand-alone interactive shell include:
• prototyping code
• identifying bugs
• experimenting with a library
• programming interactively
• learning new syntax
The interactive shell supports history recall, AutoComplete and CallTips (Tcl only), and custom
colors and fonts.
Debugging with an Interactive Shell
When the interactive shell is started from within a debug session, use the shell to access all
functions and code being debugged. When the shell is closed from within a debug session,
continue the debug process where you left off. Depending on the language used, changes made in
the shell remain in effect for the duration of the debug session. Other uses for an interactive shell
within a debug session include:
• exploring and debugging a program
• adding new code to the program being debugged (language-dependent)
• modifying existing variables using complex expressions
• adding new variables with code
The interactive shell supports history recall, AutoComplete and CallTips (Tcl only), and custom
colors and fonts.
Using the Interactive Shell
Each Komodo interactive shell is associated with a corresponding interpreter and is thus
language-specific. Each time a command or multi-line string is entered into the Shell tab, that code
is sent to the corresponding interpreter for evaluation. The interpreter evaluates the command, and
then returns output and error text.
Interactive ShellKomodo IDE only
261
Komodo User Guide
Setting Shell Preferences
Use the Preferences dialog box to specify the default language to use within an interactive shell.
Other shells can still be accessed via Tools|Interactive Shell.
To set the default shell preference:
1. On the Tools menu, select Interactive Shell|Configure
2. On the Preferred Interactive Shell drop-down list, select the desired language (Python,
Perl, Tcl).
3. Click OK.
Starting the Interactive Shell
The interactive shell can be opened as a stand-alone tool or as a shell inside of a debugging
session.
To start the shell as a stand-alone tool:
• Select Tools|Interactive Shell, and then select the desired language (Python Shell, Tcl
Shell, Perl Shell). Alternatively, click the Shell button on the Workspace toolbar.
The interactive shell opens in a Shell tab in the Bottom Pane beside the Command Output and
Breakpoint tabs.
To start the shell from within a debug session:
• On the active Debug tab, click the Interact (>>) button on the Debug toolbar, or select
Debug|Interact. The Debug tab toggles to a Shell tab. Enter code as desired. To toggle
back to the Debug tab, click the Interact button on the Debug Toolbar.
View debugging and code inspection functions by clicking the "Collapse/Expand Pane" button at
the left side of the Bottom Pane. This splits the shell into a left and right pane. The left pane
performs debugging functions while the right pane contains the interactive shell.
Using Multiple Shells
Open multiple interactive shells to interact with various code snippets from a single language or use
many shells to simultaneously explore a different language in each shell.
Using AutoComplete and CallTips
The Tcl interactive shell displays AutoComplete and CallTips when recognized code and
commands are entered into the shell. Use autocomplete and calltips to limit the amount of typing in
each session. To select a suggested item, press Enter. Use the up and down arrow keys to scroll
through the various options on the screen. To cancel or ignore the suggested autocomplete or
calltip, press Esc.
Komodo can also detect when further data is required at the command prompt. When insufficient
Setting Shell Preferences
262
Komodo User Guide
programming data is entered at the prompt, Komodo displays a language-dependent "more"
prompt. This prompt indicates that the language interpreter requires more information before the
code can run. Once enough data is entered, Komodo executes the code and the standard
language-dependent input prompt returns.
Customizing Colors and Fonts
The Shell tab displays commands, variables, error messages, and all language syntax in the same
scheme as specified in Edit|Preferences|Fonts and Colors. See Customizing Fonts and Colors
for more information.
Viewing Shell History
The code history consists of the ordered, numbered sets of commands entered in the lifetime of the
shell, including interleaved output and error messages. Use the up and down arrow keys to cycle
through the history of all entered commands. When viewing a multi-line command or function, use
the 'Enter' key to select the desired function and then use the arrow keys to cycle through the
multiple lines within that function.
Stopping a Shell Session
To stop an interactive shell session and close the Shell tab, click the X button located in the
upper-right corner of the Shell tab. To stop the interactive shell and keep the Shell tab open, click
the square button, or use the associated key binding.
Clearing the Shell Buffer
To clear the shell buffer, click the Clear Buffer button. There is no limit to buffer size; unless it is
manually cleared, the buffer will continue to increment until the interactive shell session is closed.
Manually clearing the buffer only removes the command history and command results, and has no
effect on the buffer state (such as changes to the working directory, etc).
Using the Python Interactive Shell
The Python shell prompt is a group of three angle brackets >>>. A ... prompt is displayed if Komodo
determines that more information is required before the code can execute. A
prompt is
displayed when input from stdin is required (for example, in a Python shell, enter help()). No
prompt is displayed when program output is sent to the screen. Code errors are displayed in italics.
When a Python interactive shell session begins, a welcome message is printed stating a version
number and copyright notice. The first prompt is printed as follows:
Python 2.2.2 (#37, Nov 25 2002, 13:15:27) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>>
The following example shows a series of Python statements with resulting output:
>>> # Comment: my hello world test
>>> print "Hello World"
Hello World
Using AutoComplete and CallTips
263
Komodo User Guide
>>> x=12**2
>>> x/2
72
>>>
Debugging with the Python Shell
To start a Python shell from within a debug session, click the Interact button, located in the
upper-right corner of the Debug tab. Starting a shell within a debug session enables Interact Mode.
In Interact Mode, view debugging and code inspection functions by clicking the "Collapse/Expand
Pane" button at the left side of the Bottom Pane. This splits the shell into a left and right pane. The
left pane performs debugging functions while the right pane contains the interactive shell. In
Interact Mode, debugging functionality (for example, Run, Step In, Step Out) is not available. To
return to the debugger, click the Interact button again to exit Interact Mode.
Using the Tcl Interactive Shell
The Tcl interactive shell supports the tclsh interpreter. The Tcl shell prompt is a percent character
%. A > prompt is displayed if Komodo determines that more information is required before the code
executes. A % prompt is displayed when input from stdin is required. No prompt is displayed
when program output is sent to the screen. Code errors are displayed in italics. The following
examples show how input, output, and errors are displayed in the Tcl shell:
%puts "Hello World"
Hello World
%
With an error:
%put "hello world"
invalid command name "put"
%puts "hello world"
hello world
%
Debugging with the Tcl Shell
To start a Tcl shell from within a debug session, click the Interact (>>)button, located in the
upper-right corner of the Debug tab. Starting a shell within a debug session enables Interact Mode.
In Interact Mode, view debugging and code inspection functions by clicking the "Collapse/Expand
Pane" button at the left side of the Bottom Pane. This splits the shell into a left and right pane. The
left pane performs debugging functions while the right pane contains the interactive shell. In
Interact Mode, debugging functionality (for example, Run, Step In, Step Out) is not available. To
return to the debugger, click the Interact button again to exit Interact Mode.
Using the Perl Interactive Shell
The Perl interactive shell prompt is a percent character %. A > prompt is displayed if Komodo
determines that more information is required before the code executes. No prompt is displayed
when program output is sent to the screen. Code errors are displayed in italics. The following
examples show how input, output, and errors are displayed in the Perl shell:
Using the Python Interactive Shell
264
Komodo User Guide
%print "Hello World! \n";
Hello World!
%
With an error:
%prin "Hello World! \n";
syntax error
%print "Hello World!!! \n";
Hello World!!!
%
Using Strings, Function Definitions, and Multiple Line Input
Use the Perl shell to enter function definitions, long strings, and specify if and while blocks
interactively. The Perl shell also handles multiple line input delimited by braces, curly braces, single
quotes, and double quotes. The following examples demonstrate this usage.
Example: Using single quotes "''" to enter multiple line input.
% $b = 'abc
> def
> ghi
> jkl'
abc
def
ghi
jkl
%
Example: Using curly braces "{}" to define a function and enter multiple line input.
% sub foo {
>
my $arg = shift;
>
my $arg2 = shift;
>
return $arg + $arg2;
> }
% foo(10, 12)
22
%
Example: Using braces to enter a multiple line string.
% $name = 'Bob'
Bob
% print qq(<html><head><title>
> Browser Window Caption Text
> </title></head><body bg="white">
> <p>Welcome to my fine web site, $name
> </body>
> </html>)
<html><head><title>
Browser Window Caption Text
</title></head><body bg="white">
<p>Welcome to my fine web site, Bob
</body>
</html>
%
Using the Perl Interactive Shell
265
Komodo User Guide
Example: Using a backslash to continue a statement.
% print 'abc ', 'def ', \
> 'ghi'
abc def ghi
%
Example: Using a backslash to continue a statement.
%
3
%
4
%
>
7
$first_long_variable_name = 3
$second_long_variable_name = 4
$third_long_variable_name_to_store_result = $first_long_variable_name + \
$second_long_variable_name
Example: Using a braced construct
% foreach $var (sort keys %ENV) {
>
print "$var = $ENV{$var}\n";
>
}
ALLUSERSPROFILE = C:\Documents and Settings\All Users
COMMONPROGRAMFILES = C:\Program Files\Common Files
COMSPEC = C:\winnt\system32\cmd.exe
LESS = --quit-at-eof --quit-if-one-screen --ignore-case --status-column
--hilite-unread --no-init
MSDEVDIR = C:\PROGRA~1\MICROS~3\Common\msdev98
MSVCDIR = C:\PROGRA~1\MICROS~3\VC98
NETSAMPLEPATH = C:\PROGRA~1\MICROS~1.NET\FRAMEW~1\Samples
OS = Windows_NT
OS2LIBPATH = C:\winnt\system32\os2\dll;
PATH = C:\PROGRA~1\MICROS~3\Common\msdev98\BIN;
PROCESSOR_ARCHITECTURE = x86
PROCESSOR_IDENTIFIER = x86 Family 6 Model 7 Stepping 3, GenuineIntel
PROCESSOR_LEVEL = 6
PROCESSOR_REVISION = 0703
PROGRAMFILES = C:\Program Files
PROMPT = $P$G
SYSTEMDRIVE = C:
SYSTEMROOT = C:\winnt
TEMP = C:\DOCUME~1\toto\LOCALS~1\Temp
TMP = C:\DOCUME~1\toto\LOCALS~1\Temp
USERNAME = toto
USERPROFILE = C:\Documents and Settings\toto
WINDIR = C:\winnt
Debugging with the Perl Shell
To start a Perl shell from within a debug session, click the Interact button, located in the
upper-right corner of the Debug tab. Starting a shell within a debug session enables Interact Mode.
In Interact Mode, view debugging and code inspection functions by clicking the "Collapse/Expand
Pane" button at the left side of the Bottom Pane. This splits the shell into a left and right pane. The
left pane performs debugging functions while the right pane contains the interactive shell. In
Interact Mode, debugging functionality (for example, Run, Step In, Step Out) is not available. To
return to the debugger, click the Interact button again to exit Interact Mode.
Debugging with the Perl Shell
266
Komodo User Guide
Using the JavaScript Interactive Shell
The JavaScript interactive shell is currently only available from within a JavaScript debugging
session. To start an interactive shell from within a JavaScript debug session, click the Interact (>>)
button.
In Interact Mode, the left section of the bottom pane shows the variable viewer tabs while the right
section contains the interactive shell. Debugger stepping functionality (e.g. Run, Step In, Step Out)
is not available.
In this mode, you can enter expressions, define new local and global variables, create functions,
and modify the DOM of the HTML document loaded in the browser.
Example: Entering a simple expression
> 2 + 2
4
>
Example: Setting variables
> a1 = "testing 123"
testing 123
> var a2 = "check check"
>
When variables are declared without a var statement, they are echoed in the shell and appear in
the globals variable tab on the left. When the var statement is used, they are not echoed by the
shell and appear in the locals tab.
Example: Interacting with the browser
> alert(a1 + ", " + a2)
This will cause the browser to spawn an alert pop-up. To change the Title of the page you are
viewing in the browser:
> document.title = "My new title"
My new title
>
Example: Defining a function
> function my_alert(s) {
*
alert("Testing: " + s);
* }
> my_alert(document.title)
>
The "*" character in place of the ">" in the left margin indicates a multi-line statement. The
interactive shell usually doesn't need any special escaping to let you enter a multi-line statement,
but you can put a backslash at the end of a line to explicitly specify line continuation. For example:
Using the JavaScript Interactive Shell
267
Komodo User Guide
> var a2 = 1 \
*
+ 2 + \
*
3
> a2
6
Using the interactive shell while not debugging
While debugging, click Interact to stop the interactive shell, then Go/Continue to run the
JavaScript event from the browser to completion. Once the debugger finishes, Komodo and the
JavaScript interpreter are still connected, so you can resume your interactive shell.
Once you've established a link between Komodo and Firefox, you can use the interactive shell at
any time by switching to Komodo and clicking the Interact (>>) button. Press Interact button to
re-enter the interactive shell. Variables defined in the previous session should still be present.
You're free to keep using the browser, however, the shell does not "follow" the browser as you
move from window to window.
Further information
When using the interactive shell at a true breakpoint, you can use XPath and DOM functions to
quickly find and manipulate parts of the document. In the non-debugging interactive shell, the shell
has access to a subset of the DOM, such as the title.
Subscribe to http://blogs.activestate.com/ericp/ for future postings on DHTML tricks in the
interactive shell.
Using the interactive shell while not debugging
268
Code Intelligence
Komodo's Code Intelligence system is a set of tools that makes browsing, searching, and
programming complex code easier and more accessible. Use the Code Browser to view the
hierarchical code structure within a program file or project. The Code Intelligence system includes
support for Python, Perl, Tcl, PHP, Ruby, and JavaScript. Code Intelligence is comprised of the
following tools:
• Code Browser: A tab that displays a hierarchical view of all code constructs (for example,
variables, methods, imports) in all open files. In the Code Browser, symbols can be sorted
and filtered; the current scope of a symbol can be located. To access the Code Browser,
click View|Tabs|Code Browser. The Code Browser is displayed on the Code tab beside
the Projects tab.
• AutoComplete and CallTips: The Code Intelligence system is used to drive autocomplete
and calltip functionality for Perl, Python, Tcl, Ruby, JavaScript, XSLT, CSS, and XML
(including HTML and DTD).
The Python Tutorial demonstrates the Code Browser and other Code Intelligence tools. See the
Python Tutorial to explore a Python program in Komodo.
Code BrowserKomodo IDE only
Use the Code Browser to view the general program structure of all source files open in the Editor
Pane. For each source file, the Code Browser displays a tree of symbol nodes, including modules,
classes, functions, interfaces, namespaces, imports and variables. In Python, instance attributes
are also displayed. Each node in the tree hierarchy can be expanded to display further detail,
acting as an index to your source code. Symbols can be sorted, filtered, and the current scope of a
symbol can be located. The Code Browser supports the following languages: Python, Perl, PHP,
Ruby, Tcl, and JavaScript.
Code Intelligence
269
Komodo User Guide
Use the Code Browser to:
• View program structure.
• Browse from a listed namespace, command, or variable definition and jump to the actual
source code where it is declared.
• Locate all variables used within a file.
• View a symbol definition signature.
• Find all defined symbols matching a pattern.
Context Menu
Right-click in the Code Browser Pane to access code searching options. The following options are
available:
• Go to Definition: Jumps to the definition of the associated symbol in the editor.
Alternatively, double-click the symbol name in the Code Browser tree. Objects defined
within the file, in user-defined modules, and in the site library are accessible in this way;
objects defined in a language's standard library are not. (See also Editor: Navigating within
Files)
• Copy: Copies the symbol name to the clipboard.
• Sort By File Order: Sorts all symbols in the tree by file order.
• Sort Alphabetically: Sorts all symbols in the tree alphabetically.
Sorting
Use the Sort By button to organize all Code Browser symbols by file order or alphabetically. To
sort all symbols by file order, click Sort By, and then select Sort By File Order from the drop-down
list. To sort all symbols alphabetically, click Sort By, and then select Sort Alphabetically from the
drop-down list. Alternatively, use the context menu (right-click in the Code Browser) to access
sorting options.
Locating Current Scope
Use the Locate Current Scope button to find the scope of a symbol (for example, namespace,
command, or variable definition). To view the scope of a symbol, place the cursor on the desired
symbol in the source code and then click the Locate Current Scope button. The Code Browser
tree opens to the associated scope. Alternatively, click Code|Locate Current Scope in Code
Browser to open the Code Browser tree to the associated scope.
Code BrowserKomodo IDE only
270
Komodo User Guide
Filtering Symbols
The Filter Symbols text box limits the Code Browser display to matching symbols. To filter
symbols in the Code Browser, enter the desired symbol name, or partial name, in the text box.
Press 'Tab' to switch focus between the Filter text box and the Code Browser tree. Press 'Esc' to
clear the current filter pattern.
Object BrowserKomodo IDE only
The Object Browser is currently being re-implemented with Komodo's new Code Intelligence
backend and is not available in this release.
Filtering Symbols
271
DOM ViewerKomodo IDE only
The Document Object Model (DOM) is an interface for dynamically accessing the content,
structure and style of XML and HTML documents. Komodo's DOM Viewer tab displays the DOM
nodes (e.g. elements and attributes) of the current document as a collapsible tree. The DOM
Viewer lets you find, view and jump to any of these nodes quickly.
Navigating the DOM Tree
Double-clicking on a node in the DOM Viewer moves the cursor to the corresponding node in the
document.
The Locate current node button does two things:
• If the window focus is on the DOM Viewer, it moves the cursor in the editor tab to the node
selected in the DOM Viewer.
• If the window focus is on the editor tab, it finds the node in the tree corresponding to the
current cursor position in the document.
The Show/hide attributes button toggles the visibility of element attributes. Attributes are hidden
by default.
Filtering the DOM Tree
Entering text in the Filter box performs an XPath search on the nodes in the tree, limiting the tree
view to matching nodes and their parents.
For example, when viewing an HTML document, entering table in the Filter box might limit the
tree view to the <table ...> element and the parent <body> and <html> elements. If a node
matching the search string is found in a collapsed branch, the branch is automatically expanded.
For documents that use namespace prefixes, like XSLT, use the format prefix:element-name in the
search (e.g. xsl:template).
The Filter box uses the XPath syntax supported in Python's ElementTree.
DOM Resources
More information on various aspects of the Document Object Model can be found here:
• W3C DOM Recommendations: The canonical source for DOM Technical Reports
(specifications).
• What does each DOM Level bring?: Abstracts of the three DOM Level specs by Fabian
Guisset.
• W3 Schools XML DOM Tutorial: A straightforward tutorial with links to an XML DOM object
reference and examples. See also their HTML DOM Tutorial.
DOM ViewerKomodo IDE only
272
Source Code ControlKomodo IDE only
"Source code control" refers to the practice of storing files containing program source code (and
other project artifacts) in a common repository. Using source code control (SCC), multiple
developers can work on the same project (including the same project file) at the same time. The
SCC repository can be queried for a detailed listing of the changes that occurred each time a file
was edited. Files under source code control that are open for editing can also be reverted to their
previous state.
Komodo's SCC integration works in conjunction with the CVS, Subversion and Perforce source
code control systems.
Depots, repositories, branches, and projects cannot be created or configured from within Komodo.
This must be done using the SCC software itself. Komodo's SCC features become available when
files are checked out from the source code repository.
From within Komodo, you can perform the following SCC actions:
• add files to the repository
• remove files from the repository
• compare files in the editor against their repository versions (a "diff")
• show a revision history for a file
• submit files back to the repository
• revert files to their previous state
Additionally, files under Perforce control are recognized by Komodo even when they are not open
for edit. They can be opened via the File menu, SCC context menus (locations described below), or
the SCC toolbar.
Komodo is intended to work in conjunction with these SCC programs; it does not replace them.
TortoiseCVS and TortoiseSVN are useful tools for managing files under source code control from
within Windows Explorer. Perforce provides P4Win, a graphical client for Windows used to view
and manage files in a SCC repository.
Komodo SCC functions are accessible from the following locations:
• Toolbox Context Menu: Right-click a file in the Toolbox to access the Source Control
menu options. Source code control functions can also be performed on Folders in the
Toolbox; right-click a folder and select Source Control on Contents to access the menu.
• Projects tab context menu: Right-click a file in the Project Manager to access the Source
Control menu options. SCC functions can also be performed on Folders in the Toolbox;
right-click a folder and select Source Control on Contents to access the menu. Two
source code control options are available from the Projects tab and Toolbox context menus:
♦ Source Control applies source code functions to the selected file only.
♦ Source Control on Contents applies source code functions to the contents of the
selected project or folder.
• Editor Pane: Right-click a file in the Editor Pane to access the Source Control menu
options.
• Filename Tab: Right-click the filename tab above the Editor Pane to access the Source
Control menu options.
Source Code ControlKomodo IDE only
273
Komodo User Guide
• File Menu: Select the Source Control option from the File menu.
The Source Control submenu options are the same regardless of which method is used to access
the menu.
Using Source Code Control
SCC Toolbar, Menus and Output Tab
Source Code Control Toolbar
Access common source code control commands from the SCC Toolbar at the top of the Komodo
workspace. Refer to the command descriptions below for more information. The toolbar commands
only apply to the file currently active in the Editor Pane.
Source Code Control Menus
To access source code control functions, select File|Source Control.
Invoke source code control context menus by right-clicking files or folders in the following areas:
• Projects tab
• Toolbox
• Editor Pane
Source Code Control Output Tab and Status Messages
The SCC Output tab is located in the Bottom Pane of the Komodo workspace. As you execute
source code control commands, such as editing or checking in files, details of the commands are
displayed on the SCC Output tab.
Error messages and warnings are also displayed on the SCC Output tab. Additionally, error
messages and warnings are displayed on the status bar in the bottom left corner of the Komodo
workspace.
Source Code Control Commands
As described above, source code control commands are invoked from the toolbar, the File menu
and the Source Control context menu. The following commands are available, depending on the
context:
• Add: Add a file from a designated source code directory on your local drive to the source
code repository.
• Edit: Check out a file from the current source code repository.
• Revert Changes: Check the file back into the repository, abandoning any changes made
since it was checked out.
• Remove: Delete the file from both the source code repository and the corresponding local
directory.
• Update: When the local version no longer matches the repository version of a file, select
Using Source Code Control
274
Komodo User Guide
this command to update the local version of the file.
• Diff (Compare Files): Compare the version of a file open in the Editor Pane with the
version in the source code repository. Depending on the setting in Preferences, the diff
display is shown on another Komodo editor tab or in a separate window. If the display style
for diffs (Edit|Preferences|Source Code Control) is set to Create new window, press 'F9'
or select Jump to Corresponding Line to open and/or shift focus to the original file in the
Editor Pane. If viewing a diff in an editor tab, right-click and select Jump to Corresponding
Line to shift focus to the editor tab containing the source code. Selecting this option opens
the source code tab in the Editor Pane if it is not already open.
• History: Show the change history for the current file.
• Commit Changes: Submit the file back to the source code repository.
Under Perforce, to open files for edit from within a Komodo project, you must first add files to the
project using options on the Project menu. To accomplish the same under CVS, use the following
procedure:
1. At the command prompt, enter cvs co <projname> to open working copies of the files.
2. On the Projects tab, right-click the project and select Import from File System.
3. In the Import from File System dialog box, specify the location of the files to be imported
and click Next.
4. Click OK to confirm changes to the project.
File Status Icons
If Perforce, CVS or Subversion is enabled in Komodo's Preferences, the status of files in the source
code repository is indicated by icons that appear on file tabs in the Editor Pane and next to files and
projects on the Projects tab.
The icons can appear in a variety of combinations, depending on the status of the file and where
they are displayed in the Komodo workspace. For example, a green circle next to a padlock on a
tab in the Editor Pane indicates that the file is open for edit and that the version of the file in your
local directory is in sync with the version in the source code repository.
The file is being added to the source code repository.
The file is being deleted from the source code repository.
The file is open for edit.
The version of the file in your local directory is in sync with the version in the source code
repository.
The file is read-only.
The version of the file in your local directory is out of sync with the version in the source code
repository.
There is a conflict between the version of the file in your local directory and the source file that
cannot be resolved by simply syncing your directory with the source code repository. The
discrepancy must be manually resolved.
Source Code Control Commands
275
Komodo User Guide
Refresh Status
To refresh the SCC status of the current file do one of the following:
• Right-click the on file tab or within the editor pane and select Refresh Status
• Right-click on the file in the Project tab and select Refresh Status
• Click Refresh Status on the File menu
• Press 'Ctrl' + 'K', 'R'
To refresh the SCC status of an entire folder, do one of the following:
• Right-click the on the folder and select Refresh Status
• Select the folder in the Project tab and click Refresh Status on the File menu
• Select the folder in the Project tab and press 'Ctrl' + 'K', 'R'
Configuring Source Code Control Integration
Configuring CVS
Basic CVS Configuration
1. If you have not already done so, install the cvs command-line utility on your system.
2. Check out files: Komodo does not have integrated SCC checkout functions. As necessary,
run cvs from the command line (e.g. 'cvs checkout repository ...').
3. Enable CVS support in Komodo: Under Preferences|Source Code Control|CVS and ensure
that the "CVS Integration" option is checked and that the cvs executable is available in your
PATH or is specified with a full pathname.
4. Open any file under CVS control in Komodo.
Komodo should now recognize that the file is under CVS source code control and the SCC menus
and status icons should be enabled. If not, click Refresh Status on the File menu (or Ctrl-K, R) to
force it to reset.
CVS Over SSH
Some CVS repositories (e.g. SourceForge) will only support CVS access over SSH (secure shell).
When accessing these repositories, an SSH client is required. See Configuring SSH Support for
CVS and Subversion below for details on configuring SSH support.
Configuring Subversion
Basic Subversion Configuration
1. If you have not already done so, install Subversion on your system.
2. Check out files: Komodo does not have integrated SCC checkout functions. As necessary,
run svn from the command line (e.g. 'svn checkout URL ...').
3. Enable Subversion support in Komodo: Under Preferences|Source Code
Control|Subversion and ensure that the "SVN Integration" option is checked and that the
svn executable is available in your PATH or is specified with a full pathname.
Refresh Status
276
Komodo User Guide
4. Open any file under Subversion control in Komodo.
Komodo should now recognize that the file is under Subversion source code control and the SCC
menus and status icons should be enabled. If not, click Refresh Status on the File menu (or
Ctrl-K, R) to force it to reset.
Subversion Over SSH
Some Subversion repositories only support Subversion access over SSH (secure shell). When
accessing these repositories, an SSH client is required. See Configuring SSH Support for CVS
and Subversion below for details on configuring SSH support.
Configuring Perforce
Basic Perforce Configuration
1. If you have not already done so, install Perforce on your system.
2. Check out files: Komodo does not have integrated SCC checkout functions. As necessary,
run p4 from the command line (e.g. 'p4 sync path').
3. Enable Perforce support in Komodo: Under Preferences|Source Code Control|Perforce and
ensure that the "Perforce Integration" option is checked and that the p4 executable is
available in your PATH or is specified with a full pathname.
4. Set P4 environment variables: Unless Komodo is always started from a shell with all
necessary P4 environment variables set (e.g. P4CLIENT, P4PORT, P4USER), you will
need to specify them in Komodo's Environment preferences.
5. Open any file under Perforce control in Komodo.
Komodo should now recognize that the file is under Perforce source code control and the SCC
menus and status icons should be enabled. If not, click Refresh Status on the File menu (or
Ctrl-K, R) to force it to reset.
Users of Perforce's P4CONFIG feature may find that Komodo's source code control doesn't work
unless Komodo is started from within the client view of the Perforce repository.
Configuring Preferences
Use the Source Code Control page in Komodo's Preferences to configure Source Code Control
integration. To open the Komodo Preferences dialog box, select Edit|Preferences.
Configuring SSH Support for CVS and Subversion
Tunneling your CVS or Subversion connections over SSH can provide an added level of security
for your repository access. CVS and Subversion use very similar methods for tunneling over an
SSH connection. On Windows, download and install Putty or Cygwin to provide SSH support. Linux
and OS X distributions typically include SSH support.
This is a basic guideline for configuring CVS and Subversion to use SSH, however, because server
configurations can vary, you should consult the documentation for the control system you are
using, or request help from you system administrator.
Configuring Subversion
277
Komodo User Guide
The use of Pageant (on Windows) or ssh-agent (OS X and Linux) with Komodo is strongly
recommended.
Installing and Configuring Putty on Windows
Putty is a free SSH, Telnet and Rlogin client for Windows.
1. Install Putty
Download Putty (version 0.52 or greater) and associated programs from:
http://www.chiark.greenend.org.uk/~sgtatham/putty/
To connect to a server via SSH, the following programs are required:
• putty.exe
• puttygen.exe
• pageant.exe
• pscp.exe
• plink.exe
Ensure that the directory where Putty is installed is specified in your system's PATH environment
variable.
2. Generate the Putty Key
Run the puttygen utility. Configure as follows:
1. Set Parameters: Select either "SSH2 RSA" or "SSH2 DSA".
2. Generate Key Pair: Click the Generate button to generate the key pair. While the key is
being generated, move the mouse pointer around the blank space to provide key
randomness.
3. Enter Key Passphrase: Enter and confirm a passphrase for the key. Remember the
passphrase - it is required later.
4. Save Public Key: Click the "Save public key" button and store the key in a file called
public1.key.
5. Save Private Key: Click the Save private key button and store the key in a file called
private1.key, in the same directory as the public key. Note: The extension .ppk will be
appended to the name specified (i.e. private1.key.ppk).
6. Copy Key Contents: Copy the contents of the public key field (at the top of the dialog box)
to a file named public1-openssh.key. This key is required later.
7. Close puttygen
3. Load and Configure the Putty Authentication Agent
Run the pageant program. This loads the Putty Authentication Agent into the Windows System
Tray.
Right-click the Pageant icon in the Windows System Tray. Select Add Key. Navigate to the
directory where you saved the public and private keys in the previous step, and select the file
Configuring SSH Support for CVS and Subversion
278
Komodo User Guide
private1.key.ppk.
4. Configure Putty To Use Pageant
Run the putty program. Configure as follows:
1. Specify Server: On the Session page of the Configuration form, enter the host name or IP
address of the server.
2. Specify Protocol: On the Session page, in the Protocol field, select the "SSH" protocol.
3. Create Saved Session: In the Saved Sessions field, enter the host name again. Click the
Save button.
4. Configure Connection: on the Connection page of the Configuration form, enter your
username for the server in the Auto-login username field.
5. Configure SSH Protocol: On the SSH page of the Configuration form, specify "2" for the
Preferred SSH protocol version.
6. Enable Agent Forwarding: On the Auth page of the Configuration form, check Allow
agent forwarding. In the Private key file for authentication field, specify the path and
filename of the private key created above (private1.key).
7. Save Session Information: On the Session page of the Configuration form, click the Save
button.
5. Store the Public Key on the Server
You must store the public key file generated in step 2 (public1-openssh.key) on the CVS or
Subversion server.
1. Open Command Prompt Window: Type cmd in the Windows Run dialog box.
2. Copy Public Key to Server: At the command prompt, enter:
pscp c:\path\to\public1-openssh.key [email protected]:public1-openssh.key
...where c:\path\to\public1-openssh.key specifies the location of the key file created in step
two, and [email protected] specifies your username and URL on the remote server.
You are prompted to confirm the legitimacy of the host, and may be prompted to enter your
password for the server.
3. Connect Using Putty: If necessary, run the putty program. In the Saved Sessions field,
double-click the configuration created in Step 4. This establishes a connection to the server.
4. Configure the Key on the Server: After logging on to the server, enter the following
commands to configure the SSH key:
mkdir ~/.ssh
chmod 700 .ssh
cat ~/public1-openssh.key >> ~/.ssh/authorized_keys
rm ~/public1-openssh.key
chmod 600 ~/.ssh/*
5. Log Off and Exit Putty: Enter exit to close the session of the server.
6. Test the Configuration
Restart Putty. In the Saved Sessions field, double-click the configuration created in Step 4. You
should not be prompted to log in. If you are, the configuration failed. Review the steps above and
ensure that they were completed correctly.
Installing and Configuring Putty on Windows
279
Komodo User Guide
Using CVS with Putty on Windows
Use the following additional steps if you are using CVS with Komodo.
7. Check Out a CVS Module
1. Create Local CVS Directory: Create a directory to store a copy of the CVS repository.
2. Copy Files to Local Directory: At a command prompt, enter:
set CVS_RSH=plink
set PLINK_PROTOCOL=ssh
cvs -d :ext:[email protected]:/repository_name co cvs_module
...where [email protected] specifies your username on the CVS server and the
URL of the CVS server, repository_name specifies the name of the repository on the server,
and cvs_module specifies the name of the module in the chosen working repository.
Login is handled by SSH. The files are copied to the local system. These environment
variables do not interfere with non-SSH repositories.
Ensure that these variables are permanently configured in your system environment (for example,
by adding them to the autoexec.bat file or configuring them in the system properties).
8. Using Komodo and CVS
Before starting Komodo, perform the following steps:
• Set PLINK_PROTOCOL=ssh: In the user environment, set the environment variable
PLINK_PROTOCOL to "ssh".
• Set CVS_RSH=plink: In the user environment, set the environment variable CVS_RSH to
"plink".
• Ensure Pageant Is Running: Run the pageant program to enable the authentication
agent. Ensure that the private1.key is loaded.
You can also execute Pageant and load the key via a batch file. For example:
C:\PuTTY\pageant.exe c:\path\to\private.key c:\path\to\private2.key
Using Subversion with Putty on Windows
Use the following additional steps if you are using Subversion with Komodo.
7. Check Out a Subversion Repository
1. Create Local Subversion Directory: Create a directory to store a copy of the Subversion
repository.
2. Copy Files to Local Directory: At a command prompt, enter:
svn checkout svn+ssh://svn.server.com/repository_path/module/ local_path
...where svn.server.com specifies the server domain name of the Subversion server,
Installing and Configuring Putty on Windows
280
Komodo User Guide
repository_path/module specifies the path of the repository on the server, and local_path
specifies the preferred location on your local system for your copy of the repository. The
local_path can be ommited, in which case the local path is the last part of the
repository_path.
Login is handled by SSH. The files are copied to the local system.
Ensure that these variables are permanently configured in your system environment (for example,
by adding them to the autoexec.bat file or configuring them in the system properties).
8. Using Komodo and Subversion
Set the following environment variables in Environment Preferences:
• PLINK_PROTOCOL=ssh
• SVN_SSH=c:/path/to/plink.exe -batch
Specify the full path to plink.exe using forward slashes "/" or escaped back slashes "\\". The
-batch argument is used to prevent plink from prompting for user input. You can specify a specific
private key by adding "-i C:/path/to/private_keyfile". For example:
SVN_SSH="c:/path/to/plink.exe" -i "c:/path/to/private_keyfile"
You can use the Subversion configuration file instead of setting the SVN_SSH environment
variable:
[tunnels]
ssh = $SVN_SSH plink.exe
This permits configuration of different connection types. The config file is located in the Subversion
directory, typically inside the Application Data area of the user's profile directory (eg. C:\Documents
and Settings\USERNAME\Application Data\Subversion). See the Subversion documentation for
more information.
If you use "plink = $SVN_SSH plink.exe" in the tunnels section of the config file, use "svn+plink" for
your checkout url rather than "svn+ssh".
Run pageant to enable the authentication agent. Ensure that the private1.key is loaded. You can
start Pageant and load the key using a batch file. For example:
C:\PuTTY\pageant.exe c:\path\to\private.key c:\path\to\private2.key
Configuring CVS with Windows/Cygwin-SSH or Linux/SSH
To configure CVS to use SSH, refer to
http://forrest.apache.org/docs_0_70/howto/cvs-ssh/howto-cvs-ssh.html.
On all platforms, create an environment variable as follows:
CVS_RSH=ssh
Installing and Configuring Putty on Windows
281
Komodo User Guide
CVS determines when to use SSH, depending on how you check out the modules. If you use the
"cvs login" method with the "pserver" protocol, CVS does not use SSH, even if CVS_RSH=ssh is
set in the environment.
On Windows, also configure the cygwin SSH Agent as follows:
1. Open a cygwin shell.
2. Enter exec ssh-agent bash.
3. Enter ssh-add.
4. To check out a CVS module, enter:
cvs -d :ext:[email protected]:/repository_name co cvs_module
...where [email protected] specifies your username on the CVS server and the
URL of the CVS server, repository_name specifies the name of the repository on the server,
and cvs_module specifies the name of the module in the chosen working repository.
5. Start Komodo within the cygwin shell as follows:
/path/to/komodo/bin/komodo
After completing the configuration steps above, follow these steps to open Komodo with CVS-SSH
enabled:
1. Open a cygwin shell.
2. Enter exec ssh-agent bash.
3. Enter ssh-add.
4. Start Komodo within the cygwin shell as follows:
/path/to/komodo/komodo.exe
Configuring Subversion with SSH on Linux or Mac OS X
Subversion determines when to use SSH depending on how you check out the modules. If you use
http:// or file:/// URIs, Subversion will not use SSH.
To use subversion with SSH, do the following before starting Komodo:
1. Open a shell.
2. Enter exec ssh-agent bash.
3. Enter ssh-add.
4. To check out a Subversion module, enter:
svn checkout svn+ssh://svn.server.com/repository_path/module/ local_path
...where svn.server.com specifies the server domain name of the Subversion server,
repository_path/module specifies the path of the repository on the server, and local_path
specifies the preffered location on your local system for your copy of the repository. The
local_path can be ommited, in which case the local path is the last part of the
repository_path.
5. Start Komodo from within the shell. Komodo inherits the environment set in the shell by
ssh-agent
Installing and Configuring Putty on Windows
282
Komodo User Guide
Refer to http://svnbook.red-bean.com/en/1.0/ch06s03.html#svn-ch-6-sect-3.3 for more detailed
instructions, including information on configuring svn+ssh to be non-interactive (i.e. no password
prompt).
Installing and Configuring Putty on Windows
283
Using the Rx ToolkitKomodo IDE only
Komodo's Rx Toolkit is a tool for building, editing and debugging regular
expressions. Build a regular expression in the Regular Expression pane,
and enter the sample search string in the Search Text pane. Adjust the
regular expression as necessary to produce the desired matches in the
Match Results pane.
Note: Although the Rx Toolkit has a Python back end, most Perl, PHP,
Ruby and Tcl regular expression syntax is also supported.
If you are new to Regular Expressions, see the Regular Expressions
Primer. In addition, online references for Python, Perl, PHP, Ruby, and
Tcl regular expressions are available via the Rx Toolkit's Help menu.
Tutorial
• Regular
Expression
Primer
Feature Showcase
• test a regular
expression
To open the Rx Toolkit, do one of the following:
• On the Standard Toolbar, click
.
or
• On the Tools menu, select Rx Toolkit.
To close the Rx Toolkit:
• Click the "X" button in the top right corner of the Rx Toolkit
window.
Rx Toolkit Quick Reference
• Create and edit regular expressions in the Regular Expression
pane.
• Apply one or more metacharacters to a regular expression by
selecting them from the Shortcuts menu or entering them in the
Regular Expression pane.
• Select a match type using the buttons at the top of the Rx Toolkit
window.
• Apply modifiers to a regular expression by selecting one or more
Modifiers check boxes.
• Test a regular expression against a string by entering text in the
Search Text pane, or by clicking the Search Text pane's Open
button and navigating to a file.
• Right-click a pane in the Rx Toolkit to access a context menu used
to Show/Hide Indentation Guides, Show/Hide Line Numbers,
Show/Hide EOL Markers, Show/Hide Whitespace and turn
Word Wrap on and off. This context menu is not available in the
Match Results pane.
• Select Help|Load Sample Regex and Search Text to reload the
default regular expression and search text if it has been replaced
or deleted.
Using the Rx ToolkitKomodo IDE only
284
Komodo User Guide
• Double-click a result in the Match Results pane to highlight the
corresponding text in the Search Text pane.
Creating Regular Expressions
Use the Rx Toolkit to create and edit regular expressions. Create regular expressions by typing
them in the Regular Expression pane. A regular expression can include metacharacters, anchors,
quantifiers, digits, and alphanumeric characters.
Many of the display characteristics available in the Editor Pane can be enabled in the Regular
Expression field. However, these characteristics must be manually enabled via key bindings. For
example, to display line numbers in the Regular Expression field, press 'Ctrl'+'Shift'+'6'
('Meta'+'Shift'+'6' on Mac OS X) if the default key binding scheme is in effect.
Note: Do not enclose regular expressions in forward slashes ("/"). The Rx Toolkit does not
recognize enclosing slashes.
Adding Metacharacters to a Regular Expression
The Shortcuts menu provides a list of all of the metacharacters that are valid in the Rx Toolkit.
To add a metacharacter to a regular expression:
1. Click Shortcuts to the right of the Regular Expression pane.
2. Select a metacharacter from the list. The metacharacter is added to the Regular
Expression pane.
If you already know the metacharacter you need, just type it in the Regular Expression pane.
Setting the Match Type
The buttons at the top of the Rx Toolkit Window determine which function is used to match the
regular expression to the search text. The options are based on module-level functions of Python's
re module. Choose from the following options:
• Match: Scan the search text for the first instance of a match for the regular expression.
• Match All: Find all matches for the regular expression in the search text and display them
as a series of matches in the Match Results pane.
Creating Regular Expressions
285
Komodo User Guide
• Split: Scan the search text for regular expression matches and split the string apart
wherever there is match. Each match is displayed on a separate line in the Match Results
pane.
• Replace: Scan the text for the first occurrence of the regular expression and replace it with
text specified in the Replacement pane. The Replacement pane is only displayed when
either the Replace or Replace All is selected.
• Replace All: Scan the text for all occurrences of the regular expression and replace them
with the text specified in the Replacement pane. The Replacement pane is only displayed
when either the Replace or Replace All is selected.
Adding Modifiers to a Regular Expression
Add modifiers to regular expression by selecting one or more of the check boxes to the right of the
Regular Expression pane:
Note: You must use the Modifiers check boxes to add modifiers to a regular expression. The Rx
Toolkit does not recognize modifiers entered in the Regular Expression pane.
• Ignore Case: Ignore alphabetic case distinctions while matching. Use this to avoid
specifying the case in the pattern you are trying to match.
• Multi-line Mode: Let caret "^" and dollar "$" match next to newline characters. Use this
when a pattern is more than one line long and has at least one newline character.
• Single-line Mode: Let dot "." match newline characters. Use this when a pattern is more
than one line long and has at least one newline character.
• Verbose: Permit the use of whitespace and comments in regular expressions. Use this to
pretty print and/or add comments to regular expressions.
• Unicode (Python Only): Make the special characters "\w", "\W", "\b" and "\B" dependent on
Unicode character properties.
• Locale (Python Only): Make the special characters "\w", "\W", "\b" and "\B" dependent on
the current locale.
Evaluating Regular Expressions
A debugged regular expression correctly matches the intended patterns and provides information
about which variable contains which pattern.
If there is a match...
• Matches are displayed in the Match Results pane.
• Komodo highlights the search text string in yellow.
If there is no match...
• If a regular expression does not match the test string, an error message is displayed in the
Match Results pane.
• If a regular expression is invalid, the title bar of the Match Results pane becomes red and
details of the error are displayed in that pane.
Setting the Match Type
286
Komodo User Guide
Match Results
If a regular expression collects multiple words, phrases or numbers and stores them in groups, the
Match Results pane displays details of the contents of each group.
The Match Results pane is displayed with as many as four columns, depending on which match
type is selected. The Group column displays a folder for each match; the folders contain numbered
group variables. The Span column displays the length in characters of each match. The Value
column lists the values of each variable.
Modifier Examples
This section shows some sample regular expressions with various modifiers applied. In all
examples, the default match type (Match All) is assumed:
• Ignore Case
• Multi-line
• Single-line
• Multi-line and Single-line
• Verbose
Using Ignore Case
The Ignore case modifier ignores alphabetic case distinctions while matching. Use this when you
do not want to specify the case in the pattern you are trying to match.
To match the following test string...
Testing123
...you could use the following regular expression with Ignore case selected:
^([a-z]+)(\d+)
The following results are displayed in the Match Results pane:
Evaluating Regular Expressions
287
Komodo User Guide
Discussion
This regular expression matches the entire test string.
The ^ matches the beginning of a string. The [a-z] matches any lowercase letter from "a" to "z".
The + matches any lowercase letter from "a" to "z" one or more times. The Ignore case modifier
lets the regular expression match any uppercase or lowercase letters. Therefore ^([a-z]+)
matches "Testing". The (\d+)matches any digit one or more times, so it matches "123".
Using Multi-Line Mode
The Multi-line modifier allows ^ and $ to match next to newline characters. Use this when a
pattern is more than one line long and has at least one newline character.
To match the subject part of the following test string...
"okay?"
...you could use the following regular expression with Multi-line selected:
^(\"okay\?\")
The following results are displayed in the Match Results pane:
Discussion
This regular expression matches the entire test string.
The ^ matches the beginning of any line. The \" matches the double quotes in the test string. The
string matches the literal word "okay". The \? matches the question mark "?". The \" matches the
terminal double quotes. There is only one variable group in this regular expression, and it contains
the entire test string.
Using Single-Line Mode
The Single-line modifier mode allows "." to match newline characters. Use this when a pattern is
more than one line long, has at least one newline character, and you want to match newline
Using Ignore Case
288
Komodo User Guide
characters.
To match the following test string...
Subject: Why did this
work?
...you could use the following regular expression with Single-line selected:
(:[\t ]+)(.*)work\?
The following results are displayed in the Match Results pane:
Discussion
This regular expression matches everything in the test string following the word "Subject", including
the colon and the question mark.
The (\s+) matches any space one or more times, so it matches the space after the colon. The
(.*) matches any character zero or more times, and the Single-line modifier allows the period to
match the newline character. Therefore (.*) matches "Why did this <newline> match". The \?
matches the terminal question mark "?".
Using Multi-line Mode and Single-line Mode
To match more of the following test string...
Subject: Why did this
work?
...you would need both the Multi-line and Single-line modifiers selected for this regular
expression:
([\t ]+)(.*)^work\?
The following results are displayed in the Match Results pane:
Using Single-Line Mode
289
Komodo User Guide
Discussion
This regular expression matches everything in the test string following the word "Subject", including
the colon and the question mark.
The ([\t ]+) matches a Tab character or a space one or more times, which matches the space
after the colon. The (.*) matches any character zero or more times, which matches "Why did this
<newline>". The ^work matches the literal "work" on the second line. The \? matches the terminal
question mark "?".
If you used only the Single-line modifier, this match would fail because the caret "^" would only
match the beginning of a string.
If you used only the Multi-line modifier, this match would fail because the period "." would not
match the newline character.
Using Verbose
The Verbose modifier ignores whitespace and comments in the regular expression. Use this when
you want to pretty print and/or add comments to a regular expression.
To match the following test string...
testing123
...you could use the following regular expression with the Verbose modifier selected:
(.*?)
(\d+)
# this matches testing123
The following results are displayed in the Match Results pane:
Discussion
This regular expression matches the entire test string.
The .* matches any character zero or more times, the ? makes the * not greedy, and the Verbose
modifier ignores the spaces after the (.*?). Therefore, (.*?) matches "testing" and populates
the "Group 1" variable. The (\d+) matches any digit one or more times, so this matches "123" and
populates the "Group 2" variable. The Verbose modifier ignores the spaces after (\d+) and
ignores the comments at the end of the regular expression.
Using Multi-line Mode and Single-line Mode
290
Komodo User Guide
Using Regular Expressions
Once a regular expression has been built and debugged, you can add it to your code by copying
and pasting the regular expression into the Komodo Editor Pane. Each language is a little different
in the way it incorporates regular expressions. The following are examples of regular expressions
used in Perl, Python, PHP and Tcl.
Perl
This Perl code uses a regular expression to match two different spellings of the same word. In this
case the program prints all instances of "color" and "colour".
while($word = <STDIN>){
print "$word" if ($word =~ /colou?r/i );
}
The metacharacter "?" specifies that the preceding character, "u", occurs zero or one times. The
modifier "i" (ignore case) that follows /colou?r/ means that the regular expression will match
$word, regardless of whether the specified characters are uppercase or lowercase (for example,
Color, COLOR and CoLour will all match).
Python
This Python code uses a regular expression to match a pattern in a string. In Python, regular
expressions are available via the re module.
import re
m = re.search("Java[Ss]cript", "in the JavaScript tutorial")
if m:
print "matches:", m.group()
else:
print "Doesn't match."
The re.search() function returns a match object if the regular expression matches; otherwise, it
returns none. The character class "[Ss]" is used to find the word "JavaScript", regardless of whether
the "s" is capitalized. If there is a match, the script uses the group() method to return the
matching strings. Otherwise the program prints "Doesn't Match".
Tcl
This Tcl code uses a regular expression to match all lines in a document that contain a URL.
while {[gets $doc line]!=-1} {
if {regexp -nocase {www\..*\.com} $line} {
puts $line
This while loop searches every line in a file for any instance of a URL and displays the results. Tcl
implements regular expressions using the regexp and regsub commands. In the example shown
above, the regexp is followed by the -nocase option, which specifies that the following regular
expression should match, regardless of case. The regular expression attempts to match all web
addresses. Notice the use of backslashes to include the literal dots (.) that follow "www" and
Using Regular Expressions
291
Komodo User Guide
precede "com".
PHP
This PHP code uses a Perl Compatible Regular Expressions(PCRE) to search for valid phone
numbers in the United States and Canada; that is, numbers with a three-digit area code, followed
by an additional seven digits.
$numbers = array("777-555-4444",
"800-123-4567",
"(999)555-1111",
"604.555.1212",
"555-1212",
"This is not a number",
"1234-123-12345",
"123-123-1234a",
"abc-123-1234");
function isValidPhoneNumber($number) {
return preg_match("/\(?\d{3}\)?[-\s.]?\d{3}[-\s.]\d{4}$/x", $number);
}
foreach ($numbers as $number) {
if (isValidPhoneNumber($number)) {
echo "The number '$number' is valid\n";
} else {
echo "The number '$number' is not valid\n";
}
}
This PHP example uses the preg_match function for matching regular expressions. Other Perl
compatible regular expression functions are also available. If the function isValidPhone returns
true, the program outputs a statement that includes the valid phone number. Otherwise, it outputs a
statement advising that the number is not valid.
Ruby
This Ruby code uses a regular expression that does simple email addresses validation.
puts 'Enter your email address:'
cmdline = gets.chomp
addrtest = /^\w{1,30}\@\w{1,30}\.\w{2,4}$/i
if addrtest.match(cmdline)
puts 'Address is valid.'
else
puts 'Address is NOT valid.'
tries = tries - 1
end
The regular expression is stored in the addrtest variable, which is compared to the cmdline
variable using the match method. The regular expression specifies that the address must have:
• a username part of up to 30 alphanumeric characters
• an "@"
• a domain name of up to 30 alphanumeric characters
Tcl
292
Komodo User Guide
• a "."
• a top-level domain of between two and four alphanumeric characters
It will accept some addresses that are not fully RFC compliant, and will not accept long user or
domain names. A more robust regular expression is:
/^([a-z0-9]+[._]?){1,}[a-z0-9]+\@(([a-z0-9]+[-]?){1,}[a-z0-9]+\.){1,}[a-z]{2,4}$/i
This does not limit the length of the username or domain. It also enforces some additional
requirements:
• only letters, numbers, "." and "_" can be used in the username
• only letters, numbers, and "-" can be used in the username
• "_" and "." cannot be used at the beginning or end of the username
• "-" cannot be used at the beginning or end of the domain name
• the top-level domain can only contain letters
Writing a regular expression that is fully compliant with RFC 822 is quite a bit more complicated.
Ruby
293
Regular Expressions Primer
About this Primer
The Regular Expressions Primer is a tutorial for those completely new to regular expressions. To
familiarize you with regular expressions, this primer starts with the simple building blocks of the
syntax and through examples, builds to construct expressions useful for solving real every-day
problems including searching for and replacing text.
A regular expression is often called a "regex", "rx" or "re". This primer uses the terms "regular
expression" and "regex".
Unless otherwise stated, the examples in this primer are generic, and will apply to most
programming languages and tools. However, each language and tool has it's own implementation
of regular expressions, so quoting conventions, metacharacters, special sequences, and modifiers
may vary (e.g. Perl, Python, grep, sed, and Vi have slight variations on standard regex syntax).
Consult the regular expression documentation for your language or application for details.
What are regular expressions?
Regular expressions are a syntactical shorthand for describing patterns. They are used to find text
that matches a pattern, and to replace matched strings with other strings. They can be used to
parse files and other input, or to provide a powerful way to search and replace. Here's a short
example in Python:
import re
n = re.compile(r'\bw[a-z]*', re.IGNORECASE)
print n.findall('will match all words beginning with the letter w.')
Here's a more advanced regular expression from the Python Tutorial:
# Generate statement parsing regexes.
stmts = ['#\s*(?P<op>if|elif|ifdef|ifndef)\s+(?P<expr>.*?)',
'#\s*(?P<op>else|endif)',
'#\s*(?P<op>error)\s+(?P<error>.*?)',
'#\s*(?P<op>define)\s+(?P<var>[^\s]*?)(\s+(?P<val>.+?))?',
'#\s*(?P<op>undef)\s+(?P<var>[^\s]*?)']
patterns = ['^\s*%s\s*%s\s*%s\s*$'
% (re.escape(cg[0]), stmt, re.escape(cg[1]))
for cg in cgs for stmt in stmts]
stmtRes = [re.compile(p) for p in patterns]
Komodo can accept Python syntax regular expressions in it's various Search features.
Komodo IDE's Rx Toolkit can help you build and test regular expressions. See Using Rx Toolkit for
more information.
Matching: Searching for a String
Regular expressions can be used to find a particular pattern, or to find a pattern and replace it with
Regular Expressions Primer
294
Komodo User Guide
something else (substitution). Since the syntax is same for the "find" part of the regex, we'll start
with matching.
Literal Match
The simplest type of regex is a literal match. Letters, numbers and most symbols in the expression
will match themselves in the the text being searched; an "a" matches an "a", "cat" matches "cat",
"123" matches "123" and so on. For example:
Example: Search for the string "at".
• Regex:
at
• Matches:
at
• Doesn't Match:
it
a-t
At
Note: Regular expressions are case sensitive unless a modifier is used .
Wildcards
Regex characters that perform a special function instead of matching themselves literally are called
"metacharacters". One such metacharacter is the dot ".", or wildcard. When used in a regular
expression, "." can match any single character.
Using "." to match any character.
Example: Using '.' to find certain types of words.
• Regex:
t...s
• Matches:
trees
trams
teens
• Doesn't Match:
trucks
trains
beans
Matching: Searching for a String
295
Komodo User Guide
Escaping Metacharacters
Many non-alphanumeric characters, like the "." mentioned above, are treated as special characters
with specific functions in regular expressions. These special characters are called metacharacters.
To search for a literal occurence of a metacharacter (i.e. ignoring its special regex attribute),
precede it with a backslash "\". For example:
• Regex:
c:\\readme\.txt
• Matches:
c:\readme.txt
• Doesn't Match:
c:\\readme.txt
c:\readme_txt
Precede the following metacharacters with a backslash "\" to search for them as literal characters:
^ $ + * ? . | ( ) { } [ ] \
These metacharacters take on a special function (covered below) unless they are escaped.
Conversely, some characters take on special functions (i.e. become metacharacters) when they
are preceeded by a backslash (e.g. "\d" for "any digit" or "\n" for "newline"). These special
sequences vary from language to language; consult your language documentation for a
comprehensive list.
Quantifiers
Quantifiers specify how many instances of the preceeding element (which can be a character or a
group) must appear in order to match.
Question mark
The "?" matches 0 or 1 instances of the previous element. In other words, it makes the element
optional; it can be present, but it doesn't have to be. For example:
• Regex:
colou?r
• Matches:
colour
color
• Doesn't Match:
colouur
colur
Escaping Metacharacters
296
Komodo User Guide
Asterisk
The "*" matches 0 or more instances of the previous element. For example:
• Regex:
www\.my.*\.com
• Matches:
www.my.com
www.mypage.com
www.mysite.com then text with spaces ftp.example.com
• Doesn't Match:
www.oursite.com
mypage.com
As the third match illustrates, using ".*" can be dangerous. It will match any number of any
character (including spaces and non alphanumeric characters). The quantifier is "greedy" and will
match as much text as possible. To make a quantifier "non-greedy" (matching as few characters as
possible), add a "?" after the "*". Applied to the example above, the expression
"www\.my.*?\.com" would match just "www.mysite.com", not the longer string.
Plus
The "+" matches 1 or more instances of the previous element. Like "*", it is greedy and will match
as much as possible unless it is followed by a "?".
• Regex:
bob5+@foo\.com
• Matches:
[email protected]
[email protected]
• Doesn't Match:
[email protected]
[email protected]
Number: '{N}'
To match a character a specific number of times, add that number enclosed in curly braces after
the element. For example:
• Regex:
w{3}\.mydomain\.com
• Matches:
www.mydomain.com
• Doesn't Match:
Quantifiers
297
Komodo User Guide
web.mydomain.com
w3.mydomain.com
Ranges: '{min, max}'
To specify the minimum number of matches to find and the maximum number of matches to allow,
use a number range inside curly braces. For example:
• Regex:
60{3,5} years
• Matches:
6000 years
60000 years
600000 years
• Doesn't Match:
60 years
6000000 years
Quantifier Summary
Quantifier Description
?
Matches any preceding element 0
or 1 times.
*
Matches the preceding element 0
or more times.
+
Matches the preceding element 1
or more times.
{num}
Matches the preceding element
num times.
Matches the preceding element at
{min, max} least min times, but not more than
max times.
Alternation
The vertical bar "|" is used to represent an "OR" condition. Use it to separate alternate patterns or
characters for matching. For example:
• Regex:
perl|python
• Matches:
perl
python
• Doesn't Match:
Quantifiers
298
Komodo User Guide
ruby
Grouping with Parentheses
Parentheses "()" are used to group characters and expressions within larger, more complex regular
expressions. Quantifiers that immediately follow the group apply to the whole group. For example:
• Regex:
(abc){2,3}
• Matches:
abcabc
abcabcabc
• Doesn't Match:
abc
abccc
Groups can be used in conjunction with alternation. For example:
• Regex:
gr(a|e)y
• Matches:
gray
grey
• Doesn't Match:
graey
Strings that match these groups are stored, or "delimited", for use in substitutions or subsequent
statements. The first group is stored in the metacharacter "\1", the second in "\2" and so on. For
example:
• Regex:
(.{2,5}) (.{2,8}) <\1_\2@example\.com>
• Matches:
Joe Smith <[email protected]>
jane doe <[email protected]>
459 33154 <[email protected]>
• Doesn't Match:
john doe <[email protected]>
Jane Doe <[email protected]>
Character Classes
Character classes indicate a set of characters to match. Enclosing a set of characters in square
brackets "[...]" means "match any one of these characters". For example:
Alternation
299
Komodo User Guide
• Regex:
[cbe]at
• Matches:
cat
bat
eat
• Doesn't Match:
sat
beat
Since a character class on it's own only applies to one character in the match, combine it with a
quantifier to search for multiple instances of the class. For example:
• Regex:
[0123456789]{3}
• Matches:
123
999
376
• Doesn't Match:
W3C
2_4
If we were to try the same thing with letters, we would have to enter all 26 letters in upper and lower
case. Fortunately, we can specify a range instead using a hyphen. For example:
• Regex:
[a-zA-Z]{4}
• Matches:
Perl
ruby
SETL
• Doesn't Match:
1234
AT&T
Most languages have special patterns for representing the most commonly used character classes.
For example, Python uses "\d" to represent any digit (same as "[0-9]") and "\w" to represent any
alphanumeric, or "word" character (same as "[a-zA-Z_]"). See your language documentation for the
special sequences applicable to the language you use.
Negated Character Classes
To define a group of characters you do not want to match, use a negated character class. Adding a
Character Classes
300
Komodo User Guide
caret "^" to the beginning of the character class (i.e. [^...]) means "match any character except
these". For example:
• Regex:
[^a-zA-Z]{4}
• Matches:
1234
$.25
#77;
• Doesn't Match:
Perl
AT&T
Anchors: Matching at Specific Locations
Anchors are used to specify where in a string or line to look for a match. The "^" metacharacter
(when not used at the beginning of a negated character class) specifies the beginning of the string
or line:
• Regex:
^From: root@server.*
• Matches:
From: [email protected]
• Doesn't Match:
I got this From: [email protected] yesterday
>> From: [email protected]
The "$" metacharacter specifies the end of a string or line:
• Regex:
.*\/index.php$
• Matches:
www.example.org/index.php
the file is /tmp/index.php
• Doesn't Match:
www.example.org/index.php?id=245
www.example.org/index.php4
Sometimes it's useful to anchor both the beginning and end of a regular expression. This not only
makes the expression more specific, it often improves the performance of the search.
• Regex:
^To: .*example.org$
Negated Character Classes
301
Komodo User Guide
• Matches:
To: [email protected]
To: [email protected], [email protected]
• Doesn't Match:
To: [email protected], [email protected]
Send a Message To: example.org
Substitution: Searching and Replacing
Regular expressions can be used as a "search and replace" tool. This aspect of regex use is known
as substitution.
There are many variations in substitution syntax depending on the language used. This primer uses
the "/search/replacement/modifier" convention used in Perl. In simple substitutions, the "search"
text will be a regex like the ones we've examined above, and the "replace" value will be a string:
For example, to earch for an old domain name and replace it with the new domain name:
• Regex Substitution:
s/http:\/\/www\.old-domain\.com/http://www.new-domain.com/
• Search for:
http://www.old-domain.com
• Replace with:
http://www.new-domain.com
Notice that the "/" and "." characters are not escaped in the replacement string. In replacement
strings, they do not need to be. In fact, if you were to preceed them with backslashes, they would
appear in the substitution literally (i.e. "http:\/\/www\.new-domain\.com").
The one way you can use the backslash "\" is to put saved matches in the substitution using
"\num". For example:
• Substitution Regex:
s/(ftp|http):\/\/old-domain\.(com|net|org)/\1://new-domain.\2/
• Target Text:
http://old-domain.com
• Result:
http://new-domain.com
This regex will actually match a number of URLs other than "http://old-domain.com". If we had a list
of URLs with various permutations, we could replace all of them with related versions of the new
domain name (e.g. "ftp://old-domain.net" would become "ftp://new-domain.net"). To do this we need
to use a modifier.
Anchors: Matching at Specific Locations
302
Komodo User Guide
Modifiers
Modifiers alter the behavior of the regular expression. The previous substitution example replaces
only the first occurence of the search string; once it finds a match, it performs the substitution and
stops. To modify this regex in order to replace all matches in the string, we need to add the "g"
modifier.
• Substitution Regex:
/(ftp|http):\/\/old-domain\.(com|net|org)/\1://new-domain.\2/g
• Target Text:
http://old-domain.com and ftp://old-domain.net
• Result:
http://new-domain.com and ftp://new-domain.net
The "i" modifier causes the match to ignore the case of alphabetic characters. For example:
• Regex:
/ActiveState\.com/i
• Matches:
activestate.com
ActiveState.com
ACTIVESTATE.COM
Modifier Summary
Modifier Meaning
i
Ignore case when matching exact
strings.
m
Treat string as multiple lines. Allow
"^'' and "$'' to match next to newline
characters.
s
Treat string as single line. Allow ".''
to match a newline character.
x
Ignore whitespace and newline
characters in the regular expression.
Allow comments.
o
Compile regular expression once
only.
g
Match all instances of the pattern in
the target string.
Modifiers
303
Komodo User Guide
Python Regex Syntax
Komodo's Search features (including "Find...", "Replace..." and "Find in Files...") can accept plain
text, glob style matching (called "wildcards" in the drop list, but using "." and "?" differently than
regex wildcards), and Python regular expressions. A complete guide to regexes in Python can be
found in the Python documentation. The Regular Expression HOWTO by A.M. Kuchling is a good
introduction to regular expresions in Pyhon.
More Regex Resources
Beginner:
• Python Library Reference: Regular Expression Operations, ActiveState Programmer
Network (ASPN)
• Python Regular Expressions, Dive into Python, Mark Pilgrim
• Python Cookbook, ActiveState Programmer Network (ASPN)
• Five Habits for Successful Regular Expressions, The O'Reilly ONLamp Resource Center
• Beginner's Introduction to Perl - Part 3, The O'Reilly Perl Resource Center
Intermediate:
• Rx Cookbook, ActiveState Programmer Network (ASPN)
• Regexp Power, The O'Reilly Perl Resource Center
Advanced:
• Power Regexps, Part II, The O'Reilly Perl Resource Center
Language-Specific:
• Perl: http://perldoc.perl.org/perlre.html
• PHP: http://www.php.net/manual/en/ref.pcre.php
• Python: http://docs.python.org/lib/module-re.html
• Ruby: http://www.rubycentral.com/book/ref_c_regexp.html
• Tcl: http://www.tcl.tk/man/tcl8.4/TclCmd/re_syntax.htm
• Javascript:
http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Regular_Expressions
Python Regex Syntax
304
Komodo and the Perl Dev KitKomodo IDE only
Komodo integrates with ActiveState's Perl Dev Kit (PDK), a suite of tools for creating and deploying
applications in Perl.
Perl Dev Kit 6
Users of the Perl Dev Kit 6.x can access PDK tools via the Tools menu (Tools|Perl Dev Kit) or the
Perl Dev Kit Toolbar. The VBScript Converter, Filter Builder and Visual Package Manager options
are displayed by default. The other options (described below) are only available if a Perl file is open
in the Editor Pane. Select the feature from the menu, or click the toolbar, to launch a graphical user
interface for the chosen PDK tool.
• PerlApp - Build an executable file from Perl scripts.
• PerlCtrl - Build Active X controls from Perl scripts.
• PerlNET - Create Perl components and applications that are compliant with Microsoft's
.NET Framework.
• PerlSvc - Convert Perl programs to Windows services.
• PerlTray - Write system tray applications in Perl.
• Filter Builder - Easily construct perl regular expressions and package them as filters.
• VBScript Converter - Convert VBScript code to its functional equivalent in Perl.
Instructions for using these tools can be found in the Perl Dev Kit documentation.
Perl Dev Kit 3.1 to 5.3
Integration with earlier versions of the PDK is available through an optional package installer which
adds the Build Standalone Perl Application option to the Tools menu. To install this extension:
1. Click File|Open|File...
2. Navigate to the /lib/support/modules/ subdirectory of your Komodo installation.
3. Select the perlapp.xpi package and click Open.
4. The Software Installation dialog will appear. Click Install to add the extension.
To use this extension, select Tools|Build Standalone Perl Application with a Perl script open in
Komodo's Editor Pane.
After configuring options using the tabs in the Build Standalone Perl Application dialog box, use the
buttons at the bottom of the dialog box to:
• Add to Toolbox - Once you have created a new script, click this button to add it to the
Toolbox as a run command.
• Build - Create a new build or overwrite an existing build.
• Debug - If the Komodo debugging option is selected on the General tab, click this button to
start the debugger.
Note: When using the Build Standalone Application feature with Perl 5.8.0 on a Linux installation
where the environment is set to use UTF-8, you must add the module 'utf8' on the Modules tab.
This is the equivalent of perlapp --add utf8. The module is not required for Perl 5.8.1 or
Komodo and the Perl Dev KitKomodo IDE only
305
Komodo User Guide
higher.
Configuring the General Tab
The build options for the Perl Dev Kit correspond with the tools described in the documentation
included with your version of Perl Dev Kit.
• Enter the name of the script to build using the PDK - Specify the path and filename of
the source Perl script. This option is equivalent to the -script command-line argument.
• Build the script using - Select the type of output to generate.
• Enter the name of the target executable or control - Specify the path and name of the
output file. This option is equivalent to the -exe command-line argument.
• Dependencies
♦ None - Include all necessary files in the output file, so that it can be run on systems
that do not have Perl56.dll or ActivePerl. This option is equivalent to the
-freestanding command-line argument.
♦ Perl Dll required on target - Reduce the size of the generated executable by
excluding Perl56.dll from the output file. Target systems must have the Perl56.dll
installed. This setting corresponds with the -xclude command-line argument.
♦ ActivePerl required on target - Create an output file to run on systems where
ActivePerl and any modules included via use and require statements are
installed. This option is equivalent to the -dependent command-line argument.
• Verbose build information - Generate detailed output messages while the output file is
being built. This option corresponds to the -verbose command-line argument.
• Hide console (for GUI applications) - Similar to running wperl.exe, this option is useful for
building applications that run in the background. This setting corresponds with the PerlApp
-gui command-line argument and is only available for the PerlApp tool.
• Overwrite existing build - Replace the existing build with a new build. If you attempt to
overwrite a build without selecting this option, a pop-up dialog box warns that the .exe file
already exists. You can then choose to overwrite the file, overwrite the file and enable the
check box, or cancel the command. This option is equivalent to the -force command-line
argument.
• Delete temp files after each run - Freestanding Perl applications, services and controls
sometimes contain embedded DLLs that are extracted and cached in the host system's
temporary directory. Select this check box to delete these files after each run. This setting
corresponds with the -clean command-line argument.
• Debugging - To debug the Perl executable, control or service as it is being built, select the
desired debugger from the drop-down list. If you are not using either the Komodo or PDK
debugger, specify a Hostname and Port for another debugger in the fields provided.
Configuring the Modules Tab
Use the Modules tab to add external modules to the build, and trim unwanted modules.
Specifying Extra Modules For Your Script
To add a module to the output program, enter the name of the module in the Module name field,
and click Add. The module to be added is displayed in the list box above. Remove modules from
the list box using the Delete and Delete All buttons.
Perl Dev Kit 3.1 to 5.3
306
Komodo User Guide
This option corresponds with the -add command-line argument.
Specifying Modules to Trim from the Package
To remove an unwanted module from the build, enter the name of the module in the Modules field,
and click Add. The module to be trimmed is displayed in the list box above. Remove modules from
the list box using the Delete and Delete All buttons.
This option corresponds with the -trim command-line argument.
Configuring the Files Tab
Use the Files tab to add additional files (typically data files used by the embedded program) to the
output file that is extracted when the program runs.
This option corresponds with the -bind command-line argument.
Adding Files
To add a file to the output program, click Add. In the pop-up dialog box, enter the source location of
the file on your system, and the location where the file should be extracted when the output file
runs.
Editing Files
To edit a file that has been added to the output program, click Edit. In the dialog box, as required,
alter the source location of the file on your system, and the location where the file should be
extracted when the output file runs.
Deleting Files
To remove a file that was to be added to the output program, click the file, then click Delete.
Configuring the Version Tab
Use the Version tab to embed version information in the output program. It corresponds to the
-info command-line argument.
To alter any of the version options, select the desired option in the Version field column, and enter
the desired value in the field below. This information is assembled as a version information
(VERINFO) resource and displayed to users if they view the properties for the script in Windows
Explorer.
Configuring the Library Paths Tab
Use the Library Paths tab to add directories to your build. The options on this tab correspond with
the command-line arguments -lib and -blib.
Configuring the Modules Tab
307
Komodo User Guide
Specifying "lib" and "blib" Directories to Include
To add a lib or blib directory to include in an output file, click Add. In the Browse for Folder dialog
box, select the directory path to include, and click OK. The path can contain multiple directories
that are separated in the same way as in the PATH environment variable.
Use Delete and Delete All to remove directories that you do not want to add from the "lib" and
"blib" list boxes.
Configuring the Extra Tab
The Extra tab is for adding icon files as well as manually specifying any additional command-line
arguments.
Specifying Icon files
To include .ico files in a build, click Add. From the Add Icon dialog box, select the icon(s) you want
to add, and click Open. The complete path for the icon file is displayed in the Icon File list box.
This option is equivalent to the -icon command-line argument.
Specifying Additional Command Line Parameters
If you want to specify any command-line parameters in addition to those selected using the options
in the Build Standalone Perl Application dialog box, enter them in the field provided.
Configuring the Library Paths Tab
308
Interpolation Shortcuts and Tab Stops
Interpolation shortcuts are codes embedded in run commands, snippets or templates that, at
"execution" time, get replaced with values. For example, the path and name of the current file can
be inserted via an interpolation shortcut when a run command is executed.
Interpolation shortcuts can be inserted in Run Commands using the drop-down list to the right of
Command field in the "Add Command..." and "Properties" dialog boxes, or entered manually.
When using interpolation shortcuts in snippets or templates, insert the interpolation code using
bracketed syntax. Run commands and snippets can be stored in a project or the Toolbox for
frequent use.
Tab Stop/Replace markers ("«»") are used in snippets and templates as placeholders for inserting
content using the "Tab" key.
Interpolation Code List
The following table shows the interpolation shortcuts available in Komodo. Windows users should
enclose shortcuts for files and directories in double quotes (e.g. "%F") to ensure that spaces in the
file name or file path are interpreted correctly.
Code
Description
%%
a literal percent sign (%) (e.g. %%PATH%% instead of %PATH% on Windows)
%f
the basename of the current file
%b
the basename of the current file without it's extension
%F
the full path and name of the current file
%L
the line where the editing cursor is located within the current file
%d
the base directory of the current file
%D
the entire directory path of the current file
%P
the full path of the active project
%p
the directory path of the active project
%w
the word under the cursor in the editor
%W
URL-escaped word under cursor; replaces characters that are not valid in a query
string, such as spaces and ampersands
%s
the current selection; interpolates the text that is currently selected in the editor
%S
URL-escaped selection; replaces characters that are not valid in a query string,
such as spaces and ampersands
%(perl)
the perl interpreter specified in Komodo's Perl preference
%(php)
the php interpreter specified in Komodo's PHP preference
Interpolation Shortcuts and Tab Stops
309
Komodo User Guide
%(python)
the python interpreter specified in Komodo's Python preference
%(pythonw)
the pythonw interpreter for python scripts that display a GUI (Windows and OS X
only - requires ActivePython)
%(ruby)
the ruby interpreter specified in Komodo's Ruby preference
%(tclsh)
the tclsh interpreter specified in Komodo's Tcl preference
%(wish)
the wish interpreter specified in Komodo's Tcl preference
%(browser)
the browser specified in Komodo's Web Browser preference
%(guid)
a new GUID (Global Unique Identifier)
date *
the current date
%(ask)
ask the user for a value when invoked (see %(ask) Syntax)
%(askpass)
ask the user for a password when invoked (see %(askpass) Syntax)
%(path)
special Komodo directories (see %(path) Syntax)
%(pref)
values from Komodo preferences (see %(pref) Syntax)
%(debugger) runtime properties of the debugger system (see %(debugger)
Basic Interpolation Shortcut Syntax
Interpolation shortcut blocks come in two forms: bracketed and non-bracketed. Run commands use
the non-bracketed format. snippets and templates use the bracketed format.
Non-Bracketed Syntax
The syntax for a non-bracketed interpolation code is:
%<code&gt
For shortcuts with options:
%(<code>:<backref>:<options>...)
For example:
%(perl)
%w
%guid2
%(ask:Your Name:Trent Mick)
The parentheses are optional if the block does not contain spaces. For example, the following two
commands are equivalent:
%ask:Name:Trent
%(ask:Name:Trent)
Interpolation Code List
310
Komodo User Guide
Bracketed Syntax
The syntax for a bracketed interpolation code is:
[[%(<code>:<backref>:<options>...)]]
<code> is one of the codes shown in the table above, <backref> is a number and <options>...
depend on the specific code. Back-references and options are discussed in other sections. The
following are examples of bracketed syntax:
[[%perl]]
[[%w]]
[[%guid2]]
[[%ask:Your Name:Trent Mick]]
With bracketed interpolation codes, the parentheses are always optional. The double brackets
enclose spaces, making parentheses unnecessary. For example, both of the following commands
are valid:
[[%ask:Your Name:Trent Mick]]
[[%(ask:Your Name:Trent Mick)]]
Bracketed interpolation code blocks permit some excess space immediately adjacent to the double
brackets. For example the following are equivalent:
[[%ask:Your Name:Trent Mick]]
[[
%ask:Your Name:Trent Mick]]
[[%(ask:Your Name:Trent Mick)
[[ %(ask:Your Name:Trent Mick)
]]
]]
Basic Interpolation Shortcut Options
The following table shows the standard options available for most interpolation shortcuts. The
%(ask), %(askpass), %(path), %(pref) and %(debugger) shortcuts have their own options and
syntax.
Option Syntax
Description
orask
%(<code>:orask:<question>)
If a value for the shortcut cannot be determined
automatically, the user is prompted when the command
is invoked. The <question> is text that will be displayed
when the user is asked to enter a value.
else
%(<code>:else:<default>)
If a value for the shortcut cannot be determined
automatically, then <default> is used.
Use the %(...:orask) modifier with other interpolation shortcuts to prompt for input if no value
can be determined. For example:
%(s:orask:Element Name)
If there is no selected text, a pop-up dialog box appears with a text field called "Element Name".
Bracketed Syntax
311
Komodo User Guide
See Using Command Query Shortcuts in the Run Command Tutorial for examples of %(ask) and
%(...:orask) shortcuts.
%(date)
A %(date) shortcut is replaced with the current date, formatted according to a given optional format
or the default format.
%(date) Syntax
The syntax of the %(date) shorcut is as follows:
%(date:<backref>:<optional-format>)
[[%(date:<optional-format>)]]
As noted in the Basic Interpolation Code Syntax section, the parentheses are optional. The
<backref> optional parameter is discussed in the Back-references section. The following examples
are valid:
%date
[[%date]]
%(date)
%date:%H:%M:%S
[[%date:%d/%m/%Y %H:%M:%S]]
%(date) Format Option
If no <optional-format> is specified in a date shortcut, the default date format is used. Configure the
default date format using Komodo's Internationalization preferences.
If this format is not appropriate, you can specify a different one using the following date formatting
codes (from Python's time.strftime() method):
Directive Meaning
%a
Locale's abbreviated weekday name.
%A
Locale's full weekday name.
%b
Locale's abbreviated month name.
%B
Locale's full month name.
%c
Locale's appropriate date and time representation.
%d
Day of the month as a decimal number [01,31].
%H
Hour (24-hour clock) as a decimal number [00,23].
%I
Hour (12-hour clock) as a decimal number [01,12].
%j
Day of the year as a decimal number [001,366].
%m
Month as a decimal number [01,12].
Basic Interpolation Shortcut Options
312
Komodo User Guide
%M
Minute as a decimal number [00,59].
%p
Locale's equivalent of either AM or PM.
%S
Second as a decimal number [00,61].
%U
Week number of the year (Sunday as the first day of the week) as a decimal number
[00,53]. All days in a new year preceding the first Sunday are considered to be in
week 0.
%w
Weekday as a decimal number [0(Sunday),6].
%W
Week number of the year (Monday as the first day of the week) as a decimal number
[00,53]. All days in a new year preceding the first Sunday are considered to be in
week 0.
%x
Locale's appropriate date representation.
%X
Locale's appropriate time representation.
%y
Year without century as a decimal number [00,99].
%Y
Year with century as a decimal number.
%Z
Time zone name (or by no characters if no time zone exists).
%%
A literal "%" character.
For more information about Python's time access and conversions, see
http://www.python.org/doc/2.2/lib/module-time.html
%(ask) and %(askpass)
The %(ask) and %(askpass) shortcuts will prompt the user with a pop-up dialog box for a
replacement value. The %(askpass) shortcut is appropriate for prompting for passwords as the
text is obscured in the dialog box and the password is not stored in a most-recently-used list. If a
snippet or run command includes more than one "ask" shortcut, the dialog box shows a field for
each one.
%(ask) and %(askpass) Syntax
The %(ask) and %(askpass) shorcuts can be used without options, or with optional "name" and
"default" values. The syntax is:
%(ask[:NAME:[DEFAULT]])
%(askpass[:NAME:[DEFAULT]])
"NAME" appears next to the corresponding field in pop-up dialog box, and "DEFAULT" is an
optional default value. A "DEFAULT" cannot be specified without a "NAME".
Typical usage of the %(askpass) shortcut would use "Password" for the "NAME" and not set a
"DEFAULT". For example:
%(askpass:Password)
%(date) Format Option
313
Komodo User Guide
As noted in Basic Interpolation Code Syntax, usage of parentheses depends on the context. The
following examples are valid:
%ask
[[%ask:Name]]
%ask:Name:Joe
%(ask:What is Your Name:Joe Smith)
%(ask) and %(askpass) Options
The %(ask) and %(askpass) shortcuts take two optional parameters. The first, <question>, is the
text to display to the user when prompting for the value for that shortcut. The second, <default>, is
the string used to preload the text field. For example:
%(ask:<backref>:<optional-question>:<optional-default>)
[[%(ask:<backref>:<optional-question>:<optional-default>)]]
The <backref> optional parameter is discussed in the Back-references section.
%(path)
The "path" codes are used to provide special directory paths based on the installation of Komodo
that is currently running. These include such items as the common data directory, which may be
necessary if you are building run commands that you intend to work on shared files.
%(path) Syntax
The syntax of the path shortcut is as follows:
%(path:<backref>:<pathName>)
[[%(path:<backref>:<pathName>)]]
%(path) Options
The %(path) shortcut takes one required parameter, "pathName". The pathName may be one of
the following:
Path Name
Meaning
userDataDir
User-specific data directory where Komodo stores various information
and files.
hostUserDataDir
The userDataDir contains some host-specfic directories. This is most
common on systems where user directories are shared and used from
more than one computer.
commonDataDir
The common data directory contains data and files that are shared
between multiple users.
supportDir
Komodo's data support directory. This is somewhere under the
Komodo install dir.
%(ask) and %(askpass) Syntax
314
Komodo User Guide
%(debugger)
The %(debugger) shortcuts are used to provide runtime values from the debugger subsystem in
Komodo. These codes can be used to provide debugging information to applications such as
PerlApp.
%(debugger) Syntax
The syntax of the debugger shortcut is as follows:
%(debugger:<backref>:<value>)
[[%(debugger:<backref>:<value>)]]
%(debugger) Options
The %(debugger) shortcut requires a <value> parameter, which can be one of the following:
Debugger
Value
Meaning
address
The hostname or address Komodo is running on.
port
The TCP/IP port number that the debugger system is listening on.
proxyAddress
The hostname or address of a debugger proxy that Komodo is using.
proxyPort
The TCP/IP port number of a debugger proxy that Komodo is using.
proxyKey
A session key, typically retrieved from the USER environment variable, that the
proxy uses to match debug sessions with a specific running instance of
Komodo.
The <backref> parameter is optional.
%(pref)
The %(pref) shortcut is used to provide values from Komodo's Preferences. The back-end of
Komodo's preference system is undocumented, but you can examine the settings in the prefs.xml
file in the user data directory to find the preference IDs.
%(pref) Syntax
The syntax of the %(pref) shortcut is:
%(pref:<backref>:<prefName>)
[[%(pref:<backref>:<prefName>)]]
Preference names may change between Komodo versions.
%(debugger)
315
Komodo User Guide
Back-References
Back-references are particularly useful for code snippets. You can use back-references to
interpolate the same value any number of times in the snippet. Back-references make it possible to
prompt the user for an input value only once, and then insert that value multiple times. For
example, you could create a snippet that prompts for a value, which would then be entered at
various places in the snippet text.
Back-Reference Syntax
You create a back-referenced set of shortcuts by suffixing the interpolation code with a number.
The syntax for back-reference is as follows:
%(<code><number>:<backref>:<options>...)
[[%(<code><number>:<backref>:<options>...)]]
For example:
%(ask1:Name:Trent)
%w1:else:Foo
[[%guid1]]
All interpolation blocks with the same shortcut/number pairs are part of the same back-reference
set. All members of the same back-reference set will be replaced with the first code block in that
set. For example:
echo Hi there %(ask1:Name:Trent). That name again is %ask1
This opens a pop-up dialog box prompting for one entry, "Name", with a default of "Trent".
Whatever value the user entered for "Name" would then be inserted in two places in the command,
resulting in the following command:
echo Hi there Bill. That name again is Bill
Another useful application of back-references is the "guid" code. A guid code is replaced with a new
GUID (Globally Unique Identifier). Sometimes it is desirable to have the same GUID inserted in
more than one place in a file. In snippets, this can be done by using a code "%guid1" instead of just
"%guid" wherever you want the GUID inserted.
Tab Stops
The Tab Stop/Replace marker changes the behavior of the Tab key when they are present. They
have the following format in a snippet or template:
[[%tabstop:name]]
When the snippet is used or a new file is created from the template, the marker looks like this:
«name»
Back-References
316
Komodo User Guide
The "name" between the chevron characters ("«" and "»") is the default value of the marker. It can
be set to any string (see examples below).
After the snippet is inserted, "Tab" will jump to and select the first marker it finds. The marker can
be replaced with text at this point, or left as the default value. Hitting "Tab" again replaces the
marker and all subsequent markers with the same value with the replacement text or default value.
Here's an example of a "blank" PHP function snippet that uses Tab Stop/Replace markers:
/*
* function «name»
* @param $«arg»
*/
function «name»($«arg») {
«»
}
The «name» marker is the first place "Tab" will stop. It gets replaced with the function name which
is propagated through the rest of the snippet when "Tab" is hit again. The «arg&#187 marker is the
next place "Tab" stops, and is treated the same way.
It is useful to leave the cursor in the snippet window immediately before the first Tab Stop/Replace
marker and select Maintain selected text or cursor position after insertion. If the cursor is left at
the end of the snippet, "Tab" will not encounter the markers.
Here's another example of a short snippet for HTML:
<«div»>[[%s]]</«div»>
The current selection is wrapped in an element (a "div" by default). Hitting "Tab" after insertion will
select the first "div" for replacement. If it is replaced, the closing tag will be changed when "Tab" is
hit again. If it is not replaced, "div" will be used as the element type.
Tab Stops
317
Customizing Komodo
Komodo's preferences are used to set the default behavior of Komodo. Preferences can be set for
various aspects of Komodo functionality, such as editor behavior, preferred language interpreters,
the Komodo workspace layout, etc.
Some preferences can also be configured on a per-file basis. For example, the configuration of line
endings, indentation style and word wrap can be configured for individual files. File-specific settings
override the default preferences described in this section. To configure file-specific defaults, see
File Properties and Settings in the File section of the Komodo documentation.
To display the Preferences dialog box, on the Edit menu, click Preferences. Or, in Komodo for
Mac OS X, on the Komodo menu, click Preferences.
Appearance Preferences
Use the Appearance preferences to customize the default layout of the Komodo workspace. The
functions described below can also be changed using keyboard shortcuts; see Key Bindings for
more information. To customize the Komodo workspace, select Edit|Preferences|Appearance.
Configure the following options:
Toolbar Configuration
• Show button text: Descriptive text displayed beneath toolbar icons.
• Show standard toolbar: Toolbar with commonly used functions, for example, Open and
Save.
• Show debug toolbar: Toolbar with debugging functions, for example, Step Over and Step
Through.
• Show source code control toolbar: Toolbar with source code control functions, for
example, Update and Revert.
• Show macro toolbar: Toolbar containing commands for recording macros.
Initial Page Configuration
• Show Komodo Start Page on startup: Select to display the Start Page in the Editor Pane
when Komodo launches.
• Hide Tutorials Pane: Select to hide the Tutorials section of the Komodo Start Page.
• Hide Quick Links Pane: Select to hide the Quick Links section of the Komodo Start Page.
• Hide Tip of the Day Pane: Select to hide the Tip of the Day section of the Komodo Start
Page.
Most Recently Used
• Number of Projects: The number of projects displayed on Komodo's Start Page, and on
the Recent Projects menu.
• Number of Files: The number of files displayed on Komodo's Start Page, and on the
Recent Files menu.
Customizing Komodo
318
Komodo User Guide
Code Intelligence Preferences
Code Intelligence refers to the system that provides autocomplete, calltips, and the Code
Browser.
• Enable automatic autocomplete and calltip triggering while you type: Toggles
automatic autocomplete triggering and calltips (Enabled by default). Click OK to save
changes.
• Enable autocomplete fill-up characters: Toggles"fill-up" characters. Typing certain
characters, like '(' or '.', during an autocomplete session will trigger insertion of the current
completion before the character itself is inserted.
API Catalogs
Komodo uses API catalogs to provide autocomplete and calltips for 3rd-party libraries. In the API
Catalogs panel, select the libraries that you use in your code to enable them. Selecting multiple
API catalogs for a particular language can yield confusing results if there are overlapping
namespaces, classes or function names.
Debugger PreferencesKomodo IDE only
To customize general debugging functions, select Edit|Preferences|Debugger. For
language-specific settings (such as interpreter selection), see the Language preference.
Debugging Session Startup
• When starting a new debug session: Specify whether Komodo should Ask me what files
to save (which displays a list of changed files); Save all modified files (whereby all
modified files are automatically saved); or Save no files (whereby the debugging session
starts without saving any files).
• When receiving a remote debugging connection: Specify whether Komodo should Ask
me to allow connection (Komodo prompts to allow the connection request); Allow the
connection (Komodo accepts the connection without prompting); or Refuse the
connection (Komodo refuses the connection without prompting).
• Initial break behavior: Specify whether Komodo should Break on first executable line or
Run to first breakpoint. Breaking on the first line of code is useful for adding breakpoints if
none have been set yet (e.g. in a non-local JavaScript file).
• Skip debugging options dialog: To block the display of the debugger dialog box when the
debugger is invoked, check this box. Using the 'Ctrl' key in conjunction with a debugger
command key toggles the value specified here. However, commands invoked from the
Debugger drop-down menu always use the convention specified here.
Debugging Session Shutdown
• Confirm when closing debugger session tab: If the debugger is running when you
attempt to close the Debug tab, this check box determines whether you are prompted to halt
the debug session and close the tab, or whether this happens without prompting.
Debugger Editor Options
Code Intelligence Preferences
319
Komodo User Guide
• Show expression values in hover tooltip: If this is enabled, while you are debugging, you
can hover the mouse pointer over a variable or expression in Komodo to see a tooltip with
the value of that variable.
• Try to find files on the local system when remote debugging: By default, when Komodo
performs remote debugging, it retrieves a read-only copy of the file to be debugged from the
debug engine. When this check box is selected, however, Komodo first searches for the
debugger file on the local system. While it is probably safe to leave this check box selected
for all of your remote debugging, there is a slight possibility that Komodo retrieves the
wrong file if remote debugging is performed on another machine. If, by chance, there is a
file on your local system with the same name and location as the file on the remote system,
Komodo uses the local file. This would only happen if the names and locations were
identical (e.g., if both machines contained a file called "C:\foo\bar\baz.pl").
Debugger Connection Preferences
Debugger Connection Options
• Komodo should listen for debugging connections on:
♦ a system provided free port: Komodo assigns a port automatically. This is useful
on multi-user systems where multiple instances of Komodo are running.
♦ a specific port: Set the port manually. The default is 9000.
• I am running a debugger proxy and Komodo should use it: Select this to use a
debugger proxy. The proxy must be started separately at the command line.
• Proxy Listener Address: The interface IP address and port Komodo uses to listen for
connections from the proxy. By default, the debugger proxy uses port 9000 to listen for
remote debuggers and port 9001 to listen for connections from Komodo.
• Proxy Key: This identifies which instance of Komodo requires the connection. If blank, the
USER or USERNAME environment variable is used.
Advanced Debugger Preferences
The Children per page, Variable Data retrieved, and Recursive Depth retrieved settings are for
fine tuning data displayed in the Variables tabs in the debug output pane. The default values
should generally be kept.
Directory Import
These preferences define how Komodo imports files and directories. The following import options
are available:
• Live Import: Keep the imported directories and files current with the file system via Live
Folders. By default, new projects use the base directory in which they are created as the
project's root directory and import all files and directories recursively. Files and directories in
the project are kept synchronized with the filesystem. For example, when new files are
added to a directory in the project, they will automatically appear in the corresponding Live
Folder in the project. This setting can be overridden in a particular Project's scope in Project
Properties and Settings.
• Directory to import from: Specify the directory from which you want to import files. Use the
Browse button to navigate the file system.
Debugger PreferencesKomodo IDE only
320
Komodo User Guide
• Files to include: Specify the filenames to include. Use wildcards ("*" and "?") to specify
groups of files. Separate multiple file specifications with semicolons. If the field is left blank,
all files in the specified directory are imported.
• Files and directories to exclude: Specify the file and directory names to exclude. Use
wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with
semicolons. If the field is left blank, no files in the specified directory are excluded.
• Import Subdirectories Recursively: Select this check box to import directories (and files
contained in those directories) located beneath the directory specified in the Directory to
import from field. This check box must be checked in order to specify the "Import Directory
Structure" option as the Type of folder structure to create.
• Type of folder structure to create:
♦ Import directory structure: If the Import Subdirectories Recursively box is
selected and this option is selected, Komodo creates folders within the project that
represent imported directories. Thus, the directory structure is preserved within the
project.
♦ Make a folder per language: If this option is selected, imported files are organized
into folders according to the language indicated by file pattern in the filename. File
associations are configured in the Komodo Preferences. Each folder is named after
the associated language, for example, "Perl files", "XML files", etc. Files that don't
correspond to a known file pattern are stored in a folder called "Other files".
♦ Make one flat list: If this option is selected, all the imported files are placed directly
under the project from which the Import from File System command was invoked.
These settings apply to all new projects in Komodo. They can be overridden in:
• the specific project's Directory Import settings
• the Directory Filter properties (Live Folders)
• the Import from Filesystem settings (Virtual Folders).
Editor Preferences
To configure editing preferences, select Edit|Preferences|Editor.
General Preferences
• Show whitespace characters: Display or hide whitespace characters in the editor. Spaces
are displayed as dots; tab characters appear as right arrows.
• Show end-of-line characters: This option sets the default for displaying end of line
markers. Display can also be toggled using the View|View EOL Markers menu option.
• Show line numbers: This option sets the default for displaying line numbers. If enabled,
line numbers are displayed on the left side of the Editor Pane. Line numbers can also be
toggled using the View|View Line Numbers menu option.
Options set through the Preferences dialog box are the default for all files opened in Komodo.
Some display characteristics can be assigned to individual files.
Confirmation Dialogs
When files that are opened in the Komodo editor are changed by another application, Komodo can
be configured to respond in various ways:
Directory Import
321
Komodo User Guide
• Detect when files are changed outside the environment: When this option is enabled,
Komodo pays attention to changes made to files outside the Komodo environment.
• If files have been changed: When files are changed outside Komodo, select whether
Komodo should Ask me what files to reload (prompt for reload confirmation); Reload all
files (reload without prompting); or Reload no files (do nothing).
• If files have been deleted: When files are deleted outside Komodo, select whether
Komodo should Ask me what files to close (prompt for close confirmation); Close all files
(close without prompting); or Close no files (do nothing).
If Ask me what files to reload Ask me what files to close are selected, the prompt is displayed
when:
• changing between tabs in the editor
• switching back to Komodo from another application
• saving a file
• deleting a file
Scrolling
The Scrolling setting determines the number of lines that are be displayed above or below the
editing cursor. As the editing cursor moves, the number of lines specified here are displayed
between the cursor and the top or bottom of the Editor Pane. You can also set the horizontal scroll
bar width by entering the desired size in pixels.
Incremental Search
These options set the defaults for the Incremental Search feature.
• Matches Case: Specify whether Incremental Search should be case sensitive.
• Uses: Specify the search syntax type. Plain Text exactly matches the search string;
Regular Expressions interprets the search text as a regular expression; Wildcard
interprets asterisk and question mark characters as wildcards.
Configuring Key Bindings
Most Komodo functions can be invoked via key bindings. These key bindings can be customized.
To view an HTML list of the key bindings currently in effect, select Help|List Key Bindings.
On Linux systems, key bindings defined in the window manager (including default key bindings)
take precedence over Komodo key bindings. If certain keys or key combinations do not work as
expected in Komodo, check the window manager's key binding scheme. In the case of conflicts,
change either the Komodo key bindings or the window manager key bindings.
To configure key binding defaults, select Edit|Preferences|Editor|Key Bindings. By default, menu
key bindings are accessed using 'Alt' key combinations on Windows and Linux. For example, the
File menu is opened via 'Alt'+'F'. Select Remove Alt-<letter> shortcuts from menus to disable
menu access via these key bindings. The 'Alt' key still activates the File menu.
Key Binding Schemes
Editor Preferences
322
Komodo User Guide
Key binding "schemes" are sets of pre-configured key bindings. Click the links below to view a list
of key bindings for each of the schemes.
• Windows/Linux: Consistent with standard key bindings on Windows and Linux.
• Mac OS X: Consistent with standard key bindings on Mac OS X.
• Emacs: Contains many of the most commonly used Emacs key bindings.
• Vi: Contains many of the most commonly used Vi key bindings. Requires Vi emulation.
Pre-configured schemes cannot be modified. When you attempt to modify a key binding, you are
prompted to make a copy of the scheme with a new name before making changes.
Remove Alt-<letter> shortcuts from menus
Some Emacs key bindings use 'Alt'+'letter' combinations that are also used to access Komodo
menus. To avoid this conflict, select Remove Alt-<letter> shortcuts from menus.
Vi Emulation
Vi emulation mimics the modal behavior of the Vi editor. Selecting Enable Vi emulation when a
scheme other than Vi is selected prompts you to create a new scheme. This scheme is based on
the current scheme with the Vi emulation behavior added.
Schemes created with Vi emulation enabled (including the default Vi scheme) will always require Vi
emulation. The Enable Vi emulation checkbox cannot be toggled.
Modifying Key Bindings
To alter or view a specific key binding, scroll the Commands list or enter characters in the filter
field. If multiple key bindings are assigned to a single command, the Current Key Sequence field
displays as a drop-down list. Click the Clear button to delete the key binding displayed for the
selected command; click Clear All to delete all key bindings for the selected command.
To add a new key binding for the selected command, enter the desired key binding in the New Key
Sequence field. If the key sequence is already assigned to another command, the current
assignment is displayed in the Key Sequence Already Used By field. Click Change to update the
key binding displayed in the Current Key Sequence field; click Add to make the new key binding
an additional key binding. If the key binding is already assigned, the original assignment is cleared.
Key Bindings for Custom Components
Custom key bindings can be assigned to the following types of components:
• Open Shortcuts
• URLs
• Run Commands
• Macros
• Snippets
• Templates
When the key binding associated with a component is invoked, it has the same action as
Configuring Key Bindings
323
Komodo User Guide
double-clicking the component in the Toolbox or Projects tab.
Key bindings assigned to components in a project are only available for the active project. Key
bindings for Toolbox components are always available.
To assign a key binding to a component, or to alter or delete an existing key binding, right-click the
desired component in the Toolbox or Projects tab to display the Properties dialog box, then click
the Key Binding tab. Configure as described above.
Configuring Indentation
From the Edit menu, select Preferences, then click Editor|Indentation.
• Auto-Indent Style: Choose from one of three indentation styles:
♦ Use Smart Indent: Komodo automatically anticipates logical indentation points,
based on language cues (such as open braces).
♦ Indent to first non-empty column: Komodo maintains the current level of
indentation.
♦ Don't auto-indent: Select to prevent all forms of automatic indentation.
• Auto-adjust closing braces: Komodo automatically aligns closing braces with
corresponding opening braces.
• Show indentation guides: Select to display indentation markers (grey vertical lines). An
indentation marker is displayed every time the number of spaces on the left margin equals
the value specified in the Number of spaces per indent field.
• Allow file contents to override Tab settings: If selected when files are open, Komodo
uses the indentation settings saved in the file, possibly overriding the other preferences. If
de-selected, Komodo uses the preference configuration regardless of the indentation values
in the file.
• Prefer Tab characters over spaces: Komodo displays Tab characters wherever possible,
according to the values specified in the Number of spaces per indent and the Width of
each Tab character fields. When the 'Tab' key is pressed, Komodo inserts indentation up
to the next indent width. If the new indentation is a multiple of the Tab width, Komodo
inserts a Tab character. Example: With a Tab width of 8 and an indent width of 4, the first
indent is 4 spaces, the second indent is a Tab character, and the third indent is a Tab
character plus 4 spaces.
Tab and indent widths are specified as follows:
• Number of spaces per indent: Number of spaces Komodo inserts on the left margin when
indenting a line of code.
• Width of each Tab character: Number of spaces that are equal to a Tab character.
• Fold mark style: Use the drop-down list to select the style of node used in code folding.
• Use horizontal line on folds: Displays collapsed code with fold marks; a thin line also
spans the width of the Editor Pane.
• 'Backspace' decreases indentation in leading whitespace: If this option is enabled,
pressing 'Backspace' clears an entire indentation, rather than a single space, if there is
nothing between the editing cursor and the left margin. For example, if the number of
spaces per indent is set to four, and there are five spaces between the left margin and the
editing cursor, pressing 'Backspace' once clears one space; pressing 'Backspace' a second
time clears four spaces.
Configuring Indentation
324
Komodo User Guide
• Restore fold state on document load (slows down file opening): If this option is
enabled, the current state of code folding is remembered when a file is closed, and
reinstated when the file is next opened.
Options set through the Preferences dialog box are the default for all files opened in Komodo.
Some indentation characteristics can be assigned to individual files.
Smart Editing
Background Syntax Checking
Background syntax checking validates code against the language interpreter as you type. (If Code
Intelligence is enabled for Python, the code intelligence database is used to validate Python code.)
Syntax errors and warnings are underlined in the Editor Pane. See Background Syntax Checking
for more information.
By default, Komodo performs a background syntax check one second (1000 msecs) after you stop
typing. In very large files, this background process can slow down editing. If you notice slowness in
the editor pane, try extending the delay or disabling background syntax checking. Syntax checking
can be run manually by clicking the syntax checking icon ( or ) in the status bar.
The level of background syntax checking for Perl is determined by the setting on the Perl Language
preference page.
Configuring Word Completion
The Komodo editor maintains an index of words in the current file. Instead of re-entering words that
already exist in the current file, you can use the Complete Word function to finish words. If you are
using the default key binding scheme, word completion is invoked from the keyboard by pressing
'Ctrl'+'Space' ('F5' or 'Alt'+'Esc' on Mac OS X). If you also want to be able to complete words by
pressing the 'Tab' key, select the check box labeled Use tab character to complete words like
Ctrl+Space. Note that the 'Tab' key can still be used for other purposes when this check box is
selected. Word completion only occurs when the cursor is positioned to the right of a character that
begins a word that has been stored in the editor's index.
Configuring Word or Character Wrap
Select an option from the Word wrap long lines drop-down list to have lines automatically
"wrapped"; that is, when a line exceeds the width of the Editor Pane, it wraps to the next line. This
is merely a display characteristic - no end-of-line marker is inserted. You can choose Word,
Character, or leave it as the default value of None. The Character option wraps the line at the
immediate position where the line exceeds the width of the Editor Pane; the Word option wraps the
line from the beginning of the word that extends beyond the width of the Editor Pane.
Note: For lines that have been wrapped automatically, the behavior of the 'Home' and 'End' keys is
slightly different. Pressing 'Home' or 'End' moves the cursor to the beginning or end of the current
line. Pressing the same key a second time moves the cursor to the previous or next end-of-line
marker.
Smart Editing
325
Komodo User Guide
Select an option from the Word wrap markers drop-down list to display markers in the Editor
Pane. You can choose to view End of line markers, Start of line markers, Both or None. The
default is None.
Configuring Edge Lines
The edge line is a vertical line that indicates a column marker.
• Show edge line / Highlight characters beyond edge line: Select to show where the line
wraps, and to highlight characters beyond the wrap column. With fixed-width fonts, a line is
drawn at the column specified. With proportional-width fonts, those characters beyond the
specified column are drawn on a colored background. The line or background color is
configured on the Fonts and Colors preference page.
• Edge line column: Specify the column position of the vertical marker.
Options set through the Preferences dialog box are the default for all files opened in Komodo.
Some Smart Editing features can be assigned to individual files.
Configuring Folding
Komodo can fold (i.e. hide and un-hide) logical segments of code in many languages and data file
types. The following options define how code folding looks and works:
• Fold mark style: Controls how the folding will look.
♦ Don't show fold marks (disables code folding)
♦ Square Trees (default)
♦ Curvy Trees
♦ +/- signs
♦ Arrows
• Use horizontal line on folds: Draws a horizontal line at the point of the code fold.
• Restore fold state on document load: Preserves all folding from the previous editing
session of a file. Enabling this option may increase the loading time for larger files with
numerous folds.
Save Options
To automatically fix whitespace errors when saving files:
• Clean trailing whitespace and EOL markers: Eliminates unnecessary empty space
between text and EOL markers, and fixes inappropriate EOL markers.
• Ensure file ends with EOL marker: Adds an EOL marker to the last line in a file if one
does not already exist.
Based on the specified Minutes between auto-save, Komodo saves backup copies of all files
open in the editor. When Komodo is shut down normally, the backup copies are deleted. If Komodo
is shut down abnormally (such as through a system crash), Komodo prompts to restore the backup
copy when the file is next opened. If you respond "Yes", the backup copy of the file, rather than the
(older) disk copy, is opened in the editor.
Smart Editing
326
Komodo User Guide
When files without extensions are saved, Komodo can be configured to prompt for an action.
Configure the If filename has no extension drop-down list:
• Ask me what to do: Komodo prompts you with a dialog box to decide what to do when a
particular file is saved without an extension.
• Add appropriate extension: Komodo automatically adds an extension based on file
content.
• Leave filename alone: Komodo does nothing when a file is saved without an extension.
Environment
At startup, Komodo loads all environment variables it can access. If it is launched from a desktop
icon rather than a shell, environment variables set in the default shell will not be loaded
automatically.
To ensure that Komodo runs with the correct environment variables, (e.g. SCC settings, library
locations, SSH options, etc.) set them in the User Environment Variables (override defaults) list
box. Three buttons are available for manipulating this list:
• New...: opens a dialog box prompting for a Name and Value.
• Edit...: opens a dialog box with the currently selected user environment variable. Name and
Value can be edited.
• Delete...: Deletes the currently selected user environment variable.
Additionally, double-clicking a variable in Startup Environment Variables copies it into User
Environment Variables (override defaults) where it can be edited. This new variable will override
the one in Startup Environment Variables
File Associations
Komodo's file associations determine the functionality of editing features such as autocomplete and
code coloring. Use the File Associations preference to associate file extensions and
characteristics with particular languages.
Editing the Language Associated with a File Pattern
To edit the language associated with a file pattern:
1. Select the desired extension from the Patterns list.
2. From the Language drop-down list, select the language to associate with the selected file
pattern.
To remove an association, select the desired pattern and click Remove.
Adding a New File Association
To add a new file pattern/language association:
1. Enter the desired pattern in the Pattern field. The pattern consists of the wildcards and the
Save Options
327
Komodo User Guide
naming convention. Typically, file associations are made by the filename extension; for
example, a Perl script has the extension ".pl". The pattern for a Perl script is therefore "*.pl".
2. Select the language to associate with the pattern from the Language drop-down list.
Use File Content to Determine Language
Komodo can be configured to identify the language of a file based on its contents rather than its
extension. The following characteristics can be used to override the file associations settings for
syntax checking and debugging configuration.
• XML Declarations: The Use XML Declarations option checks for XML declarations that
specify the language of a file (e.g. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0
Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> for XHTML 1.0).
• Shebang (#!...) Line: The Use shebang line option checks for a "#!/..." line at the top of a
file that specifies the interpreter (e.g. #!/usr/bin/perl).
• Emacs-Style Mode Variable: When this check box is selected, as Komodo opens files, it
checks for an embedded Emacs "mode" specification used to set the syntax checking and
debugging configuration.
Fonts and Colors Preferences
Komodo's Fonts and Colors Preference is used to customize the display of text in the Editor Pane.
To modify the font and color preferences, from the Edit menu, select Preferences, then click
Fonts and Colors.
The Sample Text window at the top of the Fonts and Colors page offers a preview of the current
scheme. If multiple schemes are configured, select the desired scheme from the Scheme
drop-down list.
To create a new scheme:
1. Select the scheme that you want to base your new scheme upon.
2. Click the New button and enter a name for the new scheme.
3. Make any necessary changes using the controls on the Fonts, Colors, Common Syntax
Coloring, and Language-Specific Coloring tabs.
4. Click OK to save the new scheme.
Schemes are added to the Scheme drop-down list. Remove the selected scheme by clicking the
Delete button. System schemes appear in bold and cannot be deleted.
Fonts
The Fonts tab is used to configure the display characteristics for fixed-width and/or proportional
fonts. Note that the default font characteristics configured on this tab are not overridden by any
language-specific font configurations.
To create a scheme that affects characters in specific encodings, select the type of encoding from
the Encoding drop-down list. If you do not specify the encoding, Komodo uses the system's default
encoding.
File Associations
328
Komodo User Guide
The Fonts tab contains two identical sets of font controls, one for fixed-width fonts on the left, and
the other for proportional fonts on the right. Select the Prefer Fixed or Prefer Prop. option button
to set the desired font type and then use the drop-down list immediately beneath the selected
option to choose a specific font.
• Font: Select specific fixed-width or proportional fonts from the drop-down lists. (On Linux,
the same list of fonts is displayed in both drop-down lists. On GTK, there is no
programmatic way to identify whether a font is proportional or not; therefore, you must know
the properties of the individual fonts when modifying these values.)
• Font Size: Select the size of the font from the drop-down list.
• Bold: If you want the default font to be displayed in bold, click the "B".
• Italic: If you want the default font to be displayed in italics, click the "I".
• Font Color: Set the font color by clicking on the "Fore" color box. Select the desired color
from the color picker dialog box. Click the small arrow button to set the font color using the
system color palette.
• Background Color: Set the background color for the Editor Pane by clicking on the "Back"
color box. Select the desired color from the color picker dialog box. Click the small arrow
button to set the background color using the system color palette.
• Reset: Click this button to return the font and color preferences to Komodo's original,
default settings.
Colors
Use the Color Choice drop-down list on the Colors tab to configure general color properties for
the Editor Pane. After selecting an interface component from the list, click the box to the right of the
drop-down list to choose a color from the color palette, or click the small arrow button to select a
color from the system color palette.
The following interface elements can be configured:
• Current Line Background Color: The color configured here does not take effect unless the
Highlight Current Line check box is selected. This sets the highlighting color of the line in
which the editing cursor is positioned.
• Cursor Color: Sets the color of the editing cursor.
• Selection Background Color: The background of text that has been selected in the Editor
Pane (by double-clicking, or clicking and dragging), is colored according to this setting.
• Selection Text Color: This option is only available if the Override Text Color in Selection
check box is selected. Regardless of other color configurations, all text that has been
selected in the Editor Pane (by double-clicking, or clicking and dragging), is displayed in the
color specified in this setting.
• Active Breakpoints Color: Sets the color of the breakpoint at which the debugger is
currently stopped.
• Pending Breakpoints Color: Sets the color of breakpoints at which the debugger has yet
to stop.
• Bookmark Color: Sets the color of the bookmarks that are inserted in the margin to the left
of the Editor Pane.
• Debugger Current Line Background Color: Sets the background color of the line
highlighted by the debugger.
• Debugger Calling Line Background Color: Sets the color of lines that call subroutines.
Caller line coloring is applied only when you have changed the stack position to view the
Fonts
329
Komodo User Guide
line that calls the current line. View caller lines in the Call Stack drop-down list box on the
Variables tab on the Debug tab.
• Edge Line/Background Color of Text Too Far: If Word Wrap is enabled, use this option to
set the color of the word wrap column marker, as well as the highlighted characters beyond
the wrap column. If using fixed-width fonts, a line is drawn at the specified column. If using a
proportional-width font, characters beyond the specified column are drawn on a colored
background.
The Override Text Color in Selection check box activates the "Selection Text Color" setting
described above. The Highlight Current Line check box activates the coloring specified in the
"Current Line Background Color" setting described above.
Common Syntax Coloring
Some language elements are common to a number of programming languages. The element
colors specified on the Common Syntax Coloring tab applies to all languages that use these
elements. Select an element from the Element Type drop-down list and use controls described
below to set the font characteristics. Note that the font characteristics configured on this tab are
overridden by any language-specific font configurations.
• Face: Select the typeface of the font from the drop-down list. You can choose either
"Fixed-width" or "Proportional".
• Size: Select the size of the font from the drop-down list.
• Bold: If you want the default font to be displayed in bold, click the "B".
• Italic: If you want the default font to be displayed in italics, click the "I".
• Font Color: Set the font color by clicking on the foreground color box. Select the desired
color from the color picker dialog box, or click the small arrow button to select a color from
the system color palette.
• Background Color: Set the background color for the Editor Pane by clicking on the
background color box. Select the desired color from the color picker dialog box, or click the
small arrow button to select a color from the system color palette.
• Reset: Click this button to return the font and color preferences to Komodo's original,
default settings.
Language-Specific Coloring
The colors configured on the Language-Specific Coloring tab apply to elements that appear in a
specific language. Select a language from the Language drop-down list and an element from the
Element Type drop-down list, then use the controls described below to set the font characteristics.
• Face: Select the typeface of the font from the drop-down list. You can choose either
"Fixed-width" or "Proportional".
• Size: Select the size of the font from the drop-down list.
• Bold: If you want the default font to be displayed in bold, click the "B".
• Italic: If you want the default font to be displayed in italics, click the "I".
• Font Color: Set the font color by clicking on the foreground color box. Select the desired
color from the color picker dialog box, or click the small arrow button to select a color from
the system color palette.
• Background Color: Set the background color for the Editor Pane by clicking on the
background color box. Select the desired color from the color picker dialog box, or click the
Colors
330
Komodo User Guide
small arrow button to select a color from the system color palette.
• Reset: Click this button to return the font and color preferences to Komodo's original,
default settings.
HTTP Inspector PreferencesKomodo IDE only
The HTTP Inspector runs a local proxy for examining HTTP traffic between browser and server.
This proxy has the following configuration options:
HTTP Inspector Options:
• Run HTTP Inspector at startup: If selected, this starts the proxy when Komodo is
launched. If not, the proxy can be started from the HTTP Inspector interface.
• Listen on port: Specify the port the proxy runs on. Most proxies use port 8080.
• Only accept connections from the local machine: Enabled by default.
Proxy forwarding:
• Enable proxy forwarding: Enable this option if you use an HTTP proxy to connect to the
internet (i.e. at your network gateway).
• Forward proxy connections on to this host: If you have enabled proxy forwarding, enter
the proxy information in the format <hostname>:<port>. If no port is specified, Komodo
will attempt to use port 8080.
Interactive Shell PreferencesKomodo IDE only
The Interactive Shell is an implementation of the language interpreter's shell within the Komodo
environment. These preferences set the default behavior for interactive shell functionality.
• Preferred Language: Specify which language interpreter's shell is launched when the
interactive shell is invoked.
• Session Control:
♦ Close tab when interactive shell session ends: If this option is selected, the Shell
tab closes when the Stop button is clicked. Otherwise, the tab remains visible
(although you must invoke another interactive shell session to use the shell).
♦ Confirm when closing interactive shell: When you attempt to close the Shell tab
before stopping the session (by clicking the Stop button), this option determines
whether you are prompted for confirmation. The confirmation dialog box has an
option to disable the warning; to re-enable the warning, set this field to Ask me each
time.
• Working Directory: This option sets the "current" directory for the interactive shell session.
Specify the desired directory.
Internationalization Preferences
Language encodings provide support for files containing characters in non-ASCII character sets.
Encodings are determined in the following order:
Language-Specific Coloring
331
Komodo User Guide
1. File Preference: If a specific encoding has been assigned to a file via the file's Properties
and Settings context menu, the assigned encoding is always used when that file is opened.
2. Auto-Detect: If the Auto-Detect File Encoding when Opened box is checked, Komodo
analyzes the existing encoding of the file by first looking for a Byte Order Marker (BOM),
then by checking for an XML declaration, and then by performing heuristic analysis on the
file's contents. If an encoding can be determined, it is applied.
3. Language-specific Default Encoding: Specific encodings can be assigned to
programming languages. (Komodo determines the programming language of a file based
on the File Association preferences.) If an encoding is associated with a programming
language, that encoding is used. Check Signature (BOM) to embed a Byte Order Marker
(BOM) at the beginning of the file. If the specified encoding is set to the default encoding,
the System Encoding or Custom Encoding is used.
4. System Encoding or Custom Encoding: If the Use Encoding Defined in Environment
box is checked, Komodo uses the encoding specified in the operating system. The following
system variables are checked:
♦ Windows: The Control Panel's "Regional Settings" (Windows 98, ME, and NT);
"Regional Options" (Windows 2000); "Regional and Language Options" (Windows
XP).
♦ Mac OS X: The "International" settings accessed via the the OS X System
Preferences.
♦ Linux: LC_CTYPE, LANG and LANGUAGE.
To use a different encoding, uncheck this box and select the desired encoding from the
Custom Encoding drop-down list.
When you create a new file, only the third and fourth methods described above are used to set the
file's encoding.
The following settings override all other encoding settings except the File Preference setting.
• Allow XML Declaration to Override Auto-Detection: Komodo always uses the XML
encoding declaration contained in the XML file when opening XML files (if applicable).
• Allow HTML META tag to Override Auto-Detection: Komodo uses the charset setting
defined in META tags in HTML documents.
• Allow 'coding:' tag to Override Auto-Detection: If the file contains a
"coding: <encoding_name>" directive within the first two lines, that encoding is used.
The Date & Time format determines the display format of the date and time for items listed on the
Start Page, and for the Current File settings display.
Language Help Settings
Use the Language Help page in Komodo Preferences (Edit|Preferences|Language Help) to
configure context-sensitive language look-up.
Configuring Reference Locations
The Language Lookup Commands section of the Language Help page displays the default URL
for language-specific help. (The %(browser) string is an interpolation shortcut.) If you are using
the default key binding scheme, 'Shift'+'F1' ('Meta'+'/' on Mac OS X) opens a browser window and
looks up the address of the sites specified here. The site is selected according to the type of file
Internationalization Preferences
332
Komodo User Guide
currently active in the Editor Pane. (To configure file association, see File Associations.)
The General Help field is used to specify a help location that does not specifically apply to a
language (or applies to a language not available in the above list).
To reset any of the help settings to their original value, click Reset beside the pertinent field.
Using Language Help
In the Editor Pane, double-click to select the keyword that you want to look up. Then, if you are
using the default key binding scheme, press 'Shift'+'F1' ('Meta'+'/' on Mac OS X) to invoke a
browser window and look up the keyword on the site configured in the Preferences. Press 'Ctrl'+'F1'
('Meta'+'Ctrl'+'/' on Mac OS X) to perform the lookup using the site configured in the General Help
field on the Language Help page.
Language Configuration
To configure the languages supported by Komodo, select Edit|Preferences|Languages, then
select the desired language.
Configuring JavaScript
Firefox Extension for Debugging: The Komodo JavaScript Debugger Firefox extension is
required to support the browser-side component of JavaScript debugging. Click Install/Upgrade
'Komodo JavaScript Debugger' Firefox extension to install this extension (and the 'jslib'
extension it needs) into Firefox.
JavaScript Directories: Specify any directories that you want Komodo to use for autocompletion
and calltips. Komodo scans these directories recursively (up to 5 directories deep) for information.
Configuring Perl
• Use this interpreter: Select Find on Path to use the first Perl interpreter that occurs in the
system's PATH variable. The paths to interpreters found in the PATH variable are available
from the drop-down list; select a specific interpreter as desired. Alternatively, click Browse
and navigate the filesystem to select the desired interpreter.
• Background Syntax Checking: Perl syntax checking is configurable; the degree of syntax
checking is determined by switches sent to the interpreter. Specify the desired level of
syntax checking by selecting the corresponding interpreter switch combination from the
drop-down list. If a setting that uses "taint" mode is selected, the PERL5LIB environment
variable is ignored; syntax checking is not performed on modules located in directories
specified via PERL5LIB.
• Debugger Logging: If this option is enabled, the Komodo debugger logs the debugging
session to a file in the directory specified in the Debugger Log Path field (or the directory
specified in the system's TEMP variable, if no directory is specified). This is primarily for
debugging the debugger, as opposed to gaining additional insight on the debug session
itself. The debugger log file is named perl-dbgp.log. The contents of the log file are
overwritten each time the debugger is invoked.
Configuring Reference Locations
333
Komodo User Guide
• Additional Perl Import Directories: Directories specified in this field are inserted at the
beginning of Perl's @INC array (in the same manner as Perl's "I" command-line argument).
Modules in the specified directories are used for debugging, syntax checking and during
interactive shell sessions.
PDK Installation Locations
To access the Perl Dev Kit preference page, select Edit|Preferences|Languages|Perl|PDK.
• Use this installation: Use the drop-down list or the Browse button to specify the path to
the PDK executable file.
Configuring PHP
Click the PHP Debugger Configuration Wizard button to configure the location of the PHP
interpreter, to modify the php.ini file for Komodo debugging, and to install the required debugging
extensions. To manually configure PHP debugging, refer to Debugging PHP for instructions.
• Use this interpreter: Select Find on Path to use the first PHP interpreter that occurs in the
system's PATH variable. The paths to interpreters found in the PATH variable are available
from the drop-down list; select a specific interpreter as desired. Alternatively, click Browse
and navigate the filesystem to select the desired interpreter.
• Path to alternate PHP configuration file: The php.ini file must be modified to support
Komodo debugging. To specify an different php.ini than the one configured by the PHP
Debugger Configuration Wizard, enter the path in this field, or use the Browse button.
See Debugging PHP for information about manually configuring the php.ini.
• PHP Directories: Specify any directories that you want Komodo to use for autocompletion
and calltips. Komodo scans these directories recursively (up to 5 directories deep) for
information.
• Comment Style: PHP can use "//" or "#" for comments. Choose one of these styles for use
by the Comment Region and Un-comment Region features.
Note: Be sure your php.ini configuration file is located in your operating system directory. If you
used the PHP Windows installer, this file should be in the correct location. To verify, on Windows
2000/NT the php.ini file should be in \winnt; on Windows 98/Me the php.ini file should be in
\windows. On Windows XP, the system directory is either \winnt or \windows, depending on
whether XP was a native installation or was an upgrade from a previous Windows version.
Sharing PHP Preferences and Files
Use Komodo's shared support functionality to share PHP preferences, run commands, code
snippets, templates, .tip files, or other items that have special usefulness within your PHP
programming group. See Configuring Shared Support for more information.
Configuring Python
• Use this interpreter: Select Find on Path to use the first Python interpreter that occurs in
the system's PATH variable. The paths to interpreters found in the PATH variable are
available from the drop-down list; select a specific interpreter as desired. Alternatively, click
Browse and navigate the filesystem to select the desired interpreter.
Configuring Perl
334
Komodo User Guide
• Additional Python Import Directories: Directories specified in this field are inserted at the
beginning of Python's PYTHONPATH environment variable. Modules in the specified
directories are used for debugging, syntax checking and during interactive shell sessions.
Configuring Ruby
• Use this interpreter: Select Find on Path to use the first Ruby interpreter that occurs in the
system's PATH variable. The paths to interpreters found in the PATH variable are available
from the drop-down list; select a specific interpreter as desired. Alternatively, click Browse
and navigate the filesystem to select the desired interpreter.
• Background Syntax Checking: Ruby syntax checking is configurable; the degree of
syntax checking is determined by switches sent to the interpreter. Specify the desired level
of syntax checking by selecting the corresponding interpreter switch combination from the
drop-down list.
• Debugger Logging: If this option is enabled, the Komodo debugger logs the debugging
session to a file in the directory specified in the Debugger Log Path field (or the directory
specified in the system's TEMP variable, if no directory is specified). This is primarily for
debugging the debugger, as opposed to gaining additional insight on the debug session
itself. The debugger log file is named ruby-dbgp.log. The contents of the log file are
overwritten each time the debugger is invoked.
• Additional Ruby Import Directories: Directories specified in this field are inserted at the
beginning of Ruby's PATH_LOAD environment variable. Modules in the specified directories
are used for debugging and syntax checking.
Configuring Tcl
Komodo provides the ability to interact with both the standard Tcl interpreter ("Tclsh") and the Tcl
interpreter that supports the Tk widget library ("Wish"). Komodo's Tcl integration also supports
logging and syntax checking. Extended Tcl editing support and the Tcl debugging libraries are
included with a subscription to ASPN Tcl.
• Use this Wish interpreter: Select Find on Path to use the first Wish interpreter that occurs
in the system's PATH variable. The paths to interpreters found in the PATH variable are
available from the drop-down list; select a specific interpreter as desired. Alternatively, click
Browse and navigate the filesystem to select the desired interpreter.
• Use this Tclsh Interpreter: As described above, specify the desired Tclsh interpreter.
• Enable Debugger Log: If this option is enabled, the Komodo debugger logs the debugging
session to a file in the directory specified in the Debugger Log Path field (or the directory
specified in the system's TEMP variable, if no directory is specified). This is primarily for
debugging the debugger, as opposed to gaining additional insight on the debug session
itself. The debugger log file is named tcl-dbgp.log. The contents of the log file are
overwritten each time the debugger is invoked.
• Additional Tcl Include Directories: Directories specified in this field are inserted at the
beginning of Tcl's TCLLIBPATH environment variable. Modules in the specified directories
are used for debugging, syntax checking and during interactive shell sessions.
Tcl Syntax Checking
To specify Tcl syntax checking:
Configuring Python
335
Komodo User Guide
• Warning messages to suppress: The warning messages listed in this dialog box can be
disabled. This prevents Komodo's syntax checking functionality from reporting these
warnings.
• Error messages to suppress: The error messages listed in this dialog box can be
disabled. This prevents Komodo's syntax checking functionality from reporting these errors.
• Additional options: Configure the level of error and warning checking by using the
switches -W1 (display parsing and syntax errors), -W2 (display parsing and syntax errors,
and usage warnings), -W3 (display parsing and syntax errors, portability warnings, upgrade
warnings, performance warnings, and usage warnings), and -Wall (displays all messages
and errors (the default)). Additionally, specific warning and error messages can be
suppressed using the -suppress error switch.
• Force checking for specific Tcl/Tk Version: To use a version of Tcl other than the default
(8.4) for warning and error checking, select the desired version from the drop-down list.
Tcl Debugging
Komodo's Tcl debugger has additional preferences for instrumenting files and logging debug
sessions.
• Tcl Instrumented Files: By default, all files are instrumented. However, once modules are
added to this list box, you can choose to not instrument specific modules by clearing the
appropriate check boxes next to the module names. To instrument modules in the list box,
select the check box beside the module name. To add a module to the list (e.g. "incrtcl,
"TclX"), click the "Add Entry" button, specify the Module Name, and click OK. To remove a
module, select one or more module names in the list box, and click "Delete Entries".
• Debugger Logging: If this option is enabled, the Komodo debugger logs the debugging
session to a file in the directory specified in the Debugger Log Path field (or the directory
specified in the system's TEMP variable, if no directory is specified). This is primarily for
debugging the debugger, as opposed to gaining additional insight on the debug session
itself. The debugger log file is named tcl.log. The contents of the log file are overwritten
each time the debugger is invoked.
Sharing Tcl Preferences and Files
Use Komodo's shared support functionality to share Tcl preferences, run commands, code
snippets, templates, .tip files, or other items that have special usefulness within your Tcl
programming group. See Configuring Shared Support for more information.
Configuring HTML
Komodo works in conjunction with HTML Tidy to provide configurable syntax checking for HTML
files. The following options can be configured:
• Error Level: Errors Only displays all HTML errors with a red underline; Errors and
Warnings displays both errors and warnings with a red underline.
• WAI Accessibility Conformance level: The Web Accessibility Initiative (WAI) provides
HTML developers with guidelines for making web content accessible to those with
disabilities. These guidelines include methods for making content understandable and
navigable (for example, adding "alt" text to an "img" tag for those who cannot view images).
WAI accessibility levels are:
Configuring Tcl
336
Komodo User Guide
♦ Off: WAI accessibility is off. No WAI-related syntax errors are reported.
♦ Priority 3: The lowest WAI conformance level. One or more groups will have
difficulty accessing the information in this document.
♦ Priority 2: Satisfying this level removes significant barriers to accessing content in
this document.
♦ Priority 1: The highest WAI conformance level. A web content developer must
satisfy this level for the greatest content accessibility.
• Configuration File: Tidy functionality can be customized via a custom configuration file.
See teaching Tidy about new tags on the W3C site for information on building a custom
configuration file. To specify a custom Tidy configuration file, click Browse beside the
Configuration File text box to locate the configuration file on your filesystem.
Configuring XML Catalogs
Komodo has built-in support for a wide range of XML dialects. Support for additional XML dialects
can be configured by adding XML Catalog files. These files map XML namespaces to local DTD
and RelaxNG Schema files.
Click the Add... button to add your own catalogs.
Click the Delete... button to delete the currently selected catalog from the list.
Use the arrow buttons to rearrange the order of the catalogs. Catalogs at the top of the list take
precedence over those below. All catalogs specified here (and the DTDs and RelaxNG Schemas
referenced by them) take precedence over the ones that ship with Komodo.
Mapped URIs
Mapped URIs are associations that allow Komodo to open files specified at one location using a
different path.
For example, opening a file with the URL:
http://www.example.org/index.html
... might open the file from:
/var/www/index.html
... which would be an editable copy of the file.
These URI mappings are particularly useful for:
• remote debugging
• dragging URLs into the Editor pane
• previewing HTML files
To map a URI (the address of an internet or network resource, such as a web URL) to a local
directory:
Configuring HTML
337
Komodo User Guide
1. Click the Add... button.
2. Enter the URI in the URI field.
3. Enter the path in the Path field or click the Local... or Remote... buttons to browse to and
select the desired directory.
Note: "Local Path" in this context can also refer to remote paths that are accessed via FTP, SFTP,
or SCP (e.g. scp://[email protected]:/home/user/). If the server is configured under Servers
Preferences, Komodo will open the file without prompting for authentication.
Double-click an existing mapping in the list to edit the URI or Local Path. URI mappings are
substring matches. For example, /home/user/public_html/project would match any directories
starting with that string (i.e. subdirectories project_1, project_2, etc.).
New Files Preferences
When the New button is used to create a new file, Komodo, by default, opens a text file in the
Editor Pane. To alter the default, select the desired file type from the drop-down list. To specify the
end-of-line marker for new files, select the desired marker from the drop-down list.
The Komodo templates used to create new files (File|New|New File) support the same
Interpolation Shortcut codes as snippets and run commands. Prior to Komodo Version 2.5, only a
limited set of variables could be used (for example, to embed the current date and time in files
created from custom templates). The new Interpolation Shortcuts are more powerful but are
backward-incompatible.
Enter a number in the Number of recent templates to remember field to specify how many recent
template names appear on the File|New drop-down menu.
The encoding for new files is determined by the configuration of the Internationalization preference.
Printing Preferences
• Print Line Numbers: Check this box to print the line numbers.
• Print in Color: To print in the colors displayed in the Editor Pane, check this box.
• Wrap long lines at n characters: Set the column at which lines will wrap. Specify "0"
characters for no line wrapping.
• Scale font sizes from screen to print by n: Specify the number of times larger or smaller
the printed font size will be in relation to its size on screen. The default is "1.5". Specify "1"
to print the current font size.
Projects and Workspace Preferences
Workspace
Use the When starting Komodo field to specify the display when Komodo is opened.
• Ask me whether to restore workspace: Komodo prompts to open recent files and
projects.
Mapped URIs
338
Komodo User Guide
• Restore last workspace: Komodo displays the workspace exactly as it was when you last
quit Komodo (including expanded tabs and open files).
• Do not restore last workspace: Komodo displays the default workspace (the Start Page
and no expanded tabs).
Opening and Closing Projects
These options specify the relationship between projects and files that are open in the Editor Pane.
When opening a project, set Komodo to:
• Ask me what to do: Komodo prompts whether the files that were open when the project
was last closed should be re-opened.
• Open recent files: Komodo automatically opens the files that were open when the project
was last closed.
• Open no files: Komodo opens the project without opening any files.
When closing a project, set Komodo to:
• Ask me what to do: Komodo prompts whether open files associated with the project should
be closed.
• Close all open files in project: Komodo automatically closes open files associated with the
project.
• Close no files: Komodo closes no files.
File Status Updates in Projects tab
The Update file status automatically option enables a periodic check of the read/write status and
the source code control status of components stored in the Projects tab and the Toolbox.
Status refresh can also be performed manually; see Refreshing Project Status for more
information.
Importing Files From Disk
Specify the defaults for the Import from File System option, available in the option in the Projects
tab, the Toolbox, and in folders stored in either a project or the Toolbox. These defaults can be
overridden in the Import from File System dialog box.
• Filenames to include: Specify the filenames to include. Use wildcards ("*" and "?") to
specify groups of files. Separate multiple file specifications with semicolons. If the field is left
blank, all files in the specified directory are imported.
• Filenames to exclude: Specify the file and directory names to exclude. Use wildcards ("*"
and "?") to specify groups of files. Separate multiple file specifications with semicolons. If
the field is left blank, no files in the specified directory are excluded.
• Import Subdirectories Recursively: To import subdirectories located beneath the directory
specified for the import, check Import Subdirectories Recursively. Specify how Komodo
should handle subdirectories by selecting one of the following options:
♦ Import directory structure: If the Import Subdirectories Recursively box is
checked and this option is selected, Komodo creates folders within the project that
Projects and Workspace Preferences
339
Komodo User Guide
represent imported directories. Thus, the directory structure is preserved within the
project.
♦ Make a folder per language: If this option is selected, imported files are organized
into folders according to the language indicated by file pattern in the filename. File
associations are configured in the Komodo Preferences. Each folder is named after
the associated language, for example, "Perl files", "XML files", etc. Files that don't
correspond to a known file pattern are stored in a folder called "Other files".
♦ Make one flat list: If this option is selected, all the imported files are placed directly
under the project or folder from which the Import from File System command was
invoked.
Triggering Macros
Macros can be configured to execute when specific Komodo events occur (such as before a file is
saved or after a file is closed). To disable this feature, uncheck Enable triggering of macros on
Komodo events.
Servers Preferences
Use the Servers page to configure server account settings for remote file access. To access the
Servers page, select Edit|Preferences|Servers. You can also manually specify a connection
(server name, username and password) when opening or saving remote files.
See Opening Remote Files for information about working with remote files.
If no servers have been previously configured, enter access information as described below and
click the Add button. If there are prior server configurations, click the New Server button to clear
the fields. To alter an existing configuration, select the configuration from the drop-down list, make
the desired changes, then click the Update button. To delete a configuration, select the desired
configuration and click the Delete button.
• Remote Accounts: Previous server configurations can be accessed via this field.
• Server Type: Select the type of connection to the server (FTP, SFTP or SCP).
• Name: Enter a name for the account. The value in this field is displayed in the "Remote
Accounts" drop-down list box, and is used as the Server name in the Remote File dialog
box.
• Hostname: Enter the name of the remote server. The name may be fully qualified (e.g.
"server.example.org", or just the hostname of a machine within a local domain.
• Port: Enter the port to use to connect to the server. SFTP and SCP generally use port 22.
FTP generally uses port 21.
• User Name: If you require an account to use the remote server, enter the user name in this
field. If the server accepts anonymous access, enter "anonymous" or click the Anonymous
Login check box.
• Password: If you require an account to use the remote server, enter the account password
in this field. If access to the server is anonymous, the password is usually an email address
(such as "[email protected]").
• Default Path: To specify the directory that displays when you connect to the server, enter
the path in this field.
• Anonymous Login: If the server allows anonymous login, check this box.
Servers Preferences
340
Komodo User Guide
Note: Passwords are stored (encrypted) using Mozilla's password manager.
Shared Support Preferences
Komodo's shared support functionality is used to configure components on one machine and
distribute them for use on other machines. Shared support is implemented via a "Common Data
Directory", which stores the shared components. The following components can be shared:
• templates
• Shared Toolbox
• Tcl .tip files (syntax definition files)
• .pcx files (checker extension files that define exact syntax information)
• .pdx files (debugger extension files)
• preferences
To configure shared support, select Edit|Preferences|Shared Support.
To access shared components, Komodo users must have "read" access rights to shared files in
both the Common Data Directory and the Shared Toolbox (if the directory is not the same as the
Common Data Directory). To alter shared components, users must also have "write" rights.
By default, the The Common Data Directory is the same as the user data directory.
To specify a custom location for the Common Data Directory:
1. On the Edit menu, select Preferences|Shared Support.
2. Click Use custom Common Data Directory location.
3. Click Choose to select a new location.
4. Click OK.
Sharing .tip, .pcx and .pdx Files
Through Shared Support, .tip files (which provide syntax checking for PHP and Tcl) can be made
available site-wide. All .tip files should be stored along with the default .tip information in the tcl
subdirectory of the Common Data Directory.
The other file types that can be shared are .pcx files, which can be used to extend the command
information supported by the TDK Checker and Komodo Tcl linter, and .pdx files, which are
debugger extension files that define debugging functions, such as spawnpoints. Like .tip files, .pcx
and .pdx files are stored in the tcl subdirectory of the Common Data Directory.
Sharing Preferences
Shared preferences are used to set a default preference configuration that is shared between
multiple Komodo users. An organization or user group can specify defaults like the language type
for new files, default tab widths, and other Komodo settings.
There are three levels of preference recognition in Komodo:
Shared Support Preferences
341
Komodo User Guide
1. user preferences
2. shared preferences (common)
3. default preferences (factory)
In a shared configuration, user preferences always override the shared preferences. Shared
preferences always override the default preferences.
To configure shared preferences, set the desired preferences in one instance of Komodo. (This
sets user preferences for that Komodo installation.) Then, edit the prefs.xml file that stores the
preferences.
The default locations are as follows:
• Windows: C:\Program Files\ActiveState Komodo 3.x
• Mac OS X: <komodo-install-directory>/Contents/SharedSupport/
• Linux: etc/komodo/
Make a backup copy of prefs.xml before editing it. In prefs.xml, make the following changes:
• Change the value of commonDataDirMethod to custom.
• Change the value of customCommonDataDir to the path to the Common Data Directory.
Copy prefs.xml to the Common Data Directory. When other Komodo sessions (configured to use
the same Common Data Directory) are started, the preferences in the Common Data Directory are
used.
Because user preferences override both default and shared preferences, ensure that user
preferences are not configured for items defined in the shared preferences. For example, if the
shared preference contains a tab size definition, and a user's personal preference contains a tab
size definition, the user's preference is used, not the shared preference.
Source Code Control PreferencesKomodo IDE only
Komodo IDE features source code control (SCC) integration, which you can use to perform the
most common SCC repository tasks from within Komodo, including checking files out, comparing
them to the repository version, and checking files back in. See Source Code Control for information
about using SCC functions within Komodo.
• Show SCC Output Tab on Commands: Select the desired action from the drop-down list
to specify whether the SCC tab is displayed when SCC commands produce output.
• Method used to display 'diff' output: Specify whether the output from the SCC diff
command should be displayed in a separate window, or within a new tab in the Komodo
Editor Pane.
CVS Integration
Configure these options to use CVS source code control integration.
• CVS Integration: Select this check box if you are using a CVS source code repository.
Sharing Preferences
342
Komodo User Guide
• CVS executable used: Choose the path to the desired CVS executable file from the
drop-down list, or click Browse to navigate to the file location.
• Check for status changes from outside of Komodo: If this check box is selected,
Komodo checks to see if the status of files that are open in the editor has changed from the
status they had at the last check. Specify the interval at which Komodo should check the file
status in the field below.
• Do recursive status checks: When checking the CVS status of files in a project, select this
check box to recurse the directories. If this check box is not selected, only the status of files
in the current directory are checked.
• Diff options: When you use the option Diff (Compare Files), the comparison is performed
according to the style specified here. Any CVS diff options may be specified. For a complete
list of options, refer to the CVS Manual.
• Do not warn about CVS external protocols (CVS_RSH) at startup: If you are using an
external protocol (such as RSH) to connect to the CVS repository, select this check box if
you do not want a warning displayed when you start Komodo.
Perforce Integration
Configure these options to use Perforce source code control integration.
• Perforce Integration: Select this check box if using a Perforce source code repository.
• Perforce executable used: Use the drop-down list or the Browse button to specify the
path to the Perforce executable file.
• Check for status changes from outside of Komodo: If this check box is selected,
Komodo checks to see if the status of files that are open in the editor has changed from the
status it had at the last check. Specify the interval at which Komodo should check the file
status in the field below.
• Do recursive status checks: When checking the status of files in a project, select this
check box to recurse the directories. If this box is not checked, only the status of files in the
current directory is checked.
• Show diff in Komodo: When you use the option Diff (Compare Files), the comparison is
performed according to the style specified here. Refer to the Perforce Manual for a
complete description of the options. (Alternatively, on the command line, enter p4 help
diff.)
• Use external diff tool: If you want to use a diff tool other than Perforce, it must be specified
in this field. The location of the diff tool must also be included in your system's PATH
environment variable.
• Automatically open files for edit before save: Select an option from the drop-down list to
determine what Komodo does if you attempt to save a file that has not been checked out of
Perforce.
Subversion Integration
Configure these options to use Subversion source code control integration.
• SVN Integration: Select this check box if you are using a Subversion source code
repository.
• SVN executable used: Use the drop-down list or the Browse button to specify the path to
the Subversion executable file.
CVS Integration
343
Komodo User Guide
• Check for status changes from outside of Komodo: If this box is selected, Komodo
checks to see if the status of files that are open in the editor has changed from the status
they had at the last check. Specify the interval at which Komodo should check the file status
in the field below.
• Do recursive status checks: When checking the Subversion status of files in a project,
check this box to recurse the directories. If this box is not checked, only the status of files in
the current directory are checked.
• Diff options: When you use the option Diff (Compare Files), the comparison is performed
according to the style specified here. Any Subversion diff options may be specified. For
more about diff options, refer to the Subversion Documentation.
• Do not warn about Subversion external protocols (SVN_SSH) at startup: If you are
using an external protocol (such as SSH) to connect to the Subversion repository, check
this box if you do not want a warning displayed when you start Komodo.
Web and Browser Preferences
• Web Browser: Specify the browser that Komodo should launch when a web-based
language query or the web browser preview is invoked. Select the desired browser from the
list, or use the Browse button to navigate to the desired browser. If you do not specify a
browser, Komodo uses the system's default browser.
• Preview in Browser: Choose the method Komodo uses to preview code in the selected
web browser:
♦ Preview in Komodo tab, other tab group: This option splits the Editor Pane to
display the browser preview in a separate pane.
♦ Preview in Komodo tab, same tab group: This option displays the browser
preview in the Editor Pane.
♦ Preview in external browser: This option opens the default browser (specified in
the Web and Browser Preferences drop-down list) in a separate window.
Windows Integration Preferences
Windows Integration preferences set system-wide file associations on the Windows platform. By
configuring file associations, Komodo becomes the default editor for specific file types. When one
of these files is invoked (for example, by double-clicking the filename in Windows Explorer),
Komodo is automatically launched (if not already running), and the file is loaded in the Editor Pane.
When a file extension is added to the "Edit with Komodo" association, the context menu displayed
when the filename is right-clicked in Window Explorer contains an "Edit with Komodo" option.
To configure file associations:
1. Select Edit|Preferences|Windows Integration.
2. Click Configure common associations. The Setup Common Komodo File Associations
dialog box opens.
3. Select the file extensions for which Komodo should be the default editor, and the files
extensions that should have the "Edit with Komodo" context menu option.
Individual file extensions may be added and deleted via the lists.
Subversion Integration
344
Komodo User Guide
If another application overrides the associations configured by Komodo, click Re-apply settings to
system to reset the Komodo associations.
Windows Integration Preferences
345
Komodo Tutorial Overview
The following tutorials provide hands-on introductions to Komodo's capabilities.
Feature Showcase
This tutorial provides an introduction to Komodo's general features in the areas of:
• Editing
• Code Analysis
• Debugging
• Search
• Tools
• Project and Workspace
Perl Tutorial
This tutorial provides an introduction to Komodo's Perl features, including:
• Installing Perl Modules
• Opening Files
• Analyzing the Program
• Running the Program to Generate Output
• Debugging the Program
PHP Tutorial
This tutorial provides an introduction to Komodo's PHP features, including:
• Opening the Tutorial Project
• Analyzing the PHP Tutorial File
• Running the Program
• Debugging the Program
Python Tutorial
This tutorial provides an introduction to Komodo's Python features, including:
• Opening the Tutorial Project
• Analyzing the Python Files
• Running the Program
• Exploring Python with the Interactive Shell
Ruby Tutorial
This tutorial provides an introduction to Komodo's Ruby features, including:
Komodo Tutorial Overview
346
Komodo User Guide
• Opening the Tutorial Project
• Analyzing the Ruby and YAML Files
• Running the Program
• Debugging the Program
XSLT Tutorial
This tutorial provides an introduction to Komodo's XSLT features, including:
• Opening the Tutorial Project
• Analyzing the Program
• Running the Program
• Debugging the Program
Run Command Tutorial
This tutorial provides an introduction to Komodo's Run Command feature, including:
• Running Simple Commands
• Using Advanced Options
• Saving and Rerunning Commands
• Using Command Shortcuts
• Using Command Query Shortcuts
• Parsing Command Output
Ruby Tutorial
347
Feature Showcase
These quick demos highlight a variety of Komodo features that help you write code quickly and
accurately. Take a look at some advanced search functions; explore your code using the code
analysis tools; create custom workspace components for code reuse and project management.
Editing
• Preview Cascading Style Sheets
• Reuse a Code Fragment
• Create a Prompting Snippet
• Code Completion Snippet
Debugging
• Break on a Variable Value
• Debug an XSLT Program
Search
• Fast String Finder
• Incremental Search
• Open/Find Toolbar
Tools
• Google Run Command
• Interactive Shell
• Test a Regular Expression
Project and Workspace
• Create a Custom Toolbar
• Directory Shortcut
• Export/Import Project Package
• Filesystem in Project
• Custom Keybindings
• Custom Template in a Project
Feature Showcase
348
Feature Showcase: Code Completion Snippet
Create a snippet that contains the structure for a code object. In this example, a common usage of
Perl's if syntax is stored in a Toolbox snippet.
Before you start: If necessary, display the Toolbox tab (View|Tabs|Toolbox).
Click in the Add button to create a new snippet in the Toolbox.
Configure the snippet.
Feature Showcase: Code Completion Snippet
349
Komodo User Guide
Double-click the snippet to insert the contents at the cursor position in the Editor Pane.
Feature Showcase: Code Completion Snippet
350
Feature Showcase: Custom Toolbar
Use custom toolbars and icons to personalize the Komodo workspace. This showcase describes
how to create a custom toolbar with a custom icon.
Select Toolbox|Add|New Custom Toolbar. Name the toolbar.
Drag and drop items onto the toolbar.
Feature Showcase: Custom Toolbar
351
Komodo User Guide
Right-click to access an item's Properties. Click Change Icon.
Choose an icon.
Use the new custom toolbar.
Feature Showcase: Custom Toolbar
352
Feature Showcase: Debug an XSLT Program
Komodo IDE only
When debugging XSLT programs in Komodo, view the execution location of the XSLT file and the
XML input file at the same time.
Before you start: Open the xslt_sample.xsl file contained in the sample project. The key bindings
used in this showcase are for Windows/Linux users. To find the equivalent key bindings for OS X,
click Help|Key Bindings.
On the Debug menu, click Step In.
In the Debugging Options dialog box, enter birds.xml (also in the Komodo Sample Project) as the
input file. Click OK.
Feature Showcase: Debug an XSLT Program Komodo IDE only
353
Komodo User Guide
Komodo displays split editor pane with yellow arrows showing point of execution in both the XML
and XSLT files. Step through the code using the Step In button ('F11'), or set breakpoints and use
the Go/Continue button ('F5').
Feature Showcase: Debug an XSLT Program Komodo IDE only
354
Komodo User Guide
When debugging is complete the results of the transformation appear in the Output tab. Select the
HTML tab to preview the rendered results.
Feature Showcase: Debug an XSLT Program Komodo IDE only
355
Feature Showcase: Shortcut to Commonly Used
Directory
Komodo's Open Shortcut is a fast method for locating files in deeply nested directories. Create a
shortcut in the Toolbox or Project Manager that opens the desired directory.
Select Toolbox|Add|New Open...Shortcut.
Feature Showcase: Shortcut to Commonly Used Directory
356
Komodo User Guide
Select a directory, and click OK.
Double-click the shortcut in the Toolbox. the Open File dialog box will open to the specified
directory.
Feature Showcase: Shortcut to Commonly Used Directory
357
Feature Showcase: Distributing a Project in a
Package
Komodo projects and the components they contain can be exported to a package file for distribution
to other Komodo users or for the sake of archiving. Exported packages can be imported by
instances of Komodo running on other machines.
On the Projects tab, right-click the project name and select Export Package.
In the Package Export Wizard, click Next.
Feature Showcase: Distributing a Project in a Package
358
Komodo User Guide
Enter a Package Name and an Export Location. Click Next. Click Finish.
On the Projects tab, click the "Add Item" button and select New Folder.
Feature Showcase: Distributing a Project in a Package
359
Komodo User Guide
Name the folder "Imported Projects" and click OK.
On the Projects tab, right-click the Imported Projects folder and select Import Package.
Feature Showcase: Distributing a Project in a Package
360
Komodo User Guide
In the Package Import Wizard, enter the package to import, and the location where the files will be
extracted. Click Next. Click Finish.
The files contained in the imported package are copied to the location on disk that you specified in
the Package Import Wizard.
Feature Showcase: Distributing a Project in a Package
361
Feature Showcase: Fast String Finder
Two keystrokes to find the next occurrence of a string in the current document - two more
keystrokes to find all occurrences of the string in the current file's directory. Use the Open/Find
Toolbar for fast searches.
Before you start: If necessary, display the Open/Find toolbar (View|Toolbars|Open/Find).
'Alt'+'I' ('Ctrl'+'I' on Mac OS X) positions the cursor in the Find field.
Enter the search string.
'Enter' searches for the string in the current file.
Feature Showcase: Fast String Finder
362
Komodo User Guide
'Tab' positions the cursor in the Find In field. Enter a period to search the directory of the current
file.
'Enter' displays all matches in the directory of the current file.
Feature Showcase: Fast String Finder
363
Feature Showcase: Store a Filesystem Layout in a
Project
To mirror a filesystem structure within a project (or within a folder in a project or the toolbox), use
the Import from Filesystem function. Folders will be created for each directory, containing the same
files as on the filesystem.
Right-click a folder in a project and select Import from File System.
Select the directory, specify inclusion and exclusion parameters, and select Import directory
structure as the folder structure.
Feature Showcase: Store a Filesystem Layout in a Project
364
Komodo User Guide
The imported file system has the same structure as the disk.
Feature Showcase: Store a Filesystem Layout in a Project
365
Feature Showcase: Google Run Command
Create a run command that launches a Google search on the term under the editing cursor. The
"%(browser)" interpolation shortcut loads the browser configured in Komodo's preferences; the
"%W" shortcut interpolates the word under the cursor in the editor pane.
In the Editor Pane, place the cursor within the word you want to search.
Open the Run Command dialog box (Tools|Run Command). Configure as shown.
Feature Showcase: Google Run Command
366
Komodo User Guide
When you click Run, the Google search results for the term are displayed in the browser.
The run command is stored in the Toolbox for re-use.
Feature Showcase: Google Run Command
367
Feature Showcase: Incremental Search
Use Incremental Search to quickly find all occurrences of a string in all open files. (The key bindings
mentioned below are part of the default Windows/Linux key binding set. If you are using Komodo on
Mac OS X, substitute 'Meta'+'I' for 'Ctrl'+'I'.)
Select the string.
'Ctrl'+'I' invokes incremental search on the selected string.
Press 'Ctrl'+'I' to find the next occurrence of the string. Continue pressing 'Ctrl'+'I' to find all
occurrences in the current file.
Feature Showcase: Incremental Search
368
Komodo User Guide
Press 'Ctrl'+'Page Down' to change to the next open file. Press 'Ctrl'+'I' to find the string.
Feature Showcase: Incremental Search
369
Feature Showcase: Using the Interactive Shell
Komodo IDE only
Press 'F12' ('Command'+'Esc' on Mac OS X) to switch between the Editor Pane and the interactive
shell. This showcase uses the sample program preprocess.py, described in the Python tutorial,
located by default in install dir\Komodo x.x\samples\python_tutorials.
Before you start: Configure the interactive shell preferences to load the Python shell by default.
The key bindings mentioned below are part of the default Windows/Linux key binding scheme. If
you are using Komodo for Mac OS X, click Help|Key Bindings to view the equivalent OS X key
bindings.
On line 67 of preprocess.py, select contenttype.
Press 'F12' ('Command'+'Esc' on Mac OS X) to open the shell. Enter import and press 'Ctrl'+'V'.
Press 'Enter' to load the module.
Feature Showcase: Using the Interactive Shell Komodo IDE only
370
Komodo User Guide
Enter help ( and press 'Ctrl'+'V' again to paste contenttype. Add a period.
Press 'F12' ('Command'+'Esc' on Mac OS X) to switch back to the Editor Pane. Select
getContentType.
Press 'F12' ('Command'+'Esc' on Mac OS X) to switch back to the interactive shell. Press 'Ctrl'+'V'
to paste getContentType, then enter a closing parenthesis and press 'Enter'.
Feature Showcase: Using the Interactive Shell Komodo IDE only
371
Feature Showcase: Assign a Key Binding to a
Toolbox Item
Assign a key binding to a frequently used component in the toolbox or a project.
In the Toolbox, right-click the item, and select Properties.
Click the Key Binding tab.
Feature Showcase: Assign a Key Binding to a Toolbox Item
372
Komodo User Guide
In the New Key Sequence field, press the desired keys (if sequence already in use, it is indicated in
the Key Sequence Currently Used By field). Click Add, and then click OK.
Feature Showcase: Assign a Key Binding to a Toolbox Item
373
Feature Showcase: Find and Open Files with the
Open/Find Toolbar
Use the Open/Find Toolbar to open files via fast keystroke-based filesystem navigation.
Before you start: If necessary, display the Open/Find toolbar (View|Toolbars|Open/Find), and
open a file in the Editor Pane.
Click in the Open field to position the cursor. Enter a period to display the files in the directory
where the current file is stored.
Enter a frontslash to display directories.
Feature Showcase: Find and Open Files with the Open/Find Toolbar
374
Komodo User Guide
Enter characters to filter the display.
Use the arrow keys to navigate the list.
Enter a frontslash after a directory to display the directory contents.
Select the desired file from the list. Press 'Enter' to update the Open field, and 'Enter' to open the
file in the Editor Pane.
Feature Showcase: Find and Open Files with the Open/Find Toolbar
375
Feature Showcase: Reuse Code Fragments
Create snippet from a code fragment. Store it in the Toolbox for reuse.
In the Editor Pane, select the code.
Drag and drop the selected code onto the Toolbox tab.
Feature Showcase: Reuse Code Fragments
376
Feature Showcase: Test a Regular Expression with
the Rx Toolkit Komodo IDE only
Use the Rx Toolkit to create, analyse and debug regular expressions in a program.
Before you start: Open the rx_sample.pl file contained in the sample project.
From the while (<DATA>) block, select the regular expression between the "/" characters.
In the Toolbar, click the Regular Expression Toolkit button.
Feature Showcase: Test a Regular Expression with the Rx Toolkit Komodo IDE only
377
Komodo User Guide
Clear the previous contents by clicking Help|Load Sample Regex and Search Text. Copy the
selected expression to the Regular Expression field.
In the Regular Expression pane, add an additional ":(.*)" and click Match All.
Feature Showcase: Test a Regular Expression with the Rx Toolkit Komodo IDE only
378
Komodo User Guide
The Match Results pane now displays three groups for each regular expression match.
Feature Showcase: Test a Regular Expression with the Rx Toolkit Komodo IDE only
379
Feature Showcase: Snippet that Prompts for Input
Create a snippet that prompts for input. This showcase uses an interpolation shortcut to prompt for
a string that is interpolated into the snippet.
Before you start: If necessary, display the Toolbox tab (View|Tabs|Toolbox).
Click in the Add button to create a new snippet in the Toolbox.
Configure the snippet. The %ask segment is an interpolation shortcut that prompts for an entry
when the snippet is used.
Feature Showcase: Snippet that Prompts for Input
380
Komodo User Guide
Double-click the snippet. A dialog box is displayed prompts for the "Company Name" value.
The value is interpolated into the comment configured in the snippet.
Feature Showcase: Snippet that Prompts for Input
381
Feature Showcase: Store a Custom Template in a
Project
Create a custom template for creating new files with custom elements. Store the template in a
project for re-use.
Create a file with the template contents.
Select File|Save as Template. Close the file in the editor.
Feature Showcase: Store a Custom Template in a Project
382
Komodo User Guide
Select File|New|New File. Select the template file and check Add to Toolbox.
Drag and drop the template file from the Toolbox to a project.
Feature Showcase: Store a Custom Template in a Project
383
Feature Showcase: Preview Cascading Style
Sheets
Use Komodo's browser preview to view the effects of CSS changes as you edit.
Before you start: Open a CSS file.
Set the web and browser preference to Preview in Komodo tab, other tab group.
Click the Web Preview button and specify a file which uses the CSS file.
Feature Showcase: Preview Cascading Style Sheets
384
Komodo User Guide
The preview displays the CSS file via the specified HTML file.
Alter the CSS file. When the changes are saved, the preview is automatically updated.
Feature Showcase: Preview Cascading Style Sheets
385
Perl Tutorial
Perl Tutorial Overview
Before You Start
This tutorial assumes...
• ...that ActivePerl build 623 or greater is installed on your system. ActivePerl is a free
distribution of the core Perl language. See Komodo's Installation Guide for configuration
instructions.
• ...that you have a connection to the Internet.
• ...that you are interested in Perl. You don't need to have previous knowledge of Perl; the
tutorial will walk you through a simple program and suggest some resources for further
information.
Perl Tutorial Scenario
You have exported a number of email messages to a text file. You want to extract the name of the
sender and the contents of the email, and convert it to XML format. You intend to eventually
transform it to HTML using XSLT. To create an XML file from a text source file, you will use a Perl
program that parses the data and places it within XML tags. In this tutorial you will:
1. Install a Perl module for parsing text files containing comma-separated values.
2. Open the Perl Tutorial Project and associated files.
3. Analyze parse.pl the Perl program included in the Tutorial Project.
4. Generate output by running the program.
5. Debug the program using the Komodo debugger.
Installing Perl Modules Using PPM
One of the great strengths of Perl is the wealth of free modules available for extending the core
Perl distribution. ActivePerl includes the Perl Package Manger (PPM) that makes it easy to browse,
download and update Perl modules from module repositories on the internet. These modules are
added to the core ActivePerl installation.
Running the Perl Package Manager
The Text::CSV_XS Perl module is necessary for this tutorial. To install it using PPM:
1. Open the Run Command dialog box. Select Tools|Run Command.
2. In the Run field, enter the command:
ppm install Text::CSV_XS
Perl Tutorial
386
Komodo User Guide
3. Click the Run button to run the command. PPM connects to the default repository,
downloads the necessary files and installs them.
About PPM
• PPM can be run directly from the command line with the ppm command. Enter ppm help
for more information on command-line options.
• By default, PPM accesses the Perl Package repository at http://ppm.activestate.com. The
ActiveState repository contains binary versions of most packages available from CPAN, the
Comprehensive Perl Archive Network.
• More information about PPM is available on ASPN. PPM documentation is also included
with your ActivePerl distribution.
• On Linux systems where ActivePerl has been installed by the super-user (i.e. root), most
users will not have permissions to install packages with PPM. Run ppm as root at the
command line to install packages.
Perl Pointer It is also possible to install Perl modules without PPM using the CPAN shell. See the
CPAN FAQ for more information.
Opening Files
Open the Perl Tutorial Project
Select File|Open|Project and choose perl_tutorial.kpf from the perl_tutorials subdirectory.
The location differs depending on your operating system.
Windows
<komodo-install-directory>\lib\support\samples\perl_tutorials
Linux
<komodo-install-directory>/lib/support/samples/perl_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/perl_tutorials
The files included in the tutorial project are displayed on the Projects tab in the Left Pane. No files
open automatically in the Editor Pane.
Open the Perl Tutorial Files
On the Projects tab, double-click the files parse.pl, mailexport.xml and mailexport.txt.
These files will open in the Editor Pane; a tab at the top of the pane displays their names.
Overview of the Tutorial Files
• mailexport.txt This file was generated by exporting the contents of an email folder (using
the email program's own Export function) to a comma-separated text file. Notice that the key
Running the Perl Package Manager
387
Komodo User Guide
to the file contents are listed on the first line. The Perl program will use this line as a
reference when parsing the email messages.
• parse.pl This is the Perl program that will parse mailexport.txt and generate mailexport.xml.
• mailexport.xml This file was generated by parse.pl, using mailexport.txt as input. When
you run parse.pl (in Generating Output), this file will be regenerated.
Analyzing the Program
Introduction
In this step, you will examine the Perl program on a line-by-line basis. Ensure that Line Numbers
are enabled in Komodo (View|View Line Numbers). Ensure that the file "parse.pl" is displayed in
the Komodo Editor Pane.
Setting Up the Program
Line 1 - Shebang Line
• Komodo analyzes this line for hints about what language the file contains
• warning messages are enabled with the "-w" switch
Komodo Tip notice that syntax elements are displayed in different colors. You can adjust the
display options for language elements in the Preferences dialog box.
Lines 2 to 4 - External Modules
• these lines load external Perl modules used by the program
• Perl module files have a ".pm" extension; "use strict" uses the "strict.pm" module, part of the
core Perl distribution
• "use Text::CSV_XS" refers to the module installed in Step One
Writing the Output Header
Lines 6 to 7 - Open Files
• input and output files are opened; if the output file does not exist, it is created
• scalar variables, indicated by the "$" symbol, store the files
• "strict" mode (enabled by loading "strict.pm" in line 2) requires that variables be declared
using the format "my $variable"
Perl Pointer scalar variables store "single" items; their symbol ("$") is shaped like an "s", for
"scalar".
Lines 9 to 13 - Print the Header to the Output File
• "<<" is a "here document" indicator that defines the string to be printed
♦ the text "EOT" is arbitrary and user-defined, and defines the beginning and end of
the string
♦ the second EOT on line 13 indicates the end of output
• lines 10 and 11 are data that will be printed to the output file
Overview of the Tutorial Files
388
Komodo User Guide
Setting Up Input Variables
Lines 15 to 16 - Assign Method Call to Scalar Variable
• the result of the method call "new" is assigned to the scalar variable $csv
• the method "new" is contained in the module Text::CSV_XS
• ({binary => 1}) tells the method to treat the data as binary
Perl Pointer good Perl code is liberally annotated with comments (indicated by the "#" symbol).
Lines 18 to 19 - Method "getline"
• the method "getline" is contained in the module Text::CSV_XS, referenced in the $csv
scalar variable
• "getline" reads the first line of mailexport.txt (referenced in the $in variable), parses the line
into fields, and returns a reference to the resulting array to the $fields variable
Starting the Processing Loop
Line 21 - "while" Loop
• the "while" statement is conditional
♦ the condition is "1', so the program endlessly repeats the loop because the condition
is always met
♦ the logic for breaking out of the loop is on line 25
♦ the loop is enclosed in braces; the opening brace is on line 21, the closing brace on
line 51
Komodo Tip Click on the minus symbol to the left of line 21. The entire section of nested code will
be collapsed. This is Code Folding.
Komodo Tip click the mouse pointer on line 21. Notice that the opening brace changes to a bold
red font. The closing brace on line 51 is displayed the same way.
Lines 22 to 25 - Extracting a Line of Input Data
• the "getline" function extracts one line of data from the input file and places it in the $record
scalar variable
• if "getline" returns an empty array, the input file has been fully processed and the program
exits the loop and proceeds to line 52
Perl Pointer variable arrays store lists of items indexed by number; their symbol ("@") is shaped
like an "a", for "array".
Converting Characters with a Regular Expression
Lines 27 to 31 - "foreach"
• "foreach" cycles through the elements stored in the @$record array
• the regular expressions on lines 29 and 30 find the characters "<" and "&", and replace
them with their character entity values ("<" and "&" are reserved characters in XML)
Setting Up Input Variables
389
Komodo User Guide
Komodo Tip Komodo's Rx Toolkit is a powerful tool for creating and debugging regular
expressions. See Regular Expressions Primer for more information.
Combining Field Reference and Field Data
Lines 33 to 35 - hash slice
• line 35 combines the @$record array with the field reference generated in line 19
Perl Pointer variable hashes are indicated by the symbol "%", and store lists of items indexed by
string.
Writing Data to the Output File
Lines 37 to 50 - Writing Data to the Output File
• one line at a time, lines from the input file are processed and written to the output file
• portions of the data line (stored in the $record scalar variable) are extracted based on the
corresponding text in the field reference (the first line in the input file, stored in the $fields
variable)
Closing the Program
Line 51 - Closing the Processing Loop
• at line 51, processing will loop back to the opening brace on line 21
• the logic to exit the loop is on line 25
Lines 52 to 54 - Ending the Program
• line 52 prints the closing tag to the XML file
• line 53 closes the output file or, if it cannot, fails with the error "Can't write mailexport.xml"
• line 54 closes the input file (it is not necessary to check the status when closing the input file
because this only fails if the program contains a logic error.)
Run the Program to Generate Output
To start, you will simply generate the output by running the program through the debugger without
setting any breakpoints.
1. Clear the contents of mailexport.xml Click on the "mailexport.xml" tab in the Editor Pane.
Delete the contents of the file - you will regenerate it in the next step. Save the file.
2. Run the Debugger Click on the "parse.pl" tab in the editor. From the menu, select
Debug|Go/Continue. In the Debugging Options dialog box,
click OK to accept the defaults.
3. View the contents of mailexport.xml Click on the "mailexport.xml" tab in the editor.
Komodo informs you that the file has changed. Click OK to reload the file.
Converting Characters with a Regular Expression
390
Komodo User Guide
Debugging the Program
In this step you'll add breakpoints to the program and "debug" it. Adding breakpoints lets you to run
the program in chunks, making it possible to watch variables and view output as it is generated.
Before you begin, ensure that line numbering is enabled in Komodo (View|View Line Numbers).
1. Set a breakpoint: On the "parse.pl" tab, click in the grey margin immediately to the left of
the code on line 9 of the program. This will set a breakpoint, indicated by a red circle.
2. Run the Debugger: Select Debug|Go/Continue. In the Debugging Options dialog box,
click OK to accept the defaults. The debugger will process the program until it encounters
the first breakpoint.
Komodo Tip Debugger commands can be accessed from the Debug menu, by shortcut keys, or
from the Debug Toolbar. For a summary of debugger commands, see Debugger Command List.
3. Watch the debug process: A yellow arrow on the breakpoint indicates the position at
which the debugger has halted. Click on the "mailexport.xml" tab. Komodo informs you that
the file has changed. Click OK to reload the file.
4. View variables: In the Bottom Pane, see the Debug tab. The variables "$in" and "$out"
appear in the Locals tab.
5. Line 9 - Step In: Select Debug|Step In. "Step In" is a debugger command that causes the
debugger to execute the current line and then stop at the next processing line (notice that
the lines between 9 and 13 are raw output indicated by "here" document markers).
6. Line 16 - Step In: On line 16, the processing transfers to the module Text::CSV_XS.
Komodo opens the file CSV_XS.pm and stops the debugger at the active line in the module.
7. Line 61 - Step Out: Select Debug|Step Out. The Step Out command will make the
debugger execute the function in Text::CSV_XS and pause at the next line of processing,
which is back in parse.pl on line 19.
8. Line 19 - Step Over: Select Debug|Step Over. The debugger will process the function in
line 19 without opening the module containing the "getline" function.
Komodo Tip What do the debugger commands do?
• Step In executes the current line of code and pauses at the following line.
• Step Over executes the current line of code. If the line of code calls a function or method,
the function or method is executed in the background and the debugger pauses at the line
that follows the original line.
• Step Out when the debugger is within a function or method, Step Out will execute the code
without stepping through the code line by line. The debugger will stop on the line of code
following the function or method call in the calling program.
9. Line 22 - Set Another Breakpoint: After the debugger stops at line 21, click in the grey
margin immediately to the left of the code on line 22 to set another breakpoint.
Perl Pointer The perl debugger will not break on certain parts of control structures, such as lines
containing only braces ( { }). With Perl 5.6 and earlier, the debugger will also not break at the start
of while, until, for, or foreach statements.
Debugging the Program
391
Komodo User Guide
10. Line 22 - Step Out: It appears that nothing happened. However, the debugger actually
completed one iteration of the "while loop" (from lines 21 to 51). To see how this works, set
another breakpoint at line 37, and Step Out again. The debugger will stop at line 37. On the
Debug Session tab, look at the data assigned to the $record variable. Then Step Out, and
notice that $record is no longer displayed, and the debugger is back on line 21. Step Out
again, and look at the $record variable - it now contains data from the next record in the
input file.
11. Line 37 - Stop the Debugger: Select Debug|Stop to stop the Komodo debugger.
Perl Pointer Did you notice that output wasn't written to mailexport.xml after every iteration of the
while loop? This is because Perl maintains an internal buffer for writing to files. You can set the
buffer to "autoflush" using the special Perl variable "$|".
More Perl Resources
ASPN, the ActiveState Programmer Network
ASPN, the ActiveState Programmer Network, provides extensive resources for Perl programmers:
• Free downloads of ActivePerl, ActiveState's Perl distribution
• Searchable Perl documentation
• Trial versions of Perl tools, like the Perl Dev Kit and Visual Perl
• The Rx Cookbook, a collaborative library of regular expressions for Perl
Documentation
There is a wealth of documentation available for Perl. The first source for language documentation
is the Perl distribution installed on your system. To access the documentation contained in the Perl
distribution, use the following commands:
• Open the Run Command dialog box (Tools|Run Command), and then type perldoc
perldoc. A description of the "perldoc" command will be displayed on your screen. Perldoc
is used to navigate the documentation contained in your Perl distribution.
Tutorials and Reference Sites
There are many Perl tutorials and beginner Perl sites on the Internet, such as:
• Introduction to Perl, a course developed by the University of Missouri
• learn.perl.org, which provides book reviews, tips, and access to Perl news lists and books
More Perl Resources
392
PHP Tutorial
Overview
Before You Start
This tutorial assumes:
• PHP 4.3.1 or greater is installed on your system. See Komodo's Installation Guide for
configuration instructions.
• You are interested in PHP. You don't need previous knowledge of PHP; the tutorial will walk
you through a simple program and suggest some resources for further information.
PHP Tutorial Scenario
This tutorial examines a PHP program that implements a form on a website - in this case, a guest
book where site visitors can log comments. In addition to providing an overview and working
example of PHP, the tutorial introduces Komodo's CGI Debugging functionality. In this tutorial you
will:
1. Open the PHP Tutorial Project and associated files.
2. Analyze guestbook.php, the PHP program included in the PHP Tutorial Project.
3. Run the program and generate HTML output by running the program.
4. Debug the program using the Komodo debugger.
See Debugging Programs for more information on this Komodo functionality.
Opening the Tutorial Project
On the File menu, click Open|Project and select php_tutorial.kpf from the php_tutorials
subdirectory. The location differs depending on your operating system.
Windows
<komodo-install-directory>\lib\support\samples\php_tutorials
Linux
<komodo-install-directory>/lib/support/samples/php_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/php_tutorials
All files included in the tutorial project are displayed on the Projects tab in the Left Pane.
PHP Tutorial
393
Komodo User Guide
Overview of the Tutorial Files
The following components are included in the php_tutorial.kpf project file:
• guestbook.php: This PHP program writes data from an HTML form to a data file, then
extracts the contents of the data file and formats it as HTML.
Open the PHP Tutorial File
On the Projects tab, double-click the file guestbook.php. The file opens in the Editor Pane; a tab at
the top of the pane displays the filename.
Analyzing the PHP Tutorial File
This section reviews the code in guestbook.php.
Analyzing guestbook.php
Introduction
In this step, you will analyze the PHP program on a line-by-line basis. Ensure that line numbers are
enabled in Komodo (View|View Line Numbers) and that the file guestbook.php is displayed in the
Komodo editor.
HTML Header
Lines 1 to 8 - HTML Header
• a standard HTML header is written to the program output
Komodo Tip: Notice that syntax elements are displayed in different colors. Adjust the display
options for language elements in the Preferences
dialog box.
PHP Declaration and Datafile
Line 9 - PHP Declaration
• PHP programs are embedded in HTML
• the characters <?php indicate the start of the PHP program
Lines 10 to 18 - Comments
• the // characters indicate a single-line comment in PHP programs; the # symbol can also
be used. Multi-line comments are nested in /* and */ characters, as shown on lines 27 to
30
Overview of the Tutorial Files
394
Komodo User Guide
Line 22 - Datafile
• the file guestbook.dat is created if it does not exist
• the tmp directory must exist beneath the root of the drive where the program resides
(unless a different location is specified in the Debugging Options).
• PHP statements are terminated with semicolons
Komodo Tip: On line 23, type $da. Komodo displays a list of the variables declared above the
cursor position that begin with the letters da. This is AutoComplete.
GuestBook Class
Lines 25 to 28 - Class Declaration
• a class is a collection of variables and functions
• class GuestBook contains the functions GuestBook, _getData", outputData, etc
• the var statement declares variables as class members, thus making them portable across
functions contained in the class
Komodo Tip: Click the mouse pointer at the end of line 25. Notice that the brace changes to a
bold red font. The closing brace on line 144 is displayed the same way. In this case, the braces
mark the beginning and end of a class. See Editing Files in the Komodo User Guide for more
about matching braces.
GuestBook Function
Lines 34 to 37 - GuestBook Function
• a function is a discrete block of code
• the $datafile argument is passed to the function GuestBook; multiple arguments are
separated by commas
• the contents of a function are enclosed in braces
• $_SERVER is a pre-defined PHP variable; it is passed to the script from the web server
♦ in PHP, global variables must be declared to be global inside a function if they are
going to be used in that function
• a local variable is defined for the current function by use of the term $this; notice that the
same syntax is used to call another function
♦ gb_dat variable is declared on line 27
♦ gb_dat variable is assigned the value of $datafile
♦ $this->data variable is cleared of any prior value
♦ $this->_getData variable calls the _getData function that begins on line 53;
when the _getData function is complete, processing returns to line 40
Komodo Tip: On line 38, type function GuestBook(. When you type the left parenthesis,
Komodo displays a pop-up hint that describes parameters for the function GuestBook. This is a
CallTip.
Lines 40 to 44 - Check for Valid Form Entry
• if the REQUEST_METHOD contained in $_SERVER is equal to POST, processing passes to the
addGuestBookEntry function on line 120
• if the REQUEST_METHOD is not equal to POST, a redirect message is displayed to the user
PHP Declaration and Datafile
395
Komodo User Guide
♦ the echo command generates output
♦ the characters \" are not included inside the double quotation marks that follow, so
that the message can be displayed as output
♦ the PHP variable PHP_SELF is the filename of the current script
♦ $_SERVER["PHP_SELF"] extracts the PHP_SELF variable from the $_SERVER
variable
Lines 45 to 46 - Check for Variable Value
• the if ($this->data) statement tests if the variable $this->data has a value
♦ the program executes the outputData function and then the outputForm function
_getData Function
Lines 53 to 58 - _getData Function
• the "file" statement parses the contents of the file stored in the gb_dat variable into the
$lines array
♦ the @ symbol suppresses warnings; in this case, if the data file is empty, the program
generates a non-fatal error
• the if ($lines) statement checks to see if the $lines variable has data
• the "join" statement converts the $lines array to a string and places it in the variable
$this->data
PHP Pointer: Use the "@" operator with care; you could disable error messages for critical errors
that terminate the execution of the script.
outputData Function
Lines 64 to 66 - outputData Function
• the contents of the $this->data variable are written to the standard output using the
echo statement
_createEntryHTML Function
Lines 72 to 77 - Retrieve Form Data
• the PHP variable $_POST is used to provide data to the script via HTTP POST
• lines 74 to 77 extract the form data and place the items in variables
Lines 80 to 83 - Validate Form Data
• On line 80, the validity of the name and message variables is tested:
♦ in !$name and !$message, "!" is a "not" operator; it is true if either variable is not
true
♦ The || symbol is an "or" operator
PHP Pointer: PHP has two "or" operators: the word "or", and the symbol ||. The || operator has
precedence over the word "or", providing flexibility in logic tests.
GuestBook Function
396
Komodo User Guide
Line 86 - Current Date and Time
• the variable $today contains the result of the PHP function date:
♦ the date function returns a string
♦ the "switches" are interpreted as follows:
◊ F: text month
◊ j: numeric day within month
◊ y: four digit year
◊ g: hour (12 hour format)
◊ a: AM / PM
Lines 89 to 94 - Interpolate Form Data with HTML
• text and HTML tags are parsed with the $today variable and the form data
• the return statement supplies the result (true or false) of a function or the value of a
variable to the routine from which it was called
_writeDataFile Function
Lines 100 to 106 - Open the Data File
• the fopen function opens the file stored in the $this->gb_dat variable
♦ the w switch opens the file if it exists
♦ If the file does not exist, fopen will attempt to create it
♦ the file is opened for writing only, and the file pointer is positioned at the top of the
file
• the if !$f statement checks to see if the $f variable contains a value
Lines 108 to 110 - Write to the Data Files
• the fwrite function writes the contents of $this->data to the file contained in the $f
variable
Lines 111 to 113 - Close the Data File
• the fclose function closes the file stored in the $f variable
• the value of the return statement is tested on line 112
Komodo Tip: Click on the minus symbol to the left of line 100. The entire_writeDataFile
function collapses. This is Code Folding.
addGuestBookEntry Function
Lines 120 to 125 - Call Functions for Writing Data
• the $entry variable is local to the addGuestBookEntry function
• the $entry contains the contents of the $data variable, returned in the
_createEntryHTML function
• on line 123, the contents of $entry are concatenated with the contents of $this->data,
and stored in $this->data
_createEntryHTML Function
397
Komodo User Guide
outputForm Function
Lines 127 to 142 - The Function for HTML Form
• these lines generate a standard HTML form
• notice the PHP snippet on line 133 that provides the program name to the HTML output
Closing Tags
Lines 148 to 151 - Closing Tags
• the $gb variable creates a new instance of the GuestBook class using the file specified in
the $datafile variable
• when the functions in the GuestBook class are complete, the PHP program is closed using
the syntax ?>
• closing HTML tags are written as output
Running the Program
This section reviews how to run the guestbook.php program using the Komodo debugger.
1. Run the debugger: Select Debug|Start.
2. Configure debugging options: In the Debugging Options dialog box, configure the
following options:
♦ General tab: Select the Simulate CGI Environment check box.
♦ CGI Input tab:
◊ Set the Request Method option button to Post.
◊ On the Post Type drop-down list, select URL encoded.
◊ On the Type drop-down list, select the variable type Post.
◊ Enter the following names in the Name text box, adding a meaningful value
for each in the Value text box. For example, the value for "name" could be
your own name. Click the Add button after each entry to add it to the
Browser Arguments.
⋅ "name"
⋅ "email"
⋅ "company"
⋅ "message"
3. Run the debugger: Click OK to run the debugger with the selected options.
4. View the Command Output tab: Notice the messages in the bottom left corner of the
Komodo screen; these inform you of the status of the debugger.
5. View the rendered HTML: Click the HTML tab on the right side of the Debug tab. The
HTML is displayed in the Bottom Pane; previous guestbook entries are displayed at the top
of the output, and the HTML form is displayed at the bottom. Click the Output tab to return
to the HTML code.
6. Create New File: To create a new HTML file that contains the HTML code on the Output
tab, select File|New|New File. In the New File dialog box, select the Common Category,
and the HTML template. Click Open.
7. Save the Output: Delete the contents of the new HTML file tab in the Editor Pane, then
select the HTML code on the Output tab. Copy the contents to the new HTML file tab in the
outputForm Function
398
Komodo User Guide
Editor Pane using the key binding associated with your selected scheme. Select File|Save
As to save the file with a unique name.
Debugging the Program
In this step you will add breakpoints to the program and debug it. Adding breakpoints lets you run
the program in chunks, making it possible to watch variables and view output as it is generated.
Before beginning, ensure that line numbering is enabled in Komodo (View|View Line Numbers).
1. Set breakpoints: On the guestbook.php tab in the editor, click on the gray margin
immediately to the left of the code in line 9 of the program. This sets a breakpoint, indicated
by a red circle. Set a second breakpoint on line 148.
2. Run the debugger: Select Go|Continue. In the Debugging Options dialog box, click OK to
accept the defaults (assuming that you created the CGI variables in the previous step,
Running the Program).
Komodo Tip: Notice that the Debugger Options have been saved from the last time a PHP
program was run or debugged.
Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or
from the Debug Toolbar. For a summary of debugger commands, see Debugger Command List.
3. Watch the debug process: A yellow arrow on the breakpoint indicates the position at
which the debugger has halted.
4. Line 9: Step In: Select Debug|Step In. "Step In" is a debugger command that causes the
debugger to execute the current line and then stop at the next processing line (line 19). The
lines between line 9 and line 19 are comments, not processing statements, and are
therefore ignored by the debugger.
5. View Variables: Expand the Bottom Pane (if necessary) by clicking and dragging the
bottom margin of the Komodo workspace. Variables defined in the program are displayed
on the Locals tab.
6. Line 19: Select Go|Continue. The debugger moves to line 148. The GuestBook class is
called from line 148.
7. Line 148: Step In: The debugger is now processing the GuestBook function.
8. View Variables: The Locals tab displays all variables.
9. Line 35: Step In: Expand the $this variable on the Locals tab in the Bottom Pane. Notice
that it now has a sub-variable gb_dat, which stores the value of the data file.
10. Line 36: Step In: Continue to step in until the debugger stops at the _getData function.
Continue to select Step In to process each statement in the function. After line 57 has been
processed and the debugger is stopped at line 58, the $lines variable can be expanded
on the Locals tab.
11. Line 58: Step Out: On line 58, select Step Out to process the rest of the _getData
function. The debugger will proceed to line 40, which follows the line where _getData was
called.
Komodo Tip: What do the debugger commands do?
Running the Program
399
Komodo User Guide
• Step In: Executes the current line of code and pauses at the following line.
• Step Over: Executes the current line of code. If the line of code calls a function or method,
the function or method is executed in the background and the debugger pauses at the line
that follows the original line.
• Step Out: Executes the code without stepping through the code line by line (when the
debugger is within a function or method). The debugger stops on the line of code following
the function or method call in the calling program.
14. Line 40: Step In: Continue to select Step In until the debugger is on line 121, in the
addGuestBookEntry function. On line 121, the addGuestBookEntry function calls the
_createEntryHTML function.
15. Line 121: Step In: In the _createEntryHTML function, the program assigns variables to
the CGI input data configured in the Debugging Options.
16. Line 74: Step Out: The _createEntryHTML function completes, and processing returns
to line 122.
17. Line 122: Step In: Use Step In to process each line of the addGuestBookEntry function,
until processing moves to the _writeDataFile function on line 102.
18. Line 102: Step In: Process line 102.
19. Open Watch Window: On line 102, the program opened the datafile (by default,
\tmp\guestbook.dat). To watch the activity in the datafile, select Tools|Watch File, then
specify the datafile.
20. Line 103: Step In: Continue to select Step In until line 108 has been processed. After line
108 is processed, the contents of the $this->data variable are written to the datafile, as
displayed in the Watch tab.
21. Line 111: Step In: Step In until processing returns to line 45 of the GuestBook function.
22. Line 45: Step Over: The Step Over debugger command executes the current line,
including any functions called by the current line. When the debugger returns to line 46,
notice that the contents of the $this->data variable have been written to the Bottom
Pane.
23. Line 46: Step Over: The debugger executes the outputForm function, which writes the
HTML form to the Bottom Pane.
24. Continue: Select Debug|Continue to run the debugger to the end of the program.
More PHP Resources
ASPN, the ActiveState Programmer Network
ASPN, the ActiveState Programmer Network, provides resources for PHP programmers:
• Mailing lists with many PHP topics.
Tutorials and Reference Sites
There are many PHP tutorials and beginner PHP sites on the Internet, including:
• The PHP Resource Index, a collection of resources dealing with PHP.
• www.PHP.net, the home of all that is PHP-related.
Debugging the Program
400
Python Tutorial
Overview
Before You Start
This tutorial assumes:
• Python 2.3 or greater is installed on your system. ActivePython is a free distribution of the
core Python language. See the Komodo Installation Guide for configuration instructions.
• You are interested in learning about Komodo functionality, including the debugger and the
interactive shell.
• You are interested in Python and have some programming experience either in Python or
another language.
Python Tutorial Scenario
The Python Tutorial demonstrates how to use the Komodo debugger and interactive shell to
explore a Python program. In particular, this tutorial examines a Python script that preprocesses
files (similar to the C preprocessor). In this tutorial you will:
1. Open the Python Tutorial Project.
2. Analyze preprocess.py the Python program included in the Tutorial Project.
3. Analyze contenttype.py the Python module included in the Tutorial Project.
4. Run the program and generate program output.
5. Debug the program using the Komodo debugger.
6. Explore Python using the Komodo interactive shell.
See Interactive Shell and Debugging Programs for more information on this Komodo functionality.
Opening the Tutorial Project
On the File menu, click Open|Project and select python_tutorial.kpf from the python_tutorials
subdirectory. The location differs depending on your operating system.
Windows
<komodo-install-directory>\lib\support\samples\python_tutorials
Linux
<komodo-install-directory>/lib/support/samples/python_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/python_tutorials
All files included in the tutorial project are displayed on the Projects tab in the Left Pane.
Python Tutorial
401
Komodo User Guide
Overview of the Tutorial Files
The following components are included in the python_tutorial.kpf project file:
• preprocess.py: The main program. This Python program parses input source files and
produces output filtered on a set of rules and statements embedded in the original input
source.
• preprocess current file: A run command for executing preprocess.py on the file currently
open in Komodo.
• contenttype.py: A Python module used by the main program (preprocess.py) to identify the
language of a given file.
• content.types: A support file used by the Python module contenttype.py.
• helloworld.html and helloworld.py: Sample files to process using preprocess.py.
Open the Python Tutorial File
On the Projects tab, double-click the preprocess.py file. This file opens in the Editor Pane; a tab at
the top of the pane displays the filename.
Analyzing the Python Files
This section reviews the code in preprocess.py and contenttype.py.
Analyzing preprocess.py
In this step, you will analyze the Python program preprocess.py in sections. This program is an
advanced Python script that is best addressed by focusing on certain areas within the code. Be
sure that line numbers are enabled in Komodo (View|View Line Numbers) and that preprocess.py
is displayed in the Komodo Editor.
About Preprocessors: A preprocessor is a program that examines a file for specific statements
called "directive statements". These directive statements are interpreted, and the resulting program
output is conditional based on those statements. In languages like C/C++, preprocessing is a
common step applied to source files before compilation. The Python preprocessor.py program
mimics a C/C++ preprocessor using similar directive statements.
About Directive Statements: Preprocessor directive statements are dependent on the
preprocessor program they are used within. In the preprocessor.py program, a directive is
preceded with a pound sign (#), and is located alone on a line of code. Placing a directive on a
unique line ensures the statement is included in a file without breaking file syntax rules. Valid
preprocessor.py directives include:
#define <var>[=<value>]
#undef <var>
#if <expr>
#elif <expr>
#else
#endif
#error <error string>
Overview of the Tutorial Files
402
Komodo User Guide
Setting Up the preprocess.py Program
Komodo Tip: Notice that syntax elements are displayed in different colors. You can adjust the
display options for language elements in the Preferences dialog box.
Lines 3 to 57 - Defining a Module Docstring
• help is defined in a module docstring
• docstrings are contained in triple-quoted strings (""")
Komodo Tip: See Explore Python with the Interactive Shell to examine these docstrings, and
other Python elements, using the Komodo interactive shell.
Komodo Tip: Click on the minus symbol to the left of line 3. The entire section of nested help code
is collapsed. This is called Code Folding.
Lines 59 to 65 - Importing Standard Python Modules
• Imports the following six modules:
♦ os: operating system dependant helper routines
♦ sys: functions for interacting with the Python interpreter
♦ getopt: parses command line options
♦ types: defines names for all type symbols in the standard Python interpreter
♦ re: evaluates regular expressions
♦ pprint: supports pretty-print output
♦ logging: writes errors to a log file
Line 67 - Importing the contenttype Module
The custom contenttype module is used by the preprocess.py program and is not included in a
standard Python installation.
• loads the contenttype module and imports the getContentType method
Komodo Tip: To interact directly with the contenttype.py module, see Explore Python with the
Interactive Shell for more information.
Defining an Exception Class
Lines 72 to 88 - Declaring an Exception
• PreprocessError class inherits from the Python Exception class
• an instance of the PreprocessError class is thrown by the preprocess module when
an error occurs
Komodo Tip: Click the mouse pointer on the closing parenthesis ")" on line 72. Notice that its color
changes to a bold red. The opening brace is displayed the same way. This is called "Brace
Matching". Related features in Komodo are Jump to Matching Brace and Select to Matching
Brace, available via the Code menu.
Setting Up the preprocess.py Program
403
Komodo User Guide
Initializing Global Objects
Line 93 - Initializing log
• log is a global object used to log debug messages and error messages
Komodo Tip: On line 95, enter: log = logging.
When you type the period, Komodo displays a list of the members in the log package. This is
called AutoComplete. If the default key bindingscheme is in effect Pressing 'Ctrl'+'J'
(Windows/Linux) or 'Meta'+'J' (Mac OS X) also displays the AutoComplete list. Delete the contents
of line 95.
Lines 98 to 111 - Mapping Language Comments
• _commentGroups is a mapping of file type (as returned by content.types) to opening
and closing comments delimiters
• mapping is private to the preprocess.py module (_commentGroups is prefixed with an
underscore to indicate that it is private to the preprocess.py module). This is a common
technique used in variable, function, and class naming in Python coding).
Note that preprocessor directives recognized by the preprocess.py module are hidden in
programming language-specific comments.
Komodo Tip: Use the Code tab, located in the Left Pane, to browse the general program structure
of all currently open files. For each file, the code browser shows a tree of classes, functions,
methods and imported modules. Python instance attributes are also displayed.
Defining a Private Method
Lines 116 to 123 - Expression Evaluation
• _evaluate method is private to the preprocess module
• evaluates the given expression string with the given context
Preprocessing a File
The preprocess method examines the directives in the sample source file and outputs the
modified processed text.
Lines 129 to 140 - The preprocess Method Interface
The preprocess method takes three parameters as input:
• first parameter is the filename, infile
• second parameter specifies the output file (defaults to stdout); outfile=sys.stdout
• third parameter is an optional list of definitions for the preprocessor; defines={}
Lines 145 to 156 - Identifying the File Type
Examines how programming comments are delimited (started and ended) based on the type of file
(for example, HTML, C++, Python).
Initializing Global Objects
404
Komodo User Guide
• getContentType is called (imported earlier from the contenttype.py module) to
determine the language type of the file
• file type is used to look up all comment delimiters (opening and closing language comment
characters) in _commentGroups
Lines 159 to 166 - Defining Patterns for Recognized Directives
This section defines advanced regular expressions for finding preprocessor directives in the input
file.
Komodo Tip: Use the Komodo Rx Toolkit to build, edit, or test regular expressions. New to regular
expressions? The Regular Expressions Primer is a tutorial for those wanting to learn more about
regex syntax.
Lines 178 to 303 - Scanning the File to Generate Output
This block of code implements a basic state machine. The input file is scanned line by line looking
for preprocessor directives with the patterns defined above (stmtRes). This code determines
whether each line should be skipped or written to the output file.
• source file is processed
• output is generated by a state machine implemented in Python
Lines 311 to 349 - Interpreting Command Line Arguments
The main method takes the text entered at the command line and uses the getopt module to
parse the data into arguments. These arguments are then passed into the "preprocess" method.
• runs when preprocess.py is executed as a program rather than loaded as a module
• parses the filename and any defines (-D) set as command line arguments
• passes all data to the preprocess method
Lines 351 to 352 - Running the Main Method
• runs the main method when preprocess.py is executed as a program
Analyzing contenttype.py
In this step, you will analyze the Python program contenttype.py in sections. This Python script is
best addressed by focusing on certain areas within the code. Be sure that line numbers are
enabled in Komodo (View|View Line Numbers) and that contenttype.py is displayed in the
Komodo Editor Pane.
Open contenttype.py
On the Projects tab, double-click the contenttype.py file. This file opens in the Editor Pane; a tab at
the top of the pane displays the filename.
Preprocessing a File
405
Komodo User Guide
Setting Up the contenttype.py Module
The contenttype.py module is used by the main program, preprocess.py, to identify what
programming language a particular file is written in based on the file extension and several other
tests.
Lines 16 to 19 - Importing External Modules
• imports external modules used in this file (re, os, sys, logging)
• logging is not a standard module; it is new in Python 2.3
Getting Data from content.types
Lines 29 to 31 - Finding the Helper File (content.types)
This section outlines the usage of the private _getContentTypesFile method located in the
contenttype module.
• returns the complete path to the content.types file
• assumes the file is in the same directory as contenttype.py
• _getContentTypesFile is a private method that cannot be accessed from outside of the
contenttype module
Lines 33 to 80 - Loading the Content Types from content.types
This section outlines the usage of the private _getContentTypesRegistry method located in
the contenttype module.
• locates the content.types file and scans it to calculate three mappings to return, as
follows:
file suffix -> content type (i.e. ".cpp", a C++ implementation file)
regex -> content type (i.e. ".*\.html?", an HTML file)
filename -> content type (i.e. "Makefile", a Makefile)
• _getContentTypesRegistry is a private method that cannot be accessed from outside
of the contenttype module.
♦ Lines 44 to 45: gets the content.types file; if none is specified in the parameter
for the method, _getContentTypesFile is called to find the system default
♦ Lines 47 to 49: lists the three mappings to return (empty mappings are created
here)
♦ Lines 51 to 79: opens and processes the content.types file on a line-by-line
basis
◊ scanning of the file stops when the last line is found, line 57
⋅ Lines 58 to 78: each line is parsed to determine which of the three
mappings it contains
⋅ an entry is made in the matching one
⋅ commented lines (starts with #) are ignored
♦ Lines 79 to 80: closes the content.types file and returns the mappings
Setting Up the contenttype.py Module
406
Komodo User Guide
Lines 85 to 118 - Determining a File's Content Type
This section outlines the usage of the public getContentType method located in the
contenttype module.
• takes one parameter (the name of the file to determine the content)
• returns a string specifying the content type (for example,
getContentType("my_web_page.htm") returns "HTML" )
• getContentType is the only publicly accessible method in the module
♦ Line 92: _getContentTypesRegistry is called to load the content.types file
and to load the mappings
♦ Lines 96 to 99: filenameMap is first checked to determine if the whole filename
can be used to find a match
♦ Lines 101 to 109: if the filename has a suffix (contains a '.'), the suffix map is then
used to find a match
♦ Lines 111 to 117: each regex in the regex map is then used to determine if it
matches the filename
♦ Line 118: returns the content type for the file (returns an empty string if no match
was found by the above three mappings)
Running the Program
This section reviews how to run the preprocess.py program using both a run command and the
Komodo debugger.
Using a Run Command
To start, generate simple output by running the program with the preprocess current file run
command, included in the python_tutorial.kpf project.
1. Open the Source File: On the Projects tab, double-click the helloworld.html file. The file
opens in the Editor Pane.
2. Open the Run Command: On the Projects tab, double-click the preprocess current file
run command. A Preprocess Current File dialog box appears.
3. Preprocess Current File: In the Preprocessor Options text area, enter:
-D SAY_BYE
Click OK to run the program.
4. View Output: The helloworld.html file output is displayed on the Command Output tab as
follows:
['path_to_file\\python_tutorials\\helloworld.html']
<html>
<head> <title>Hello World</title> </head>
<body>
<p>Hello, World!</p>
</body>
</html>
Python Tutorial Tip: For more information about the -D SAY_BYE command, see Using the
Debugger.
Getting Data from content.types
407
Komodo User Guide
Komodo Tip: For more infomation on using run commands in Komodo, see the Run Command
Tutorial.
Using the Debugger
Generate output by running the program through the debugger without setting any breakpoints.
1. Run the debugger: Select the preprocess.py tab in the editor. From the menu, select
Debug|Go/Continue. In the Debugging Options dialog box, click OK to accept the
defaults.
2. View the Debug Output Tab: Notice the messages in the bottom left corner of the Komodo
screen; these inform you of the status of the debugger. When the program has finished,
program output is displayed in the Bottom Pane, on the right side. If necessary, click the
Debug Output tab to display it.
Troubleshooting: "Why is this error message displayed?"
preprocess: error: incorrect number of arguments:
argv=['C:\\path_to_tutorial\\preprocess.py']
This error message is the expected output by the preprocess.py program when no source file or
arguments are specified before it is run. The following instructions explain how to specify a file at
the command line.
3. Specify a File to Process: On the Projects tab in the Left Pane, double-click the file
helloworld.html. Note the preprocessor directives inside the comments (#) in this file. Select
the preprocess.py tab in the editor. From the menu select Debug|Go/Continue. In the
Script Arguments text box on the Debugging Options dialog box, enter
helloworld.html. Click OK.
Troubleshooting: "Why is this error message displayed?"
<html>
<head> <title>Hello World</title> </head>
<body>
preprocess: error: helloworld.html:5: #error: "SAY_BYE is not
defined, use '-D' option"
This error message is the expected output by the preprocess.py program when no command-line
arguments are specified with the source file helloworld.html. The following instructions explain how
to specify a command-line argument with the source file to be processed.
4. Specify an Argument with the Source File: Select Debug|Go/Continue. In the Script
Arguments text box in the Debugging Options dialog box, enter the following source file
and argument: -D SAY_BYE helloworld.html. Click OK.
Troubleshooting: Specifying -D SAY_BYE helloword.html outputs the following:
<html>
<head> <title>Hello World</title> </head>
<body>
<p>Hello, World!</p>
</body>
Using a Run Command
408
Komodo User Guide
</html>
In the helloworld.html file, if SAY_BYE is not defined, preprocessing generates an error. If SAY_BYE
is defined, the preprocessor includes the line <p>Hello, World!</p> in the body of the output
of the HTML. This demonstrates how a Python preprocessor can be used to conditionally include
blocks of a source file being processed.
5. View the Debug Output Tab: Notice the HTML output and compare the result to the actual
file helloworld.html.
6. View Rendered HTML: On the right side of the Bottom Pane, click the HTML tab. The
rendered HTML for the helloworld.html file is displayed in the Bottom Pane. Click the
Output tab to return to the HTML code.
7. Create New File: To create a new HTML file that will later contain the HTML code in the
Bottom Pane, select File|New|New File. In the New File dialog box, select the HTML
Category. Click Open.
8. Save the Output: Delete the contents of the new HTML file tab in the Editor Pane, and then
select the contents of the Output tab on the Bottom Pane. Copy the contents to the new
HTML file tab in the Editor Pane. Select File|Save As to save the file with a unique name.
9. Specify Another Source File: Go through steps 3 to 5 using the file helloworld.py in place
of helloworld.html. Notice how the output displayed is now in Python, (for example, print
"Hello, World!"). This demonstrates how the preprocess.py program can be used to
process files written in different language types.
Debugging the Program
In this step you will add breakpoints to the program and "debug" it. Adding breakpoints lets you run
the program in sections, making it easier to watch variables and view the output as it is generated.
1. Set a breakpoint: On the preprocessor.py tab, click on the gray margin immediately to the
left of the code on line 347 of the program. This sets a breakpoint, indicated by a red circle.
2. Run the debugger: Select Debug|Go/Continue. In the Script Arguments text box on the
Debugging Options dialog box, enter the following source file and argument (if not there
from a recent run): -D "SAY_BYE" helloworld.html. Click OK.
Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or
from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command
List.
3. Watch the debug process: Notice that the line where the breakpoint is set (line 347) turns
pink. Also, a yellow arrow appears on the breakpoint. This arrow indicates the position at
which the debugger has halted.
4. View variables: On the Debug tab, click the Locals tab. If necessary, resize the pane by
clicking and dragging the upper margin. On the Locals tab, notice the declared variables
are assigned values. Examine the infile variable. This variable contains the name of the
file specified above (helloworld.html).
Komodo Tip: What do the debugger commands do?
• Step In: Executes the current line of code and pauses at the following line.
Using the Debugger
409
Komodo User Guide
• Step Over: Executes the current line of code. If the line of code calls a function or method,
the function or method is executed in the background and the debugger pauses at the line
that follows the original line.
• Step Out: When the debugger is within a function or method, Step Out executes the code
without stepping through the code line-by-line. The debugger stops on the line of code
following the function or method call in the calling program.
5. Step In: Select Debug|Step In until the debugger stops at line 129, the preprocess
method. "Step In" is a debugger command that causes the debugger to enter a function
called from the current line.
6. Set another breakpoint: Click on the gray margin immediately to the left of the code in line
145 to set another breakpoint. Line 145 is where getContentType is called.
7. Run the debugger: Select Debug|Go/Continue.
8. Step Over: When line 145 is processed, the variable contentType is assigned the source
file's (helloworld.html) type (HTML). "Step Over" is a debugger command that executes the
current line of code. If the line of code calls a function or method, the function or method is
executed in the background and the debugger pauses at the line that follows the original
line.
9. View variables: On the Debug tab, click the Locals tab. Examine the contentType
variable. This variable contains the type of the source file; the type is "HTML" for
helloworld.html.
10. Set another breakpoint: Click on the gray margin immediately to the left of the code in line
197 to set another breakpoint. Line 197 is inside of the loop where the source file
helloworld.html is being processed.
11. Run the debugger: Select Debug|Go/Continue.
12. Add Watches for Variables: On the Debug tab, click the Watch tab. Click the New button
in the lower-right corner of the Debug tab. An Add Variable dialog box appears. In the Add
Variable dialog box, enter lineNum in the text box. Click OK. Notice that the lineNum
variable and its value are displayed in the Watch tab. The lineNum variable is the line
number of the line currently being processed in the source file helloworld.html. Follow the
above steps again to enter a watch for the variable line. The line variable contains the
actual text of the line currently being processed.
13. Run the debugger: Select Debug|Go/Continue. Notice how the variables in the Watch tab
change every time the debugger stops at the breakpoint set at line 197. Also, notice the
output in the right side of the Debug tab. This output changes as new lines are displayed.
14. Disable and Delete a breakpoint: Click on the red breakpoint at line 197. The red
beakpoint is now white with a red outline. This breakpoint is now disabled. Click on the
disabled white breakpoint. This removes the breakpoint, but does not stop the debugger.
15. Stop the Debugger: On the Debug menu, click Stop.
Explore Python with the Interactive Shell
In this step you will use the interactive shell to explore the contenttype module. The Komodo
interactive shell helps you test, debug, and examine your program. See Interactive Shell for more
information.
If starting this section of the tutorial with currently open Python shells, please follow the steps below
to ensure the Python shell's current directory is the Python Tutorial directory.
Debugging the Program
410
Komodo User Guide
1. Close any Current Python Shells: Click the "X" button, located in the upper-right corner of
the Shell tab, for each open Python shell.
2. Make python_tutorial.kpf the Active Project: On the Project menu, select Make Active
Project|preprocess.
Start using the interactive shell with the Python Tutorial project files:
1. Start the Interactive Shell: On the Tools menu, select Interactive Shell|Start New
Python Shell. A Python Shell tab is displayed in the Bottom Pane.
2. Import a Module: At the ">>>" Python prompt in the interactive shell, enter: import
contenttype
Notice that another ">>>" Python prompt appears after the import statment. This indicates
that the contenttype module imported successfully.
3. Get Help for a Module: At the prompt, enter: help (contenttype)
The help instructions embedded in the contenttype.py file are printed to the interactive shell
screen. This is useful for easily accessing Python documentation without installing external
help files.
4. Get Help for a Method in a Module: At the prompt, press the up arrow to redisplay
previously entered commands. When help (contenttype) is redisplayed, enter
.getContentType at the end of the command. The entire command is as follows:
help (contenttype.getContentType)
Press Enter. The help instructions for the getContentType method are printed to the
shell screen. The ability to instantly access help on specific Python functions is a powerful
use for the interactive shell.
5. Run a Method: At the prompt, enter:
contenttype.getContentType("helloworld.html")
Notice the output identifies the file type as HTML.
6. Run Another Method: At the prompt, enter:
contenttype.getContentType("helloworld.py")
Notice the output identifies the file type as Python.
7. Run a Final Method: At the prompt, enter:
contenttype.getContentType("test.txt")
Notice the output identifies the file type as Text. The contenttype module uses several
tests to determine the data type used within a file. The test that determined that test.txt is a
text file simply analyzed the file extension.
More Python Resources
ASPN, the ActiveState Programmer Network
ASPN, the ActiveState Programmer Network, a source of numerous resources for Python
programmers, including:
• Free downloads of ActivePython, ActiveState's Python distribution.
• Searchable Python documentation.
• The Python Cookbook, a collaborative library of regular expressions for Python.
Explore Python with the Interactive Shell
411
Komodo User Guide
Tutorials and Reference Sites
There are many Python tutorials and beginner Python sites on the Internet, including:
• The Python Home Page, the home of all that is Python.
• Python DevCenter, run by O'Reilly Networks, which provides access to tips, articles and
other Python related items.
Preprocessor Reference
The preprocess.py program in this tutorial is a simplified version of another Python preprocess.py
script available via http://starship.python.net/crew/tmick/#preprocess. The version available on
starship.python.net is an advanced portable multi-language file preprocessor.
Tutorials and Reference Sites
412
Ruby Tutorial
Overview
Before You Start
This tutorial assumes:
• Ruby 1.8.0 or greater is installed on your system.
• You are interested in learning about Komodo functionality, including the debugger.
• You are interested in Ruby and have some programming experience either in Ruby or
another language.
Ruby Tutorial Scenario
The Ruby Tutorial demonstrates how to use Komodo to write and debug a simple Ruby program
which saves it's data in a YAML file. In this tutorial you will:
1. Open the Ruby Tutorial Project.
2. Analyze menagerie.rb the Ruby program included in the Tutorial Project.
3. Run the program in Komodo.
4. Debug the program using the Komodo debugger.
See Debugging Programs for more information on debugging in Komodo.
Opening the Tutorial Project
On the File menu, click Open|Project and select ruby_tutorial.kpf from
<installdir>r\samples\ruby_tutorials. All files included in the tutorial project are
displayed on the Projects tab in the Left Pane.
Overview of the Tutorial Files
The ruby_tutorial project contains:
• menagerie.rb: A program which stores and retrieves information on animals.
• animals.yaml: A YAML data file containing a base list of animals.
• check_fname: A code snippet that can be added to the program.
Open the Ruby Tutorial File
On the Projects tab, double-click the menagerie.rb file. This file opens in the Editor Pane; a tab at
the top of the pane displays the filename.
Ruby Tutorial
413
Komodo User Guide
Analyzing the Ruby program
The menagerie.rb program is a simple interactive program that can add, list, and search for
information about animals. It can also store this information in a YAML file (e.g. animals.yaml). It is
essentially an extremely simple database with predefined fields.
Introduction
In this step, you will analyze the program in sections. Ensure that line numbers are enabled in
Komodo (View|View Line Numbers) and that the file menagerie.rb is displayed in the Komodo
editor.
Line 6 - Importing the YAML class
• This line loads Ruby's core YAML class.
Komodo Tip: Notice that syntax elements are displayed in different colors. You can adjust the
display options for language elements in the Preferences dialog box.
Line 8 to 13 - Define and Initialize the Entry class
The Entry class contains variables which hold data for individual entries in our simple database,
and the behavior of that data. Information about each animal in our menagerie will be contained in
an Entry class object.
• class Entry declares the class
• the initialize method sets the instance variables @sci_name, @desc, and @time_mod.
These variables need to be private (instance variables) rather than global because there will be an
instance of the Entry class for each animal in the menagerie.
Line 15 - Expose instance variables
• attr_reader is a Ruby shortcut for exposing @sci_name, @desc, and @time_mod as
read-only attributes of the Entry class.
Line 18 to 26 - Data Storage Methods
• the sci_name= method ensures that @time_mod is updated with the current time whenever
@sci_name is updated.
• the desc= method does the same thing for @desc.
Komodo Tip: Click on the minus symbol to the left of line 18. The section of code for the
sci_name method is collapsed. Doing this at line 8 collapses the entire Entry class. This is called
Code Folding.
Line 28 to 35 - Data Behavior Methods
• the contains? method lets the cmd_search method determine if a particular entry contains
the string the user entered (see line 82).
Analyzing the Ruby program
414
Komodo User Guide
• the to_sci method returns the scientific name and description of an entry (see lines 77 and
83).
Line 39 to 46 - Command Help
• the $help global variable contains a string with information on command usage, providing
an easy way for methods to display help information when needed.
Line 48 to 55 - Define and Initialize the Menagerie class
The Menagerie class contains the @menagerie hash: the container which holds the multiple
instances of the Entry class. It also contains all the methods available to the user of the application
(via the command interface starting at line 154.
• class Menagerie declares the class
• initialize sets the instance variables @menagerie and @fname.
The name of the animal is stored as a key in the @menagerie hash. It references the Entry object
which contains the rest of the information, namely the scientific name (sci_name) and description
(descr). All the information we store on each animal is kept in two separate areas -- the
@menagerie key and the Entry it points to.
Line 57 to 69 - Adding Entries
• the split method (from Ruby's String class) allows us to enter an entire record in one line,
specifying the separator character we intend to use
• line 60 checks for an existing entry of the same name
• if none is found, a new entry (i.e. Entry.new) is added
• if there is an existing key of the same name, the entry is only updated if there is a change to
sci_name or descr (or both)
Exercise: After completing the tutorial, come back to this section and try writing a more "user
friendly" version of this cmd_add method which asks for the name, scientific name and description
separately (i.e. one at a time).
Line 74 to 88 - Searching for Entries
• line 75 checks to make sure an argument has been provided
• line 76 searches @menagerie's key for a match
• if there is a matching key, line 77 returns the result using the to_sci method from the Entry
class
Line 90 to 98 - Deleting Entries
• line 91 checks to make sure an argument (name) has been given
• line 92 checks if the name given matches a key in @menagerie
• if the name matches the delete method removes the entry
Introduction
415
Komodo User Guide
Line 100 to 102 - Listing Entries
• line 100 specifies that the argument for cmd_list is called "not_used" - a placeholder
argument name which tells us that the method will not actually use the argument
• line 101 calls the dump method of the YAML class (see line 6) to show the entire Menagerie
object in YAML format
Line 104 to 133 - Saving to a File
• line 105 to 112: checks if the first character of the fname argument is "!"; this sets the
overwrite variable which determines whether cmd_save can overwrite an existing file
• line 115 to 117: if overwrite is false and the specified file exists, warn the user with a
helpful message.
• line 118 to 122: if the fname argument exists, set the @fname instance variable, if not,
prompt the user with a useful error message.
• line 123 to 126 uses ruby's File class to open the file for writing
• a file descriptor (fd) is created on line 124 which is written to in the next line (a YAML dump
of our menagerie)
• line 127 to 131 provides error handling for problems during the save
Line 135 to 143 - Loading from a File
• line 136 assigns the method's argument to an instance variable
• line 138 loads the data using the YAML class's load_data method
• line 139 to 141 provides error handling for problems during loading
Line 145 to 149 - Showing Help
• prints the $help variable (see line 39)
Line 151 - Starting the Program
• creates a new instance of the Menagerie class called obj
Line 153 to 180 - Handling Commands from the User
The program needs a way to handle input from the user. This section deals with parsing input and
splitting it into commands which call methods in the Menagerie class, and arguments for those
methods.
• line 153 compiles a regular expression into the cmd_re variable
• line 154 prints the list of available commands (see line 39)
• line 156 prompts the user for a command
• line 159 captures user input and saves it to the cmdline variable
• the if block beginning at line 160 matches the user input against cmd_re
• this regular expression captures the first word "(\w+)" and the word that follows it "(.*)"
• the input is split into two parts:
•
♦ the first word has the string "cmd_" prepended to it, and is then assigned to the cmd
variable
♦ the second word, or words, are assumed to be arguments and assigned to the args
Introduction
416
Komodo User Guide
variable
• line 163 checks if cmd is a valid method in the Menagerie class.
•
♦ if it is, cmd and args are passed to the current Menagerie object using the send
method (inherited from Ruby's Object class)
♦ if the command is "quit" the program is ended with a break
♦ if neither, an error message is passed to the user
• if the cmd_re regular expression cannot parse the command, line 177 prints an error
message refering the user to the 'help' command
Running the Program
In this step you will run the program and interact with it.
1. To run menagerie.rb without debugging: Select Debug|Go/Continue. The program
interface displays in the Command Output tab. Try various commands to test the program.
2. In the Command Output tab, enter various commands to test the program.
3. Enter the following commands:
♦ load animals.yaml
♦ list
♦ delete Komodo dragon
The output of the last command (including "Error: undefined method...") indicates that something is
not working correctly. Debugging can help trace this problem. Type quit in the Output window
before starting the debugger.
Debugging the Program
In this step you will add breakpoints to the program and "debug" it. Adding breakpoints lets you run
the program in sections, making it easier to watch variables and view the output as it is generated.
Breakpoints are used to identify exactly where a program may be having problems. A bug has been
intentionally left in the cmd_delete method which can illustrate this.
1. Set a breakpoint: On the menagerie.rb tab, click on the gray margin immediately to the left
of the code on line 93 of the program. This sets a breakpoint, indicated by a red circle.
2. Run the debugger: Select Debug|Go/Continue (or enter 'F5', or use the Debug Toolbar).
The Debugging Options dialog box will then pop up; press the Return key or OK button to
dismiss it. You can pass program options to the program with the Script Arguments text
box, but this particular program doesn't take any.
3. Enter commands: In the Command Output tab, re-enter the commands from the Running
the Program section ('load animals.yaml', 'list', and 'delete Komodo dragon').
Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or
from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command
List.
4. Watch the debug process: After the last command, notice that a yellow arrow appears
where breakpoint is set (line 93). This arrow indicates the position at which the debugger
has halted. This tells us that our command did match a key in @menagerie.
Running the Program
417
Komodo User Guide
5. Check the relevant variables: Click on the Self tab to see the current object's instance and
class variables. Notice the @menagerie hash. Expand the view of the hash by clicking the
plus symbol next to it. It should only contain the "Leopard gecko" entry after the "Komodo
dragon" entry has been deleted.
6. Set a Watch variable: Select the Watch tab of the debugger window, highlight
'@menagerie.has_key?(name))' on line 92 and drag it into the Watch tab. You can
place most valid Ruby expressions in this area, including assignments, whether they're in
the program or not. For example, placing the expression 'x = 2 + 2' in the Watch tab will
show that a local variable called 'x' is set to 4.
Komodo Tip: What do the debugger commands do?
• Step In: Executes the current line of code and pauses at the following line.
• Step Over: Executes the current line of code. If the line of code calls a function or method,
the function or method is executed in the background and the debugger pauses at the line
that follows the original line.
• Step Out: When the debugger is within a function or method, Step Out executes the code
without stepping through the code line-by-line. The debugger stops on the line of code
following the function or method call in the calling program.
6. Step In: Select Debug|Step In until the debugger stops at line 166 (print status_message).
"Step In" is a debugger command that causes the debugger to enter a function called from
the current line.
7. View local variable: On the Debug tab, click the Locals tab. Examine the
status_message variable. This variable contains the message that will be returned to the
user.
8. Run the debugger: Select Debug|Go/Continue (or enter 'F5', or use the Debug Toolbar).
The command returns "#<Entry:0x83096f8>Error: undefined method `[]' for
#<Entry:0x83096f8>" which is not a very user-friendly message. The cmd_delete
method is missing an explicit return value to provide if the deletion was successful.
9. Fix the problem: On the Debug menu, click Stop (or use the Stop button on the Debug
Toolbar). Uncomment line 94 by removing the "#".
10. Disable and Delete a breakpoint: Click on the red breakpoint at line 93. The red
breakpoint is now white with a red outline. This breakpoint is now disabled. Click on the
disabled white breakpoint. This removes the breakpoint.
11. Run the debugger: Select Debug|Go/Continue and re-run the commands used previously
('load animals.yaml', 'list', and 'delete Komodo dragon'). The 'delete' command now returns
the message "Deleted".
More Ruby Resources
Tutorials and Reference Sites
There are many Ruby tutorials and beginner Ruby sites on the Internet, including:
• ruby-lang.org: The main page for the ruby language, including release notes and
downloads.
• ruby-doc.org: Extensive online documentation including tutorials and links, with well
Debugging the Program
418
Komodo User Guide
organized core and standard library API documentation.
• Programming Ruby: Tutorial and reference.
• why's (poignant) guide to ruby: An entertaining introduction to Ruby.
• Learn to Program: Excellent Ruby tutorials for beginners by Chris Pine.
• Ruby on Rails - Documentation: Documentation and tutorials for the Ruby on Rails web
development framework.
Tutorials and Reference Sites
419
Ruby on Rails Tutorial
Overview
Before You Start
For this tutorial you will need:
• A recent local installation of Ruby (1.8.5 or later).
• A local installation of Rails.
• Access to a MySQL database.
Several online "how to" guides are available for installing and configuring Ruby on Rails. See Rails Resourc
and installation bundles
Tutorial Scenario
This tutorial walks you through the creation of a very simple Rails application. The Movie Lending Library ap
that allows you to add, remove, borrow and return movies from a shared library.
Komodo has a very powerful Ruby on Rails project template with macros and commands for further automa
applications. The entire application can be created within Komodo using these tools and Komodo itself, with
command-line.
In this tutorial you will:
1. Create a new Rails scaffold using the Ruby on Rails Komodo project template.
2. Create a MySQL database.
3. Create the core of the application using just the project macros.
4. Write some code to iteratively develop the Movie Library application.
5. Debug the application.
Creating a Rails Project
Komodo ships with a powerful template for Rails projects, containing several macros for:
• Creating and deleting databases
• Generating controllers, migrations, models and scaffolds
• Migrating databases
• Running Webrick (the built-in web-server for Rails)
• Debugging the application
To create the tutorial project file:
1. Make a new directory/folder in a convenient location (e.g. C:\rails on Windows, or /home/username/r
2. In Komodo, select File|New|New Project from Template.
3. In the New Project dialog box, select the Ruby on Rails template from the Common category.
4. Give the file a useful name. Since this tutorial creates a movie lending library, let's call it movielib.kpf
Ruby on Rails Tutorial
420
Komodo User Guide
5. Specify your working directory (the one created in the first step) in the Directory field. Use the Brow
wish.
6. Click Open.
If Rails has been installed correctly, you should see a Komodo Alert dialog box saying "The movielib project
project should open in the Projects tab on the left, and should contain "Live Folders" of all the directories cr
command (app, components, config, db, etc.) plus a Virtual Folder containing the Komodo macros we'll be u
Komodo Tip: Komodo project templates can have a special macro called
oncreate which run when a new project is created from the template. The
oncreate macro in this Ruby on Rails template runs the command 'rails .
--force' in the current working directory to create the project.
Creating the Database
Editing the database.yml file
If MySQL is installed locally and can accept connections by 'root' without a password (it often is by default),
macro in the Rails Tools project folder to create the database.
If you have set a MySQL root password, created another MySQL account that you would like to use, or are r
different host, you will need to configure the database.yml file:
1. Open the Config project folder and double-click database.yml to open it in an editor tab.
2. As necessary, modify the username and password values to match the configuration of your MySQ
what values to use, leave the default values ('username: root' and 'password: '). In this tutorial,
the development database, but you should modify the test and production sections as well to
Databases macro below.
3. If you are running MySQL on a remote server, add the setting hostname: host to the development
modify the value if that setting is already present (set to localhost by default.
If you would like to use a database server other than MySQL, consult the Rails documentation on configurin
have the necessary database drivers installed, and creating the database manually. The database macros in
with MySQL.
Running the Create Databases Macro
In the Rails Tools project folder is a macro called Create Databases. Double-click the macro to run it.
If the database.yml file (and the database server) are configured correctly, a database called movielib (as s
file - derived from the project name) will be created and an alert will appear indicating that the database crea
Generating Models
Now that we have a directory tree with stub files, and a database for the application to use, we need to crea
command line we would use 'ruby script/generate model name', but in Komodo we have a macro to
In the Rails Tools/Generators project folder are macros for creating various parts of a Rails application. Dou
dialog-box appears prompting for a model name.
Creating a Rails Project
421
Komodo User Guide
The Movie Model
Since our application is a library for movies, we will need a movie model. Enter movie in the dialog box and
The following output should appear in the Command Output tab showing the files created in this step:
exists
exists
exists
create
create
create
create
create
app/models/
test/unit/
test/fixtures/
app/models/movie.rb
test/unit/movie_test.rb
test/fixtures/movies.yml
db/migrate
db/migrate/001_create_movies.rb
Komodo will also open these files in editor tabs. At this point we need to define the database table that this m
001_create_movies.rb editor tab (or open it from the db/migrate/ project folder). Notice that Rails has pluraliz
database table name.
Add the following below the 'create_table :movies do |t|' line:
t.column :title, :string
t.column :created_on, :date
This is the file that will control the creation of the movies table in the database. The create_table line ad
additions create the columns 'title' (a string) and 'created_on' (a special Rails value for date stamping n
The Person Model
We will need to track the name of the person borrowing a movie. We'll do this with a person model.
Double-click on the model macro again. This time, specify person as the model name and click OK.
The Command Output tab will again show us which files were created. The file we need to edit is 002_creat
following below the create_table line:
t.column :name, :string
With both models, Rails will automatically add a tablename_id key for the table. We only need to add the
The Checkout Model
Now we need a way to link people with movies. We'll do this with a 'checkout' model. Double-click on the mo
specify checkout as the model name and click OK.
Add the following to to the newly created 003_create_checkouts.rb below the 'create_table' line:
t.column :person_id, :integer, :null => false
t.column :movie_id, :integer, :null => false
t.column :created_on, :date
The Movie Model
422
Komodo User Guide
Migration
Now that we've defined the models in Rails, we need to apply them to our database. In Rails this is done wit
command. Again, there's a macro to do this for us.
Double-click the db:migrate macro in Rails Tools|Migrate. The Command Output tab should show that the t
'checkouts' have been created.
Creating a Scaffold
Generating a scaffold is a quick way to get a skeletal, working Rails application that can be modified iterative
driven web applications are very similar in their basic design, Rails builds a generic application based on the
which you can then modify to meet your specific requirements.
In the Generators folder, double-click the scaffold macro. In the dialog box enter movie as the model name
scaffold name. Click OK
Several files are created and opened in editor tabs. Since the tutorial won't be dealing with most of these file
unclutter your workspace - they can all be opened from the project later as needed.
Starting the Webrick Server
At this point we have a working application. It's not yet useful as a lending library, but we can have a look at
In the Run folder, double-click the run server macro. This will start the the Webrick web server in a separate
Open the http://localhost:3000/library in your favourite web browser. You should see a "Listing movies" page
movie" link. This isn't actually usable yet, but we can leave the webserver running and see our changes as w
Listing and Adding Movies
So far, the main Library page doesn't tell us much. We need to create a basic listing page to view the library
Open the list.rhtml file from the app/views/library project directory, or click on it's editor tab if it is already ope
the following:
<h1>DVD Lending Library</h1>
<table>
<tr>
<th class="dvdlib_header">Title</th>
<th class="dvdlib_header">Status</th>
</tr>
<% for movie in @movies %>
<tr>
<td class="dvdlib_item"><%=h movie.title %></td>
<td class="dvdlib_item">In</td>
<td><%= link_to 'Check out', :action => 'checkout', :id => movie %></td>
<td><%= link_to 'Details', :action => 'details', :id => movie %></td>
<td><%= link_to 'Edit', :action => 'edit', :id => movie %></td>
<td><%= link_to 'Remove', { :action => 'destroy', :id => movie },
:confirm => 'Are you sure?', :method => :post %></td>
Migration
423
Komodo User Guide
</tr>
<% end %>
</table>
<%= link_to 'Previous page', { :page => @movie_pages.current.previous } if @movie_pages.current.p
<%= link_to 'Next page', { :page => @movie_pages.current.next } if @movie_pages.current.next %>
<br />
<%= link_to 'Add new movie', :action => 'new' %>
We also need to create a form to add movies. The <%= link_to 'Add new movie', :action => 'n
which in turn calls _form.rhtml. Open _form.rhtml (app/views/library/_form.rhtml) and replace the contents w
<%= error_messages_for 'movie' %>
<!--[form:movie]-->
<p><label for="movie_title">Title</label><br/>
<%= text_field 'movie', 'title' %></p>
<p><label for="movie_created_on">Added to library on:</label><br/>
<%= date_select 'movie', 'created_on' %></p>
<!--[eoform:movie]-->
We've created an editable field for entering the movie title, and shown the current date stamp as the creation
Go ahead and add a few of your favourite movies. The "Check out" and "Details" links won't do anything yet
Remove titles.
Editing a Title in Place
Rails has some built in JavaScript methods that provide some useful functionality. We could use one of thes
our main library/list view editable.
Open list.rhtml (apps/views/library/list.rhtml) and replace the <td class="dvdlib_item"><%=h movie.
the following:
<td class="dvdlib_item">
<% @movie = movie %>
<%= in_place_editor_field
</td>
:movie, :title %>
The in_place_editor_field requires an instance name, so we need to assign the current value to @mo
instead of pasting, you'll notice autocompletion for the in_place_editor_field method.
Next, open library.rhtml (apps/views/layouts/library.rhtml). Add the following line in the <head> section:
This line includes the default Rails JavaScript libraries (<script src="/javascripts/...) in the library
edited in place. Since the 'Edit' link is now redundant, feel free to remove this line from list.rhtml:
<td><%= link_to 'Edit', :action => 'edit', :id => movie %>&lt/td>
The field in the page is now editable, but the change is not savable until we make a change in library_contro
(app/controllers/library_controller.rb). Add the following on line 2, just below the LibraryController class decla
in_place_edit_for :movie, :title
Listing and Adding Movies
424
Komodo User Guide
Komodo Tip: Komodo has some useful tools for debugging AJAX calls. Check
out the HTTP Inspector and JavaScript Debugger.
Check Out a Movie
On the main library list page, each movie has four actions associated with it: "Check out", "Details", and "Re
"Edit" action that we just removed) is a generic web/database function that Rails provides which works well e
application. "Check out" and "Details" are specific to our application and will have to be defined in our Contro
Our check out function should do the following:
• Redirect to a form
• Ask for the borrower's name
♦ if the name is in the database, accept
♦ if not, prompt the user to enter a new name
• Link the borrower to the movie in the database
• Redirect back to the main list
Here are the routines we need to add to library_controller.rb. Put them at the bottom of the file, just before th
def checkout
@movie = Movie.find(params[:id])
end
def do_checkout
movie_id = params[:id]
name = params[:person][:name]
if name.blank?
flash[:notice] = 'No name given'
redirect_to :action => :checkout, :id => movie_id
elsif (@name = Person.find_by_name(name)).blank?
flash[:notice] = "Who is #{name}?"
redirect_to :action => checkout, :id => movie_id
else
@movie = Movie.find(movie_id)
checkout = Checkout.create(:movie_id => movie_id,
:person_id => @name.id).save
redirect_to :action => :list
end
end
def register
movie_id = params[:id]
name_to_register = params[:person][:name]
if name_to_register.blank?
flash[:notice] = 'No name given'
else
person = Person.find_by_name(name_to_register)
if person
flash[:notice] = "#{person.name} is already registered"
else
Person.create(:name => name_to_register).save
end
end
redirect_to :action => :checkout, :id => movie_id
Editing a Title in Place
425
Komodo User Guide
end
Now we need to create the checkout page. Right-click on the library folder (app/views/library) and select Ad
filename checkout.rhtml and click Open. Add the following in the new file:
<h1>Checkout a movie</h1>
<p>Title: <%= h @movie.title %></p>
<% form_tag :action => 'do_checkout', :id => @movie do %>
<p>Your name: <%= text_field_with_auto_complete(:person, :name) %>
<%= submit_tag 'Check out' %>
<% end %>
<h2>Please register me</h2>
<% form_tag :action => 'register', :id => @movie do %>
<p><label for="movie_title">Your name</label><br/>
<%= text_field 'person', 'name' %></p>
<%= submit_tag 'Add me' %>
<% end %>
<%= link_to 'Back to the library', :action => 'list' %>
Notice the text_field_with_auto_complete(:person, :name). This should give us autocompletion
people we've added to the library database. Currently (even after adding a few people to the database) this
output in the Webrick window shows "ActionController::UnknownAction (No action responded
auto_complete_for_person_name)". As with the in_place_editor_field in list.rhtml, we need to
LibraryController class. Insert the following into library_controller.rb at line 3:
auto_complete_for :person, :name
The field should now give autocompletion options when you start typing a name into it.
To change the main library list page to show whether a movie is "In" or "Out". In list.rhtml, replace the placeh
class="dvdlib_item">In</td>' with:
<% checkout = Checkout.find_by_movie_id(@movie) %>
<td class="dvdlib_item"><%= Checkout.find_by_movie_id(@movie) ? "Out" : "In" %></td>
Debugging Rails Komodo IDE only
There is a bug in the do_checkout function that can be triggered by entering new (i.e. not registered) nam
section of checkout.rhtml. Entering a new name in the 'Your name' field section generates a 'No action respo
should instead give us a message saying "Who is name?" We can use Komodo's debugger to try to find the
Open library_controller.rb in an editor tab. Set a breakpoint on the 'flash[:notice] = "Who is #{nam
blank margin to the left. An orange octagonal icon should appear indicating the breakpoint.
1. Stop the WEBrick server by entering 'Ctrl'+ 'C' in the terminal window running the server.
2. Start the debugging version of the server by double-clicking the debug rails app macro. By default,
first line of executable code, in this case line 2 of script/server.
3. Click Go/Continue in the Debug menu ('F5') or the Go/Continue button in the toolbar.
4. In your browser, navigate to http://localhost:3000/library/checkout/1 (or the checkout page for the mo
5. Enter a new name in the 'Your name' field of the 'Checkout a movie' section (one that is not already i
Check Out a Movie
426
Komodo User Guide
The library_controller.rb tab should come to the foreground in Komodo, with a yellow arrow over the breakpo
execution of the application is paused, we can examine variables and interact with the application via the Ru
on the left side of the bottom pane, we can see the following variables from the do_checkout function:
Name
Type
checkout
null
movie_id
string
Value
1
name
string
NewName
The movie_id and name variables are as expected, but where does this checkout variable come from?
The line immediately below our breakpoint has the following:
redirect_to :action => checkout, :id => movie_id
The :action is checkout (an undefined variable) rather than :checkout (a symbol for the checkout fu
the checkout page should work as expected.
You can now leave WEBrick in debugging mode, or shut it down ('Ctrl'+'C' in the console) and restart it with
Returning a movie
Now that we can check out a movie, we should add the ability to return it. Currently we have a 'Check out' lin
that it shows 'Check out' if the movie is in, and 'Return' if the movie is out. Replace the entire second <tr> s
following:
<tr>
<td class="dvdlib_item">
<% @movie = movie %>
<%= in_place_editor_field :movie, :title %>
</td>
<% checkout = Checkout.find_by_movie_id(@movie) %>
<td class="dvdlib_item"><%= checkout ? "Out" : "In" %></td>
<td><% if checkout %>
<%= link_to 'Return', :action => 'return', :id => movie %>
<% else %>
<%= link_to 'Check out', :action => 'checkout', :id => movie %>
<% end %>
</td>
<td><%= link_to 'Details', :action => 'details', :id => movie %></td>
<td><%= link_to 'Remove', { :action => 'destroy', :id => movie }, :confirm => 'Are you sure?'
</tr>
Here is the method we need to add to library_controller.rb:
def return
movie_id = params[:id]
checkout = Checkout.find_by_movie_id(movie_id)
if checkout
Checkout.delete(checkout)
end
redirect_to :action => :list
end
Debugging Rails Komodo IDE only
427
Komodo User Guide
Viewing Checkout Details
The application is now mostly working. There's just one crucial component left to implement. The 'Details' lin
anything (besides bringing up an "Unknonw action" error). We want this page to show us who has the movie
out.
Right-click on the library folder (app/views/library) and select Add|New File.... Enter the filename details.rhtm
following in the new file:
<h1>Checkout details</h1>
<ul>
<li>Movie: <%= h @movie.title %></li>
<li>Borrower: <%= h(@person.name) %></li>
<li>Borrowed: <%= @checkout_date %></li>
</ul>
</p>
<%= link_to 'Return', :action => 'return', :id => @movie %>
<%= link_to 'List', :action => 'list' %>
Of course, we'll need another method in library_controller.rb:
def details
movie_id = params[:id]
@movie = Movie.find(movie_id)
checkout_id = params[:checkout]
checkout = Checkout.find(checkout_id)
if !checkout
redirect_to :action => :list
else
@person = Person.find(checkout.person_id)
@checkout_date = checkout.created_on
end
end
Lastly, we must pass a checkout id as a parameter when the page is called, because we're viewing the chec
movie details. Modify the 'link_to 'Details' line in list.rhtml to include the following:
<td><% if checkout %>
<%= link_to 'Details', :action => 'details', :id => movie, :checkout => checkout %>
<% end %>
</td>
Not only does this pass the checkout_id parameter, it hides the 'Details' link if the movie is not checked o
Rails Resources
Tutorials and Reference Sites
• Ruby on Rails: The home page of the Ruby on Rails project. Links to downloads, documentation and
• Rolling with Ruby on Rails (Revisited): A Windows-based tutorial by Bill Walton and Curt Hibbs.
• Instant Rails: An all-in-one bundle for windows containing Ruby, Rails, Apache, and MySQL.
• 74 Quality Ruby on Rails Resources and Tutorials: An excellent compendium of Rails resources.
Viewing Checkout Details
428
JavaScript Tutorial
Overview
Before You Start
This tutorial assumes:
• Some knowledge of HTML.
• You have the Firefox web browser installed.
• You have installed and configured the Komodo JavaScript Debugger Firefox extension.
Line numbers are referenced in this tutorial. To enable line numbering in the editor tabs, click View
Line Numbers in the View menu.
JavaScript Tutorial Scenario
This tutorial examines an HTML page that uses the Yahoo! User Interface Library and some
additional JavaScript to create a special right-click context menu for an image map. In this tutorial,
you will:
1. Open the JavaScript Tutorial Project.
2. Open jsdemo.html in Komodo and Firefox.
3. Analyze context-menu.js using the JavaScript debugger to see how it works.
4. Add dynamically generated links by manipulating DOM objects with JavaScript.
Opening the Tutorial Project
Opening this tutorial from the Start Page gives you the option to open the associated project.
Otherwise, click Open|Project in the File menu and select js_tutorial.kpf from
<install_directory>\samples\js_tutorials. All files included in the tutorial project are displayed
on the Projects tab in the Left Pane.
Overview of the Tutorial Files
The JavaScript tutorial project contains the following:
• jsdemo.html: This "City picker" demo is an HTML page that uses JavaScript to display
special right-click context menus over an image map, and add the selected items to a table
on the right.
• context-menu.js: A JavaScript file containing the functions used in jsdemo.html.
• YUI directory: A collection of Yahoo! User Interface JavaScript libraries used in the demo.
Opening the City Picker
On the Projects tab, double-click jsdemo.html to open it in the Editor Pane. In the View menu, click
Preview in Browser ('Ctrl'+'K', 'Ctrl'+'V').
JavaScript Tutorial
429
Komodo User Guide
If Firefox is not set as your default browser in Komodo's Web Browser preferences, use the file
URL in your browser's address bar to locate the file and open it in Firefox.
Try the application. Right-clicking over a country in the map brings up a country-specific context
menu instead of Firefox's default context menu. Selecting a city from the menu adds that city under
the appropriate country heading in the table to the right and removes it from the menu. Reloading
the page resets the page to the initial view.
The context menu for Mexico is intentionally broken so that we can find the problem with the
debugger later in this tutorial and fix it.
Analyzing the JavaScript program
Look over jsdemo.html. Other than some inline CSS style for the YUI context menu, it's all HTML.
The JavaScript that makes the page work is sourced from external .js files. The one we'll be
working with is context-menu.js. Open it from the tutorial project.
The first thing we notice is the cities object. This is a list of the countries with nested lists of cities
that belong to them. Next is the demo function, which contains the onContextMenu function that
brings up the custom context menu, and the onCitySelect which controls the actions on that
menu. The comments describe what is happening in the code.
Komodo Tip: To enable autocompletion for the YUI libraries, click Preferences... on the Code
menu and select the YUI API Catalog in the Code Intelligence section.
Debugging the Page Komodo IDE only
If you have not already done so, configure the JavaScript Debugger.
Starting the Debugger
In Firefox refresh the City Picker page, click the Connect to Komodo Debugger button, and
move your mouse pointer over the image map.
If the debugger is configured correctly, the file event-min.js should open in a Komodo tab. Though
you haven't set any breakpoints in this file, the debugger stops at the first line of JavaScript
executed by the browser (in this case a YUI event handler). This gives you the opportunity to set
breakpoints in the file if you want to, or step through the code with the Step In button.
To leave this event handler and start debugging context-menu.js, click the Go/Continue
Debugging button in the main or debugging toolbar. Select the context-menu.js editor tab.
Set a breakpoint on line 62 of context-menu.js by clicking in the empty left margin. Breakpoints are
displayed as an orange-red octagonal icon in the breakpoint margin.
Right-click over Mexico in the City Picker map.
Komodo Tip: While the JavaScript debugger is in a break state, clicking Interact on the Debug
menu opens up a JavaScript shell where you can interact with the Firefox's JavaScript engine
directly.
Opening the City Picker
430
Komodo User Guide
Viewing and Changing Variables
As soon as the browser registers a right-click over Mexico on the image map, the debugger should
stop on line 62 of context-menu.js. A yellow arrow icon indicating the current breakpoint will appear
in the margin at that line.
One of the most useful things the debugger does is keep track of variables in the code. In the
locals tab in the Output pane we can see a list of all variables in the current scope (i.e. variables in
the demo function). The globals tab shows everything in the window object; you can see the DOM
objects by expanding the document node in this list. The instance tab shows properties of the
current object.
You may have noticed earlier that the context menu for Mexico is broken. The variables list in the
locals tab can help us find out why.
The curr_country variable was set on line 61 and appears to have the value "Mexic" which
doesn't match the country variable which is "Mexico".
We can modify this variable within the debugger while the it is in a break state. Double click on
curr_country in the locals tab to bring up the Edit Variable Value dialog box. Change "Mexic"
to "Mexico" and click "OK". Click the Go/Continue Debugging button to resume execution. The
context menu for Mexico should appear in Firefox. (Note: The default context menu may appear
initially because of how the debugger handles coming out of a break state. Clicking anywhere on
the Komodo or Firefox windows will clear this and show the expected menu.)
That solved the problem for this debugging session only. We need to find out where that typo came
from. Since the only appearance of the country's name in context-menu.js is spelled correctly on
line 7, we can assume there's a problem in jsdemo.html. Since curr_country is taken from
e.target.id, we can extrapolate that the "alt=" attribute of the image map area for Mexico is
wrong.
Komodo Tip: If we didn't know where the e.target.id came from, we could use Komodo's
Find... feature to locate the typo in jsdemo.html
Adding Links
The cities are added to the country lists by manpulating the DOM. These are plain text <LI>
elements, but it's fairly simple to turn these into useful links by creating an <A> element and
populating it with a URL containing the selected city's name in an href attribute.
Wikipedia has a fairly simple URL syntax for topic names, and it has information on all of the cities
in our lists, so we could easily use it for our link targets.
Lines 43 to 45 in context-menu.js handle creating the list elements and inserting the city name:
var newItem = document.createElement("LI");
newItem.appendChild(document.createTextNode(cityName));
targetList.appendChild(newItem);
Insert the following after line 43 to create an <A> element:
Viewing and Changing Variables
431
Komodo User Guide
var newLink = document.createElement('A');
Wikipedia articles can be accessed by adding the subject name to the end of the base URL. To set
the href attribute to a combination of the Wikipedia base URL and the selected city name, add the
following line:
newLink.setAttribute('href', 'http://en.wikipedia.org/wiki/' + cityName)
To insert this link in the list, modify the subsequent two lines to use newLink rather than newItem:
newLink.appendChild(document.createTextNode(cityName));
targetList.appendChild(newLink);
Save the file and reload the page. Selected cities will now appear as Wikipedia links.
More JavaScript Resources
Tutorials and Reference Sites
• W3 Schools JavaScript Tutorial: An easy to follow introduction to JavaScript and DOM.
• Mozilla's About JavaScript: An overview of the language with numerous links to reference
material such as standards and proposals.
• W3C Document Object Model (DOM) page: Overview of the DOM interface with links to
specifications.
• A re-introduction to JavaScript: A concice JavaScript tutorial/overview for programmers by
Simon Wilson.
• Yahoo! User Interface Library: The example in this tutorial uses several "minified" versions
of YUI libraries. The Yahoo! YUI pages have more readable, commented versions of these
and other libraries along with documentation and examples.
Adding Links
432
XSLT Tutorial
XSLT Tutorial Overview
Before You Start
This tutorial assumes:
• You are interested in XSLT. Previous knowledge of XSLT is not required for this tutorial.
The XSLT Tutorial walks you through a simple program and later suggests various
resources for further information.
XSLT Tutorial Scenario
In the Perl Tutorial, a Perl program converts a text file containing exported email messages to an
XML file. In this tutorial, XSLT converts the XML file to HTML. Note that you do not need to
complete the Perl Tutorial before doing the XSLT Tutorial. Each tutorial can be completed
independently. In this tutorial you will:
1. Open the XSLT Tutorial Project and associated files.
2. Analyze mailexport.xml the XSLT program included in the XSLT Tutorial Project.
3. Run the Program and generate HTML output through the transformation.
4. Debug the program using the Komodo debugger.
Opening the Tutorial Project
On File menu, click Open|Project and navigate to the xslt_tutorial.kpf project file on the
xslt_tutorials subdirectory. The location differs depending on your operating system.
Windows
<komodo-install-directory>\lib\support\samples\xslt_tutorials
Linux
<komodo-install-directory>/lib/support/samples/xslt_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/xslt_tutorials
All files included in the tutorial project are displayed on the Projects tab in the Left Pane.
Opening the XSLT Tutorial Files
On the Projects tab, double-click the files mailexport.html, mailexport.xml, and mailexport2html.xsl.
These files open in the Editor Pane; a tab at the top of the pane displays each of their names.
XSLT Tutorial
433
Komodo User Guide
Overview of the Tutorial Files
• mailexport.xml: An input file that contains email messages converted to XML format. (See
how this was done in the Perl Tutorial.)
• mailexport2html.xsl: An XSLT program that generates an HTML file from the
mailexport.xml input file.
• mailexport.html: A file that stores the HTML output from the XSLT transformation.
Analyzing the Program
In this step, you will analyze the XSLT program on a line-by-line basis. Open the XSLT Tutorial
Project and associated files as described in the previous step. Be sure Line Numbers are enabled
in Komodo (View|View Line Numbers). Be sure the mailexport2html.xsl file is displayed in the
Komodo Editor Pane.
XSLT Header
Lines 1 to 3 - XML and XSLT Declarations
• an XSLT program is an XML document - thus, the XML version and character set are
declared on the first line
• the namespace declaration on the second line tells the "parser" (the XSLT interpreter) that
XSLT elements are prefixed with xsl: to prevent confusion with user-defined element
names and non-XSLT elements
• xsl:output controls the appearance of the generated output; for example, the presence
of this line generates a META declaration in the head of the HTML output
Komodo Tip: Notice that different types of language elements are displayed in different colors.
Adjust the display options for language elements in the Preferences dialog box.
XSLT Pointer: Processing routines in XSLT programs are enclosed in opening and closing tags
similar to those in XML.
HTML Header
Line 6 - XSLT "template"
• template is the main processing element in an XSLT program
• the match="/" attribute specifies that the template is selected when the document element
is processed
XSLT Pointer: XSLT commands have (up to) four components: namespace ("xsl"), element
("template"), attribute(s) ("match="), and attribute value(s) ("/").
XSLT Pointer: XSLT uses XPath expressions to select data from XML documents. On line 6,
match="/" selects a "node" in the XML document's hierarchy, rather than a specific item of data.
Overview of the Tutorial Files
434
Komodo User Guide
Lines 7 to 11 - HTML Tags
• writes standard HTML tags to the output document
Line 12 - XSLT apply-templates
• processes each node of the XML document (that is, each sub-section contained beneath
the current position in the XML document)
• for each node, the XSLT "engine" (the internal processor) checks the XSLT program for a
matching template
• the first XML tag with a corresponding template is <EMAIL>
Lines 13 to 15 - HTML Tags
• after processing all the nodes in the XML document, processing returns to line 13, where
the closing tags for the HTML page are written to the output
• line 15 closes the XSLT processing routine, completing the program
Format Email Header
Lines 18 to 21 - Select HEADER content
• when line 18 is processed, content in <HEADER> tags in the XML document are processed
• lines 19 and 21 write standard HTML formatting around the content generated in line 20
• on line 20, the value-of statement selects content contained in the <SUBJECT> tag and
writes it to the output document
Komodo Tip: Click the minus symbol to the left of line 19. The entire section of nested code is
collapsed. This is called Code Folding.
Lines 22 to 29 - call-template
• after the From: text, the call-template routine causes the XSLT program to proceed to
the template formatEmail on line 51; after completing the formatEmail routine,
processing returns to line 23
• with-param indicates that the parameter address should be applied to the contents of
the <ORIGADDRESS> XML tag
• the same selection and formatting routine is applied to the contents of the <DESTADDRESS>
XML tag on lines 26 to 28
XSLT Pointer: Notice the <BR/> HTML tag on line 25. XML and XSLT treat all tags as container
tags that have both opening and closing elements. However, some HTML tags (like <BR> and
<IMG>) stand alone, and do not require a closing tag. They are represented with a closing slash.
XSLT tags also use a closing slash if they are not a tag pair (as shown on line 23).
Process Email
HTML Header
435
Komodo User Guide
Lines 33 to 34 - Process First Message
• when the apply-templates tag in line 12 is encountered, processing jumps to line 33
• on line 34, the HEADER node is selected and processing jumps to line 18
XSLT Pointer: Comments in XSLT programs are enclosed in the tags <!-- and -->, the same as
in HTML.
Lines 36 to 39 - Process Email Body
• after processing the email header, the XSLT program proceeds to line 36
• the contents of the BODY tag are placed in the HTML tags
Komodo Tip: XSLT programs and XML input documents must be "well-formed" in order to
perform transformations. Komodo's Background Syntax Checking makes it easy to identify and fix
coding errors.
Format Email Addresses
Lines 45 to 52 - Format Email Addresses
• the routine that starts on line 47 is called from lines 22 and 26
• address parameter contents are determined on lines 23 and 27
• on line 49, the contents of the address parameter are converted to a variable and
concatenated with the text that constitutes a valid email address reference in HTML
Running the Program
To start, generate program output by running the program through the debugger without setting any
breakpoints.
1. Assign XML input file: On the Debug menu, click Go/Continue. In the Debugging Options
dialog box, specify mailexport.xml as the XML input file. Use the Browse button to navigate
to the directory containing the XSLT tutorial project files.
2. Run the debugger: Click OK to run the debugger.
3. Stop the debugger: From the Debug menu, select Stop to end the debugging process.
4. View Debug Output: Notice the messages displayed on the status bar in the bottom left
corner of the screen; these indicate the debugger status. The results of the transformation
are displayed on the Debug tab.
5. View the Output as HTML: On the right side of the Bottom Pane, click the HTML tab. The
rendered HTML is displayed in the Bottom Pane. Click the Output tab to return to the HTML
code.
6. Create New File: To create a new HTML file that will later contain the HTML code in the
Bottom Pane, select File|New|New File. In the New File dialog box, select the HTML
Category. Click Open.
7. Save the Output: Delete the contents of the new HTML file tab in the Editor Pane, and then
select the contents of the Output tab on the Bottom Pane. Copy the contents to the new
HTML file tab in the Editor Pane. Select File|Save As to save the file with a unique name.
Process Email
436
Komodo User Guide
Debugging the Program
This section reviews how to add breakpoints to the program and "debug" it. Adding breakpoints lets
you to run the program in parts, making it possible to watch variables and view output as they are
generated. Before beginning, be sure that line numbering is enabled in Komodo (View|View Line
Numbers).
1. Step In/Assign the XML input file: If necessary, click on the mailexport2html.xsl tab in the
editor. From the menu, select Debug|Step In. In the Debugging Options dialog box, specify
mailexport.xml as the XML input file. This should already be set if the input file was
assigned in the previous step. Assigning the XML input file to the XSLT program file selects
the XML file as the default input file when running the transformation.
2. Start Debugging: In the Debugging Options dialog box, click OK to start debugging.
Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or
from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command
List.
3. Watch the debug process: A yellow arrow on line 7 indicates the position in the XSLT file
where the debugger has halted.
4. View Debug tab: In the Bottom Pane, click the Debug tab. On the right side of the Debug
tab, click the Call Stack tab. On the Call Stack tab, notice that the current call stack is the
template in line 6 of the XSLT program.
5. Set a breakpoint: On the mailexport2html.xsl tab in the Editor Pane, click the gray margin
immediately to the left of the code on line 12. This sets a breakpoint, indicated by a red
circle.
Komodo Tip: Breakpoints can be set at any time. An enabled breakpoint is a solid red circle. A
disabled breakpoint is a white circle with a red outline. Click once in the gray margin to enable a
breakpoint. Click an enabled breakpoint once to disable it.
6. Line 7: Continue: Select Debug|Go/Continue. The debugger runs until it encounters the
breakpoint on line 12. If no breakpoint had been set, the debugger would have run to the
end of the program.
7. Line 12: Step In: Click Debug|Step In. Notice the debugger jumps to line 33 of the XSLT
program, and shows a pointer in the XML file on line 3. When the debugger processed line
12 (xsl:apply-templates), it looked for a template that matched the top node in the
XML document (<EMAILCOMMENTS>). When no matching template was found, it proceeded
to the next node in the XML document (<EMAIL>) and found a matching template on line
33.
8. View the Debug tab: Notice that the Call Stack tab displays the current template match.
Previous template matches can be selected from the list; double-clicking them jumps to the
corresponding lines in both files.
9. Line 33: Step In: Use the Step In command until the current-line pointer in the XSLT file is
on line 20.
10. Line 20: Step In: Watch the Bottom Pane as you Step In line 21. The xsl:value-of
statement selects the contents of the <SUBJECT> field on line 7 of the XML file and places it
within the HTML tags on lines 19 and 21.
11. Line 21: Step In: Line 22 calls the template formatEmail on line 45. Continue to step in
until line 49 is processed. The formatEmail template is processed with the address
Debugging the Program
437
Komodo User Guide
parameter on line 46. This routine processes the contents of the <ORIGADDRESS> node in
the XML document. In order to generate the hyperlink in the output HTML document, lines
48 and 49 concatenate the string mailto: with the contents of the <ORIGADDRESS> node.
12. Line 49 to end: Go/Continue: On Debug menu, click Go/Continue to run the rest of the
XSLT program. The program's output is displayed in the Bottom Pane: raw output in the
Output tab and rendered output in the HTML tab.
More XSLT Resources
ASPN, the ActiveState Programmer Network
ASPN, the ActiveState Programmer Network, hosts the XSLT Cookbook, a collaborative library of
XSLT code.
Documentation
The W3C (World Wide Web Consortium) specifications are available online:
• XSLT
• XPath
• XML
Tutorials and Reference Sites
There are many XSLT tutorials and beginner XSLT sites on the Internet, including:
• xml.com's What is XSLT?
• free tutorials at W3Schools.com
More XSLT Resources
438
Run Command Tutorial
Run Command Tutorial Overview
Run Command Tutorial Scenario
This tutorial introduces you to the Komodo Run Command feature. You will learn how to run simple
and complex custom commands (such as grep, make, and perl); use these commands to
process and analyze files; save commands to run with a single keystroke; and use commands to
make Komodo a more powerful editor. In this tutorial you will:
1. Run simple commands using the Komodo Run Command feature.
2. Use advanced command options to control how and where a command is run.
3. Save commands in the Toolbox and assign keyboard shortcuts.
4. Using interpolation shortcuts to customize commands for reuse.
5. Prompting for input to have your commands prompt you for information before running.
6. Parse command output into a list of results by specifying a regular expression.
Opening the Tutorial Project
On the File menu, click Open|Project and select runcmd_tutorial.kpf from the
\samples\runcmd_tutorials subdirectory of the Komodo installation. All files included in the
tutorial project are displayed on the Projects tab in the Left Pane.
Running Simple Commands
Hello, World!
The Komodo Run Command feature offers another way to run commands that would otherwise be
run on the system command line. This section starts with a simple echo command.
1. Select Tools|Run Command to open the Run Command dialog box.
2. In the Run field, enter echo Hello World.
3. Click Run. The results are displayed on the Command Output tab.
Run Command Tutorial
439
Komodo User Guide
Command Output Tab
Output from commands is displayed on the Command Output tab.
Use the Command Output tab to interact with commands; if the command accepts input, enter it
directly into the command on the Command Output tab. The Command Output tab has the
following features:
• Output written to stderr (standard error output) is displayed in red at the top of the
Command Output tab.
• To terminate a running command, click the
button in the upper right-hand corner of the
tab.
• Many keyboard shortcuts available in the Komodo editor can also be executed on the
Command Output tab. For example, 'Ctrl'+'Shift'+'8' ('Meta'+'Shift'+'8' on Mac OS X)
displays white space and 'Ctrl'+'Shift'+'7' ('Meta'+'Shift'+'7' on Mac OS X) displays line
endings (if the default key binding scheme is in effect).
The Toggle Raw/Parsed Output View button
section of this tutorial.
is discussed in the Parsing Command Output
Inserting Command Output
Insert command output into a document using the Insert output option.
1. On the Projects tab, double-click the file play.txt. The file opens in the Editor Pane; a tab at
the top of the pane displays its name.
2. Select Tools|Run Command.
3. In the Run field, enter the command dir (on Windows) or ls -al (on Linux).
4. Select the Insert output check box, and then click Run. The contents of Komodo's current
directory are inserted into play.txt.
Filtering Parts of a Document
The Pass selection as input option passes selected text to the specified command. Use this
option together with the Insert output option to filter selected regions of a document.
1. Open play.txt from the Run Command tutorial project (if it is not already open).
2. Select all six lines containing the word frog.
Command Output Tab
440
Komodo User Guide
3. Select Tools|Run Command.
4. In the Run field, enter the command sort (on Windows) or sort -n (on Linux).
Note that the Pass selection as input and Insert output options are selected automatically.
If one or more lines are selected in a document, the Run Command expects to filter the
selected lines.
5. Click Run to sort the list of frogs.
Use the grep command line utility to filter lines of text. Use grep to filter out all but the red frogs
from the list.
This tutorial assumes the grep utility is installed on your system and is in your system's PATH.
Grep is a Linux utility that searches for text and characters in files. Windows operating system
users may not have a grep installation. There are a number of free versions available on the Web.
Search using the keywords grep for Windows.
1. Open play.txt from the Run Command tutorial project (if it is not already open).
2. Select the "5 red frogs" and "6 green frogs" lines.
3. Select Tools|Run Command.
4. In the Run field, enter the command grep red.
5. Click Run to remove all but the red frogs.
Using Advanced Options
Clicking the More button in the Run Command dialog box reveals a number of advanced options.
Filtering Parts of a Document
441
Komodo User Guide
Specifying a Command's Working Directory
To set the current working directory for a command:
1. Select Tools|Run Command. Click More to display Advanced Options.
2. In the Run field, enter the command: dir (on Windows), or ls -al (on Linux).
3. In the Start in field, enter C:\ (on Windows), or /home (on Linux).
4. Click Run to generate a C:\ directory listing.
Specifying Environment Variables
Specify which environment variables to set for a command. For example, use this feature for
setting PERL5LIB or PYTHONPATH when running Perl or Python scripts.
1. Select Tools|Run Command.
2. In the Run field, enter the command: set.
3. Click New... to add a new environment variable. For the variable name, enter: PERL5LIB
4. Click Add Path... to choose a value for PERL5LIB (the actual value you choose does not
matter for this example). Click OK.
5. Click Run to display all environment variables. Scroll through the results on the Command
Output tab until the PERL5LIB setting is located.
Using Advanced Options
442
Komodo User Guide
Running GUI Apps or Running Commands in a Console
Run GUI programs outside of the Command Output tab by changing the Run in option to No
Console.
1. Select Tools|Run Command.
2. In the Run field, enter the command: mozilla
If the Mozilla browser is not installed on your system, choose another GUI application to
run. For example, on Windows, try running either the iexplore or notepad command.
3. From the Run in drop-down list, select No Console (GUI Application).
4. Click Run to open the GUI application rather then the Command Output tab.
To run commands in a new console window:
1. Select Tools|Run Command.
2. In the Run field, enter the command: dir
3. From the Run in drop-down list, select New Console.
4. Click Run to execute the command and open a new console window.
Saving and Rerunning Commands
Save frequently used commands for quick access and reuse.
Rerunning Recent Commands
Select Tools|Recent Commands to rerun recently run commands.
Saving Commands in the Toolbox
The Run Command dialog box contains an option for saving commands in the Toolbox for reuse. A
command saved in the Toolbox is indicated with the
icon.
Running GUI Apps or Running Commands in a Console
443
Komodo User Guide
1. Select Tools|Run Command.
2. In the Run field, enter the command: echo Hello World
3. Select the Add to Toolbox check box.
4. Click Run. Notice that a command named echo Hello World is added to the Toolbox.
5. Double-click the
icon next to echo Hello World to rerun the command.
Saving Commands in a Project
Commands can also be stored in a Komodo Project.
For example, the Run Command Tutorial project includes a Command to echo "Hello World".
Consider adding commands to your projects to run make or other command line tools. There are
two ways to add commands to a project:
• Right click on a project and select Add New Command....
• Drag and drop a command from the Toolbox tab or another open project onto the Projects
tab.
Editing Saved Command Properties
Edit command properties in the Command Properties dialog box.
Saving Commands in the Toolbox
444
Komodo User Guide
To open this dialog box, right click on any saved command and select Properties.
Using Interpolation Shortcuts
Run Command can use interpolation shortcuts for putting filenames, directory names, paths and
other arguments into commands as variables. This creates commands that are more generic and
useful. Enter command shortcuts in the Run and Start in fields, or select them from the drop-down
lists to the right of the Run and Start in fields. Windows users should enclose all interpolation
shortcuts (with the exception of %(browser)) in double quotation marks to ensure that spaces in
filenames or file paths are interpreted correctly.
Click the arrow button to the right of the Run field to view a list of Run Command shortcuts.
Editing Saved Command Properties
445
Komodo User Guide
Shortcuts for the Current File
The string %F in a command expands the full path of the current file.
1. On the Projects tab, double-click the file play.txt. The file opens in the Editor Pane; a tab at
the top of the pane displays its name.
2. Select Tools|Run Command.
3. In the Run field, enter the command:
echo "%F"
4. Click Run.
Change the current file status from "writable" to "read-only".
1. Open play.txt (if it is not already open).
2. Select Tools|Run Command.
3. In the Run field, enter the command:
attrib +R "%F"
on Windows, or:
chmod u+w "%F"
on Linux.
4. Click Run. The result is displayed at the top of the Command Output tab.
To open a current HTML file in a Web browser, combine %F with the %(browser) shortcut.
1. On the Projects tab, double-click the file index.html.
2. Select Tools|Run Command.
3. Click the arrow to the right the Run field to display the shortcuts drop-down list. Select
%browser, press the space bar, and then select %F. Enclose the %F in double quotation
marks.
4. From the Run in drop-down menu, select No Console (GUI Application).
Using Interpolation Shortcuts
446
Komodo User Guide
5. Click Run.
Shortcuts for the Current Selection
The %s, %S, %w and %W codes insert current selections, or the current word under the cursor,
into commands. This shortcut helps when running utilities like grep, or for searching the Web.
1. On the Projects tab, double-click the file index.html.
2. Position the cursor over the word "PHP" in index.html.
3. Select Tools|Run Command.
4. In the Run field, enter the command:
%(browser) http://www.google.com/search?q="%W".
5. Select the Add to Toolbox check box to save this command.
6. Click Run to search for "PHP" with Google.
Now that you have searched for a word or selection in Google, try the following shortcut to search
for PHP methods.
1. Open index.html.
2. Select the text mysql_info methods in the file.
3. Select Tools|Run Command.
4. In the Run field, enter the command "%(browser)
http://www.php.net/manual-lookup.php?pattern=%S".
5. Select the Add to Toolbox check box to save this command.
6. Click Run to search mysql_info methods in PHP's online manual.
These two commands are built into Komodo. If the default key binding scheme is in effect,
'Ctrl'+'F1' ('Meta'+'Ctrl'+'/' on Mac OS X) starts a Google search for the current selection. 'Shift'+'F1'
('Meta'+'/' on OS X) in a Perl, Python or PHP file starts a help search appropriate for that language.
Customize searches in the Preferences dialog box (Edit|Preferences|Language Help).
Using Shortcuts for a Command's Directory
Run commands from the directory where the current file is stored, rather then the current directory.
For example, use the command %(perl) "%F" to run the current file with a configured Perl
interpreter.
1. On the Projects tab, double-click the file hello.pl.
2. Select Tools|Run Command.
3. In the Run field, enter the command:
%(perl) "%F"
4. In the Start in field, enter: "%D"
5. Click Run.
This example assumes a perl interpreter is configured on your system. If a perl interpreter is not
configured (the required file is perl.exe), an error message displays at the top of the Command
Output tab. Alternatively, run the command dir (Windows) or ls (Linux) to display a list of files
and folders beneath the current directory.
Shortcuts for the Current File
447
Komodo User Guide
Prompting for Input
Introduction
Run Commands can prompt for specific input with a dialog box. These queries can be configured
with default values and/or prompt the user if no value could be determined automatically (e.g. a
command to search Google for the current selection that prompts for a search term if nothing is
selected).
The %(ask) and %(askpass) shortcuts always prompts the user for data. Other shortcuts can
use the orask modifier to prompt the user if no valid value could be determined.
Windows users should enclose all Komodo shortcuts (with the exception of %(browser)) in
double quotation marks. This is necessary to ensure that any spaces in filenames or file paths are
interpreted correctly.
Always Prompting with %(ask) or %(askpass)
The full syntax of %(ask) and %(askpass) shortcut are:
%(ask[:NAME:[DEFAULT]])
%(askpass[:NAME:[DEFAULT]])
where NAME is an optional name to use when prompting in the dialog box and DEFAULT is an
optional default value to place in the dialog box.
For example:
1. Select Tools|Run Command.
2. In the Run field, enter the command: echo Your favorite number is "%(ask)"
3. Click the Run button to run the command. The Interpolation Query dialog box is displayed.
4. Enter your favorite number and click OK to finish running the command.
Refine this shortcut by adding a more meaningful name than "Value 0" and a more appropriate
default value.
1. Select Tools|Run Command.
2. In the Run field, enter the command: echo Your favorite number is "%(ask:Fav
Number:42)"
3. Click the Run button to run the command. The Interpolation Query dialog box will now look
like this:
Prompting for Input
448
Komodo User Guide
4. If your favorite number does not happen to be 42, enter a different number and click OK to
finish running the command.
Prompting When Necessary with %(...:orask)
Any Run Command shortcut can be modified to prompt the user for a value if one cannot be
determined automatically. The full syntax of the modified shortcut is:
%(SHORTCUT:orask[:NAME])
where NAME is an optional name to use when prompting in the dialog box.
In the previous step we created a shortcut to search for the selected word on Google with the
command:
%(browser) http://www.google.com/search?q="%W"
However, if nothing has been selected and there is no word under the cursor, the command fails. In
this case, it would be better if the command prompted you for a search term.
1. Be sure your cursor is not positioned over a word.
2. Select Tools|Run Command.
3. In the Run field, enter the command:
%(browser) http://www.google.com/search?q="%(W:orask:Search for)"
4. Click Run. The Interpolation Query dialog box prompts for a search term.
Parsing Command Output
Introduction
Use Run Commands to specify a regular expression to parse filename and line number information
from lines of output. The parsed results are displayed in a table to quickly identify the desired file.
Explore this usage by creating a "Find in Files" command later in this section.
Parsing Output with a Regular Expression
Output from a run command can be parsed with a Python regular expression and displayed in the
Command Output tab as a list.
Komodo Tip: Use the Komodo Rx Toolkit to build, edit, or test regular expressions. New to regular
expressions? The Regular Expressions Primer is a tutorial for those wanting to learn more about
regex syntax.
Always Prompting with %(ask) or %(askpass)
449
Komodo User Guide
Named groups in Python regular expressions (e.g. (?P<name>pattern) ) can be used to sort
match data. The names 'file', 'line', 'column' and 'content' can be used as column titles in Parsed
Ouptut mode, with the matching text displayed in the columns under the names.
For example, the output of the "Find in Files" example below contains the following:
hello.pl:5:print "Hello, frogs!\n";
Output lines are of the form:
<file>:<line>:<content>
An regular expression to match the important elements of this line could be:
(.+?):(\d+):(.*)
However, to view this information as a useful list, we need to define the column headings by
naming the groups:
(?P<file>.+?):(?P<line>\d+):(?P<content>.*)
When parsing the run command output, Komodo determines that hello.pl is the file, 5 is the line
and print "Hello, frogs!\n"; is the content, and displays the output sorted into the
appropriate columns:
Parts of the output that match outside the named groups in the regular expression (e.g. the ":"
delimiters seen above) are visible when viewed as raw output, but are hidden when viewed as a
list. You can use this technique to filter out extraneous information when viewing output as a list.
For example, if you were not interested in viewing the line number of the match, you could change
the regular expression to the following:
(?P<file>.+?):\d+:(?P<content>.*)
Komodo can use the information from the 'file' and 'line' groups to open a file in an editor tab at a
particular line (see below).
Parsing Output with a Regular Expression
450
Komodo User Guide
Using "Find in Files"
Create a "Find in Files" command using all information presented in this tutorial.
1. On the Projects tab, double-click the file hello.pl.
2. Position the cursor over the word frogs.
3. Select Tools|Run Command.
4. On Windows, enter the command:
findstr /s /n /c:"%(w:orask:Search Term)" "%(ask:File Pattern:*.*)"
Or on Linux enter the command:
find . -name "%(ask:File Pattern:*)" | xargs -l grep -nH
"%(w:orask:Search Term)"
Note that findstr is a Windows command line utility that searches for strings in files.
5. Select the Add to Toolbox check box to save this command.
6. In the Start in field, enter:
%(ask:Start Directory:%D)
(When the command is run, Komodo should prompt for the "Start Directory" using the
directory of the current file, or %D as the default value).
7. Select the Parse output with check box and enter:
^(?P<file>.+?):(?P<line>\d+):(?P<content>.*)$
as the regular expression with which to parse.
8. Select the Show parsed output as a list check box.
9. Click Run. The Interpolation Query dialog box is displayed.
10. Click OK to run findstr. A list of all occurrences of "frogs" in the files of the Run Command
tutorial project is displayed on the Command Output tab.
11. Double-click on a parsed result to jump to a specific file and line.
12. Click the
button to toggle back to the Command Output tab.
Using "Find in Files"
451
Komodo User Guide
Alternatively, double-click on lines in the raw output view to jump to that file and line.
Using "Find in Files"
452
Komodo FAQ
• Where is Komodo installed?
• Where does Komodo keep settings data?
• Where does Komodo save log files?
• Komodo doesn't start
• I can't see my Left or Right Pane
• I can't see my Bottom Pane
• I want to maximize my Editor Pane
• How do I know if I'm debugging?
• How do I know if I'm editing?
• How can I add command-line arguments to my program for debugging?
• Komodo crashes. What can I do?
• Why is Komodo so big?
• I already have Mozilla. Why do I need to have two versions?
• I'm having trouble debugging PHP. What do I do?
• How do I emulate sessions in PHP debugging?
• How do I configure Virtual Hosting on an Apache Web server?
• I moved my Komodo installation on Linux, and am now getting Perl debugging errors.
• How do I prevent the dialog from displaying every time I start the debugger?
• Why do I get a CGI security alert when debugging PHP?
• The Check Configuration window reports that a language installed on my system is not
available. Why?
• My screen goes black for a second or two whenever I open files for which Komodo performs
background syntax checking. Why?
• How can I run additonal CVS commands from within Komodo?
• Why doesn't Ruby debugging work on my Linux x64 system?
Where is Komodo installed?
The Komodo installer will prompt for an installation directory; you can choose any directory you
have permissions to install to. The default location varies by platform, and the name of the directory
corresponds to the version of Komodo you are running ("IDE" or "Edit" plus the version number e.g. "Komodo-IDE-4.0"):
Windows
C:\Program Files\ActiveState Komodo [IDE|Edit] <version>\
Linux
/opt/Komodo-[IDE|Edit]-<version>/
OS X
/Applications/Komodo-[IDE|Edit]-<version>.app
Komodo FAQ
453
Komodo User Guide
Where does Komodo keep settings data?
Komodo stores preferences, macros, templates, keybinding schemes and other settings in a
user-specific directory called the user data directory. The name and location of this directory varies
depending on the operating system and Komodo version:
Windows 2000 and XP
C:\Documents and Settings\<user>\Application Data\ActiveState\Komodo[IDE|Edit]\<version>
Windows Vista
C:\Users\<user>\AppData\ActiveState\Komodo[IDE|Edit]\<version>
Linux
/home/<user>/.komodo[ide|edit]/<version>
Mac OS X
/Users/<user>/Library/Application Data/Komodo[IDE|Edit]/<version>
The location of this directory can be overridden using the KOMODO_USERDATADIR environment
variable.
Where does Komodo log output and errors?
Within the user data directory is the host data directory (host-<hostname>). It contains
pystderr.log and pystdout.log, which can be useful for troubleshooting problems with
Komodo.
Komodo doesn't start. Why?
If Komodo doesn't start, there could be one of several issues.
• Do you have a license installed?
Komodo needs a license to become functional. If you have a Beta release, we include a trial
license with the package. If you have a final release (non-Beta), you can download a license
from ActiveState.
• Do you have Norton Anti-Virus (NAV) installed, or more specifically, the File System
Realtime Protection feature enabled?
The problematic relationship between Komodo and Norton Anti-Virus' File System Realtime
Protection feature is a known issue, which we are working to remedy. In the meantime, you
can disable NAV Corp 7.5 FSRP before running Komodo, and then re-enable it after
Komodo starts.
If none of these seem to apply to you, please follow the instructions in this FAQ entry to log a bug
in Komodo's bug database.
Where does Komodo keep settings data?
454
Komodo User Guide
Why can't I see my Left or Right Pane
One or more panes may be hidden.
To view the Left Pane, click the Show/Hide Left Pane button on the toolbar, use the options on the
View menu, or use the associated key binding.
I can't see my Bottom Pane
The Bottom Pane appears below the Editor Pane during debugging. If you can't see your Bottom
Pane, it may be hidden.
To view the Bottom Pane, click the Show/Hide Bottom Pane button on the toolbar, use the options
on the View menu, or use the associated key binding.
For more information, see Debugging Programs
I want to maximize the Editor Pane
I like to see the Left and Right Panes and the Bottom Pane, but right now I want to maximize my
Editor Pane to get some coding done. How can I maximize my Editor Pane?
To maximize your Editor Pane, hide the other panes in the Komodo workspace:
1. Click the close arrow button that appears in the top right corner of each of these panes.
How do I know if I'm debugging?
When Komodo is debugging, the title of the Komodo workspace includes an indication of the state
of the debugger. If the debugger is running, the title looks similar to [pathname\filename] ActiveState Komodo - Debugger is running. If the debugger has hit a breakpoint, the title looks
similar to [pathname\filename] - ActiveState Komodo - Debugger is in Break Mode.
How do I know if I'm editing?
You are editing any time you're not formally debugging. When Komodo is editing, the title of the
Komodo workspace is [pathname\filename] - ActiveState Komodo.
How can I add command-line arguments to my program for
debugging?
If you want to send add command-line arguments to your program for debugging, you can add
these using the Debugger Launch Options dialog:
1. On the Debug menu, click Start.
2. In the Debugger Launch Options dialog, select the directory you want to begin debugging
your program in. Click Browse and navigate to the appropriate directory.
Why can't I see my Left or Right Pane
455
Komodo User Guide
3. In the same Debugger Launch Options dialog, enter your command-line arguments. These
are sent to the script and not to the interpreter. Separate the arguments with spaces.
4. Click OK.
Komodo crashes. What can I do?
As Komodo is running it updates a few log files with debugging and error information. If Komodo
crashes, you can help us best determine the issue by sending us those log files, along with
information on how you came across the crash. On some operating systems the system creates a
crash log as well, which you should also send to us. The log files may include:
• startup.log (in your Komodo user data dir)
• pystderr.log (in your Komodo user data dir)
• pystdout.log (in your Komodo user data dir)
• console.log (in your Komodo user data dir)
• komodo-bin.crash.log (Mac OS X only, in ~/Library/Logs/CrashReporter)
Please use the following steps to send us your crash information:
Step 1: Ensure the logs are for the time Komodo crashed
Komodo's log files are only for the last time Komodo was run. If you have restarted Komodo since
the time it crashed on you, you must reproduce the crash so that the log files are relevant.
Note: If Komodo is hung (i.e. won't shutdown), you may need to manually stop the komodo-bin
process:
Windows
Press 'Ctrl'+'Shift'+'Esc' to open "Windows Task Manager". Select the
"Processes" tab. Right-click on the "komodo.exe" entry and select "End Process".
Mac OS X
Right-click (or 'Option'+click) on the Komodo head icon in the Dock and select the "Force
Quit" option.
Linux
At the terminal run ps ux | grep komodo-bin to determine the Komodo process id (or
"pid"). Then run kill -9 PID where "PID" is the process id from the previous command.
Step 2: Locating the error log files
Komodo stores its log files in the host data subdirectory of the user data directory.
On Mac OS X, an additional komodo-bin.crash.log is created by the system in
~/Library/Logs/CrashReporter/.
Step 3: Verifying and sending the files to ActiveState
To send the error log files to ActiveState:
1. Locate the files.
2. Verify that the files are not blank by viewing them with a text editor.
How can I add command-line arguments to my program fordebugging?
456
Komodo User Guide
3. Create a bug describing what happened just before the crash in the ActiveState bug
database. (If you do not already have an ASPN or ActiveState bug database account, you
can open one by selecting "join".)
4. Once the bug has been created, add the error log files by selecting Create in the
Attachments and Dependencies section of the bug report.
Why is Komodo so big?
Because Komodo is built on the Mozilla framework, it is necessary for us to include the Mozilla
build that exactly matches the development version of Komodo. For that reason, even if you have
Mozilla on your system, Komodo installs the Mozilla version that it requires.
Another sizeable component of Komodo is language support. Komodo is so tightly integrated with
Perl, Python, Ruby and PHP that it is necessary to include components of those languages, at
specific version levels, for debugger and editor support.
I already have Mozilla. Why do I need to have two versions?
When ActiveState develops a Komodo release, the work is based upon a specific version of
Mozilla. During the development process, we upgrade the level of Mozilla used by Komodo, but this
process requires considerable testing to ensure that no functionality is lost. Additionally, we add
some custom components to the Mozilla tree that are used by Komodo. For these reasons, we
recommend that you do not replace the Mozilla version included with Komodo with a later Mozilla
version.
I'm having trouble debugging PHP. What do I do?
If you receive an error message when attempting to debug a PHP program or if the debugging
process does not proceed as expected, verify that you have installed PHP and the Xdebug
extension as per the instructions in the Debugging PHP documentation, then check the following:
Confirm PHP Configuration
1. xdebug: in the command or shell window, enter php -m. "xdebug" should be listed as both
a regular module and a zend extension. If this is not the case, your configuration is
incorrect. See "Common PHP Configuration Problems" below.
2. Syntax Checking: in Komodo, select Edit|Preferences. Click on Smart Editing, and
ensure that "Enable background syntax checking" is checked. Open a PHP file and enter
something that is syntactically incorrect, such as:
<?
asdf
echo test;
?>
Komodo should display a red squiggly line under echo test;. If it does not, it indicates
that Komodo is not able to communicate with the PHP interpreter.
3. Debug: if steps one and two were successful, ensure that the debugger is functioning by
opening a PHP program and debugging it. Ensure that the correct Preferences are
configured for PHP.
Komodo crashes. What can I do?
457
Komodo User Guide
If any of the steps above were unsuccessful, proceed to the next section.
Common PHP Configuration Problems
• Multiple PHP executables on one machine: in Komodo's Preferences, explicitly specify
the PHP interpreter configured in your php.ini file. The location of the php.ini file can also be
explicitly set.
• Verify the PHP version: PHP 4.0.5 or greater is required for PHP syntax checking. PHP
4.3.1 or greater is required to debug PHP programs.
• Verify Xdebug library specification: The location of xdebug.dll (Windows) or xdebug.so
(Linux) must be defined the php.ini file, for example:
♦ Windows: zend_extension_ts=C:\php-4.3.7\extensions\php_xdebug.dll
♦ Linux: zend_extension=/php-4.3.7/extensions/php_xdebug.dll
• Ensure that the Xdebug extension is configured correctly in the php.ini file as per the
Remote PHP Debugging instructions.
Windows-Specific Configuration Issues
• Windows 2000 upgrade: if you upgraded to Windows 2000 from an earlier version of
Windows, check the value of the "COMSPEC" variable in the "System variables" (as
described above). It should point to C:\WINNT\system32\cmd.exe, and not
command.com. If you must change the variable, reboot your system.
• There are known issues regarding the installation of PHP on Windows Millennium systems;
please refer to the PHP site for installation information.
Version Error Messages
If you receive a dialog with the following text:
Warning
xdebug: Unable to initialize module
Module compiled with debug=0, thread-safety=1 module API=20001222
PHP compiled with debug=0, thread-safety=1 module API=20001222
These options need to match
... download an updated version of xdebug.dll (Windows) or xdebug.so (Linux) from the
Xdebug.org site.
How do I emulate sessions in PHP debugging?
Though it is possible to emulate sessions in local debugging mode, this requires pre-knowledge of
session keys, and how those session keys are communicated to PHP.
It is easier to debug sessions using remote debugging. Run the script under a web server and start
the debugging session from a web browser. Komodo intercepts the session and debugs it. All
session data is available and modifiable through the Variable tabs.
I'm having trouble debugging PHP. What do I do?
458
Komodo User Guide
How do I configure Virtual Hosting on an Apache Web
server?
Virtual Hosting is an Apache feature for maintaining multiple servers on the same machine,
differentiating them by their apparent hostname. For example, a single machine could contain two
servers, "www.yourdomain.com" and "debug.yourdomain.com".
If you have configured your Apache installation to use Virtual Hosting (see
httpd.apache.org/docs/1.3/vhosts/), you can add directives to your VirtualHost sections to specify
how Komodo's PHP debugger extension operates for those hosts. Use the "php_admin_value" to
set specific debugger settings for that virtual host. Here is an example:
NameVirtualHost *
<VirtualHost *>
php_admin_value xdebug.enabled 0
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/www.error.log
Servername www.yourdomain.com
</VirtualHost>
<VirtualHost *>
php_admin_value xdebug.enabled 1
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/debug.error.log
Servername debug.yourdomain.com
</VirtualHost>
This will enable debugging under debug.yourdomain.com, but not under www.yourdomain.com.
You can additionally configure the Virtual Host to use a specific machine for remote debugging:
<VirtualHost *>
php_admin_value xdebug.enabled 1
php_admin_value xdebug.host komodo.yourdomain.com
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/debug.error.log
Servername debug.yourdomain.com
</VirtualHost>
For more information on configuring Virtual Hosting under Apache, see the Apache documentation
at httpd.apache.org/docs/.
I moved my Komodo installation on Linux, and am now
getting Perl debugging errors.
On Linux, you cannot relocate an existing Komodo installation to a new directory. You must
uninstall Komodo from the existing location and reinstall it in the new location. See Uninstalling
Komodo on Linux for instructions.
How do I prevent the dialog from displaying every time I
start the debugger?
How do I configure Virtual Hosting on an Apache Web server?
459
Komodo User Guide
To prevent the debugger dialog from appearing each time you start the debugger, hold down the
'Ctrl' key when you start the debugger. For example, on Windows and Linux, press 'Ctrl'+'F5' rather
than 'F5' to start debugging. Click Help|List Key Bindings to find the equivalent key binding for the
Emacs and OS X default key binding schemes.
Why do I get a CGI security alert when debugging PHP?
The CGI security alert only occurs when you compile PHP with --enable-cgi-force-redirect. That
compilation directive forces PHP to check if it is being run as a CGI by looking at environment
variables commonly available only under a CGI environment. If they exist, it looks for another
environment variable that is reliably available ONLY under Apache, REDIRECT_STATUS (or
HTTP_REDIRECT_STATUS under Netscape/iPlanet). If that environment variable does not exist,
the security alert is generated.
To run your compilation of PHP under Komodo with CGI emulation, you have to add a CGI
environment variable called REDIRECT_STATUS with any value.
When I click Check Configuration on the Start Page,
Komodo reports that a language that is installed on my
system is not available. Why?
In order for Komodo to detect the presence of a language installed on your system, the location of
the language interpreter must be specified in your system's PATH environment variable. If the
Komodo Start Page states that a language is "Not Functional", or if the Komodo Preferences say
that the language interpreter is not found on your system, check that the interpreter is specified in
your PATH.
My screen goes black for a second or two whenever I open
files for which Komodo performs background syntax
checking. Why?
Komodo launches a process as part of the background syntax checking that can cause a full
screen command prompt to momentarily appear on some Windows systems. You can make the
process invisible by editing the properties for the command prompt window. On the Windows Start
menu, right-click the Command Prompt item, and select Properties. Select the Options tab, and
change the Display options to Window.
How can I run additonal CVS commands from within
Komodo?
Komodo can be used to check out, add, remove, compare, submit and revert files in a CVS
repository. CVS offers additional commands such as import, checkout, history, annotate, rdiff and
watch which can be put into Run Commands and saved to a project or the Toolbox. For example,
the following cvs import command prompts for the User, Host, Module, Project and Version to
import:
How do I prevent the dialog from displaying every time Istart the debugger?
460
Komodo User Guide
cvs -d :ext:%(ask:User)@%(ask:Host):%(ask:Path) import %(ask:Module:)
%(ask:Project:) %(ask:Version:)
Alternatively, the %(ask:...) interpolation shortcut could be populated with defaults or replaced
with static values:
cvs -d :ext:%(ask:User:jdoe)@myhost:/var/cvsroot import %(ask:Module:)
%(ask:Project:MyProject)
CVS reqires a real terminal for adding change descriptions. Be sure to set Run in: New Console in
the command's properties.
Why doesn't Ruby debugging work on my Linux x64
system?
Linux users trying to debug a Ruby application on AMD 64bit systems may see the following error:
The Komodo ruby debugger couldn't load the ruby-debug-base component.
This library ships with Komodo, but also can be installed by running `gem install
ruby-debug-base'
Komodo ships with a 32-bit version of ruby-debug-base, which will not work with 64-bit versions of
Ruby. To fix this:
1. Delete the installed ruby-debug libraries by removing the
/lib/support/dbgp/rubylib/1.8/ directory.
2. Download the latest ruby-debug-base gem from http://rubyforge.org/frs/?group_id=1900
3. Install the downloaded file using gem:
sudo gem install ruby-debug-base-0.9.x.gem
Komodo will automatically find and use the new version of the debugging library.
How can I run additonal CVS commands from withinKomodo?
461
Default Key Bindings
The following pages lists the default Komodo key bindings for each available scheme:
• Windows/Linux default key bindings
• Mac OS X default key bindings
• Emacs default key bindings
• Vi default key bindings
To view the current list of key bindings for your Komodo installation, including any custom key
bindings, select Help|List Key Bindings. The default key binding scheme is set according to your
platform. To select a different key binding scheme, select Edit|Preferences|Editor|Keybindings.
Default Key Bindings
462
Windows/Linux Key Bindings (Default)
This page lists the default key bindings on Windows and Linux. There are also pages that list the
default key bindings on Mac OS X. On any platform, you can also choose to use Emacs key
bindings. As any of these key bindings schemes can be customized, these pages stand as
references to the defaults. To view the current list of key bindings for your Komodo installation
(including any custom key bindings), select Help|List Key Bindings. The different key binding
schemes are either set according to the platform on which you installed Komodo, or they are
selected in Edit|Preferences|Editor|Keybindings.
Windows/Linux Scheme
Code Browser
Locate current scope...
Ctrl+K, Ctrl+L
Code Intelligence
Find Symbol
Ctrl+K, Ctrl+F
Debugger
Clear All Breakpoints
Ctrl+F9
Disable/Enable Breakpoint
F9
New Session
Ctrl+Shift+F5
Run Script
F7
Ctrl+F7
Run to Cursor
Shift+F10
Ctrl+Shift+F10
Show Current Statement
Alt+*
Start
F5
Ctrl+F5
Start/Find/Hide Default Interactive Shell
F12
Step In
F11
Ctrl+F11
Step Out
Shift+F11
Ctrl+Shift+F11
Step Over
F10
Ctrl+F10
Stop
Shift+F5
Windows/Linux Key Bindings (Default)
463
Komodo User Guide
Editor
Back
Shift+Backspace
Backspace
Backspace
Beginning of Line (first char/first column)
Home
Cancel AutoComplete
Escape
Copy
Ctrl+C
Ctrl+Insert
Cut
Ctrl+X
Shift+Delete
Ctrl+Shift+X
Delete
Delete
Delete Word Left
Ctrl+Backspace
Delete Word Right
Ctrl+Delete
End of Line
End
Go to End of Document
Ctrl+End
Go to End of word
Ctrl+E
Go to Line...
Ctrl+G
Go to Next Bookmark
F2
Go to Next Line
Down
Go to Previous Bookmark
Shift+F2
Go to Previous Line
Up
Go to Top of Document
Ctrl+Home
Insert Newline
Return
Insert Newline (align with current line)
Ctrl+Shift+Return
Insert Newline (continue comments)
Shift+Return
Insert Newline (no favors)
Ctrl+Return
Insert Next Key as Literal Character
Ctrl+M
Join current and next lines
Ctrl+K, Ctrl+J
Move Back Part of Word
Alt+Right
Move Forward Part of Word
Alt+Left
Move Left One Character
Left
Move One Character Right
Right
Move One Word Left
Ctrl+Left
Move One Word Right
Ctrl+Right
Page Down
Page_Down
Editor
464
Komodo User Guide
Page Up
Page_Up
Paste
Ctrl+V
Shift+Insert
Paste and Select
Ctrl+Shift+V
Redo
Ctrl+Y
Reflow paragraph(s)
Ctrl+Q
Remove All Bookmarks
Ctrl+Shift+F2
Repeat next keystroke N times
Ctrl+K, Ctrl+U
Scroll One Line Down
Ctrl+Down
Scroll One Line Up
Ctrl+Up
Select All
Ctrl+A
Select Next Character
Shift+Right
Select Next Part of Word
Alt+Shift+Right
Select Next Word
Ctrl+Shift+Right
Select Page Down
Shift+Page_Down
Select Page Up
Shift+Page_Up
Select Previous Character
Shift+Left
Select Previous Part of Word
Alt+Shift+Left
Select Previous Word
Ctrl+Shift+Left
Select to Beginning of Line (first char/first
column)
Shift+Home
Select to Beginning of word
Ctrl+Shift+W
Select to End of Document
Ctrl+Shift+End
Select to End of Line
Shift+End
Select to Next Line
Shift+Down
Select to Previous Line
Shift+Up
Select to Top of Document
Ctrl+Shift+Home
Toggle Bookmark
Ctrl+F2
Toggle Overtype/Insert Mode
Insert
Transpose Current and Previous Characters
Ctrl+T
Trigger preceding autocomplete list or calltip
Ctrl+J
Undo
Ctrl+Z
Zoom Font Size Down
Ctrl+Shift+-
Zoom Font Size Up
Ctrl+Shift+=
Ctrl+Shift++
Editor
465
Komodo User Guide
Find
Find Next
F3
Find Next Result
Ctrl+Shift+F3
Find Next Selected
Ctrl+F3
Find Previous
Shift+F3
Find in Files...
Ctrl+Shift+F
Find...
Ctrl+F
Incremental Search
Ctrl+I
Incremental Search Backwards
Ctrl+Shift+I
Replace...
Ctrl+H
General
Close Window
Ctrl+W
Ctrl+F4
Edit Properties
Alt+Return
Least Recently Viewed File
Ctrl+Shift+F6
Most Recently Viewed File
Ctrl+F6
New File (default type)
Ctrl+Shift+N
New File...
Ctrl+N
Next File
Ctrl+Page_Down
Open File...
Ctrl+O
Open Project...
Ctrl+Shift+J
Previous File
Ctrl+Page_Up
Refresh Status
Ctrl+K, R
Save
Ctrl+S
Save All
Ctrl+Shift+S
Help
Alternate Help on Selection
Ctrl+F1
Help...
F1
Language-Specific Help on Selection
Shift+F1
Macro
End Recording
Ctrl+K, )
Execute Last Macro
Ctrl+K, _
Start/Resume Recording
Ctrl+K, (
Find
466
Komodo User Guide
Source Code
Comment Region
Ctrl+3
Complete Word
Ctrl+Space
Complete Word (backwards)
Ctrl+Shift+Space
Convert Selection to Lower Case
Ctrl+Shift+U
Convert Selection to Upper Case
Ctrl+U
Find All Functions
Ctrl+F8
Find Next Function
F8
Find Previous Function
Shift+F8
Jump to Matching Brace
Ctrl+]
Select Block
Ctrl+B
Select to Matching Brace
Ctrl+Shift+]
Un-comment Region
Ctrl+Shift+3
Source Control
Add File
Ctrl+K, A
Add Folder
Ctrl+K, Shift+A
Commit Changes
Ctrl+K, C
Commit Changes in Folder
Ctrl+K, Shift+C
Compare
Ctrl+K, D
Compare Files in Folder
Ctrl+K, Shift+D
Edit
Ctrl+K, E
Remove File
Ctrl+K, O
Revert Changes
Ctrl+K, V
Revert Changes in Folder
Ctrl+K, Shift+V
Update
Ctrl+K, U
Update Folder
Ctrl+K, Shift+U
Tools
Run Command...
Ctrl+R
User Interface
Browser Preview
Ctrl+K, Ctrl+V
Focus on Editor
Ctrl+Shift+E
Show/Hide Code Browser Tab
Ctrl+Shift+C
Show/Hide End of Lines
Ctrl+Shift+7
Source Code
467
Komodo User Guide
Show/Hide Output Pane
Ctrl+Shift+O
Show/Hide Projects Tab
Ctrl+Shift+P
Show/Hide Toolbar Button Text
Ctrl+Shift+B
Show/Hide Toolbox Tab
Ctrl+Shift+T
Show/Hide Whitespace
Ctrl+Shift+8
View Source
Ctrl+K, Ctrl+S
View/Hide Indentation Guides
Ctrl+Shift+5
View/Hide Line Numbers
Ctrl+Shift+4
Word-wrap long lines
Ctrl+Shift+9
Snippets
<b> Bold
Ctrl+K, Ctrl+H, B
<i> Italic
Ctrl+K, Ctrl+H, I
<u> Underline
Ctrl+K, Ctrl+H, U
<br/> Break Line
Ctrl+K, Ctrl+H, Return
<h1> Header 1
Ctrl+K, Ctrl+H, 1
<h2> Header 2
Ctrl+K, Ctrl+H, 2
<h3> Header 3
Ctrl+K, Ctrl+H, 3
<h4> Header 4
Ctrl+K, Ctrl+H, 4
<h5> Header 5
Ctrl+K, Ctrl+H, 5
<h6> Header 6
Ctrl+K, Ctrl+H, 6
<li> List Item
Ctrl+K, Ctrl+H, L
<ol> Ordered List
Ctrl+K, Ctrl+H, Ctrl+O
<ul> Unordered List
Ctrl+K, Ctrl+H, Ctrl+U
<p> Paragraph w/Dialog
Ctrl+K, Ctrl+H, Ctrl+P
<p> Paragraph
Ctrl+K, Ctrl+H, P
<table> Table 1 row 1 col
Ctrl+K, Ctrl+H, Ctrl+T
<tr> Table Row
Ctrl+K, Ctrl+H, R
<td> Table Cell
Ctrl+K, Ctrl+H, D
<pre> Preformated Text
Ctrl+K, Ctrl+H, T
<A> URI Link w/Dialog
Ctrl+K, Ctrl+H, Ctrl+A
<A> URI Link
Ctrl+K, Ctrl+H, A
<form> Form w/Dialog
Ctrl+K, Ctrl+H, Ctrl+F
<input/> Form Input w/Dialog
Ctrl+K, Ctrl+H, Ctrl+I
<select> Form Select w/Dialog
Ctrl+K, Ctrl+H, Ctrl+S
<option> Form Option w/Dialog
User Interface
468
Komodo User Guide
Ctrl+K, Ctrl+H, O
<textarea> Form Text Area w/Dialog
Snippets
Ctrl+K, Ctrl+H, Ctrl+Q
469
OS X Key Bindings (Default)
This page lists the default key bindings on Mac OS X. There are also pages that list the default key
bindings on Windows/Linux. On any platform, you can also choose to use Emacs key bindings. As
any of these key bindings schemes can be customized, these pages stand as references to the
defaults. To view the current list of key bindings for your Komodo installation (including any custom
key bindings), select Help|List Key Bindings. The different key binding schemes are either set
according to the platform on which you installed Komodo, or they are selected in
Edit|Preferences|Editor|Keybindings.
Note: The "Meta" key referred to in the following list may be better known to Mac OS X users as
the "Command" key.
OS X Scheme
Code Browser
Locate current scope...
Ctrl+K, Ctrl+L
Code Intelligence
Find Symbol
Ctrl+K, Ctrl+F
Debugger
Clear All Breakpoints
Meta+Ctrl+\
Disable/Enable Breakpoint
Meta+\
New Session
Meta+Ctrl+Y
Run Script
Meta+Ctrl+R
Run to Cursor
Meta+Ctrl+I
Show Current Statement
Meta+Shift+C
Start
Meta+Shift+.
Meta+>
Start/Find/Hide Default Interactive Shell
Meta+Escape
Step In
Meta+Shift+I
Step Out
Meta+Shift+T
Step Over
Meta+Shift+O
Stop
Meta+Ctrl+P
Editor
Back
Shift+Backspace
Backspace
Backspace
OS X Key Bindings (Default)
470
Komodo User Guide
Beginning of Line (first char/first column)
Meta+Left
Home
Cancel autocomplete
Escape
Copy
Meta+C
Cut
Meta+X
Cut rest of line
Ctrl+Backspace
Ctrl+Delete
Delete
Delete
Delete Word Left
Meta+Backspace
Delete Word Right
Meta+Delete
End of Line
Meta+Right
End
Go to End of Document
Meta+Down
Meta+End
Go to End of word
Meta+E
Go to Line...
Meta+L
Go to Next Bookmark
F2
Go to Next Line
Down
Go to Previous Bookmark
Shift+F2
Go to Previous Line
Up
Go to Top of Document
Meta+Up
Meta+Home
Insert Newline
Return
Insert Newline (align with current line)
Meta+Shift+Return
Insert Newline (continue comments)
Shift+Return
Insert Newline (no favors)
Meta+Return
Insert Next Key as Literal Character
Meta+M
Join current and next lines
Ctrl+K, Ctrl+J
Move Back Part of Word
Meta+Alt+Right
Move Forward Part of Word
Meta+Alt+Left
Move Left One Character
Left
Move One Character Right
Right
Move One Word Left
Alt+Left
Move One Word Right
Alt+Right
Page Down
Page_Down
Page Up
Page_Up
Editor
471
Komodo User Guide
Paste
Meta+V
Paste and Select
Meta+Shift+V
Redo
Meta+Shift+Z
Reflow paragraph(s)
Meta+Shift+Q
Remove All Bookmarks
Meta+Shift+F2
Repeat next keystroke N times
Ctrl+K, Ctrl+U
Scroll One Line Down
Meta+Alt+Down
Scroll One Line Up
Meta+Alt+Up
Select All
Meta+A
Select Next Character
Shift+Right
Select Next Word
Alt+Shift+Right
Select Page Down
Shift+Page_Down
Select Page Up
Shift+Page_Up
Select Previous Character
Shift+Left
Select Previous Word
Alt+Shift+Left
Select Rectangular Next Character
Ctrl+Shift+Right
Select Rectangular Page Down
Ctrl+Shift+Page_Down
Select Rectangular Page Up
Ctrl+Shift+Page_Up
Select Rectangular Previous Character
Ctrl+Shift+Left
Select Rectangular to Beginning of Line (first
char/first column)
Ctrl+Shift+Home
Select Rectangular to End of Line
Ctrl+Shift+End
Select Rectangular to Next Line
Ctrl+Shift+Down
Select Rectangular to Previous Line
Ctrl+Shift+Up
Select to Beginning of Line (first char/first
column)
Shift+Home
Meta+Shift+Left
Select to End of Document
Meta+Shift+Down
Select to End of Line
Shift+End
Meta+Shift+Right
Select to Next Line
Shift+Down
Select to Previous Line
Shift+Up
Select to Top of Document
Meta+Shift+Up
Toggle Bookmark
Meta+F2
Toggle Overtype/Insert Mode
Insert
Transpose Current and Previous Characters
Meta+T
Trigger preceding autocomplete list or calltip
Meta+J
Editor
472
Komodo User Guide
Undo
Meta+Z
Zoom Font Size Down
Meta+Shift+-
Zoom Font Size Up
Meta+Shift+=
Find
Find Next
Meta+G
Find Next Result
Meta+Shift+F3
Find Next Selected
Meta+F3
Find Previous
Meta+Shift+G
Find in Files...
Meta+Shift+F
Find...
Meta+F
Incremental Search
Meta+I
Incremental Search Backwards
Meta+Shift+I
Replace...
Meta+=
General
Close All Windows
Meta+Ctrl+W
Close Project
Ctrl+W
Close Window
Meta+W
Edit Properties
Alt+Return
Least Recently Viewed File
Meta+Shift+F6
Most Recently Viewed File
Meta+F6
New File (default type)
Meta+N
New File...
Meta+Ctrl+N
New Project...
Meta+Shift+N
Next File
Meta+Page_Down
Open File...
Meta+O
Open Project...
Meta+Ctrl+O
Preferences...
Meta+,
Previous File
Meta+Page_Up
Quit
Meta+Q
Refresh Status
Ctrl+K, R
Revert
Meta+Ctrl+U
Save
Meta+S
Save All
Meta+Ctrl+S
Save As...
Meta+Shift+S
Find
473
Komodo User Guide
Help
Alternate Help on Selection
Ctrl+/
Help...
Meta+Shift+/
Meta+?
Language-Specific Help on Selection
Meta+/
Macro
End Recording
Ctrl+K, )
Execute Last Macro
Ctrl+K, _
Start/Resume Recording
Ctrl+K, (
Source Code
Comment Region
Ctrl+3
Complete Word
F5
Alt+Escape
Complete Word (backwards)
Shift+F5
Alt+Shift+Escape
Convert Selection to Lower Case
Meta+Shift+U
Convert Selection to Upper Case
Meta+U
Find All Functions
Meta+F8
Find Next Function
F8
Find Previous Function
Shift+F8
Jump to Matching Brace
Meta+]
Select Block
Meta+Ctrl+L
Select to Matching Brace
Meta+Shift+]
Un-comment Region
Ctrl+Shift+3
Source Control
Add File
Ctrl+K, A
Add Folder
Ctrl+K, Shift+A
Commit Changes
Ctrl+K, C
Commit Changes in Folder
Ctrl+K, Shift+C
Compare
Ctrl+K, D
Compare Files in Folder
Ctrl+K, Shift+D
Edit
Ctrl+K, E
Remove File
Ctrl+K, O
Help
474
Komodo User Guide
Revert Changes
Ctrl+K, V
Revert Changes in Folder
Ctrl+K, Shift+V
Update
Ctrl+K, U
Update Folder
Ctrl+K, Shift+U
Tools
Run Command...
Meta+R
User Interface
Browser Preview
Ctrl+K, Ctrl+V
Focus on Editor
Ctrl+Shift+E
Show/Hide Code Browser Tab
Ctrl+Shift+C
Show/Hide End of Lines
Meta+Shift+7
Show/Hide Output Pane
Ctrl+Shift+O
Show/Hide Projects Tab
Ctrl+Shift+P
Show/Hide Toolbar Button Text
Meta+Shift+B
Show/Hide Toolbox Tab
Ctrl+Shift+T
Show/Hide Whitespace
Meta+Shift+8
Split view of tab
Meta+Shift+'
Meta+"
View Source
Ctrl+K, Ctrl+S
View/Hide Indentation Guides
Meta+Shift+5
View/Hide Line Numbers
Meta+Shift+4
Word-wrap long lines
Meta+Shift+9
Snippets
<b> Bold
Ctrl+K, Ctrl+H, B
<i> Italic
Ctrl+K, Ctrl+H, I
<u> Underline
Ctrl+K, Ctrl+H, U
<br/> Break Line
Ctrl+K, Ctrl+H, Return
<h1> Header 1
Ctrl+K, Ctrl+H, 1
<h3> Header 2
Ctrl+K, Ctrl+H, 2
<h3> Header 3
Ctrl+K, Ctrl+H, 3
<h4> Header 4
Ctrl+K, Ctrl+H, 4
<h5> Header 5
Ctrl+K, Ctrl+H, 5
<h6> Header 6
Ctrl+K, Ctrl+H, 6
<li> List Item
Source Control
475
Komodo User Guide
Ctrl+K, Ctrl+H, L
<ol> Ordered List
Ctrl+K, Ctrl+H, Ctrl+O
<ul> Unordered List
Ctrl+K, Ctrl+H, Ctrl+U
<p> Paragraph w/Dialog
Ctrl+K, Ctrl+H, Ctrl+P
<p> Paragraph
Ctrl+K, Ctrl+H, P
<table> Table 1 row 1 col
Ctrl+K, Ctrl+H, Ctrl+T
<tr> Table Row
Ctrl+K, Ctrl+H, R
<td> Table Cell
Ctrl+K, Ctrl+H, D
<pre> Preformatted Text
Ctrl+K, Ctrl+H, T
<A> URI Link w/Dialog
Ctrl+K, Ctrl+H, Ctrl+A
<A> URI Link
Ctrl+K, Ctrl+H, A
<form> Form w/Dialog
Ctrl+K, Ctrl+H, Ctrl+F
<input/> Form Input w/Dialog
Ctrl+K, Ctrl+H, Ctrl+I
<select> Form Select w/Dialog
Ctrl+K, Ctrl+H, Ctrl+S
<option> Form Option w/Dialog
Ctrl+K, Ctrl+H, O
<textarea> Form Text Area w/Dialog
Ctrl+K, Ctrl+H, Ctrl+Q
Snippets
476
Emacs Key Bindings (Default)
This page lists the default Emacs key bindings. There are also pages that list the default key
bindings on the Windows/Linux and Mac OS X platforms. As any of these key bindings schemes
can be customized, these pages stand as references to the defaults. To view the current list of key
bindings for your Komodo installation (including any custom key bindings), select Help|List Key
Bindings. The different key binding schemes are either set according to the platform on which you
installed Komodo, or they are selected in Edit|Preferences|Editor|Keybindings.
Emacs Scheme
Code Browser
Locate current scope...
Ctrl+C, Ctrl+L
Code Intelligence
Find Symbol
Ctrl+C, Ctrl+F
Debugger
Clear All Breakpoints
Ctrl+F9
Disable/Enable Breakpoint
F9
Listen for Debugger Connections
Ctrl+Shift+F7
Run Script
F7
Ctrl+F7
Run to Cursor
Shift+F10
Ctrl+Shift+F10
Show Current Statement
Alt+*
Start
F5
Ctrl+F5
Step In
F11
Ctrl+F11
Step Out
Shift+F11
Ctrl+Shift+F11
Step Over
F10
Ctrl+F10
Stop
Shift+F5
Editor
Back
Shift+Backspace
Backspace
Backspace
Emacs Key Bindings (Default)
477
Komodo User Guide
Beginning of Line (first char/first column)
Home
Cancel AutoComplete
Ctrl+G
Copy
Alt+W
Ctrl+Insert
Cut
Shift+Delete
Ctrl+Shift+X
Cut Region
Ctrl+W
Cut rest of line
Ctrl+K
Decrease Line Indent
Ctrl+C, <
Delete
Alt+D
Ctrl+Delete
Ctrl+D
Delete
Delete Word Left
Alt+Delete
Alt+Backspace
Ctrl+Backspace
End of Line
End
Exchange Current Point and Mark
Ctrl+X, Ctrl+X
Go to End of Document
Ctrl+End
Go to End of word
Ctrl+E
Go to Line...
Alt+L
Alt+G
Go to Next Bookmark
F2
Go to Next Line
Ctrl+N
Down
Go to Previous Bookmark
Shift+F2
Go to Previous Line
Ctrl+P
Up
Go to Top of Document
Ctrl+Home
Increase Line Indent
Ctrl+C, >
Insert Newline
Return
Insert Newline (align with current line)
Ctrl+Shift+Return
Insert Newline (continue comments)
Shift+Return
Insert Newline (no favors)
Ctrl+Return
Join current and next lines
Ctrl+J
Move Back Part of Word
Alt+Right
Move Forward Part of Word
Alt+Left
Editor
478
Komodo User Guide
Move Left One Character
Ctrl+B
Left
Move One Character Right
Ctrl+F
Right
Move One Word Left
Ctrl+Left
Move One Word Right
Ctrl+Right
Move to previous mark in mark ring
Ctrl+U, Ctrl+Space
Page Down
Ctrl+V
Page_Down
Page Up
Alt+V
Page_Up
Paste
Ctrl+Y
Shift+Insert
Paste and Select
Ctrl+Shift+V
Reflow paragraph(s)
Escape, Q
Remove All Bookmarks
Ctrl+Shift+F2
Repeat next keystroke N times
Ctrl+U
Scroll One Line Down
Alt+Z
Escape, Z
Ctrl+Down
Scroll One Line Up
Ctrl+Z
Ctrl+Up
Scroll current line to center of screen
Ctrl+L
Scroll current line to top of screen
Ctrl+X, !
Select All
Ctrl+A
Select Next Character
Shift+Right
Select Next Part of Word
Alt+Shift+Right
Select Next Word
Ctrl+Shift+Right
Select Page Down
Shift+Page_Down
Select Page Up
Shift+Page_Up
Select Previous Character
Shift+Left
Select Previous Part of Word
Alt+Shift+Left
Select Previous Word
Ctrl+Shift+Left
Select to Beginning of Line (first char/first
column)
Shift+Home
Select to Beginning of word
Ctrl+Shift+W
Select to End of Document
Ctrl+Shift+End
Editor
479
Komodo User Guide
Select to End of Line
Shift+End
Select to Next Line
Shift+Down
Select to Previous Line
Shift+Up
Select to Top of Document
Ctrl+Shift+Home
Set Mark
Ctrl+Space
Toggle Bookmark
Ctrl+F2
Toggle Overtype/Insert Mode
Insert
Transpose Current and Previous Characters
Ctrl+T
Transpose Current and Previous Lines
Ctrl+L
Undo
Ctrl+/
Ctrl+X, U
Zoom Font Size Down
Ctrl+Shift+-
Zoom Font Size Up
Ctrl+Shift+=
Ctrl+Shift++
Find
Find Next
F3
Find Next Result
Ctrl+Shift+F3
Find Next Selected
Ctrl+F3
Find Previous
Shift+F3
Find in Files...
Ctrl+Shift+F
Incremental Search
Ctrl+S
Incremental Search Backwards
Ctrl+R
Replace...
Ctrl+H
General
Close Window
Ctrl+X, K
Ctrl+F4
Edit Properties
Alt+Return
Least Recently Viewed File
Ctrl+Shift+F6
Most Recently Viewed File
Ctrl+F6
New File (default type)
Ctrl+Shift+N
Next File
Ctrl+Page_Down
Open File...
Ctrl+X, Ctrl+F
Open Project...
Ctrl+Shift+J
Previous File
Ctrl+Page_Up
Find
480
Komodo User Guide
Quit
Ctrl+X, Ctrl+C
Refresh Status
Ctrl+C, R
Save
Ctrl+X, Ctrl+S
Save All
Ctrl+Shift+S
Help
Alternate Help on Selection
Ctrl+F1
Help...
F1
Language-Specific Help on Selection
Shift+F1
Macro
End Recording
Ctrl+X, )
Ctrl+X, )
Execute Last Macro
Ctrl+X, M
Ctrl+X, m
Start/Resume Recording
Ctrl+X, (
Ctrl+X, (
Source Code
Comment Region
Ctrl+C, #
Ctrl+C, c
Ctrl+3
Complete Word (backwards)
Ctrl+Shift+Space
Find All Functions
Ctrl+F8
Find Next Function
F8
Find Previous Function
Shift+F8
Jump to Matching Brace
Ctrl+]
Select to Matching Brace
Ctrl+M
Un-comment Region
Ctrl+C, u
Ctrl+Shift+3
Source Control
Add File
Ctrl+C, A
Add Folder
Ctrl+C, Shift+A
Commit Changes
Ctrl+C, C
Commit Changes in Folder
Ctrl+C, Shift+C
Compare
Ctrl+C, D
Compare Files in Folder
Ctrl+C, Shift+D
General
481
Komodo User Guide
Edit
Ctrl+C, E
Remove File
Ctrl+C, O
Revert Changes
Ctrl+C, V
Revert Changes in Folder
Ctrl+C, Shift+V
Update
Ctrl+C, U
Update Folder
Ctrl+C, Shift+U
Tools
Run Command...
Ctrl+R
User Interface
Browser Preview
Ctrl+C, Ctrl+V
Focus on Editor
Ctrl+Shift+E
Show/Hide Code Browser Tab
Ctrl+Shift+C
Show/Hide End of Lines
Ctrl+Shift+7
Show/Hide Output Pane
Ctrl+Shift+O
Show/Hide Projects Tab
Ctrl+Shift+P
Show/Hide Toolbar Button Text
Ctrl+Shift+B
Show/Hide Toolbox Tab
Ctrl+Shift+T
Show/Hide Whitespace
Ctrl+Shift+8
Split view of tab
Ctrl+X, 5, 2
View Source
Ctrl+C, Ctrl+S
View/Hide Indentation Guides
Ctrl+Shift+5
View/Hide Line Numbers
Ctrl+Shift+4
Word-wrap long lines
Ctrl+Shift+9
Snippets
<b> Bold
Ctrl+K, Ctrl+H, B
<i> Italic
Ctrl+K, Ctrl+H, I
<u> Underline
Ctrl+K, Ctrl+H, U
<br/> Break Line
Ctrl+K, Ctrl+H, Return
<h1> Header 1
Ctrl+K, Ctrl+H, 1
<h2> Header 2
Ctrl+K, Ctrl+H, 2
<h3> Header 3
Ctrl+K, Ctrl+H, 3
<h4> Header 4
Ctrl+K, Ctrl+H, 4
<h5> Header 5
Ctrl+K, Ctrl+H, 5
Source Control
482
Komodo User Guide
<h6> Header 6
Ctrl+K, Ctrl+H, 6
<li> List Item
Ctrl+K, Ctrl+H, L
<ol> Ordered List
Ctrl+K, Ctrl+H, Ctrl+O
<ul> Unordered List
Ctrl+K, Ctrl+H, Ctrl+U
<p> Paragraph w/Dialog
Ctrl+K, Ctrl+H, Ctrl+P
<p> Paragraph
Ctrl+K, Ctrl+H, P
<table> Table 1 row 1 col
Ctrl+K, Ctrl+H, Ctrl+T
<tr> Table Row
Ctrl+K, Ctrl+H, R
<td> Table Cell
Ctrl+K, Ctrl+H, D
<pre> Preformated Text
Ctrl+K, Ctrl+H, T
<A> URI Link w/Dialog
Ctrl+K, Ctrl+H, Ctrl+A
<A> URI Link
Ctrl+K, Ctrl+H, A
<form> Form w/Dialog
Ctrl+K, Ctrl+H, Ctrl+F
<input/> Form Input w/Dialog
Ctrl+K, Ctrl+H, Ctrl+I
<select> Form Select w/Dialog
Ctrl+K, Ctrl+H, Ctrl+S
<option> Form Option w/Dialog
Ctrl+K, Ctrl+H, O
<textarea> Form Text Area w/Dialog
Ctrl+K, Ctrl+H, Ctrl+Q
Snippets
483
Vi Key Bindings
Vi emulation mimics the modal behavior of the Vi editor. The Vi scheme (and custom schemes created with
in order to assign keystrokes to appropriate actions in the various modes.
Keybinding schemes and Vi emulation are configured in Edit|Preferences|Editor|Keybindings.
Vi Emulation
Komodo emulates the following Vi modes:
• Normal: navigation and editing.
When you open a file in Komodo with the Vi scheme enabled, you start off in command mode. Keyst
movement, deletion, cutting, pasting and other standard editing commands that are generally mappe
other schemes.
• Input: entering text.
Hitting an "input" command key in Normal mode (i.e. 'i' to insert, 'a' to append, or 'o' to open a new li
Input mode. Keystrokes in this mode enter text. Use the 'Esc' key to exit into Normal mode.
• Visual: visual selection of text with navigation keystrokes.
Similar to Vim's visual modes. Entering 'v' enables selection by character, 'V' enables linewise select
selection. Navigation keystrokes within these modes expand and contract the selection area. Use the
• Command-line: running vi/ex commands.
In Normal mode, entering ':' opens a text box in the status bar at the bottom of the Komodo window f
following Vi and Vim commands have been implemented in the default Vi scheme:
♦ edit
♦ exit
♦ help
♦ next
♦ previous
♦ quit
♦ set
♦ splitview
♦ undo
♦ write
♦ wq
♦ xit
♦ number <line number>
♦ <range>s/<search string>/<substitution>/[g|i|I]
Custom Vi Commands
To add your own Vi commands, create a Toolbox folder named Vi Commands, then add Macros or Run Co
command is executed when you type its name in the Vi command-line text box.
Vi Key Bindings
484
Komodo User Guide
Command-line arguments can be passed to Macros using the koIViCommandDetail XPCOM service. Th
attribute long startLine;
// Start line (current line when unset)
attribute long endLine;
// End line (current line when unset)
attribute boolean forced;
// Command name ended with a "!"
attribute wstring commandName;
// Command name being run
attribute wstring leftover;
// Everything after the command
attribute wstring rawCommandString; // Raw command string as typed in
void getArguments(out unsigned long count,
[array, size_is(count), retval] out wstring args);
void setArguments(in unsigned long count,
[array, size_is(count)] in wstring args);
void clear();
JavaScript sample macro:
var viCommandDetails = Components.classes['@activestate.com/koViCommandDetail;1'].
getService(Components.interfaces.koIViCommandDetail);
var count = new Object();
var args = viCommandDetails.getArguments(count);
var msg = "startLine:" + viCommandDetails.startLine + "\n" +
"endLine:" + viCommandDetails.endLine + "\n" +
"commandName:" + viCommandDetails.commandName + "\n" +
"arguments:" + args + "\n" +
"rawCommandString:" + viCommandDetails.rawCommandString;
alert(msg);
Python sample macro:
from xpcom import components
viCommandDetails = components.classes['@activestate.com/koViCommandDetail;1'].getService(componen
msg = [ "startLine: %d" % viCommandDetails.startLine ]
msg.append("endLine: %d" % viCommandDetails.endLine)
msg.append("commandName: %s" % viCommandDetails.commandName)
msg.append("arguments: %r" % viCommandDetails.getArguments())
msg.append("rawCommandString: %s" % viCommandDetails.rawCommandString)
print "\n".join(msg)
Vi Scheme
The default Vi scheme is based on the Default scheme (which varies slightly between platforms) and include
not conflict with those used in Vi emulation. To view the list of key bindings for your current scheme, select H
following are key bindings which are unique to the Vi scheme.
Vi key bindings
Cancel
Ctrl+[
Esc
Cut One Character
x
Cut One Character to Left
X
Cut to End of Line and Enter Insert Mode
C
Delete the Current Character and Enter Insert Mode
s
Custom Vi Commands
485
Komodo User Guide
Deletes from cursor to end of line.
D
Enter Insert Mode
i
Enter Insert Mode after the Cursor Position
a
Enter Insert Mode at Start of the Line
I
Enter Insert mode at the End of the Current Line
A
Enter command mode
:
Enter visual block mode
Ctrl+V
Enter visual character mode
v
Enter visual line mode
V
Go to Next Line
j
Go to Previous Line
k
Goto Line
G
Join current and next lines
J
Move Left One Character
h
Move One Word Left
b
Move Right One Character
Space
l
Move To End of Word To Right
e
Move To Start of Word To Right
w
Move one page down
Ctrl+F
Move one page up
Ctrl+B
Move one word left, past any punctuation
B
Move one word right, past any punctuation
W
Move to Beginning of Line (first visible char/first column)
^
Move to Beginning of the Current Line
|
0
Move to Beginning of the Previous Line
-
Move to End of Current Line
$
Move to end of word to the right, past any punctuation
E
Move to the Beginning of the Paragraph
{
Move to the Beginning of the Section
[, [
Move to the Beginning of the Sentence
(
Move to the Bottom of the Screen
L
Move to the Center of the Screen
M
Move to the End of the Paragraph
}
Vi key bindings
486
Komodo User Guide
Move to the End of the Section
], ]
Move to the End of the Sentence
)
Move to the Top of the Screen
H
New Line Starting After the Current Line
o
New Line Starting Before the Current Line
O
Paste
P
Paste After
p
Redo
Ctrl+R
Repeat the last command again
.
Replace characters with the ones that are typed
R
Replace the current char with the next typed character
r
Scroll One Line Down
Ctrl+E
Scroll One Line Up
Ctrl+P
Search for the Next Occurance of the Word at the Current Cursor
Position
Search for the Previous Occurance of the Word at the Current Cursor
Position
*
#
Start Change Text Operation
c
Start Delete Text Operation
d
Start Yank Text Operation
y
Swap the current character's case.
~
Undo
u
Enter Search Backwards
?
Enter Search Forward
/
Find Next Pattern
n
Find Previous Pattern
N
Find the Character Typed, After Cursor in Current Line
f
Find the Character Typed, Before Cursor in Current Line
F
Decrease Line Indent
Increase Line Indent
>, >
Jump to Matching Brace
%
Vi key bindings
487
XML Catalogs
Komodo can add XML autocompletion support for any XML dialect with a DTD or RelaxNG
Schema. This is done by mapping external identifier entries to local copies of the DTD or RelaxNG
Schema for that document type using XML Catalogs.
Using an Existing XML Catalog
Some toolkits bundle DTDs or RelaxNG Schemas with their own XML catalogs. As long as the
relative path from the catalog to the .dtd or .rng file is preserved on the local filesystem, you can
add support for the dialect by specifying the catalog file in Preferences under SGML/XML Catalogs.
Creating an XML Catalog
If the DTD or RelaxNG Schema for the dialect does not have a catalog file, you can create one by
mapping the external identifiers and URI references in the document's namespace declaration to a
local filesystem URI. For example, the XSPF playlist format uses the following namespace
declaration:
<playlist version="1" xmlns="http://xspf.org/ns/0/">
A simple catalog for this XML dialect would look like this:
<?xml version='1.0'?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
prefer="public">
<uri name="http://xspf.org/ns/0/" uri="xspf-draft8.rng"/>
</catalog>
If your documents use the DOCTYPE declaration, you can add support for that in the catalog by
using the public and system identifier. For example, XUL uses DOCTYPE declarations like this
one:
<!DOCTYPE overlay PUBLIC "-//MOZILLA//DTD XUL V1.0//EN"
"http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
Komodo's catalog for XUL uses publicId and systemId in addition to uri for the mapping.
<?xml version='1.0'?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
<public publicId="-//MOZILLA//DTD XUL V1.0//EN"
uri="xul.dtd"/>
<system systemId="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
uri="xul.dtd"/>
<uri name="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
uri="xul.dtd"/>
</catalog>
XML Catalogs
488
Komodo User Guide
XML Catalog Resources
The XML Catalog specification can be found at:
• http://www.oasis-open.org/committees/entity/spec.html
Examples of XML catalog files can be found in the Komodo installation under:
• <komodo-install-directory>\lib\support\catalogs (Windows)
• /Applications/Komodo.app/Contents/SharedSupport/catalogs/ (OS X)
• <komodo-install-directory>/lib/support/catalogs (Linux)
XML Catalog Resources
489
User-Defined Language Support
Luddite Reference
Komodo's system for defining multi-language syntax lexing and
user-defined syntax highlighting is called UDL (User Defined Languages).
UDL files are written in a language called Luddite, then compiled into
Scintilla lexers and packaged for use in Komodo.
• Keywords
• Style Names
• Terms
• Concepts
Introduction
Komodo includes a general-purpose lexer engine that loads a description resource, and walks it
while lexing the buffer. It currently allows for up to five sub-languages, each of which is expected to
be a member of a pre-defined family ("markup", "style", "client-side scripting language", "server-side
scripting language", and "template language"). The format of these resource files is low-level and
intended to be fast to parse, so we have provided a programming language that is intended to allow
users to build lexers for their own programming languages.
Currently these lexers allow for six-bit colorizing, meaning that both errors and warnings can be
highlighted in the buffer. The lexer description language allows for:
• specifying a set of keywords and folding conditions for each family
• disambiguation rules for each family (e.g. in JavaScript, when does '/' indicate division, and
when does it start a regex?)
• constant strings and patterns to look for, and what to do with them
Luddite Language Overview
Luddite programs typically consist of a set of files, called modules. A well-designed Luddite program
will contain one main file, that provides a name for the target language, and then a list of include
statements that load the other modules.
Luddite consists of a set of declarations, most of which can appear in any order, except for the initial
"family" declaration. This is because some declarations are family-specific, and bind to the
prevailing family declaration.
A Sample
The php-mainlex.udl file defines the PHP lexer. It is a useful example as it uses one of each of the
language families: markup (HTML), css (CSS), client-side (JavaScript), and server-side (PHP). It
includes transitions from HTML to JavaScript, CSS, and PHP, followed by transitions back to HTML
from each of these languages, and finally the main language modules.
language PHP
include "html2js.udl"
include "html2css.udl"
include "html2php.udl"
User-Defined Language Support
490
Komodo User Guide
include "css2html.udl"
include "js2html.udl"
include "php2html.udl"
include
include
include
include
"html.udl"
"csslex.udl"
"jslex.udl"
"phplex.udl"
Working from the bottom of the list towards the top, we have four core files that contain code to
describe how to lex each language on it's own. Above those are files that explain how to transition
from one language to another (e.g. "php2html.udl"). As rules are attempted in the order they're first
presented, we normally need to test transition rules before we attempt internal rules, which is why
the core modules appear at the bottom.
Luddite in a Nutshell
Luddite programs consist of declarative statements separated either by newlines or semi-colons.
Comments start with "#" and continue to the end of line. Because it's a declarative language, the
order of different statements doesn't matter, but the order of rules in the same group does.
The Luddite compiler allows lists to be entered with minimal punctuation (i.e without quotes around
strings, or commas between entries). However, the following words should always be quoted when
declared as strings as they are reserved words in Luddite:
• skip
• keyword_style
• accept
• state
• language
• all
• sublanguage
• namespace
• at_eol
• sub_language
• no_keyword
• clear_delimiter
• system_id
• paint
• delimiter
• token_check
• pattern
• family
• start_style
• public_id
• fold
• end_style
• include
• redo
• upto
• reject
• initial
• set_delimiter
• spush_check
• keep_delimiter
• set_opposite_delimiter • spop_check
• keywords
Luddite is intended to work only with Scintilla. It is helpful to refer to the Scintilla documentation
when writing lexers in Luddite. To reduce redundancy, you can refer to the names of colors by using
either the full name, such as "SCE_UDL_M_ATTRNAME", or you can drop the common prefix, and
refer to "M_ATTRNAME". A partial prefix won't work, nor will hard-wired numeric values.
Families
Most lexer components need to declare which language family they belong to: markup, css, csl
(client-side language), ssl (server-side language - usually JavaScript ), or tpl (template language).
This last language is usually used by the server-side processor that has to determine which code is
markup to be output "as is", and which is server-side code to be executed (e.g. PHP's Smarty and
A Sample
491
Komodo User Guide
Perl's Template Toolkit).
The default family is "markup". You can write a lexer for any language that lives in one family, and it
won't look like markup. This is an arbitrary starting point that makes sense for most template
languages.
All directives in a file belong to the most recent family directive. When a new file is included, it starts
off in the family at the point of inclusion. If a new family is specified, when the include-file is
processed, Luddite pops to using the family that was current when the include began.
There are currently three domains that are family-specific: keywords, named patterns, and
look-back tests, which are used to disambiguate.
Example:
family csl
Styles
For each family, we currently need to specify the style from scintilla.iface that the family will use.
Example:
start_style CSL_DEFAULT
end_style CSL_REGEX
This isn't surprising, as the code in scintilla.iface reads like so:
# Template: client-side language
val SCE_UDL_CSL_DEFAULT=30
val SCE_UDL_CSL_COMMENT=31
val SCE_UDL_CSL_COMMENTBLOCK=32
val SCE_UDL_CSL_NUMBER=33
val SCE_UDL_CSL_STRING=34
val SCE_UDL_CSL_WORD=35
val SCE_UDL_CSL_IDENTIFIER=36
val SCE_UDL_CSL_OPERATOR=37
val SCE_UDL_CSL_REGEX=38
# Start at 30
A complete list of Scintilla Styles can be found in the Luddite Reference.
Keywords
Most sub-languages have a set of keywords that we want to color differently from identifiers. You
specify them using keywords, supplying a list of names and strings, which may be
comma-separated, as in this code for JavaScript:
keywords [as break case catch class const # ...
get, "include", set
abstract debugger enum goto implements # ...
]
Families
492
Komodo User Guide
The string "include" is quoted because it is a Luddite keyword. Commas are optional, and
comments can be added at the end of a line inside a list.
You must generally specify a different list of keywords for each family, however it is possible to
define some languages without keywords (e.g. HTML).
Tell Luddite when to color a range of text as a keyword with the keyword_style directive. For
example:
keyword_style CSL_IDENTIFIER => CSL_WORD
A complete list of Luddite Keywords can be found in the Luddite Reference.
To prevent the color for an identifer from being converted into a keyword, use the no_keyword
command.
Pattern Variables
To specify how Luddite should process text, provide a string for it to match verbatim, or provide a
pattern. The pattern syntax is nearly identical to Perl's regex language.
Patterns for a particular language tend to be repetitive. To make it easier to use them, Luddite
supports family-based pattern variables, which are interpolated into pattern expressions. These are
the four pattern variables used in the JavaScript lexer:
pattern
pattern
pattern
pattern
NMSTART = '\w\x80-\xff'
# inside cset
CS = '\w\d_\x80-\xff'
# inside cset
WS = '\s\t\r\n'
# inside cset
OP = '!\#%&\(\)\*\+,-\.\/:;<=>\?@\[\]\^\{\}~|'
These patterns are interpolated into a character set. For example:
/[^$WS]+/
# Match one or more non-white-space characters
The CSS UDL includes a more complex set of statements:
family css
pattern
pattern
pattern
pattern
pattern
pattern
pattern
CS = '-\w\d._\x80-\xff'
# inside cset
WS = '\s\t\r\n'
# inside cset
NONASCII = '[^\x00-\x7f]'
UNICODE = '\\[0-9a-f]{1,6}'
ESCAPE = '$UNICODE|\\[ -~\x80-\xff]'
NMCHAR = '[a-zA-Z0-9-]|$NONASCII|$ESCAPE'
NMSTART = '[a-zA-Z]|$NONASCII|$ESCAPE'
Pattern variables can nest within one another. You need to keep track of which variables define a
character set, and which ones are intended to be used inside a character set.
States and Transitions
The heart of every Luddite program is a set of state-transitions. The key concept is that states in
Keywords
493
Komodo User Guide
Luddite, unlike most Scintilla lexers that are hand-coded in C, are not directly related to the colors
that each character will be given. In Luddite you create your own names for each state, describe for
each state which pieces of text or patterns to look for, and specify what to do with them.
The Initial State
The HTML lexer starts with this code:
initial IN_M_DEFAULT
The first statement means that we should start lexing at the state we call "IN_M_DEFAULT".
Subsequent initial statements are ignored, without warning messages.
Specifying State Transitions
To specify a state transition, provide a state block. For example, with HTML:
state IN_M_DEFAULT:
'<?' : paint(upto, M_DEFAULT), => IN_M_PI_1
'<[CDATA[' : paint(upto, M_DEFAULT), => IN_M_CDATA
'<!--' : paint(upto, M_DEFAULT), => IN_M_COMMENT
# These are more complicated, because if they aren't followed
# by a character we want to leave them as text.
'</' : paint(upto, M_DEFAULT), => IN_M_ETAG_1
'&#' : paint(upto, M_DEFAULT), => IN_M_ENT_CREF_1
'&' : paint(upto, M_DEFAULT), => IN_M_ENT_REF_1
'<' : paint(upto, M_DEFAULT), => IN_M_STAG_EXP_TNAME
When we're in the state we call "IN_M_DEFAULT" (Luddite turns this into an arbitrary number to be
used by Scintilla), if we match any of the above strings, we first will have Scintilla color (or "paint")
everything up to the current starting position the SCE_UDL_M_DEFAULT color (remember, the
prefix is implicit), and then change to the state named to the right of the "=>". The comma before
"=>" is optional, but advisable in more complex rules.
The match strings may use double-quotes instead of single-quoted. Simple C-like
backslash-escaping is used, such as ' and ", but not hex or octal escapes.
Include, Upto, and EOF Conditions
state IN_M_PI_1:
'?>' : paint(include, M_PI) => IN_M_DEFAULT
/\z/ : paint(upto, M_PI)
The "include" directive for the paint command paints from the last paint-point, to the position we
end at. Recall that paint(upto,[color]) stops at the position we were at when we attempted to
match the string.
One of the advantages of this approach over a standard regular expression based set of rules,
specifying the start and end delimiters, is that Luddite is geared to building editor lexers. When
people are using lexers they often are typing at the end of the file. For example, if I was typing this
code:
States and Transitions
494
Komodo User Guide
---- top ---...
<?somepi<EOF>
---- bottom ----
I would like the last line to be colored like a processing instruction, even though I haven't completed
it. Luddite lets you do things to confound your users, such as choosing a different color for an
incomplete directive at the end of file. However, most of the time, you won't want to do this. If all of
the first colors in a state block map to the same color, Luddite will automatically supply that color for
an end-of-file condition at that state. In other words, the '/z/'-condition is rarely necessary.
Redo and Lookahead
There are two main ways to to delay state transitions and colorizing in Luddite:
1. Perl-like (?=...) lookahead test in a regular expression, which will match but won't
advance the cursor into that text.
2. The redo command. In the following example, we modify our rules for recognizing
processing instructions in HTML. If the "<?" is followed immediately by "php", and then by a
non-name character, we want to transition to the server-side family, which presumably
implements a PHP lexer.
In the HTML lexer, we rewrite the state blocks for PIs as follows:
state IN_M_PI_1:
/./ : redo, => IN_M_PI_2
state IN_M_PI_2:
'?>' : paint(include, M_PI) => IN_M_DEFAULT
Wait a minute, you say. That does just the same thing, and less efficiently than when there was just
the one state. In fact, all state IN_M_PI_1 does is a so-called epsilon transition to state IN_M_PI_2
("epsilon" transitions don't consume input).
Go back to that sample at the beginning of this document. Notice that the "html2php.udl" file is
included before "html.udl". This file is short, and is reproduced here without comments:
family markup
state IN_M_PI_1:
/php\b/ : paint(upto, M_OPERATOR), paint(include, M_TAGNAME), \
=> IN_SSL_DEFAULT
Because "html2php.udl" is processed before "html.udl", its pattern will be attempted earlier. If the
lexer finds "php" followed by a word boundary, it will then paint the leading "<?" as a markup
operator, paint the "php" as a markup tagname, and then switch to the default state in the
server-side language family.
If you write a Luddite program that ends up where two states do epsilon transitions to one another,
the lexer engine will detect this. More precisely, if it notices that it has carried out 1000 consecutive
epsilon transitions, it will move on to the next character. This shows up in Komodo as the rest of the
buffer highlighted in a single color (remember the implicit end-of-buffer coloring).
Include, Upto, and EOF Conditions
495
Komodo User Guide
Preventing Keyword Promotion
The no_keyword command is used to prevent identifier to keyword promotion when an identifier is
recognized. This is useful for programming languages that allow any token, even keywords, to be
used in certain contexts, such as after the "." in Python, Ruby, and VBScript, or after "::" or "->" in
Perl. See sample Luddite code.
Pattern Syntax
The Luddite syntax for patterns is very similar to Perl's. Only forward slashes may be used as regex
delimiters, all the usual escaping rules apply. For example, JavaScript uses this pattern to handle
single-line comments:
state IN_CSL_DEFAULT:
# ...
# Swallow to end-of-line
/\/\/.*/ : paint(upto, CSL_DEFAULT), paint(include, CSL_COMMENT)
If no target state is specified, the lexer will stay in the current state.
Pushing States
In many languages you need to push one state, transition to another, and at some point return to
the previous state. There are many examples where this comes up in template-based languages.
In most Smarty files, you transition from HTML to Smarty on "{", and transition back on "}". But if you
find an open-brace while processing Smarty code, you should allow for a matching "}".
In RHTML, the delimiters "<%=" and "%>" are used to transition from HTML into a Ruby expression,
and back. These delimiters can occur in many different parts of HTML files, including attribute
strings and content. The lexer needs to be told which state to return to when it finishes processing
the Ruby expression.
In Ruby proper, you can interpolate arbitrary amounts of Ruby code inside double-quoted strings
between "#{" and "}". By pushing a state when you find "#{" in a Ruby string, you can allow for
multiple nested pairs of braces in the expression, and return to the string when the matching "}" is
reached.
The Luddite code for expressing this is simple. Let's look at how it's expressed for double-quoted
strings in Ruby:
state IN_SSL_DEFAULT:
#...
'"' : paint(upto, SSL_DEFAULT), => IN_SSL_DSTRING
#... Note the redo here for things that could be operators
/[$OP]/ : paint(upto, SSL_DEFAULT), redo, => IN_SSL_OP1
#...
state IN_SSL_DSTRING:
'#{' : paint(include, SSL_STRING), spush_check(IN_SSL_DSTRING), \
=> IN_SSL_DEFAULT
...
Preventing Keyword Promotion
496
Komodo User Guide
state IN_SSL_OP1:
'{' : paint(include, SSL_OPERATOR), spush_check(IN_SSL_DEFAULT) \
=> IN_SSL_DEFAULT
'}' : paint(upto, SSL_DEFAULT), paint(include, SSL_OPERATOR), \
spop_check, => IN_SSL_DEFAULT
# ...
When we find "#{" while processing a double-quoted string, we push the state we want to return to
(IN_SSL_DSTRING), and transition to the default Ruby state (IN_SSL_DEFAULT), where we lex an
expression.
If we find an open-brace while looking for operators, we again push the default state on the stack.
To handle a close-brace, we carry out a "spop_check" test. If there's something on the stack, we
pop it and transition to the state it specified. Otherwise, we transition to the specified state. If users
never made mistakes, you would never need to specify a target state in a directive containing an
"spop" command. But because people are capable of typing things like:
cmd {
yield
}
...we need to tell Luddite what to do on the extra close-brace.
Handling Newlines
Some template languages use line-oriented embedded languages. For example, in Mason you can
insert a line of Perl code by putting a '%' character at the start of the line.
The simplest way to express this in Luddite is to put an at_eol command in the transition into that
state. When the lexer reaches the end of that line, it will automatically transition into the specified
state. For example, the Luddite code to express this for the above Mason example is here:
state IN_M_DEFAULT:
/^%/ : paint(upto, M_DEFAULT), paint(include, TPL_OPERATOR), \
at_eol(IN_M_DEFAULT), => IN_SSL_DEFAULT
Supporting Arbitrary Delimiters
Some languages support arbitrary delimiters for objects like strings and regular expressions. For
example, in Perl you can provide a list of words with the 'qw' construct (e.g. qw/abc def 1234/),
and in Ruby you can use the '%' character to delimit a string (e.g. %Q(abc(nested
parens)def)). You can express these in Luddite using the delimiter keyword.
There are actually four parts to supporting delimiters:
1. Targeting an "opposite" delimiter, so that one of the four characters "[", "{", "(" or "<" is
matched by its closing character "]", "}", ")", or ">" respectively. These pairs are hard-wired
into UDL.
2. Targeting any character as the closing delimiter. Alphabetic characters can be targeted. The
only character that cannot be targeted is the "\".
3. Matching a delimiter.
Pushing States
497
Komodo User Guide
4. Continuing use of a delimiter. For example, to support a construct like Perl's "s,\\,/,g"
idiom, set the target delimiter to ",", match it, and keep it as the target for one more match.
This code shows how the delimiter-oriented keywords are used to work together. We'll walk through
support for Perl's matching statement first:
state IN_SSL_DEFAULT:
# ...
/m([\{\[\(\<])/ : paint(upto, SSL_DEFAULT), \
set_opposite_delimiter(1), => IN_SSL_REGEX1_TARGET
/m([^\w\d])/ : paint(upto, SSL_DEFAULT), \
set_delimiter(1), => IN_SSL_REGEX1_TARGET
# ...
state IN_SSL_REGEX1_TARGET:
delimiter: paint(include, SSL_REGEX), => IN_SSL_REGEX_POST
/\\./ #stay
The first transition matches one of the open-bracket characters in a grouped pattern, and sets the
target delimiter to the opposite of the contents of the first pattern group. The
opposite_delimiter() routine requires its input to be one character long, and returns its input if
it isn't one of the opening characters. So the two patterns could be expressed with the one
transition:
/m([^\w\d])/ : paint(upto, SSL_DEFAULT), set_opposite_delimiter(1), \
=> IN_SSL_REGEX1_TARGET
Handling a construct like Perl's substitution syntax is slightly more complicated because it can use
various delimiters (e.g. s/foo/bar/, s'foo'bar', s#foo#bar#, etc.). Furthermore, if the character after the
's' is an opening bracket character, the full pattern can use either two pairs of bracketing delimiters,
or non-bracketing delimiters, as in
s[find] {replace}
s<first>/second/
White space is always ignored after the first pair. To encode this in Luddite we need several states:
/s([\{\[\(\<])/ : paint(upto, SSL_DEFAULT), \
set_opposite_delimiter(1), => IN_SSL_REGEX2_TARGET1_OPPOSITE_1
# ...
state IN_SSL_REGEX2_TARGET1_OPPOSITE_1:
/\\./ : #stay
delimiter: paint(include, SSL_REGEX), \
=> IN_SSL_REGEX2_TARGET1_OPPOSITE_2
/\z/ : paint(upto, SSL_REGEX)
state IN_SSL_REGEX2_TARGET1_OPPOSITE_2:
/\\./ : #stay
/[$WS]/ : #stay -- assume we're in {...} [ ... ]x
/([\{\[\(\<])/ : paint(upto, SSL_DEFAULT), \
set_opposite_delimiter(1), => IN_SSL_REGEX1_TARGET
/([^\w\d])/ : paint(upto, SSL_DEFAULT), set_delimiter(1), \
=> IN_SSL_REGEX1_TARGET
/\z/ : paint(upto, SSL_DEFAULT)
Matching the second half is similar to matching the delimiter after the 'm'.
Supporting Arbitrary Delimiters
498
Komodo User Guide
The final part is handling constructs like the standard 's/.../.../' language. To do that we tell
UDL to keep the current delimiter for another round of matching:
/s([^\w\d])/ : paint(upto, SSL_DEFAULT), set_delimiter(1), \
=> IN_SSL_REGEX2_TARGET1_SAME
# ...
state IN_SSL_REGEX2_TARGET1_SAME
/\\./ : #stay
delimiter: keep_delimiter, => IN_SSL_REGEX1_TARGET
/\z/ : paint(upto, SSL_REGEX)
Often when a construct is bracketed with matching delimiters, the target language is smart enough
to ignore inner matched pairs. For example, if in Ruby you were to write
puts %Q(first(middle)second)
Ruby would write out the string "first(middle)second". To encode this in Luddite use UDL's built-in
stack:
/%[%qQwWx]([\{\[\(\<])/ : paint(upto, SSL_DEFAULT),
set_opposite_delimiter(1), => IN_SSL_QSTRING_NESTED
# ...
state IN_SSL_QSTRING_NESTED:
delimiter: paint(include, SSL_STRING), => IN_SSL_DEFAULT
/\\./ : #stay
/[\[\{\(\<]/ : paint(upto, SSL_STRING), \
spush_check(IN_SSL_QSTRING_NESTED), => IN_SSL_QSTRING_NESTED2
state IN_SSL_QSTRING_NESTED2:
/\\./ : #stay
/[\[\{\(\<]/ : spush_check(IN_SSL_QSTRING_NESTED2), \
=> IN_SSL_QSTRING_NESTED2
/[\]\}\)\>]/ : spop_check, => IN_SSL_QSTRING_NESTED
/\z/ : paint(include, SSL_STRING)
Finally, you've probably noticed that we put an end-of-buffer transition in many of these states.
Notice that the final IN_SSL_QSTRING_NESTED2 state actually does no painting in its other
matches. Normally Luddite will look at the colors a state uses to determine how to color the rest of
the text if it reaches the end of the buffer. If more than one color is used, or none is used, the
Luddite program should specify a color. Otherwise it's possible that Komodo will repeatedly invoke
the colorizer until something is chosen.
Supporting Here Documents
"Here documents" are a convenient way of defining multi-line strings. Typically they start by defining
the "terminating identifier", preceded by an operator like << or <<<. The string starts on the
following line, and ends when we find a line containing only the terminating identifier.
The following Luddite code outlines how to add here-document processing to a language, using
PHP as an example, where we assume a here document always begins with the three less-than
characters followed by a name, then the end of line:
IN_SSL_PRE_HEREDOC_1
state IN_SSL_PRE_HEREDOC_1:
/([$NMSTART][$NMCHAR]*)/ : set_delimiter(1), paint(include, SSL_IDENTIFIER)
Supporting Arbitrary Delimiters
499
Komodo User Guide
/\r?$/ : paint(include, SSL_DEFAULT), => IN_SSL_IN_HEREDOC_1
state IN_SSL_IN_HEREDOC_1:
delimiter : keep_delimiter, paint(upto, SSL_STRING), => IN_SSL_IN_FOUND_HEREDOC_1
/./ : => IN_SSL_IN_HEREDOC_2 # Not this line
state IN_SSL_IN_HEREDOC_2:
/.+/ : #stay
/$/ : => IN_SSL_IN_HEREDOC_1
state IN_SSL_IN_FOUND_HEREDOC_1:
/[\r\n]+/ : clear_delimiter, paint(upto, SSL_IDENTIFIER), => IN_SSL_DEFAULT
/./ : => IN_SSL_IN_HEREDOC_2 # The delimiter continues, so keep looking
]]>
# Got it!
In this example the keywords delimiter, keep_delimiter, and clear_delimiter all work
together. After matching the delimiter, we retain it with the keep_delimiter action, and then test
to make sure the delimiter is followed immediately by the end of the line. If it is, we clear it.
Otherwise we return to states IN_SSL_IN_HEREDOC_2 and IN_SSL_IN_HEREDOC_1, looking for
a line that contains the terminating identifier, and nothing else. By default matching a delimiter
clears it, so we need to keep it and then explicitly clear it. The following example shows why this is
needed:
Disambiguation
In both Ruby and JavaScript, sometimes a '/' is just a '/', and sometimes it's the start of a regular
expression. Luddite's token_check directive directs this. For example, in JavaScript, to determine if
a '/' is the start of a regex, and not a division operator, you could write a test like this:
state IN_CSL_DEFAULT:
#...
'/' token_check : paint(upto, CSL_DEFAULT), => IN_CSL_REGEX
Note that the "token_check" directive is part of the test, not the action to perform. This states that if
we do match, color everything before the '/' with the default color, and change to the regex state.
What happens during a token_check test depends on the contents of the token_check block
specified for the current family. In a token_check block, you look at the tokens to the left of the
current position. Each token consists of a two-value tuple, containing its colored style, and its text.
On each token, we can decide whether to accept the token (meaning the test passes), reject the
token (meaning it fails), or skip the token, meaning we get the previous token in the buffer, working
towards the beginning.
Here's the JavaScript token_check block:
token_check:
CSL_OPERATOR: reject [")", "++", "--", "]", "}", ";"]
CSL_WORD: reject [class false function null private protected public
super this true get "include" set]
# All other keywords prefer an RE
Disambiguation
500
Komodo User Guide
CSL_DEFAULT: skip all
CSL_COMMENT: skip all
# Default is to reject / as the start of a regex if it follows
# an unhandled style
####
####
####
####
CSL_IDENTIFIER: reject all
CSL_NUMBER: reject all
CSL_REGEX: reject all
CSL_STRING: reject all
You can provide either a list of strings and/or names, or the "all" keyword. Here are the rules on
defaults:
• If a color isn't specified: reject all tokens of that color.
• If a color has only a reject list: accept all others.
• If a color has only an accept list: reject everything else.
• If a color has only a skip list: reject everything else.
• If a style has two of the lists, the missing one is the default.
• If a style has all three lists, anything else is rejected.
Specifying Folding
To get Scintilla to calculate fold levels on each line, specify which tokens increase the folding level,
and which decrease it:
Here is all the folding the JavaScript lexer currently specifies:
fold "{" CSL_OPERATOR +
fold "}" CSL_OPERATOR -
Recognizing XML Vocabularies
By default, Komodo looks at the extension of the file to determine the kind of language in the file,
and then it loads the appropriate language-related code. This mechanism can be further extended
by opening the "File Associations" section of the Preferences area, and specifying that Komodo
should look for XML namespace attributes and doctype declarations to further determine which
language to load.
Authors writing UDL-based lexers for XML vocabularies can tap into this mechanism by using any
combination of the namespace, public_id, and system_id declarations to specify which
language Komodo should associate with a particular file, regardless of the actual extension of the
filename it is saved by.
For example, XBL (XML Binding Language) contains a combination of XML and JavaScript, and is
widely used for Firefox extensions and Mozilla applications. These files often are saved with names
containing ".xml" extensions, but they usually contain the following prologue:
<!DOCTYPE bindings PUBLIC "-//MOZILLA//DTD XBL V1.0//EN" "http://www.mozilla.org/xbl">
<bindings id="koListboxBindingsNew"
xmlns="http://www.mozilla.org/xbl" ...>
Specifying Folding
501
Komodo User Guide
Any combination of the following three declarations in a Luddite file for XBL will be sufficient to
direct Komodo to load the Luddite-based XBL mode instead of the default XML mode:
namespace "http://www.mozilla.org/xbl"
public_id "-//MOZILLA//DTD XBL V1.0//EN"
system_id "http://www.mozilla.org/xbl"
Compiling and Installing
The Luddite compiler and sample .udl files can be found in an archive within the Komodo installation
tree:
• Windows: C:\Program Files\ActiveState Komodo 4.0\lib\support\luddite\luddite.zip
• Mac OS X: /Applications/Komodo.app/Contents/SharedSupport/luddite/luddite.tar.gz
• Linux: /opt/Komodo-4.0/lib/support/luddite.tar.gz
Consult the README.txt file in this package for installation instructions.
UDL files are compiled into .lexres files by the luddite.py script.
To compile the lexer:
python luddite.py help compile
python luddite.py compile UDL_PATH
To build the Komodo extension with the built resources:
python luddite.py help package
python luddite.py package LANG
To install that extension, open the resulting .xpi file in Komodo or use the following command:
python luddite.py install LANG
Note: The luddite.py script requires a zip executable in the path. Info-Zip, a free implementation of
zip for Windows can be found here: http://www.info-zip.org/Zip.html#Win32.
Samples
Sample UDL files can be found in the udl subdirectory of the luddite archive.
Luddite Reference
Luddite is the language Komodo uses for user-defined syntax highlighting and multi-language
lexing. An introduction to the Luddite language can be found in the User-Defined Language Support
documentation.
Recognizing XML Vocabularies
502
Komodo User Guide
Keywords
The following is a list of Luddite keywords - not to be confused with the keywords described by the
UDL file itself for the target language definition. The Luddite keyword is always given followed by its
argument list, where applicable; optional arguments are given in square brackets ([ ... ]).
accept name-or-string-list | all
Used in token_check definitions to disambiguate characters. If all is specified, then a
token_check test will always succeed. If the previous token falls in the name-or-string list,
the token_check test succeeds. Otherwise Luddite will look at the results of any skip and
reject statements in the current family to decide which action to take.
all
Used in accept, reject, and skip statements in token_check definitions. This means that the
token_check test will follow whatever directive is associated with this occurrence of all.
at_eol(state-name)
Used to specify the Luddite state to transition to when the end of the current line is reached.
This is useful for processing languages like the Perl-based template language, Mason, in
which one can embed Perl code on a single line by putting a '%' character at the start of the
line, as in this example:
Good
% if ($time > 12) {
afternoon
% } else {
morning
% }
This is easily handled with this Luddite code:
state IN_M_DEFAULT:
/^%/ : paint(upto, M_DEFAULT), paint(include, TPL_OPERATOR), \
at_eol(IN_M_DEFAULT), => IN_SSL_DEFAULT
If there's a percent character at the start of a line in markup mode, cause it to be lexed as a
template operator, and switch to Perl lexing (IN_SSL_DEFAULT), and switch back to
markup-based lexing when it reaches the end of the line.
clear_delimiter
Used in conjunction with keep_delimiter, this action explicitly clears the current delimiter
(useful in recognizing terminating identifiers in here documents).
delimiter
Used in place of a pattern or match-string in transitions, this will succeed if there's a current
delimiter defined, and it can be matched at the current point in the buffer. When it's matched,
the current delimiter will be unset, unless the keep_delimiter action is given in the
transition.
family csl | markup | ssl | style | tpl
The sub-type of this sub-language. The meaning of each family name is:
csl
client-side language (e.g. usually JavaScript)
Keywords
503
Komodo User Guide
markup
markup language (e.g. HTML, XHTML, other XML dialects)
ssl
server-side language (e.g. Perl, Python, Ruby)
style
stylesheet language (usually CSS)
tpl
a "template-oriented" language, usually geared to either adding template-side
processing to the server-side language, or making it easier to inject the server-side
language into other parts of the full multi-language document, as in CSS or JS.
Examples include Smarty for PHP processing.
fold "name-or-string" style +|Used to describe which tokens start and end a code-folding block. For example:
fold "{" CSL_OPERATOR +
fold "if" SSL_WORD +
fold "end" SSL_WORD -
keep_delimiter
Used when the delimiter directive was used in place of a pattern or string, this tells the
UDL lexer to retain that directive for subsequent matching. This is useful for matching a
construct like Perl's s,/,\\, construct, where we would be using ',' as the regex delimiter,
instead of the normal '/'.
keywords name-or-string-list
List the words that should be colored as keywords (as opposed to identifiers) in the defined
language. Keywords for the target language that are the same as reserved words in Luddite
must be quoted.
keywords ["build/release/docs/komodo-doc-luddite.html", "167", BEGIN, class ensure nil ]
keyword_style style-name => style-name
This directive works with keywords to tell UDL which identifier-type style needs to be
promoted to a keyword style. So all tokens listed in keywords that are colored as the first
style normally will be promoted to the second style.
keyword_style SSL_IDENTIFIER => SSL_WORD
include [path/]file
Include a UDL file. The include path starts with the current directory; if you include a file in a
different directory, that file's directory is appended to the include path.
include "html2ruby.udl"
include
When used as an argument to the paint keyword, include a style.
initial state-name
The state processing for the current family should start at.
initial IN_SSL_DEFAULT
Keywords
504
Komodo User Guide
language name
The name of the language being defined. The language directive must be given. It may be
given more than once, but only with the same value is given each time. This value shows up
in the Komodo UI in places like Language Preferences and the "New File" command.
language RHTML
namespace XML Namespace identifier
The namespace declaration tells Komodo to load the language service described by the
current Luddite program when it sees an XML file that uses the specified namespace as a
default attribute value.
namespace "http://www.w3.org/2001/XMLSchema"
namespace "http://www.w3.org/1999/XMLSchema"
# Be prepared if a new version is released in a few centuries.
namespace "http://www.w3.org/2525/XMLSchema"
no_keyword
The no_keyword command is used to prevent identifier => keyword promotion when an
identifier is recognized. This is useful for programming languages that allow any token, even
keywords, to be used in certain contexts, such as after the "." in Python, Ruby, and
VBScript, or after "::" or "->" in Perl.
state IN_SSL_DEFAULT:
/\.(?=[a-z])/ : paint(upto, SSL_DEFAULT), \
paint(include, SSL_OPERATOR), => IN_SSL_NON_KEYWORD_IDENTIFIER_1
state IN_SSL_NON_KEYWORD_IDENTIFIER_1:
/[^a-zA-Z0-9_]/ : paint(upto, SSL_IDENTIFIER), redo, no_keyword, \
=> IN_SSL_DEFAULT
paint(include|upto, style-name)
These directives are used in state transitions, and are key to the way UDL generates lexers.
They appear in a context like this:
state IN_SSL_COMMENT_1 :
/$/ : paint(include, SSL_COMMENT) => IN_SSL_DEFAULT
This means that when we're in a state with name "IN_SSL_COMMENT_1" (remember that
state names are completely arbitrary in your Luddite programs), and we find the end of the
line, we should paint everything from the last "paint point" to the end of the line with the style
"SCE_UDL_SSL_COMMENT". This will also move the paint-point to the point after the last
character this command styles.
A transition can have a paint(include...) command, a paint(upto...) command, both of them,
or neither.
pattern name = string
These are used as macro substitution inside patterns used in state tables. The names
should contain only letters, and are referenced in patterns and the right-hand side of Luddite
patterns by putting a "$" before them.
pattern NMSTART