diff --git a/.gitignore b/.gitignore index 8c960ec..3f02ca7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *.jl.cov *.jl.*.cov *.jl.mem +Manifest.toml diff --git a/README.md b/README.md index 420ecb0..f934f9f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ This package offers Python-style general formatting and c-style numerical format This package is pure Julia. Setting up this package is like setting up other Julia packages: ```julia -Pkg.add("Format") +import Pkg; Pkg.add("Format") ``` or ```julia @@ -59,24 +59,24 @@ This package depends on Julia of version 1.4 or above, and. The package is MIT-l #### Types to Represent Formats -This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification. +This package has two types `FormatSpec` and `FormatExpr` to represent a format specification. -In particular, ``FormatSpec`` is used to capture the specification of a single entry. One can compile a format specification string into a ``FormatSpec`` instance as +In particular, `FormatSpec` is used to capture the specification of a single entry. One can compile a format specification string into a `FormatSpec` instance as ```julia fspec = FormatSpec("d") fspec = FormatSpec("<8.4f") ``` -Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details. +Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details. -``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as +`FormatExpr` captures a formatting expression that may involve multiple items. One can compile a formatting string into a `FormatExpr` instance as ```julia fe = FormatExpr("{1} + {2}") fe = FormatExpr("{1:d} + {2:08.4e} + {3|>abs2}") ``` -Please refer to [Python's format string syntax](http://docs.python.org/2/library/string.html#format-string-syntax) for details. +Please refer to [Python's format string syntax](http://docs.python.org/3/library/string.html#format-string-syntax) for details. **Note:** If the same format is going to be applied for multiple times. It is more efficient to first compile it. @@ -84,67 +84,66 @@ Please refer to [Python's format string syntax](http://docs.python.org/2/library #### Formatted Printing -One can use ``printfmt`` and ``printfmtln`` for formatted printing: +One can use `printfmt` and `printfmtln` for formatted printing: - **printfmt**(io, fe, args...) - **printfmt**(fe, args...) - Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``. - - **Examples** - - ```julia - printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00") - printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") - - fs = FormatSpec("#04x") - printfmt(fs, 12) # --> print("0x0c") - - fe = FormatExpr("{} = {:#04x}") - printfmt(fe, "abc", 12) # --> print("abc = 0x0c") - ``` + Print given arguments using given format `fe`. Here `fe` can be a formatting string, an instance of `FormatSpec` or `FormatExpr`. - **Notes** + **Examples** - If the first argument is a string, it will be first compiled into a ``FormatExpr``, which implies that you can not use specification-only string in the first argument. + ```julia + printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00") + printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") - ```julia - printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance - printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance - # such a string to specify a format specification for single argument + fs = FormatSpec("#04x") + printfmt(fs, 12) # --> print("0x0c") - printfmt(FormatSpec("d"), 10) # OK - printfmt(FormatExpr("{1:d}", 10)) # OK - ``` + fe = FormatExpr("{} = {:#04x}") + printfmt(fe, "abc", 12) # --> print("abc = 0x0c") + ``` + **Notes** + + If the first argument is a string, it will be first compiled into a `FormatExpr`, which implies that you can not use specification-only string in the first argument. + + ```julia + printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance + printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance + # such a string to specify a format specification for single argument + + printfmt(FormatSpec("d"), 10) # OK + printfmt(FormatExpr("{1:d}", 10)) # OK + ``` - **printfmtln**(io, fe, args...) - **printfmtln**(fe, args...) - Similar to ``printfmt`` except that this function print a newline at the end. + Similar to `printfmt` except that this function print a newline at the end. #### Formatted String -One can use ``pyfmt`` to format a single value into a string, or ``format`` to format one to multiple arguments into a string using an format expression. +One can use `pyfmt` to format a single value into a string, or `format` to format one to multiple arguments into a string using an format expression. - **pyfmt**(fspec, a) - Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``. + Format a single value using a format specification given by `fspec`, where `fspec` can be either a string or an instance of `FormatSpec`. - **format**(fe, args...) - Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``. + Format arguments using a format expression given by `fe`, where `fe` can be either a string or an instance of `FormatSpec`. #### Difference from Python's Format At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences: -- In terms of argument specification, it supports natural ordering (e.g. ``{} + {}``), explicit position (e.g. ``{1} + {2}``). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. ``{1} + {}``). +- In terms of argument specification, it supports natural ordering (e.g. `{} + {}`), explicit position (e.g. `{1} + {2}`). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. `{1} + {}`). -- The package provides support for filtering (for explicitly positioned arguments), such as ``{1|>lowercase}`` by allowing one to embed the ``|>`` operator, which the Python counter part does not support. +- The package provides support for filtering (for explicitly positioned arguments), such as `{1|>lowercase}` by allowing one to embed the `|>` operator, which the Python counter part does not support. ## C-style functions diff --git a/src/Format.jl b/src/Format.jl index 226b93d..11200ff 100644 --- a/src/Format.jl +++ b/src/Format.jl @@ -1,5 +1,5 @@ """ -Format.jl +# Format.jl This package provides various functions to provide formatted output, either in a fashion similar to C printf or Python format strings. @@ -8,18 +8,22 @@ either in a fashion similar to C printf or Python format strings. #### Types to Represent Formats -This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification. +This package has two types `FormatSpec` and `FormatExpr` to represent a +format specification. -In particular, ``FormatSpec`` is used to capture the specification of a single entry. One can compile a format specification string into a ``FormatSpec`` instance as +In particular, `FormatSpec` is used to capture the specification of a single +entry. One can compile a format specification string into a `FormatSpec` +instance as ```julia fspec = FormatSpec("d") fspec = FormatSpec("<8.4f") ``` -Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details. +Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details. -``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as +`FormatExpr` captures a formatting expression that may involve multiple items. +One can compile a formatting string into a `FormatExpr` instance as ```julia fe = FormatExpr("{1} + {2}") @@ -33,67 +37,77 @@ Please refer to [Python's format string syntax](http://docs.python.org/2/library #### Formatted Printing -One can use ``printfmt`` and ``printfmtln`` for formatted printing: +One can use `printfmt` and `printfmtln` for formatted printing: - **printfmt**(io, fe, args...) - **printfmt**(fe, args...) - Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``. - - **Examples** - - ```julia - printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00") - printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") - - fs = FormatSpec("#04x") - printfmt(fs, 12) # --> print("0x0c") - - fe = FormatExpr("{} = {:#04x}") - printfmt(fe, "abc", 12) # --> print("abc = 0x0c") - ``` + Print given arguments using given format `fe`. Here `fe` can be a formatting + string, an instance of `FormatSpec` or `FormatExpr`. - **Notes** + **Examples** - If the first argument is a string, it will be first compiled into a ``FormatExpr``, which implies that you can not use specification-only string in the first argument. + ```julia + printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00") + printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c") - ```julia - printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance - printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance - # such a string to specify a format specification for single argument + fs = FormatSpec("#04x") + printfmt(fs, 12) # --> print("0x0c") - printfmt(FormatSpec("d"), 10) # OK - printfmt(FormatExpr("{1:d}", 10)) # OK - ``` + fe = FormatExpr("{} = {:#04x}") + printfmt(fe, "abc", 12) # --> print("abc = 0x0c") + ``` + **Notes** + + If the first argument is a string, it will be first compiled into a `FormatExpr`, + which implies that you can not use specification-only string in the first argument. + + ```julia + printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance + printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance + # such a string to specify a format specification for single argument + + printfmt(FormatSpec("d"), 10) # OK + printfmt(FormatExpr("{1:d}", 10)) # OK + ``` - **printfmtln**(io, fe, args...) - **printfmtln**(fe, args...) - Similar to ``printfmt`` except that this function print a newline at the end. + Similar to `printfmt` except that this function print a newline at the end. #### Formatted String -One can use ``pyfmt`` to format a single value into a string, or ``format`` to format one to multiple arguments into a string using an format expression. +One can use `pyfmt` to format a single value into a string, or `format` to +format one to multiple arguments into a string using an format expression. - **pyfmt**(fspec, a) - Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``. + Format a single value using a format specification given by `fspec`, where + `fspec` can be either a string or an instance of `FormatSpec`. - **format**(fe, args...) - Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``. + Format arguments using a format expression given by `fe`, where `fe` can be + either a string or an instance of `FormatSpec`. #### Difference from Python's Format -At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences: +At this point, this package implements a subset of Python's formatting language +(with slight modification). Here is a summary of the differences: -- In terms of argument specification, it supports natural ordering (e.g. ``{} + {}``), explicit position (e.g. ``{1} + {2}``). It hasn't supported named arguments or fields extraction yet. Note that mixing these two modes is not allowed (e.g. ``{1} + {}``). +- In terms of argument specification, it supports natural ordering (e.g. + `{} + {}`), explicit position (e.g. `{1} + {2}`). It hasn't supported named + arguments or fields extraction yet. Note that mixing these two modes is not + allowed (e.g. `{1} + {}`). -- The package provides support for filtering (for explicitly positioned arguments), such as ``{1|>lowercase}`` by allowing one to embed the ``|>`` operator, which the Python counter part does not support. +- The package provides support for filtering (for explicitly positioned + arguments), such as `{1|>lowercase}` by allowing one to embed the `|>` + operator, which the Python counter part does not support. ## C-style functions