basis/help/syntax/syntax.factor

   1 ! Copyright (C) 2005, 2009 Slava Pestov.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: accessors arrays ascii combinators
   4 combinators.short-circuit compiler.units definitions help
   5 help.markup help.topics kernel lexer math namespaces parser
   6 sequences splitting strings strings.parser vocabs.parser words ;
   7 IN: help.syntax
   8
   9 DEFER: HELP{
  10
  11 <PRIVATE
  12
  13 :: parse-help-token ( end -- str/obj/f )
  14     ?scan-token dup {
  15         [ "{" = [ \ HELP{ ] [ f ] if ]
  16         [ "syntax" lookup-word ]
  17         [ "help.markup" lookup-word ]
  18         [ dup ?last ":{[(/\"" member-eq? [ search ] [ drop f ] if ]
  19     } 1|| {
  20         { [ dup not ] [ drop ] }
  21         { [ dup end eq? ] [ 2drop f ] }
  22         { [ dup parsing-word? ] [
  23             nip V{ } clone swap execute-parsing first
  24             dup wrapper? [ wrapped>> \ $link swap 2array ] when ] }
  25         { [ dup ] [ nip ] }
  26     } cond ;
  27
  28 : push-help-text ( accum sbuf obj -- accum sbuf' )
  29     [ dup empty? [ >string suffix! SBUF" " clone ] unless ]
  30     [ [ suffix! ] curry dip ] bi* ;
  31
  32 : help-block? ( word -- ? )
  33     {
  34         $description $heading $subheading $syntax
  35         $class-description $error-description $var-description
  36         $contract $notes $curious $deprecated $errors
  37         $side-effects $content $warning $subsections $nl
  38         $list $table $example $unchecked-example $code
  39     } member-eq? ;
  40
  41 : push-help-space ( accum sbuf -- accum sbuf )
  42     dup empty? [
  43         over empty? not
  44         pick ?last dup array? [ ?first ] when
  45         help-block? not and
  46     ] [
  47         dup last CHAR: \s eq? not
  48     ] if [ CHAR: \s suffix! ] when ;
  49
  50 :: parse-help-text ( end -- seq )
  51     V{ } clone SBUF" " clone [
  52         lexer get line>> :> m
  53         end parse-help-token :> obj
  54         lexer get line>> :> n
  55
  56         obj string? n m - 1 > and [
  57             { [ dup empty? not ] [ over ?last string? ] } 0||
  58             [ \ $nl push-help-text ] when
  59         ] when
  60
  61         obj [
  62             [
  63                 dup string? [
  64                     dup ?first " .,;:" member? [
  65                         [ push-help-space ] dip
  66                     ] unless append!
  67                 ] [
  68                     [ push-help-space ]
  69                     [ push-help-text ] bi*
  70                 ] if
  71             ] when*
  72         ] keep
  73     ] loop [ >string suffix! ] unless-empty >array ; inline
  74
  75 : parse-help-values ( -- seq )
  76     [ scan-token dup "}" = not ] [
  77         dup "{" = [
  78             drop \ } parse-until >array
  79         ] [
  80             ":" ?tail drop scan-object 2array
  81         ] if
  82     ] produce nip ;
  83
  84 : code-lines ( str -- seq )
  85     split-lines [ [ ascii:blank? ] trim ] map harvest ;
  86
  87 : make-example ( str -- seq )
  88     code-lines dup { [ array? ] [ length 1 > ] } 1&& [
  89         dup length 1 - over [ unescape-string ] change-nth
  90         \ $example prefix
  91     ] when ;
  92
  93 : parse-help-examples ( -- seq )
  94     \ } parse-until dup [ string? ] all?
  95     [ [ make-example ] { } map-as ] [ >array ] if ;
  96
  97 : parse-help-code ( -- seq )
  98     \ } parse-until dup { [ length 1 = ] [ first string? ] } 1&&
  99     [ first code-lines ] [ >array ] if ;
 100
 101 : help-text? ( word -- ? )
 102     {
 103         $description $snippet $emphasis $strong $url $heading
 104         $subheading $syntax $class-description
 105         $error-description $var-description $contract $notes
 106         $curious $deprecated $errors $side-effects $content
 107         $slot $image $warning
 108     } member-eq? ;
 109
 110 : help-code? ( word -- ? )
 111     { $example $unchecked-example $code } member-eq? ;
 112
 113 : help-values? ( word -- ? )
 114     { $values $inputs $outputs } member-eq? ;
 115
 116 : help-examples? ( word -- ? )
 117     { $examples } member-eq? ;
 118
 119 PRIVATE>
 120
 121 SYNTAX: HELP{
 122     scan-object dup \ } eq? [ drop { } ] [
 123         {
 124             { [ dup help-text? ] [ \ } parse-help-text ] }
 125             { [ dup help-code? ] [ parse-help-code ] }
 126             { [ dup help-values? ] [ parse-help-values ] }
 127             { [ dup help-examples? ] [ parse-help-examples ] }
 128             [ \ } parse-until >array ]
 129         } cond swap prefix
 130     ] if suffix! ;
 131
 132 SYNTAX: HELP:
 133     H{ { "{" POSTPONE: HELP{ } } [
 134         scan-word bootstrap-word
 135         [ >link save-location ]
 136         [ [ parse-array-def ] dip set-word-help ]
 137         bi
 138     ] with-words ;
 139
 140 SYNTAX: ARTICLE:
 141     location [
 142         scan-object scan-object
 143         \ ; parse-help-text <article>
 144         over add-article >link
 145     ] dip remember-definition ;
 146
 147 SYNTAX: ABOUT:
 148     current-vocab scan-object >>help changed-definition ;