Skip to content

Commit a1a6e37

Browse files
abhroabhro
authoredJul 9, 2024··
Documentation updates (#87)
* Ignore Manifest.toml files * Add import statement in install instructions * Use single backtick for monospace Double backtick names get passed on to the (La/Ka)TeX renderer * Combine markdown lists Repeated newlines are interpreted as separate lists * Use python 3 for reference * Make package name a header
1 parent dc82a01 commit a1a6e37

File tree

3 files changed

+86
-72
lines changed

3 files changed

+86
-72
lines changed
 

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
*.jl.cov
22
*.jl.*.cov
33
*.jl.mem
4+
Manifest.toml

‎README.md

+35-36
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ This package offers Python-style general formatting and c-style numerical format
3737
This package is pure Julia. Setting up this package is like setting up other Julia packages:
3838

3939
```julia
40-
Pkg.add("Format")
40+
import Pkg; Pkg.add("Format")
4141
```
4242
or
4343
```julia
@@ -59,92 +59,91 @@ This package depends on Julia of version 1.4 or above, and. The package is MIT-l
5959

6060
#### Types to Represent Formats
6161

62-
This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification.
62+
This package has two types `FormatSpec` and `FormatExpr` to represent a format specification.
6363

64-
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
64+
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
6565

6666
```julia
6767
fspec = FormatSpec("d")
6868
fspec = FormatSpec("<8.4f")
6969
```
70-
Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details.
70+
Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details.
7171

7272

73-
``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as
73+
`FormatExpr` captures a formatting expression that may involve multiple items. One can compile a formatting string into a `FormatExpr` instance as
7474

7575
```julia
7676
fe = FormatExpr("{1} + {2}")
7777
fe = FormatExpr("{1:d} + {2:08.4e} + {3|>abs2}")
7878
```
79-
Please refer to [Python's format string syntax](http://docs.python.org/2/library/string.html#format-string-syntax) for details.
79+
Please refer to [Python's format string syntax](http://docs.python.org/3/library/string.html#format-string-syntax) for details.
8080

8181

8282
**Note:** If the same format is going to be applied for multiple times. It is more efficient to first compile it.
8383

8484

8585
#### Formatted Printing
8686

87-
One can use ``printfmt`` and ``printfmtln`` for formatted printing:
87+
One can use `printfmt` and `printfmtln` for formatted printing:
8888

8989
- **printfmt**(io, fe, args...)
9090

9191
- **printfmt**(fe, args...)
9292

93-
Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``.
94-
95-
**Examples**
96-
97-
```julia
98-
printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
99-
printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
100-
101-
fs = FormatSpec("#04x")
102-
printfmt(fs, 12) # --> print("0x0c")
103-
104-
fe = FormatExpr("{} = {:#04x}")
105-
printfmt(fe, "abc", 12) # --> print("abc = 0x0c")
106-
```
93+
Print given arguments using given format `fe`. Here `fe` can be a formatting string, an instance of `FormatSpec` or `FormatExpr`.
10794

108-
**Notes**
95+
**Examples**
10996

110-
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.
97+
```julia
98+
printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
99+
printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
111100

112-
```julia
113-
printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance
114-
printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance
115-
# such a string to specify a format specification for single argument
101+
fs = FormatSpec("#04x")
102+
printfmt(fs, 12) # --> print("0x0c")
116103

117-
printfmt(FormatSpec("d"), 10) # OK
118-
printfmt(FormatExpr("{1:d}", 10)) # OK
119-
```
104+
fe = FormatExpr("{} = {:#04x}")
105+
printfmt(fe, "abc", 12) # --> print("abc = 0x0c")
106+
```
120107

108+
**Notes**
109+
110+
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.
111+
112+
```julia
113+
printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance
114+
printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance
115+
# such a string to specify a format specification for single argument
116+
117+
printfmt(FormatSpec("d"), 10) # OK
118+
printfmt(FormatExpr("{1:d}", 10)) # OK
119+
```
121120

122121
- **printfmtln**(io, fe, args...)
123122

124123
- **printfmtln**(fe, args...)
125124

126-
Similar to ``printfmt`` except that this function print a newline at the end.
125+
Similar to `printfmt` except that this function print a newline at the end.
127126

128127
#### Formatted String
129128

130-
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.
129+
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.
131130

132131
- **pyfmt**(fspec, a)
133132

134-
Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``.
133+
Format a single value using a format specification given by `fspec`, where `fspec` can be either a string or an instance of `FormatSpec`.
135134

136135
- **format**(fe, args...)
137136

138-
Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``.
137+
Format arguments using a format expression given by `fe`, where `fe` can be either a string or an instance of `FormatSpec`.
139138

140139

141140
#### Difference from Python's Format
142141

143142
At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences:
144143

145-
- 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} + {}``).
144+
- 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} + {}`).
146145

147-
- 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.
146+
- 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.
148147

149148
## C-style functions
150149

‎src/Format.jl

