aful.scrbl (4219B)
1 #lang scribble/manual 2 3 @(require scribble/eval 4 scribble-code-examples 5 (for-label (except-in racket/base 6 read read-syntax) 7 (except-in aful/reader 8 read read-syntax))) 9 @author[ 10 "Alex Knauth" 11 @author+email["Suzanne Soy" "racket@suzanne.soy"]] 12 @title{aful} 13 14 @;; example: @aful-code{(map #λ(+ % 1) '(1 2 3))} 15 @(define-syntax-rule @aful-code[stuff ...] 16 @code[#:lang "aful racket" stuff ...]) 17 18 source code: @url["https://github.com/jsmaniac/aful/"] 19 20 @section{#lang aful} 21 22 @defmodulelang[aful]{ 23 The @racketmodname[aful] language is a lang-extension like @racketmodname[at-exp] 24 that adds @racketmodname[rackjure]-like anonymous function literals to a language. 25 @margin-note{see @secref["func-lit" #:doc '(lib "rackjure/rackjure.scrbl")]} 26 27 For example, @racket[@#,hash-lang[] @#,racketmodname[aful] @#,racketmodname[racket/base]] 28 adds anonymous function literals to @racketmodname[racket/base], so that 29 @codeblock{ 30 #lang aful racket/base} 31 @code-examples[#:lang "aful racket/base" #:context #'here]|{ 32 (map #λ(+ % 1) '(1 2 3)) 33 (map #λ(+ % %2) '(1 2 3) '(1 2 3)) 34 }| 35 36 For the @racketmodname[aful] language to work properly for a module, the module 37 has to depend on @racketmodname[racket/base] in some way, although that does not 38 mean it has to explicitly require it or that the language it uses has to provide 39 anything from it. It does mean that for instance 40 @racket[@#,hash-lang[] @#,racketmodname[aful] @#,racketmodname[racket/kernel]] 41 won't work properly. 42 } 43 44 @section{aful/reader} 45 46 @defmodule[aful/reader] 47 48 @deftogether[(@defproc[(aful-read [in input-port? (current-input-port)] 49 [#:arg-str arg-str string? (current-arg-string)]) any]{} 50 @defproc[(aful-read-syntax [source-name any/c (object-name in)] 51 [in input-port? (current-input-port)] 52 [#:arg-str arg-str string? (current-arg-string)]) 53 (or/c syntax? eof-object?)]{})]{ 54 These procedures implement the @racketmodname[aful] reader. They do so by 55 constructing a readtable based on the current one, and using that 56 for reading. 57 58 The @racket[arg-str] argument lets you specify something else to use as a placeholder instead of 59 @racket[%]. 60 61 @examples[ 62 (require aful/reader) 63 (aful-read (open-input-string "#λ(+ % %2)")) 64 (aful-read (open-input-string "#λ(+ _ _2)") #:arg-str "_") 65 ] 66 67 @racketmodname[aful/reader] also exports these functions under the names @racket[read] and 68 @racket[read-syntax]. 69 } 70 71 @defproc[(make-aful-readtable [orig-readtable readtable? (current-readtable)] 72 [#:outer-scope outer-scope (-> syntax? syntax?)] 73 [#:arg-str arg-str string? (current-arg-string)]) readtable?]{ 74 makes an @racketmodname[aful] readtable based on @racket[orig-readtable]. 75 76 The @racket[outer-scope] argument should be a function that introduce scopes to preserve hygiene, 77 normally produced by @racket[make-syntax-introducer] and similar functions. For versions of racket 78 that support it, these should generally be specified as use-site scopes. 79 80 The @racket[arg-str] argument lets you specify something else to use as a placeholder instead of 81 @racket[%], just like for @racket[aful-read]. 82 } 83 84 @defproc[(use-aful-readtable [orig-readtable readtable? (current-readtable)] 85 [#:arg-str arg-str string? (current-arg-string)]) void?]{ 86 passes arguments to @racket[make-aful-readtable] and sets the @racket[current-readtable] parameter to 87 the resulting readtable. 88 It also enables line counting for the @racket[current-input-port] via @racket[port-count-lines!]. 89 90 This is mostly useful for the REPL. 91 92 @verbatim{ 93 Examples: 94 95 > @aful-code{(require aful/reader)} 96 > @aful-code{(use-aful-readtable)} 97 > @aful-code{(map #λ(+ % %2) '(1 2 3) '(1 2 3))} 98 @racketresult['(2 4 6)] 99 > @aful-code{(use-aful-readtable #:arg-str "_")} 100 > @aful-code{(map #λ(+ _ _2) '(1 2 3) '(1 2 3))} 101 @racketresult['(2 4 6)] 102 }} 103 104 @defparam[current-arg-string arg-str string?]{ 105 a parameter that controls default values of the @racket[arg-str] arguments to @racket[aful-read] etc. 106 }