Refactor blueboxes name to signature-box

scribble-doc/scribblings/scribble/internals.scrbl

@@ -14,6 +14,6 @@
 @include-section["docreader.scrbl"]
 @include-section["xref.scrbl"]
 @include-section["tag.scrbl"]
-@include-section["blueboxes.scrbl"]
+@include-section["signature-box.scrbl"]
 @include-section["config.scrbl"]
 

scribble-doc/scribblings/scribble/renderer.scrbl

@@ -744,7 +744,7 @@ via a @racketmodname[scribble/text-render] renderer).
 
 It saves this information in three pieces in a file
 inside the @racket[dests] directories called
-@filepath{blueboxes.rktd}. The first piece is
+@filepath{signature-box.rktd}. The first piece is
 a single line containing a (decimal, ASCII) number. That number
 is the number of bytes that the second piece of information
 occupies in the file. The second piece of information
@@ -771,7 +771,7 @@ it saves the resulting files in a different place.
                           [ri render-info?])
                   void?]{
   Just like @method[override-render-mixin-multi render], except
-  that it saves the file @filepath{blueboxes.rktd} in
+  that it saves the file @filepath{signature-box.rktd} in
   the same directory where each @racket[dests] element resides.
 }}
 }

scribble-doc/scribblings/scribble/signature-box.scrbl

