basis/http/server/dispatchers/dispatchers-docs.factor

   1 ! Copyright (C) 2008 Slava Pestov.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: classes help.markup help.syntax ;
   4 IN: http.server.dispatchers
   5
   6 HELP: new-dispatcher
   7 { $values { "class" class } { "dispatcher" dispatcher } }
   8 { $description "Creates a new instance of a subclass of " { $link dispatcher } "." } ;
   9
  10 HELP: dispatcher
  11 { $class-description "The class of dispatchers. May be subclassed, in which case subclasses should be constructed by calling " { $link new-dispatcher } "." } ;
  12
  13 HELP: <dispatcher>
  14 { $values { "dispatcher" dispatcher } }
  15 { $description "Creates a new pathname dispatcher." } ;
  16
  17 HELP: vhost-dispatcher
  18 { $class-description "The class of virtual host dispatchers." } ;
  19
  20 HELP: <vhost-dispatcher>
  21 { $values { "dispatcher" vhost-dispatcher } }
  22 { $description "Creates a new virtual host dispatcher." } ;
  23
  24 HELP: add-responder
  25 { $values
  26     { "dispatcher" dispatcher } { "responder" "a responder" } { "path" "a pathname string or hostname" } }
  27 { $description "Adds a responder to a dispatcher." }
  28 { $notes "The " { $snippet "path" } " parameter is interpreted differently depending on the dispatcher type." }
  29 { $side-effects "dispatcher" } ;
  30
  31 ARTICLE: "http.server.dispatchers.example" "HTTP dispatcher examples"
  32 { $heading "Simple pathname dispatcher" }
  33 { $code
  34     "<dispatcher>
  35     <new-action> \"new\" add-responder
  36     <edit-action> \"edit\" add-responder
  37     <delete-action> \"delete\" add-responder
  38     <list-action> \"\" add-responder
  39 main-responder set-global"
  40 }
  41 "In the above example, visiting any URL other than " { $snippet "/new" } ", " { $snippet "/edit" } ", " { $snippet "/delete" } ", or " { $snippet "/" } " will result in a 404 error."
  42 { $heading "Another pathname dispatcher" }
  43 "On the other hand, suppose we wanted to route all unrecognized paths to a “view” action:"
  44 { $code
  45     "<dispatcher>
  46     <new-action> \"new\" add-responder
  47     <edit-action> \"edit\" add-responder
  48     <delete-action> \"delete\" add-responder
  49     <view-action> >>default
  50 main-responder set-global"
  51 }
  52 "The " { $slot "default" } " slot holds a responder to which all unrecognized paths are sent to."
  53 { $heading "Dispatcher subclassing example" }
  54 { $code
  55     "TUPLE: golf-courses < dispatcher ;
  56
  57 : <golf-courses> ( -- golf-courses )
  58     golf-courses new-dispatcher ;
  59
  60 <golf-courses>
  61     <new-action> \"new\" add-responder
  62     <edit-action> \"edit\" add-responder
  63     <delete-action> \"delete\" add-responder
  64     <list-action> \"\" add-responder
  65 main-responder set-global"
  66 }
  67 "The action templates can now emit links to responder-relative URLs prefixed by " { $snippet "$golf-courses/" } "."
  68 { $heading "Virtual hosting example" }
  69 { $code
  70     "<vhost-dispatcher>
  71     <casino> \"concatenative-casino.com\" add-responder
  72     <dating> \"raptor-dating.com\" add-responder
  73 main-responder set-global"
  74 }
  75 "Note that the virtual host dispatcher strips off a " { $snippet "www." } " prefix, so " { $snippet "www.concatenative-casino.com" } " would be routed to the " { $snippet "<casino>" } " responder instead of receiving a 404." ;
  76
  77 ARTICLE: "http.server.dispatchers" "HTTP dispatchers and virtual hosting"
  78 "The " { $vocab-link "http.server.dispatchers" } " vocabulary implements two responders which route HTTP requests to one or more child responders."
  79 { $subsections "http.server.dispatchers.example" }
  80 "Pathname dispatchers implement a directory hierarchy where each subdirectory is its own responder:"
  81 { $subsections
  82     dispatcher
  83     <dispatcher>
  84 }
  85 "Virtual host dispatchers dispatch each virtual host to a different responder:"
  86 { $subsections
  87     vhost-dispatcher
  88     <vhost-dispatcher>
  89 }
  90 "Adding responders to dispatchers:"
  91 { $subsections add-responder }
  92 "The " { $slot "default" } " slot holds a responder which receives all unrecognized URLs. By default, it responds with 404 messages." ;
  93
  94 ABOUT: "http.server.dispatchers"