basis/editors/editors-docs.factor

   1 USING: help.markup help.syntax parser source-files
   2 source-files.errors vocabs.loader kernel ;
   3 IN: editors
   4
   5 ARTICLE: "editor" "Editor integration"
   6 "Factor development is best done with one of the supported editors; this allows you to quickly jump to definitions from the Factor environment."
   7 { $subsections edit }
   8 "Depending on the editor you are using, you must load one of the child vocabularies of the " { $vocab-link "editors" } " vocabulary, for example " { $vocab-link "editors.emacs" } ":"
   9 { $code "USE: editors.emacs" }
  10 "If you intend to always use the same editor, it helps to have it load during stage 2 bootstrap. Place the code to load and possibly configure it in the " { $link ".factor-boot-rc" } "."
  11 $nl
  12 "Editor integration vocabularies store an object in a global variable when loaded:"
  13 { $subsections editor-class }
  14 "If a syntax error was thrown while loading a source file, you can jump to the location of the error in your editor:"
  15 { $subsections :edit }
  16 "If your favourite editor is missing, you can add support for it. A tutorial is available at "
  17 { $link "create-editor-integration" } "."
  18 ;
  19
  20 ARTICLE: "create-editor-integration" "Creating an editor integration"
  21 "First, let's start with creating a vocabulary for our editor:"
  22 { $code "\"editors.foo\" scaffold-basis" }
  23 "Open it up in your favourite editor (or your second favourite.)"
  24 $nl
  25 "To create a new integration, we need to implement the editor protocol:"
  26 { $list
  27   { "Define a new class to represent your integration, set in " { $link editor-class } }
  28   { "Define an " { $link editor-command } " method to construct a command that opens your editor" }
  29   { "Define an " { $link editor-detached? } " method that denotes whether your editor should be run in "
  30     "detached mode. This should return " { $link t } " for editors that run in a separate terminal." }
  31   { "Define an " { $link editor-is-child? } " method that tells Factor whether it should be eun as "
  32     "a child process." }
  33 }
  34 $nl
  35 "Every editor is required to reserve its own " { $link editor-class } ". For example:"
  36 { $code "SINGLETON: foo" }
  37 { $link editor-class } " will be set to this singleton when Factor is set to use your editor of"
  38 " choice. Now, we will define words that will dispatch when the editor class is set to "
  39 { $snippet "foo" } "."
  40 $nl
  41 { $link editor-command } " takes a file path and line number as strings. Your implementation should "
  42 "form a command that opens the editor to the given line. Many editors have a " { $snippet "+" }
  43 " option for this. For a simple example of this word's implementation, we can look at "
  44 { $vocab-link "editors.gedit" } ":"
  45 { $code "M: gedit editor-command
  46     [
  47             gedit-path , number>string \"+\" prepend , ,
  48     ] { } make ;" }
  49 "Here, " { $snippet gedit-path } " is a word that either pushes the location of " { $snippet "gedit" }
  50 " from PATH, or uses a user-defined path, set in a global."
  51 $nl
  52 "Finally, if your editor does not use a GUI, the " { $link editor-detached? } " method must be "
  53 "defined:"
  54 { $code "M: foo editor-detached? t ;" }
  55 "If your editor has both GUI and TUI frontends, you may want to use more complex logic, or "
  56 "create a variable that the user can set."
  57 ;
  58
  59 ABOUT: "editor"
  60
  61 HELP: edit
  62 { $values { "object" object } }
  63 { $description "Opens the source file containing the definition using the current " { $link editor-class } ". See " { $link "editor" } "." }
  64 { $examples
  65     "Editing a word definition:"
  66     { $code "\\ foo edit" }
  67     "A word's documentation:"
  68     { $code "\\ foo >link edit" }
  69     "A method definition:"
  70     { $code "M\\ fixnum + edit" }
  71     "A help article:"
  72     { $code "\"handbook\" >link edit" }
  73 } ;
  74
  75 HELP: edit-location
  76 { $values { "file" "a pathname string" } { "line" "a positive integer" } }
  77 { $description "Opens a source file at the specified line number containing using the current " { $link editor-class } ". Line numbers are indexed starting from 1. See " { $link "editor" } "." } ;
  78
  79 HELP: :edit
  80 { $description "If the most recent error was a " { $link source-file-error } " thrown while parsing a source file, opens the source file at the failing line in the default editor. See " { $link "editor" } "." } ;