From 833a368c661fd37d788e7828e0a5dc18edd9f96b Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 15 Oct 2013 12:36:25 -0600
Subject: [PATCH] document pkg/name

Also, tighten contracts and add `package-source-format?`.
---
 .../racket-doc/pkg/scribblings/apis.scrbl     |  1 +
 .../racket-doc/pkg/scribblings/name.scrbl     | 44 +++++++++++++++++++
 racket/collects/pkg/name.rkt                  | 10 +++--
 3 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 pkgs/racket-pkgs/racket-doc/pkg/scribblings/name.scrbl

diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/apis.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/apis.scrbl
index ecf55ed1de..7928f6614b 100644
--- a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/apis.scrbl
+++ b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/apis.scrbl
@@ -44,4 +44,5 @@ to the @exec{raco pkg} sub-subcommands.
 
 @include-section["lib.scrbl"]
 @include-section["path.scrbl"]
+@include-section["name.scrbl"]
 @include-section["db.scrbl"]
diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/name.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/name.scrbl
new file mode 100644
index 0000000000..8c2e66501d
--- /dev/null
+++ b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/name.scrbl
@@ -0,0 +1,44 @@
+#lang scribble/manual
+@(require (for-label racket/base
+                     racket/contract/base
+                     pkg/name))
+                     
+
+@title[#:tag "name"]{Package Source Parsing}
+
+@defmodule[pkg/name]{The @racketmodname[pkg/name] library provides
+functions for parsing and normalizing a package source, especially for
+extracting a package name.}
+
+
+@defproc[(package-source-format? [v any/c]) boolean?]{
+
+Returns @racket[#t] if @racket[v] is @racket['name] , @racket['file],
+@racket['dir], @racket['github], @racket['file-url],
+@racket['dir-url], @racket['link], or @racket['static-link], and
+returns @racket[#f] otherwise.
+
+The @racket['link] and @racket['static-link] formats are the same as
+@racket['dir] in terms of parsing, but they are treated differently
+for tasks such as package installation.}
+
+
+@defproc[(package-source->name [source string?]
+                               [type (or/c package-source-format? #f)
+                                #f])
+          (or/c #f string?)]{
+
+Extracts the @tech{package name} from a @tech{package source}, where
+the package source type is inferred if @racket[type] is @racket[#f].
+If a valid name cannot be inferred, the result is @racket[#f].}
+
+
+@defproc[(package-source->name+type [source string?]
+                                    [type (or/c package-source-format? #f)
+                                     #f])
+          (values (or/c #f string?)
+                  (or/c package-source-format? #f))]{
+
+Like @racket[package-source->name], but also returns the type of the
+source (which is useful when the type is inferred). If the source is
+not well-formed, the second result can be @racket[#f].}
diff --git a/racket/collects/pkg/name.rkt b/racket/collects/pkg/name.rkt
index 08509bd3aa..e178e25a9e 100644
--- a/racket/collects/pkg/name.rkt
+++ b/racket/collects/pkg/name.rkt
@@ -6,19 +6,23 @@
          net/url)
 
 (provide
+ package-source-format?
  (contract-out
-  [package-source->name+type (->* (string? (or/c #f symbol?))
+  [package-source->name+type (->* (string? (or/c #f package-source-format?))
                                   (#:complain (-> string? string? any)
                                               #:must-infer-name? boolean?
                                               #:link-dirs? boolean?)
-                                  (values (or/c #f string?) (or/c #f symbol?)))]
+                                  (values (or/c #f string?) (or/c #f package-source-format?)))]
   [package-source->name (->* (string?)
-                             ((or/c #f symbol?))
+                             ((or/c #f package-source-format?))
                              (or/c #f string?))]))
 
 (define rx:package-name #rx"^[-_a-zA-Z0-9]+$")
 (define rx:archive #rx"[.](plt|zip|tar|tgz|tar[.]gz)$")
 
+(define package-source-format?
+  (or/c 'name 'file 'dir 'github 'file-url 'dir-url 'link 'static-link))
+
 (define (validate-name name complain inferred?)
   (and name
        (cond