#lang scribble/doc
@(require scribble/manual
          scribble/eval
          "planet.ss"
          "eval.ss")
@(require (for-label scheme "../text.ss"))

@title[#:style 'quiet #:tag "text"]{Text Representations}

@defmodule/this-package[text]

This module provides tools for manipulating and converting textual data.

@section{Contracts and Predicates}

@deftogether[(
@defthing[text/c flat-contract?]{}
@defproc[(text? [v any/c]) boolean?]{}
)]{

This contract and predicate recognize text values: strings, byte strings,
symbols, and keywords, as well as syntax objects containing them.

@defexamples[
#:eval (evaluator)
(text? "text")
(text? #"text")
(text? 'text)
(text? '#:text)
(text? #'"text")
(text? #'#"text")
(text? #'text)
(text? #'#:text)
(text? '(not text))
]

}

@deftogether[(
@defproc[(string-literal? [v any/c]) boolean?]{}
@defproc[(bytes-literal? [v any/c]) boolean?]{}
@defproc[(keyword-literal? [v any/c]) boolean?]{}
)]{

These predicates recognize specific text types stored in syntax objects.

@defexamples[
#:eval (evaluator)
(string-literal? #'"literal")
(string-literal? "not literal")
(bytes-literal? #'#"literal")
(bytes-literal? #"not literal")
(keyword-literal? #'#:literal)
(keyword-literal? '#:not-literal)
]

}

@section{Text Conversions}

@deftogether[(
@defproc[(text->string [text text/c] ...) string?]{}
@defproc[(text->bytes [text text/c] ...) bytes?]{}
@defproc[(text->symbol [text text/c] ...) symbol?]{}
@defproc[(text->keyword [text text/c] ...) keyword?]{}
)]{

These functions convert text values to specific types, retaining their textual
content and concatenating text when necessary.

@defexamples[
#:eval (evaluator)
(text->string #"concat" #'enate)
(text->bytes 'concat #'#:enate)
(text->symbol '#:concat #'"enate")
(text->keyword "concat" #'#"enate")
]

}

@deftogether[(
@defproc[(text->string-literal [text text/c] ...
                               [#:stx stx (or/c syntax? false/c) #f])
         string-literal?]{}
@defproc[(text->bytes-literal [text text/c] ...
                              [#:stx stx (or/c syntax? false/c) #f])
         bytes-literal?]{}
@defproc[(text->identifier [text text/c] ...
                           [#:stx stx (or/c syntax? false/c) #f])
         identifier?]{}
@defproc[(text->keyword-literal [text text/c] ...
                                [#:stx stx (or/c syntax? false/c) #f])
         keyword-literal?]{}
)]{

These functions convert text values to specific syntax object types, retaining
their textual value, concatenating text when necessary, and deriving syntax
object properties from the @scheme[stx] argument.

@defexamples[
#:eval (evaluator)
(define (show stx) (values stx (syntax-e stx)))
(show (text->string-literal #"concat" #'enate))
(show (text->bytes-literal 'concat #'#:enate))
(show (text->identifier '#:concatenate #:stx #'props))
(show (text->keyword-literal "concatenate" #:stx #'props))
]

}

@section{Text Concatenation}

@defproc[(text-append [#:before before string? ""]
                      [#:between between string? ""]
                      [#:after after string? ""]
                      [text text/c] ...) text/c]{

Produces a text value (of arbitrary type) concatenating each @scheme[text]
input.  Multiple inputs are joined with @scheme[between], and given prefix
@scheme[before] and suffix @scheme[after].

@defexamples[
#:eval (evaluator)
(text-append #'one '- #'two)
(text-append #:before "(" #:between ", " #:after ")")
(text-append #:before "(" #:between ", " #:after ")" "Tom")
(text-append #:before "(" #:between ", " #:after ")"
             "Tom" "Dick" "Harry")
]

}

@section{Text Comparisons}

@deftogether[(
@defproc[(text=? [one text/c] [two text/c]) boolean?]
@defproc[(text<? [one text/c] [two text/c]) boolean?]
@defproc[(text<=? [one text/c] [two text/c]) boolean?]
@defproc[(text>? [one text/c] [two text/c]) boolean?]
@defproc[(text>=? [one text/c] [two text/c]) boolean?]
)]{

These predicates compare the character content of two text values.  They are
equivalent to:

@schemeblock[
(text=? one two) = (string=? (text->string one) (text->string two))
(text<? one two) = (string<? (text->string one) (text->string two))
(text<=? one two) = (string<=? (text->string one) (text->string two))
(text>? one two) = (string>? (text->string one) (text->string two))
(text>=? one two) = (string>=? (text->string one) (text->string two))
]

@defexamples[
#:eval (evaluator)
(text=? #"x" #'y)
(text<? #"x" #'y)
(text<=? #"x" #'y)
(text>? #"x" #'y)
(text>=? #"x" #'y)
]

}