<commit_before>#lang scribble/doc
@(require "web-server.ss")

@title[#:tag "web.ss"]{Web Interaction}
@(require (for-label web-server/servlet/web
                     web-server/servlet/servlet-structs
                     web-server/http))

@defmodule[web-server/servlet/web]{The
@schememodname[web-server/servlet/web] library provides the primary
functions of interest for the servlet developer.

@defproc[(send/back [response response?])
         void?]{
 Sends @scheme[response] to the client. No continuation is captured, so the servlet is done.
       
 Example:
 @schemeblock[
  (send/back
   `(html
     (body
      (h1 "The sum is: "
          ,(+ first-number
              second-number)))))
 ]
}

@defproc[(send/suspend [make-response response-generator/c]
                       [exp expiration-handler/c (current-servlet-continuation-expiration-handler)])
         request?]{
 Captures the current continuation, stores it with @scheme[exp] as the expiration
 handler, and binds it to a URL. @scheme[make-response] is called with this URL and
 is expected to generate a @scheme[response?], which is sent to the client. If the
 continuation URL is invoked, the captured continuation is invoked and the request is
 returned from this call to @scheme[send/suspend].
 
 Example:
 @schemeblock[
  (send/suspend
   (lambda (k-url)
     `(html (head (title "Enter a number"))
            (body 
             (form ([action ,k-url])
                   "Enter a number: "
                   (input ([name "number"]))
                   (input ([type "submit"])))))))
  ]
 
 When this form is submitted by the browser, the request will be sent to the URL generated by @scheme[send/suspend].
 Thus, the request will be ``returned'' from @scheme[send/suspend] to the continuation of this call.
}
                  
@defproc[(send/suspend/dispatch [make-response (embed/url/c . -> . response?)])
         any/c]{
 Calls @scheme[make-response] with a function that, when called with a procedure from
 @scheme[request?] to @scheme[any/c] will generate a URL, that when invoked will call
 the function with the @scheme[request?] object and return the result to the caller of
 @scheme[send/suspend/dispatch].
 
 Use @scheme[send/suspend/dispatch] when there are multiple `logical' continuations of a page.
 For example, we could either add to a number or subtract from it:
 @schemeblock[
  (define (count-dot-com i)
    (count-dot-com 
     (send/suspend/dispatch
      (lambda (embed/url)
        `(html 
          (head (title "Count!"))
          (body
           (h2 (a ([href
                    ,(embed/url
                      (lambda (req)
                        (sub1 i)))])
                  "-"))
           (h1 ,(number->string i))
           (h2 (a ([href
                    ,(embed/url
                      (lambda (req)
                        (add1 i)))])
                  "+"))))))))
  ]
 It is very common that the return value of @scheme[send/suspend/dispatch] is irrevelant in
 your application and you may think of it as ``embedding'' value-less callbacks.
}

@defproc[(send/forward [make-response response-generator/c]
                       [exp expiration-handler/c (current-servlet-continuation-expiration-handler)])
         request?]{
 Calls @scheme[clear-continuation-table!], then @scheme[send/suspend].
       
 Use this if the user can logically go `forward' in your application, but cannot go backward.
}
<commit_msg>Doc request<commit_after>#lang scribble/doc
@(require "web-server.ss")

@title[#:tag "web.ss"]{Web Interaction}
@(require (for-label web-server/servlet/web
                     web-server/servlet/servlet-structs
                     web-server/http))

@defmodule[web-server/servlet/web]{The
@schememodname[web-server/servlet/web] library provides the primary
functions of interest for the servlet developer.

@defproc[(send/back [response response?])
         void?]{
 Sends @scheme[response] to the client. No continuation is captured, so the servlet is done.
       
 Example:
 @schemeblock[
  (send/back
   `(html
     (body
      (h1 "The sum is: "
          ,(+ first-number
              second-number)))))
 ]
}

@defproc[(send/suspend [make-response response-generator/c]
                       [exp expiration-handler/c (current-servlet-continuation-expiration-handler)])
         request?]{
 Captures the current continuation, stores it with @scheme[exp] as the expiration
 handler, and binds it to a URL. @scheme[make-response] is called with this URL and
 is expected to generate a @scheme[response?], which is sent to the client. If the
 continuation URL is invoked, the captured continuation is invoked and the request is
 returned from this call to @scheme[send/suspend].
 
 Example:
 @schemeblock[
  (send/suspend
   (lambda (k-url)
     `(html (head (title "Enter a number"))
            (body 
             (form ([action ,k-url])
                   "Enter a number: "
                   (input ([name "number"]))
                   (input ([type "submit"])))))))
  ]
 
 When this form is submitted by the browser, the request will be sent to the URL generated by @scheme[send/suspend].
 Thus, the request will be ``returned'' from @scheme[send/suspend] to the continuation of this call.
}
                  
@defproc[(send/suspend/dispatch [make-response (embed/url/c . -> . response?)])
         any/c]{
 Calls @scheme[make-response] with a function (@scheme[embed/url]) that, when called with a procedure from
 @scheme[request?] to @scheme[any/c] will generate a URL, that when invoked will call
 the function with the @scheme[request?] object and return the result to the caller of
 @scheme[send/suspend/dispatch]. Therefore, if you pass @scheme[embed/url] the identity function,
 @scheme[send/suspend/dispatch] devolves into @scheme[send/suspend]:
 
 @schemeblock[
  (define (send/suspend response-generator)
    (send/suspend/dispatch
     (lambda (embed/url)
       (response-generator (embed/url (lambda (x) x))))))
  ]
 
 Use @scheme[send/suspend/dispatch] when there are multiple `logical' continuations of a page.
 For example, we could either add to a number or subtract from it:
 @schemeblock[
  (define (count-dot-com i)
    (count-dot-com 
     (send/suspend/dispatch
      (lambda (embed/url)
        `(html 
          (head (title "Count!"))
          (body
           (h2 (a ([href
                    ,(embed/url
                      (lambda (req)
                        (sub1 i)))])
                  "-"))
           (h1 ,(number->string i))
           (h2 (a ([href
                    ,(embed/url
                      (lambda (req)
                        (add1 i)))])
                  "+"))))))))
  ]
 Notice that in this example the result of the handlers are returned to the continuation of @scheme[send/suspend/dispatch].
 However, it is very common that the return value of @scheme[send/suspend/dispatch] is irrevelant in
 your application and you may think of it as ``embedding'' value-less callbacks. Here is the same example in this style:
 @schemeblock[
  (define (count-dot-com i)
    (send/suspend/dispatch
     (lambda (embed/url)
       `(html 
         (head (title "Count!"))
         (body
          (h2 (a ([href
                   ,(embed/url
                     (lambda (req)
                       (count-dot-com (sub1 i))))])
                 "-"))
          (h1 ,(number->string i))
          (h2 (a ([href
                   ,(embed/url
                     (lambda (req)
                       (count-dot-com (add1 i))))])
                 "+")))))))
  ]
}

@defproc[(send/forward [make-response response-generator/c]
                       [exp expiration-handler/c (current-servlet-continuation-expiration-handler)])
         request?]{
 Calls @scheme[clear-continuation-table!], then @scheme[send/suspend].
       
 Use this if the user can logically go `forward' in your application, but cannot go backward.
}

{'fraction_non_alphanumeric': 0.11760998361275683, 'fraction_numerical': 0.0021429471826547334, 'mean_word_length': 2.2934827729348277, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 8, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6332714', 'n_tokens_mistral': 2258, 'n_tokens_neox': 2176, 'n_words': 743}