Difference between revisions of "Descend"
(→Style Context Reference) |
(→Push Changesets to hgkw) |
||
(7 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
==Getting Started== | ==Getting Started== | ||
− | The Descend source code is available in a [http://www.selenic.com/mercurial/wiki/ Mercurial] repository. Mercurial can be downloaded from [http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages]. Windows users may find [http://tortoisehg.sourceforge.net/ TortoiseHG] useful. | + | The Descend source code is available in a [http://www.selenic.com/mercurial/wiki/ Mercurial] repository. Mercurial can be downloaded from [http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages Selenic]. Windows users may find [http://tortoisehg.sourceforge.net/ TortoiseHG] useful. |
− | Descend currently does not contain a local copy of XULRunner (and may never have one; It would be best to use a globally available XULRunner). You can use the XULRunner bundled with Firefox 3.x to run | + | Descend currently does not contain a local copy of XULRunner (and may never have one; It would be best to use a globally available XULRunner). You can use the XULRunner bundled with Firefox 3.x to run Descend. |
==Setup Your Mercurial Client== | ==Setup Your Mercurial Client== | ||
Line 11: | Line 11: | ||
At the minimum, you should configure your Mercurial client with a "username". For hg, add the following to your ~/.hgrc file (or create a new one) | At the minimum, you should configure your Mercurial client with a "username". For hg, add the following to your ~/.hgrc file (or create a new one) | ||
− | + | [ui] | |
− | + | username = Real Name <[email protected]> | |
==Development== | ==Development== | ||
Line 20: | Line 20: | ||
Create a local repository with the following command: | Create a local repository with the following command: | ||
− | + | <nowiki>$ hg clone http://hg.kodewerx.org/descend</nowiki> | |
This will create a new subdirectory called "descend" containing all of the source code and repository history. | This will create a new subdirectory called "descend" containing all of the source code and repository history. | ||
Line 28: | Line 28: | ||
If you have developer access to push changesets to the hgkw repository, use the following command: (Don't forget to commit to your local repository, first!) | If you have developer access to push changesets to the hgkw repository, use the following command: (Don't forget to commit to your local repository, first!) | ||
− | + | $ hg push ssh://hg@hg.kodewerx.org/repos/descend | |
==Running Descend== | ==Running Descend== | ||
Line 38: | Line 38: | ||
On Windows, go to Start -> Run, and type: | On Windows, go to Start -> Run, and type: | ||
− | + | "C:\Program Files\Mozilla Firefox\firefox.exe" --app "path/to/descend" | |
− | You can also create a batch script to do the same thing. | + | Be sure to verify the path the your Firefox installation is correct. You can also create a batch script to do the same thing. |
==Developer Notes== | ==Developer Notes== | ||
Line 48: | Line 48: | ||
===Style Contexts=== | ===Style Contexts=== | ||
− | The concept of a "Style Context" is greatly inspired by [http://qbnz.com/highlighter/ GeSHi], which uses "[http://qbnz.com/highlighter/geshi-doc.html#language-files Language Files]" to define to the highlighter engine how text should be styled. Descend uses files similar to GeSHi's | + | The concept of a "Style Context" is greatly inspired by [http://qbnz.com/highlighter/ GeSHi], which uses "[http://qbnz.com/highlighter/geshi-doc.html#language-files Language Files]" to define to the highlighter engine how text should be styled. Descend uses files similar to GeSHi's Language Files (called Syntax Contexts) to define syntax. |
Writing new syntax highlighters should be very simple. See ''[http://hg.kodewerx.org/index.cgi/descend/file/tip/chrome/content/styles/6502.js descend/chrome/content/styles/6502.js]'' for the 6502 style context. | Writing new syntax highlighters should be very simple. See ''[http://hg.kodewerx.org/index.cgi/descend/file/tip/chrome/content/styles/6502.js descend/chrome/content/styles/6502.js]'' for the 6502 style context. | ||
Line 60: | Line 60: | ||
====Example Style Context==== | ====Example Style Context==== | ||
− | + | var style = [ | |
− | + | { | |
− | + | rule: /hello,?\s*world!/g, | |
− | + | class: 'hello-world' | |
− | + | }, | |
− | + | { | |
− | + | rule: [ 'hello', 'world' ], | |
− | + | class: 'hello-world' | |
− | + | } | |
− | + | ]; | |
====Style Context Reference==== | ====Style Context Reference==== | ||
Line 95: | Line 95: | ||
|- | |- | ||
! style="width: 100px;" |''icase'' | ! style="width: 100px;" |''icase'' | ||
− | |A Boolean value identifying the rule as case- | + | |A Boolean value identifying the rule as case-insensitive (true) or case-sensitive (false, default). Only has effect with String ''rule''s. |
|- | |- | ||
! style="width: 100px;" |''id'' | ! style="width: 100px;" |''id'' | ||
− | |A Number representing which remembered match to use for the anchor | + | |A Number representing which remembered match to use for the ''anchor'' or ''link'' name. Defaults to 0. Only has effect with ''anchor'' or ''link'', and RegExp ''rule''s. |
|- | |- | ||
! style="width: 100px;" |''link'' | ! style="width: 100px;" |''link'' |
Latest revision as of 07:06, 21 October 2010
Descend is a proof of concept, showing the possibilities of creating an open source debugger UI with Mozilla XULRunner. Descend is distributed under the MPL/GPL/LGPL tri-license.
Contents
Getting Started
The Descend source code is available in a Mercurial repository. Mercurial can be downloaded from Selenic. Windows users may find TortoiseHG useful.
Descend currently does not contain a local copy of XULRunner (and may never have one; It would be best to use a globally available XULRunner). You can use the XULRunner bundled with Firefox 3.x to run Descend.
Setup Your Mercurial Client
At the minimum, you should configure your Mercurial client with a "username". For hg, add the following to your ~/.hgrc file (or create a new one)
[ui] username = Real Name <[email protected]>
Development
Clone the Source Repository
Create a local repository with the following command:
$ hg clone http://hg.kodewerx.org/descend
This will create a new subdirectory called "descend" containing all of the source code and repository history.
Push Changesets to hgkw
If you have developer access to push changesets to the hgkw repository, use the following command: (Don't forget to commit to your local repository, first!)
$ hg push ssh://[email protected]/repos/descend
Running Descend
On Linux, run the included descend_linux shell script. (Tested on Ubuntu 8.10)
On Mac OS X, run the included descend_osx shell script.
On Windows, go to Start -> Run, and type:
"C:\Program Files\Mozilla Firefox\firefox.exe" --app "path/to/descend"
Be sure to verify the path the your Firefox installation is correct. You can also create a batch script to do the same thing.
Developer Notes
In its current form, Descend is just a "syntax highlighter" that can process simple 6502 assembly source code. It will spit out an XHTML-ized copy of the source, with some pretty CSS.
Style Contexts
The concept of a "Style Context" is greatly inspired by GeSHi, which uses "Language Files" to define to the highlighter engine how text should be styled. Descend uses files similar to GeSHi's Language Files (called Syntax Contexts) to define syntax.
Writing new syntax highlighters should be very simple. See descend/chrome/content/styles/6502.js for the 6502 style context.
The Style Context is a JavaScript object which tells highlight.js how to interpret the input text. It is technically an array of simple objects, where each object contains (at a minimum) a rule and a class.
The rule tells highlight.js what to search for. It can be either a regular expression (do use the /g flag if you want to find all occurrences) or an array of strings.
The class is simply which CSS class to give the text which matches rule. The CSS used is template.css.
Example Style Context
var style = [ { rule: /hello,?\s*world!/g, class: 'hello-world' }, { rule: [ 'hello', 'world' ], class: 'hello-world' } ];
Style Context Reference
Each object contains two mandatory members; rule and class:
rule | Specifies a matching rule as either a single RegExp or as an Array of Strings which will later each be searched for as exact matches.
Notes for using RegExps: Always include the 'g' flag; Only use the 'm' and 'i' flags if you truly need them (eg. using ^ or $ to match the beginning/end of lines, or if your RegExp includes strings that must match case-insensitively!) There is currently no need for the 'y' flag. Use remembering-parentheses sparingly (and only with the id member). |
---|---|
class | Specifies which CSS class[es] should be used to style the matches. Multiple classes should be separated by spaces. |
In addition, each object may have zero or more optional members:
anchor | A String which specifies that these matches should be generated as HTML anchors. The String given is used as a prefix for the anchor's 'name' attribute. |
---|---|
delim | An Array containing 1 or 2 Strings that specifies which characters are allowed to appear before [0] and after [1] the rule. An empty String designates that any character is allowed (default). If only one String is specified, it is used for both before and after delimiters. Only has effect with String rules. |
icase | A Boolean value identifying the rule as case-insensitive (true) or case-sensitive (false, default). Only has effect with String rules. |
id | A Number representing which remembered match to use for the anchor or link name. Defaults to 0. Only has effect with anchor or link, and RegExp rules. |
link | A String which specifies that these matches should be generated as HTML links. The String given is used as a prefix for the target anchor. |
sub | A sub-context: an Array of Objects containing rules, classes, etc. The text matching rule will be recursively styled with this sub-context. |
The highlighter will match text in Object-order. For example, you should match single line comments (beginning with //) before matching division operators (a single /) by writing your comment-matching rule first. If they are specified in opposite order, you will be given two consecutive division operators and the comment will not be styled.