HelpSource/Classes/SCDocParser.schelp

   1 class:: SCDocParser
   2 summary:: Parse SCDoc markup text
   3 categories:: HelpSystem
   4 related:: Classes/SCDoc, Classes/SCDocRenderer, Guides/WritingHelp, Reference/SCDocSyntax
   5
   6 description::
   7 This class is part of the SCDoc help system, and handles the parsing of the help sourcefiles into an internal tree of elements.
   8
   9 The markup language used in the help sourcefile is explained in link::Reference/SCDocSyntax::.
  10
  11 The internal tree representation consists of an array of nodes, each node looks like this:
  12 code::
  13 (tag:'tagSymbol', text:"textString", children:[], display:\block)
  14 ::
  15 If the tag has text, it is put in the code::text:: field. If it has children, then the code::children:: field contains an array of children nodes. The code::display:: element is either code::\block:: or code::\inline::
  16
  17 In normal cases you won't need to use this class directly, link::Classes/SCDoc:: uses this class to parse and render all help sourcefiles.
  18
  19 classmethods::
  20
  21 method::new
  22 Create a parser instance.
  23
  24 method:: getMethodDoc
  25 Find helpfile for class and parse it to get the documentation for a specific method.
  26 argument:: classname
  27 The name of the class.
  28 argument:: methodname
  29 The name of the method, must be prefixed with code::*:: for classmethods and code::-:: for instancemethods.
  30 returns:: The parsed node tree for the specific method documentation.
  31 discussion::
  32 This is used internally by the code::copymethod\:::: tag.
  33
  34 instancemethods::
  35 private:: init, leaveLevel, popTree, pushTree, setTopNode, enterLevel, endCurrent, addTag, handleWord, addText, endLine, dumpSubTree, makeCategoryTree, generateUndocumentedMethods, dumpClassTree, handleCopyMethod
  36
  37 method::parseFile
  38 Parse a help sourcefile written in SCDoc markup language.
  39 returns:: the parser object.
  40 argument::filename
  41 The full path to the file.
  42 discussion:: The resulting tree is available in code::parser.root::
  43
  44 method::parse
  45 Parse a string of SCDoc markup language.
  46 returns:: the parser object.
  47 argument::string
  48 The string to parse.
  49 discussion:: The resulting tree is available in code::parser.root::
  50
  51 method::parseMetaData
  52 Parse metadata of document and collect methods.
  53 discussion::
  54 This method will leave a list of all method names in code::parser.methodList::, prefixed with xk where
  55 list::
  56 ## x is "+" for extended methods, or else "_"
  57 ## k is "*" for classmethods, "-" for instancemethods and "." for generic methods (often interfaces documented in a non-class helpfile)
  58 ::
  59 It will also leave a list of all explicitly added keywords in code::parser.keywordList::
  60
  61 method::root
  62 Set/get the root array of the internal document tree.
  63
  64 method:: methodList
  65 Get the list of documented methods after running link::-parseMetaData::
  66
  67 method:: keywordList
  68 Get the list of keywords after running link::-parseMetaData::
  69
  70 method::dump
  71 Dump the internal document tree to the post window in a human-readable form.
  72
  73 method::findNode
  74 Find a node.
  75 returns:: An object representing the node, if the node was not found the resulting object will have code::.tag:: set to nil.
  76 argument::tag
  77 The tag to search for.
  78 argument::rootNode
  79 The array to search, defaults to code::this.root::.
  80 discussion::
  81 Example:
  82 code::
  83 p = SCDocParser.new.parseFile("/path/to/myfile.schelp");
  84 p.findNode("related").text.postln;
  85 ::
  86
  87 examples::
  88
  89 code::
  90 p = SCDocParser.new;
  91 p.parseFile("/path/to/an/example.schelp");
  92 p.dump;
  93 p.findNode("summary").text.postln;
  94 p.parse("inline code::code example::.").dump;
  95 ::
  96