+50-36
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
"""
2-
Format.jl
2+
# Format.jl
33
44
This package provides various functions to provide formatted output,
55
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.
88
99
#### Types to Represent Formats
1010
11-
This package has two types ``FormatSpec`` and ``FormatExpr`` to represent a format specification.
11+
This package has two types `FormatSpec` and `FormatExpr` to represent a
12+
format specification.
1213
13-
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
14+
In particular, `FormatSpec` is used to capture the specification of a single
15+
entry. One can compile a format specification string into a `FormatSpec`
16+
instance as
1417
1518
```julia
1619
fspec = FormatSpec("d")
1720
fspec = FormatSpec("<8.4f")
1821
```
19-
Please refer to [Python's format specification language](http://docs.python.org/2/library/string.html#formatspec) for details.
22+
Please refer to [Python's format specification language](http://docs.python.org/3/library/string.html#formatspec) for details.
2023
2124
22-
``FormatExpr`` captures a formatting expression that may involve multiple items. One can compile a formatting string into a ``FormatExpr`` instance as
25+
`FormatExpr` captures a formatting expression that may involve multiple items.
26+
One can compile a formatting string into a `FormatExpr` instance as
2327
2428
```julia
2529
fe = FormatExpr("{1} + {2}")
@@ -33,67 +37,77 @@ Please refer to [Python's format string syntax](http://docs.python.org/2/library
3337
3438
#### Formatted Printing
3539
36-
One can use ``printfmt`` and ``printfmtln`` for formatted printing:
40+
One can use `printfmt` and `printfmtln` for formatted printing:
3741
3842
- **printfmt**(io, fe, args...)
3943
4044
- **printfmt**(fe, args...)
4145
42-
Print given arguments using given format ``fe``. Here ``fe`` can be a formatting string, an instance of ``FormatSpec`` or ``FormatExpr``.
43-
44-
**Examples**
45-
46-
```julia
47-
printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
48-
printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
49-
50-
fs = FormatSpec("#04x")
51-
printfmt(fs, 12) # --> print("0x0c")
52-
53-
fe = FormatExpr("{} = {:#04x}")
54-
printfmt(fe, "abc", 12) # --> print("abc = 0x0c")
55-
```
46+
Print given arguments using given format `fe`. Here `fe` can be a formatting
47+
string, an instance of `FormatSpec` or `FormatExpr`.
5648
57-
**Notes**
49+
**Examples**
5850
59-
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.
51+
```julia
52+
printfmt("{1:>4s} + {2:.2f}", "abc", 12) # --> print(" abc + 12.00")
53+
printfmt("{} = {:#04x}", "abc", 12) # --> print("abc = 0x0c")
6054
61-
```julia
62-
printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance
63-
printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance
64-
# such a string to specify a format specification for single argument
55+
fs = FormatSpec("#04x")
56+
printfmt(fs, 12) # --> print("0x0c")
6557
66-
printfmt(FormatSpec("d"), 10) # OK
67-
printfmt(FormatExpr("{1:d}", 10)) # OK
68-
```
58+
fe = FormatExpr("{} = {:#04x}")
59+
printfmt(fe, "abc", 12) # --> print("abc = 0x0c")
60+
```
6961
62+
**Notes**
63+
64+
If the first argument is a string, it will be first compiled into a `FormatExpr`,
65+
which implies that you can not use specification-only string in the first argument.
66+
67+
```julia
68+
printfmt("{1:d}", 10) # OK, "{1:d}" can be compiled into a FormatExpr instance
69+
printfmt("d", 10) # Error, "d" can not be compiled into a FormatExpr instance
70+
# such a string to specify a format specification for single argument
71+
72+
printfmt(FormatSpec("d"), 10) # OK
73+
printfmt(FormatExpr("{1:d}", 10)) # OK
74+
```
7075
7176
- **printfmtln**(io, fe, args...)
7277
7378
- **printfmtln**(fe, args...)
7479
75-
Similar to ``printfmt`` except that this function print a newline at the end.
80+
Similar to `printfmt` except that this function print a newline at the end.
7681
7782
#### Formatted String
7883
79-
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.
84+
One can use `pyfmt` to format a single value into a string, or `format` to
85+
format one to multiple arguments into a string using an format expression.
8086
8187
- **pyfmt**(fspec, a)
8288
83-
Format a single value using a format specification given by ``fspec``, where ``fspec`` can be either a string or an instance of ``FormatSpec``.
89+
Format a single value using a format specification given by `fspec`, where
90+
`fspec` can be either a string or an instance of `FormatSpec`.
8491
8592
- **format**(fe, args...)
8693
87-
Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``.
94+
Format arguments using a format expression given by `fe`, where `fe` can be
95+
either a string or an instance of `FormatSpec`.
8896
8997
9098
#### Difference from Python's Format
9199
92-
At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences:
100+
At this point, this package implements a subset of Python's formatting language
101+
(with slight modification). Here is a summary of the differences:
93102
94-
- 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} + {}``).
103+
- In terms of argument specification, it supports natural ordering (e.g.
104+
`{} + {}`), explicit position (e.g. `{1} + {2}`). It hasn't supported named
105+
arguments or fields extraction yet. Note that mixing these two modes is not
106+
allowed (e.g. `{1} + {}`).
95107
96-
- 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.
108+
- The package provides support for filtering (for explicitly positioned
109+
arguments), such as `{1|>lowercase}` by allowing one to embed the `|>`
110+
operator, which the Python counter part does not support.
97111
98112
## C-style functions
99113

0 commit comments

Comments
 (0)
Please sign in to comment.