//=========================================================================
// (c) Microsoft Corporation 2005-2009. 
//=========================================================================

/// This namespace contains types and modules for generating and formatting text with F#
namespace Microsoft.FSharp.Text

open Microsoft.FSharp.Core
open Microsoft.FSharp.Collections
open System.IO
open System.Text

/// Type of a formatting expression.
///     'Printer : function type generated by printf
///     'State: type argument passed to %a formatters
///     'Residue: value generated by the overall printf action (e.g. sprint generates a string)
///     'Result: value generated after post processing (e.g. failwithf generates a string internally then raises an exception)
type PrintfFormat<'Printer,'State,'Residue,'Result> =
    /// Construct a format string 
    new : value:string -> PrintfFormat<'Printer,'State,'Residue,'Result>
    /// The raw text of the format string 
    member Value : string
    
/// Type of a formatting expression.
///     'Printer : function type generated by printf
///     'State: type argument passed to %a formatters
///     'Residue: value generated by the overall printf action (e.g. sprint generates a string)
///     'Result: value generated after post processing (e.g. failwithf generates a string internally then raises an exception)
///     'Tuple: tuple of values generated by scan or match
type PrintfFormat<'Printer,'State,'Residue,'Result,'Tuple> = 
    inherit PrintfFormat<'Printer,'State,'Residue,'Result>
    /// Construct a format string 
    new: value:string -> PrintfFormat<'Printer,'State,'Residue,'Result,'Tuple>

/// Type of a formatting expression
///     'Printer : function type generated by printf
///     'State: type argument passed to %a formatters
///     'Residue: value generated by the overall printf action (e.g. sprint generates a string)
///     'Result: value generated after post processing (e.g. failwithf generates a string internally then raises an exception)
type Format<'Printer,'State,'Residue,'Result> = PrintfFormat<'Printer,'State,'Residue,'Result>

/// Type of a formatting expression
///     'Printer : function type generated by printf
///     'State: type argument passed to %a formatters
///     'Residue: value generated by the overall printf action (e.g. sprint generates a string)
///     'Result: value generated after post processing (e.g. failwithf generates a string internally then raises an exception)
///     'Tuple: tuple of values generated by scan or match
type Format<'Printer,'State,'Residue,'Result,'Tuple> = PrintfFormat<'Printer,'State,'Residue,'Result,'Tuple>

