<commit_before>#lang scribble/doc
@(require "mz.ss"
          (for-label scheme/control))

@title{Classical Control Operators}

@note-lib-only[scheme/control]

@(define control-eval
         (let ([the-eval (make-base-eval)])
          (the-eval '(require scheme/control))
          the-eval))

The @scheme[scheme/control] library provides various control operators
from the research literature on higher-order control operators, plus a
few extra convenience forms. These control operators are implemented
in terms of @scheme[call-with-continuation-prompt],
@scheme[call-with-composable-continuations], etc., and they generally
work sensibly together. Many are redundant; for example,
@scheme[reset] and @scheme[prompt] are aliases.
 
@; ----------------------------------------------------------------------

@defproc[(abort [v any/c] ...) any]{

Returns the @scheme[v]s to a prompt using the default continuation
prompt tag and the default abort handler.

That is, @scheme[(abort v ...)] is equivalent to

@schemeblock[
(abort-current-continuation
 (default-continuation-prompt-tag)
 (lambda () (values v ...)))
]

@examples[#:eval control-eval
(prompt
  (printf "start here\n")
  (printf "answer is ~a\n" (+ 2 (abort 3))))
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform*[[(% expr)
           (% expr handler-expr)]]
@defproc[(fcontrol [v any/c]) any]
)]{


Sitaram's operators @cite["Sitaram93"].

The essential reduction rules are:

@schemeblock[
(% _val proc) => _val
(% _E[(fcontrol _val)] _proc) => (_proc _val (lambda (_x) _E[_x]))
  (code:comment @#,t{where @scheme[_E] has no @scheme[%]})
]

When @scheme[handler-expr] is omitted, @scheme[%] is the same as 
@scheme[prompt].

@examples[#:eval control-eval
(% (+ 2 (fcontrol 5))
   (lambda (v k)
     (k v)))
(% (+ 2 (fcontrol 5))
   (lambda (v k)
     v))
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(prompt expr ...+)]
@defform[(control id expr ...+)]
)]{

Among the earliest operators for higher-order control
@cite["Felleisen88" "Sitaram90"].

The essential reduction rules are:
@schemeblock[
(prompt _val) => _val
(prompt _E[(control _k _expr)]) => (prompt ((lambda (_k) _expr)
                                            (lambda (_v) _E[_v])))
  (code:comment @#,t{where @scheme[_E] has no @scheme[prompt]})
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(prompt-at prompt-tag-expr expr ...+)]
@defform[(control-at prompt-tag-expr id expr ...+)]
)]{

Like @scheme[prompt] and @scheme[control], but using specific prompt
tags:

@schemeblock[
(prompt-at _tag _val) => _val
(prompt-at _tag _E[(control-at _tag _k _expr)]) => (prompt-at _tag 
                                                    ((lambda (_k) _expr)
                                                     (lambda (_v) _E[_v])))
  (code:comment @#,t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]})
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(reset expr ...+)]
@defform[(shift id expr ...+)]
)]{

Danvy and Filinski's operators @cite["Danvy90"].

The essential reduction rules are:
<commit_msg>add prompt/control examples<commit_after>#lang scribble/doc
@(require "mz.ss"
          (for-label scheme/control))

@title{Classical Control Operators}

@note-lib-only[scheme/control]

@(define control-eval
         (let ([the-eval (make-base-eval)])
          (the-eval '(require scheme/control))
          the-eval))

The @scheme[scheme/control] library provides various control operators
from the research literature on higher-order control operators, plus a
few extra convenience forms. These control operators are implemented
in terms of @scheme[call-with-continuation-prompt],
@scheme[call-with-composable-continuations], etc., and they generally
work sensibly together. Many are redundant; for example,
@scheme[reset] and @scheme[prompt] are aliases.
 
@; ----------------------------------------------------------------------

@defproc[(abort [v any/c] ...) any]{

Returns the @scheme[v]s to a prompt using the default continuation
prompt tag and the default abort handler.

That is, @scheme[(abort v ...)] is equivalent to

@schemeblock[
(abort-current-continuation
 (default-continuation-prompt-tag)
 (lambda () (values v ...)))
]

@examples[#:eval control-eval
(prompt
  (printf "start here\n")
  (printf "answer is ~a\n" (+ 2 (abort 3))))
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform*[[(% expr)
           (% expr handler-expr)]]
@defproc[(fcontrol [v any/c]) any]
)]{


Sitaram's operators @cite["Sitaram93"].

The essential reduction rules are:

@schemeblock[
(% _val proc) => _val
(% _E[(fcontrol _val)] _proc) => (_proc _val (lambda (_x) _E[_x]))
  (code:comment @#,t{where @scheme[_E] has no @scheme[%]})
]

When @scheme[handler-expr] is omitted, @scheme[%] is the same as 
@scheme[prompt].

@examples[#:eval control-eval
(% (+ 2 (fcontrol 5))
   (lambda (v k)
     (k v)))
(% (+ 2 (fcontrol 5))
   (lambda (v k)
     v))
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(prompt expr ...+)]
@defform[(control id expr ...+)]
)]{

Among the earliest operators for higher-order control
@cite["Felleisen88" "Sitaram90"].

The essential reduction rules are:
@schemeblock[
(prompt _val) => _val
(prompt _E[(control _k _expr)]) => (prompt ((lambda (_k) _expr)
                                            (lambda (_v) _E[_v])))
  (code:comment @#,t{where @scheme[_E] has no @scheme[prompt]})
]

@examples[#:eval control-eval
(prompt
  (+ 2 (control k (k 5))))
(prompt
  (+ 2 (control k 5)))
(prompt
  (+ 2 (control k (+ 1 (control k1 (k1 6))))))
(prompt
  (+ 2 (control k (+ 1 (control k1 (k 6))))))
(prompt
  (+ 2 (control k (control k1 (control k2 (k2 6))))))
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(prompt-at prompt-tag-expr expr ...+)]
@defform[(control-at prompt-tag-expr id expr ...+)]
)]{

Like @scheme[prompt] and @scheme[control], but using specific prompt
tags:

@schemeblock[
(prompt-at _tag _val) => _val
(prompt-at _tag _E[(control-at _tag _k _expr)]) => (prompt-at _tag 
                                                    ((lambda (_k) _expr)
                                                     (lambda (_v) _E[_v])))
  (code:comment @#,t{where @scheme[_E] has no @scheme[prompt-at] for @scheme[_tag]})
]}

@; ----------------------------------------------------------------------

@deftogether[(
@defform[(reset expr ...+)]
@defform[(shift id expr ...+)]
)]{

Danvy and Filinski's operators @cite["Danvy90"].

The essential reduction rules are:

{'fraction_non_alphanumeric': 0.2536699941280094, 'fraction_numerical': 0.006752789195537287, 'mean_word_length': 2.2551361681796465, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1554896', 'n_tokens_mistral': 2143, 'n_tokens_neox': 2033, 'n_words': 597}