@@ -0,0 +1,59 @@
+#lang scribble/doc
+@(require scribble/manual "utils.rkt"
+          (for-label scribble/core
+                     scribble/signature-box
+                     racket/contract
+                     setup/xref))
+
+@title[#:tag "signature-box"]{Blue Boxes Utilities}
+
+@defmodule[scribble/signature-box]{
+  The @racketmodname[scribble/signature-box] provides access
+  to the content of the ``blue boxes'' that describe
+  some module's export (but without any styling).}
+
+@defproc[(fetch-signature-box-strs [tag tag?]
+                               [#:signature-box-cache signature-box-cache
+                                                  signature-box-cache?
+                                                  (make-signature-box-cache #t)])
+         (or/c #f (non-empty-listof string?))]{
+  Returns a list of strings that show the content of the blue box
+  (without any styling information) for the documentation referenced
+  by @racket[tag].
+
+  The first string in the list describes the export (e.g. @racket["procedure"]
+  when @racket[defproc] is used, or @racket["syntax"] when @racket[defform]
+  was used to document the export).
+}
+
+@defproc[(fetch-signature-box-method-tags [method-name symbol?]
+                                      [#:signature-box-cache signature-box-cache
+                                                         signature-box-cache?
+                                                         (make-signature-box-cache #t)])
+         (listof method-tag?)]{
+  Returns the list of tags for all methods that are documented in the documentation
+  in @racket[signature-box-cache].
+
+  @history[#:added "1.11"]
+}
+
+@defproc[(make-signature-box-cache
+          [populate? boolean?]
+          [#:signature-box-dirs signature-box-dirs (listof path?) (get-doc-search-dirs)])
+         signature-box-cache?]{
+  Constructs a new (mutable) signature-box cache.
+
+  If @racket[populate?] is @racket[#f], the cache is initially
+  unpopulated, in which case it is filled in the first time the cache
+  is passed to @racket[fetch-bluebxoes-strs]. Otherwise, the cache is
+  populated immediately.
+
+  The @racket[signature-box-dirs] argument is a list of directories that are
+  looked inside for @filepath{signature-box.rktd} files. The default value
+  is only an approximation for where those files usually reside. See
+  also @racket[get-rendered-doc-directories].
+}
+
+@defproc[(signature-box-cache? [v any/c]) boolean?]{
+  Determines if @racket[v] is a signature-box cache.
+}

scribble-lib/scribble/contract-render.rkt

@@ -28,10 +28,10 @@
         (define cb.rktd 
           (cond
             [multi?
-             (build-path dest "blueboxes.rktd")]
+             (build-path dest "signature-box.rktd")]
             [else
              (define-values (base name dir?) (split-path dest))
-             (build-path base "blueboxes.rktd")]))
+             (build-path base "signature-box.rktd")]))
         (call-with-output-file cb.rktd
           (λ (port)
             (fprintf port "~a\n" (string-utf-8-length table-str))

scribble-lib/scribble/blueboxes.rkt → scribble-lib/scribble/signature-box.rkt

@@ -11,52 +11,52 @@
                [definition-tag->class/interface-tag (Definition-Tag -> Class/Interface-Tag)]
                [get-class/interface-and-method (Method-Tag -> (values Symbol Symbol))]
                )
-(require/typed "valid-blueboxes-info.rkt" [valid-blueboxes-info? (Any -> Boolean)])
+(require/typed "valid-signature-box-info.rkt" [valid-signature-box-info? (Any -> Boolean)])
 
-(provide fetch-blueboxes-strs
-         make-blueboxes-cache
-         blueboxes-cache?
-         fetch-blueboxes-method-tags
+(provide fetch-signature-box-strs
+         make-signature-box-cache
+         signature-box-cache?
+         fetch-signature-box-method-tags
          )
 
 (define-type Bluebox-Info bluebox-info)
 (struct bluebox-info
-  ([blueboxes.rktd : Path-String]
+  ([signature-box.rktd : Path-String]
    [offset : (U Natural #f)]
-   [tag-ht : (U Blueboxes-Info-Hash #f)] ; (or/c valid-blueboxes-info? #f)
+   [tag-ht : (U Signature-box-Info-Hash #f)] ; (or/c valid-signature-box-info? #f)
    [mod-time : (U Natural #f)])
   #:mutable)
 
-(define-type Blueboxes-Cache blueboxes-cache)
-(struct blueboxes-cache
+(define-type Signature-box-Cache signature-box-cache)
+(struct signature-box-cache
   ([info-or-paths : (U (Listof Path) (Listof Bluebox-Info))]
    [method->tags : (U (HashTable Symbol (Listof Method-Tag)) #f)])
   #:mutable)
 
-(: make-blueboxes-cache :
+(: make-signature-box-cache :
    Boolean
-   [#:blueboxes-dirs (Listof Path)]
+   [#:signature-box-dirs (Listof Path)]
    ->
-   Blueboxes-Cache)
-(define (make-blueboxes-cache
+   Signature-box-Cache)
+(define (make-signature-box-cache
          populate?
-         #:blueboxes-dirs
-         [blueboxes-dirs (for*/list ([d (in-list (get-doc-search-dirs))]
+         #:signature-box-dirs
+         [signature-box-dirs (for*/list ([d (in-list (get-doc-search-dirs))]
                                      [c (in-list (if (directory-exists? d)
                                                      (directory-list d)
                                                      '()))])
                            : (Listof Path)
                            (build-path d c))])
-  (define cache (blueboxes-cache blueboxes-dirs #f))
+  (define cache (signature-box-cache signature-box-dirs #f))
   (when populate? (populate-cache! cache))
   cache)
 
-(: fetch-blueboxes-strs :
+(: fetch-signature-box-strs :
    Tag
-   [#:blueboxes-cache Blueboxes-Cache]
+   [#:signature-box-cache Signature-box-Cache]
    ->
    (U #f (List* String (Listof String))))
-(define (fetch-blueboxes-strs tag #:blueboxes-cache [cache (make-blueboxes-cache #f)])
+(define (fetch-signature-box-strs tag #:signature-box-cache [cache (make-signature-box-cache #f)])
   (define plain-strs (fetch-strs-for-single-tag tag cache))
   (cond
     [(and plain-strs (definition-tag? tag))
@@ -70,15 +70,15 @@
              (if constructor-strs (cdr constructor-strs) '()))]
     [else plain-strs]))
 
-(: fetch-strs-for-single-tag : Tag Blueboxes-Cache -> (U #f (List* String (Listof String))))
+(: fetch-strs-for-single-tag : Tag Signature-box-Cache -> (U #f (List* String (Listof String))))
 (define (fetch-strs-for-single-tag tag cache)
   (populate-cache! cache)
-  (for/or ([ent (in-list (blueboxes-cache-info-or-paths cache))])
+  (for/or ([ent (in-list (signature-box-cache-info-or-paths cache))])
     : (U #f (List* String (Listof String)))
     (when (bluebox-info? ent)
       (check-and-update-bluebox-info! ent))
     (match ent
-      [(bluebox-info blueboxes.rktd offset tag-ht _)
+      [(bluebox-info signature-box.rktd offset tag-ht _)
        (define offset+lens (and tag-ht (hash-ref tag-ht tag #f)))
        (cond
          [offset+lens
@@ -87,7 +87,7 @@
              append
              (for/list ([offset+len (in-list offset+lens)])
                : (Listof (Listof (U String EOF)))
-               (call-with-input-file blueboxes.rktd
+               (call-with-input-file signature-box.rktd
                  (λ ([port : Input-Port])
                    (port-count-lines! port)
                    (file-position port (+ (car offset+len) (or offset 0)))
@@ -102,63 +102,63 @@
       [_ (log-warning "expected bluebox-info?, given: ~v" ent)
          #f])))
 
-(: fetch-blueboxes-method-tags : Symbol [#:blueboxes-cache Blueboxes-Cache] -> (Listof Method-Tag))
-(define (fetch-blueboxes-method-tags sym #:blueboxes-cache [cache (make-blueboxes-cache #f)])
+(: fetch-signature-box-method-tags : Symbol [#:signature-box-cache Signature-box-Cache] -> (Listof Method-Tag))
+(define (fetch-signature-box-method-tags sym #:signature-box-cache [cache (make-signature-box-cache #f)])
   (populate-cache! cache)
-  (define ht (blueboxes-cache-method->tags cache))
+  (define ht (signature-box-cache-method->tags cache))
   (or (and ht (hash-ref ht sym (λ () '()))) '()))
 
 (define listof-path? (make-predicate (Listof Path)))
 
-(: populate-cache! : Blueboxes-Cache -> Void)
+(: populate-cache! : Signature-box-Cache -> Void)
 (define (populate-cache! cache)
-  (define cache-content (blueboxes-cache-info-or-paths cache))
+  (define cache-content (signature-box-cache-info-or-paths cache))
   (when (listof-path? cache-content)
-    (define the-cache (build-blueboxes-cache cache-content))
+    (define the-cache (build-signature-box-cache cache-content))
     (define mtd-table (compute-methods-table the-cache))
-    (set-blueboxes-cache-method->tags! cache mtd-table)
-    (set-blueboxes-cache-info-or-paths! cache the-cache)))
+    (set-signature-box-cache-method->tags! cache mtd-table)
+    (set-signature-box-cache-info-or-paths! cache the-cache)))
 
 (: compute-methods-table : (Listof Bluebox-Info) -> (HashTable Symbol (Listof Method-Tag)))
 (define (compute-methods-table lst)
   (: meth-ht : (HashTable Symbol (Listof Method-Tag)))
   (define meth-ht (make-hash))
   (for ([a-bluebox-info (in-list lst)])
     (match a-bluebox-info
-      [(bluebox-info blueboxes.rktd offset tag-ht mod-time)
+      [(bluebox-info signature-box.rktd offset tag-ht mod-time)
        (when tag-ht
          (for ([(tag val) (in-hash tag-ht)])
            (when (method-tag? tag)
              (define-values (class/intf meth) (get-class/interface-and-method tag))
              (hash-set! meth-ht meth (cons tag (hash-ref meth-ht meth (λ () '())))))))]))
   meth-ht)
 
-(: build-blueboxes-cache : (Listof Path) -> (Listof Bluebox-Info))
-(define (build-blueboxes-cache blueboxes-dirs)
+(: build-signature-box-cache : (Listof Path) -> (Listof Bluebox-Info))
+(define (build-signature-box-cache signature-box-dirs)
   (filter
    values
-   (for*/list ([doc-dir-name (in-list blueboxes-dirs)])
+   (for*/list ([doc-dir-name (in-list signature-box-dirs)])
      : (Listof Bluebox-Info)
-     (define blueboxes.rktd (build-path doc-dir-name "blueboxes.rktd"))
-     (define a-bluebox-info (bluebox-info blueboxes.rktd #f #f #f))
+     (define signature-box.rktd (build-path doc-dir-name "signature-box.rktd"))
+     (define a-bluebox-info (bluebox-info signature-box.rktd #f #f #f))
      (populate-bluebox-info! a-bluebox-info)
      a-bluebox-info)))
 
 (: check-and-update-bluebox-info! : bluebox-info -> Void)
 (define (check-and-update-bluebox-info! a-bluebox-info)
   (match a-bluebox-info
-    [(bluebox-info blueboxes.rktd offset tag-ht mod-time)
+    [(bluebox-info signature-box.rktd offset tag-ht mod-time)
      (when (or (not mod-time)
-               (and (file-exists? blueboxes.rktd)
-                    (not (mod-time . = . (file-or-directory-modify-seconds blueboxes.rktd)))))
+               (and (file-exists? signature-box.rktd)
+                    (not (mod-time . = . (file-or-directory-modify-seconds signature-box.rktd)))))
        (populate-bluebox-info! a-bluebox-info))]))
 
 (: populate-bluebox-info! : Bluebox-Info -> Void)
 (define (populate-bluebox-info! a-bluebox-info)
-  (define blueboxes.rktd (bluebox-info-blueboxes.rktd a-bluebox-info))
+  (define signature-box.rktd (bluebox-info-signature-box.rktd a-bluebox-info))
   (cond
-    [(file-exists? blueboxes.rktd)
-     (call-with-input-file blueboxes.rktd
+    [(file-exists? signature-box.rktd)
+     (call-with-input-file signature-box.rktd
        (λ ([port : Input-Port])
          (port-count-lines! port)
          (define first-line (read-line port))
@@ -170,11 +170,11 @@
                                                      (exn-message x))
                                         #f)])
              (define candidate (deserialize (read port)))
-             (unless (valid-blueboxes-info? candidate)
-               (error 'build-blueboxes-cache
-                      "blueboxes info didn't have the right shape: ~s"
+             (unless (valid-signature-box-info? candidate)
+               (error 'build-signature-box-cache
+                      "signature-box info didn't have the right shape: ~s"
                       candidate))
-             (cast candidate Blueboxes-Info-Hash)))
+             (cast candidate Signature-box-Info-Hash)))
          (define first-line-num (and (string? first-line) (string->number first-line)))
          (cond
            [(exact-nonnegative-integer? first-line-num)
@@ -184,13 +184,13 @@
                          first-line-num)])
          (set-bluebox-info-tag-ht! a-bluebox-info desed)
          (set-bluebox-info-mod-time! a-bluebox-info
-                                     (file-or-directory-modify-seconds blueboxes.rktd))))]
+                                     (file-or-directory-modify-seconds signature-box.rktd))))]
     [else
      (set-bluebox-info-offset! a-bluebox-info #f)
      (set-bluebox-info-tag-ht! a-bluebox-info #f)
      (set-bluebox-info-mod-time! a-bluebox-info #f)]))
 
-(define-type Blueboxes-Info-Hash
+(define-type Signature-box-Info-Hash
   (HashTable
    Tag
    (Listof (Pairof Natural

scribble-lib/scribble/valid-blueboxes-info.rkt → scribble-lib/scribble/valid-signature-box-info.rkt

@@ -1,10 +1,10 @@
 #lang racket/base
 
-(provide valid-blueboxes-info?)
+(provide valid-signature-box-info?)
 
 (require scribble/core racket/contract/base)
 
-(define valid-blueboxes-info?
+(define valid-signature-box-info?
   (hash/c
    tag?
    (listof (cons/c exact-nonnegative-integer?