/// Extensible printf-style formatting for numbers and other datatypes
///
/// Format specifications are strings with "%" markers indicating format 
/// placeholders. Format placeholders consist of:
///  <c>
///    %[flags][width][.precision][type]
///  </c>
/// where the type is interpreted as follows:
///  <c>
///     %b:         bool, formatted as "true" or "false"
///     %s:         string, formatted as its unescaped contents
///     %d, %i:     any basic integer type formatted as a decimal integer, signed if the basic integer type is signed.
///     %u:         any basic integer type formatted as an unsigned decimal integer
///     %x, %X, %o: any basic integer type formatted as an unsigned hexadecimal 
///                 (a-f)/Hexadecimal (A-F)/Octal integer
/// 
///     %e, %E, %f, %F, %g, %G: 
///                 any basic floating point type (float,float32) formatted
///                 using a C-style floating point format specifications, i.e
/// 
///     %e, %E: Signed value having the form [-]d.dddde[sign]ddd where 
///                 d is a single decimal digit, dddd is one or more decimal
///                 digits, ddd is exactly three decimal digits, and sign 
///                 is + or -
/// 
///     %f:     Signed value having the form [-]dddd.dddd, where dddd is one
///                 or more decimal digits. The number of digits before the 
///                 decimal point depends on the magnitude of the number, and 
///                 the number of digits after the decimal point depends on 
///                 the requested precision.
/// 
///     %g, %G: Signed value printed in f or e format, whichever is 
///                 more compact for the given value and precision.
/// 
/// 
///    %M:      System.Decimal value
/// 
///    %O:      Any value, printed by boxing the object and using it's ToString method(s)
/// 
///    %A:      Any value, printed by using Microsoft.FSharp.Text.StructuredPrintfImpl.Display.any_to_string with the default layout settings 
/// 
///    %a:      A general format specifier, requires two arguments:
///                 (1) a function which accepts two arguments:
///                     (a) a context parameter of the appropriate type for the
///                         given formatting function (e.g. an #System.IO.TextWriter)
///                     (b) a value to print
///                         and which either outputs or returns appropriate text.
/// 
///                 (2) the particular value to print
/// 
/// 
///    %t:      A general format specifier, requires one argument:
///                 (1) a function which accepts a context parameter of the
///                     appropriate type for the given formatting function (e.g. 
///                     an System.IO.TextWriter)and which either outputs or returns 
///                     appropriate text.
///
///  Basic integer types are:
///     byte,sbyte,int16,uint16,int32,uint32,int64,uint64,nativeint,unativeint
///  Basic floating point types are:
///     float, float32
///
/// The following format patterns are accepted but a warning is printed:
///
///     %h(d|u|x|X|o)
///     %l(d|u|x|X|o)
///
///  The following format patterns are now deprecated:
///
///     %Ld, %Li, %Lu, %Lx, %LX, %Lo: same, but an int64
///     %nd, %ni, %nu, %nx, %nX, %no: same, but a nativeint
///     %Ud, %Ui, %Uu, %Ux, %UX, %Uo: same, but an unsigned int32 (uint32)
///     %ULd, %ULi, %ULu, %ULx, %ULX, %ULo: same, but an unsigned int64 (uint64)
///     %Und, %Uni, %Unu, %Unx, %UnX, %Uno: same, but an unsigned nativeint (unativeint)
/// </c>
/// The optional width is an integer indicating the minimal width of the
/// result. For instance, %6d prints an integer, prefixing it with spaces
/// to fill at least 6 characters. If width is '*', then an extra integer
/// argument is taken to specify the corresponding width.
/// <c>
///     any number
///     '*': 
/// </c>
/// Valid flags are:
/// <c>
///     0: add zeros instead of spaces to make up the required width
///     '-': left justify the result within the width specified
///     '+': add a '+' character if the number is positive (to match a '-' sign 
///          for negatives)
///     ' ': add an extra space if the number is positive (to match a '-' 
///              sign for negatives)
/// </c>
/// The printf '#' flag is invalid and a compile-time error will be reported if it is used.
module Printf = 

    /// Represents a statically-analyzed format associated with writing to a <c>System.Text.StringBuilder</c>. The first type parameter indicates the
    /// arguments of the format operation and the last the overall return type.
    type BuilderFormat<'T,'Result>    = Format<'T, StringBuilder, unit, 'Result>
    /// Represents a statically-analyzed format when formatting builds a string. The first type parameter indicates the
    /// arguments of the format operation and the last the overall return type.
    type StringFormat<'T,'Result>     = Format<'T, unit, string, 'Result>
    /// Represents a statically-analyzed format associated with writing to a <c>System.IO.TextWriter</c>. The first type parameter indicates the
    /// arguments of the format operation and the last the overall return type.
    type TextWriterFormat<'T,'Result> = Format<'T, TextWriter, unit, 'Result>

    /// Represents a statically-analyzed format associated with writing to a <c>System.Text.StringBuilder</c>. The type parameter indicates the
    /// arguments and return type of the format operation.
    type BuilderFormat<'T>     = BuilderFormat<'T,unit>
    /// Represents a statically-analyzed format when formatting builds a string. The type parameter indicates the
    /// arguments and return type of the format operation.
    type StringFormat<'T>      = StringFormat<'T,string>
    /// Represents a statically-analyzed format associated with writing to a <c>System.IO.TextWriter</c>. The type parameter indicates the
    /// arguments and return type of the format operation.
    type TextWriterFormat<'T>  = TextWriterFormat<'T,unit>

    /// Print to a <c>System.Text.StringBuilder</c>
    val bprintf : builder:StringBuilder -> format:BuilderFormat<'T> -> 'T

    /// Print to a text writer or an OCaml-compatible channel
    val fprintf : textWriter:TextWriter -> format:TextWriterFormat<'T> -> 'T

    /// Print to a text writer or an OCaml-compatible channel, adding a newline
    val fprintfn : textWriter:TextWriter -> format:TextWriterFormat<'T> -> 'T

    /// Print to any subtype of the .NET type System.IO.TextWriter
    val twprintf : textWriter:TextWriter -> format:TextWriterFormat<'T> -> 'T

    /// Print to any subtype of the .NET type System.IO.TextWriter, and add a newline
    val twprintfn : textWriter:TextWriter -> format:TextWriterFormat<'T> -> 'T

    /// Formatted printing to stderr
    val eprintf :                 format:TextWriterFormat<'T> -> 'T

    /// Formatted printing to stderr, adding a newline 
    val eprintfn :                format:TextWriterFormat<'T> -> 'T

    /// Formatted printing to stdout
    val printf  :                 format:TextWriterFormat<'T> -> 'T

    /// Formatted printing to stdout, adding a newline 
    val printfn  :                format:TextWriterFormat<'T> -> 'T

    /// Print to a string via an internal string buffer and return 
    /// the result as a string.  Helper printers must return strings.
    val sprintf :                 format:StringFormat<'T> -> 'T

    /// bprintf, but call the given 'final' function to generate the result.
    /// See <c>kprintf</c>.
    val kbprintf : continutation:(unit -> 'Result)   -> builder:StringBuilder ->    format:BuilderFormat<'T,'Result> -> 'T

    /// fprintf, but call the given 'final' function to generate the result.
    /// See <c>kprintf</c>.
    val kfprintf : continutation:(unit -> 'Result)   -> textWriter:TextWriter -> format:TextWriterFormat<'T,'Result> -> 'T

    /// printf, but call the given 'final' function to generate the result.
    /// For example, these let the printing force a flush after all output has 
    /// been entered onto the channel, but not before. 
    val kprintf  : continutation:(string -> 'Result) ->                format:StringFormat<'T,'Result> -> 'T

    /// twprintf, but call the given 'final' function to generate the result.
    /// See <c>kprintf</c>.
    val ktwprintf : continutation:(unit -> 'Result)   -> textWriter:TextWriter -> format:TextWriterFormat<'T,'Result> -> 'T

    /// sprintf, but call the given 'final' function to generate the result.
    /// See <c>kprintf</c>.
    val ksprintf : continutation:(string -> 'Result) ->                format:StringFormat<'T,'Result>  -> 'T

    /// Print to a string buffer and raise an exception with the given
    /// result. Helper printers must return strings.
    val failwithf: format:StringFormat<'T,'Result> -> 'T