Skip to content

Commit 021424d

Browse files
wenchywenchy
committed
feat: add docs for Version, field property, and metasheet options
1 parent ae568aa commit 021424d

File tree

4 files changed

+180
-18
lines changed

4 files changed

+180
-18
lines changed

‎content/en/docs/basics/wellknown-types.md‎

Lines changed: 34 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,13 @@ You should include the proto files provided by Tableau and Protocol Buffers:
2323

2424
## Datetime
2525

26-
| Type | Default | Description |
27-
| ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
26+
> For use cases, see [Excel wellknown types: Datetime →]({{< relref "../excel/wellknown-types/#datetime" >}})
27+
28+
| Type | Default | Description |
29+
| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
2830
| `datetime` | `0000-00-00 00:00:00` | Format: `yyyy-MM-dd HH:mm:ss` or RFC3339. <br>e.g.: `2020-01-01 05:10:00`<br>or `2020-01-01T05:10:00+08:00`. |
29-
| `date` | `0000-00-00` | Format: `yyyy-MM-dd` or `yyyyMMdd`. <br>e.g.: `2020-01-01` or `20200101`. |
30-
| `time` | `00:00:00` | Format: `HH:mm:ss` or `HHmmss`, `HH:mm` or `HHmm`. <br>e.g.: `05:10:00` or `051000`, `05:10` or `0510`. |
31+
| `date` | `0000-00-00` | Format: `yyyy-MM-dd` or `yyyyMMdd`. <br>e.g.: `2020-01-01` or `20200101`. |
32+
| `time` | `00:00:00` | Format: `HH:mm:ss` or `HHmmss`, `HH:mm` or `HHmm`. <br>e.g.: `05:10:00` or `051000`, `05:10` or `0510`. |
3133
{.table-striped}
3234

3335
**Tips:**
@@ -38,6 +40,8 @@ You should include the proto files provided by Tableau and Protocol Buffers:
3840

3941
## Duration
4042

43+
> For use cases, see [Excel wellknown types: Duration →]({{< relref "../excel/wellknown-types/#duration" >}})
44+
4145
| Type | Default | Description |
4246
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
4347
| `duration` | `0s` | Format like: `72h3m0.5s`. <br>A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. <br>Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. |
@@ -50,6 +54,8 @@ You should include the proto files provided by Tableau and Protocol Buffers:
5054

5155
## Fraction
5256

57+
> For use cases, see [Excel wellknown types: Fraction →]({{< relref "../excel/wellknown-types/#fraction" >}})
58+
5359
A fraction represents a part of a whole or, more generally, any number of equal parts. See [wiki: Fraction](https://en.wikipedia.org/wiki/Fraction) for more details.
5460

5561
| Type | Default | Description |
@@ -65,6 +71,8 @@ message Fraction {
6571

6672
## Comparator
6773

74+
> For use cases, see [Excel wellknown types: Comparator →]({{< relref "../excel/wellknown-types/#comparator" >}})
75+
6876
A comparator holds a `sign` and a fraction `value`. Any number or fraction can compare with it.
6977

7078
| Type | Default | Description |
@@ -89,16 +97,29 @@ message Comparator {
8997

9098
## Version
9199

92-
A version holds a version data with 3 formats: string, value interger and value list. A `pattern` option is required to parse the string into value interger, otherwise the default pattern `255.255.255` will be used.
100+
> For use cases, see [Excel wellknown types: Version →]({{< relref "../excel/wellknown-types/#version" >}})
101+
102+
A version represents the version number in [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation).
103+
Version form is: `<MAJOR>.<MINOR>.<PATCH>[.<OTHER>]...`.
104+
105+
A version field holds three forms of representation for easy use:
106+
107+
- string version: `str`
108+
- integer version: `val`
109+
- integer version parts: `major`, `minor`, `patch`, `others`
110+
111+
You can specify the version `pattern` (a field property) as `<MAJOR_MAX>.<MINOR_MAX>.<PATCH_MAX>[.<OTHER_MAX>]...`.
112+
113+
- Each part with suffix "MAX" represents the max decimal value of each part in the [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation).
114+
- Each part "XXX_MAX+1" represents the part's value occupying in an integer.
115+
- Integer version formula for general pattern `<MAJOR_MAX>.<MINOR_MAX>.<PATCH_MAX>` is: `MAJOR*(MINOR_MAX+1)*(PATCH_MAX+1) + MINOR*(PATCH_MAX+1) + PATCH`
116+
117+
Default `pattern` is: `255.255.255`.
93118

94-
| Type | Default | Description |
95-
| -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96-
| `str` | `""` | Format: `<MAJOR>.<MINOR>.<PATCH>[.<OTHER>]...`. <br>e.g.: `1.0.1` |
97-
| `val` | `0` | Value interger of the version, see the conversion algorithm [here](https://github.com/tableauio/tableau/commit/444a01ff8c4947a249e8d0ea5c4c8c491cea69d3#diff-fd73b99348b802b948424f1740df144f17b6df75a8ff86316cd858f19fe7f87cR471). |
98-
| `major` | `0` | Major version value, the 1st interger value of version string. |
99-
| `minor` | `0` | Minor version value, the 2nd interger value of version string. Zero if there is no 2nd interger value in pattern. |
100-
| `patch` | `0` | Patch version value, the 3rd interger value of version string. Zero if there is no 3rd interger value in pattern. |
101-
| `others` | `[]` | Other version values, the 4rd or following interger values of version string. Nil if there is no 4rd or following interger values in pattern. |
119+
| Type | Default | Description |
120+
| -------------------------------------- | ------- | -------------------------------------------------------------- |
121+
| `version` | `""` | Format: `<MAJOR>.<MINOR>.<PATCH>`. <br>e.g.: `1.0.1` |
122+
| `version\|{pattern:"255.255.255.255"}` | `""` | Format: `<MAJOR>.<MINOR>.<PATCH>.<OTHER>`. <br>e.g.: `1.0.1.1` |
102123

103124
```protobuf
104125
message Version {

‎content/en/docs/excel/field-property.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ toc: true
2929
| `sep` | string | Field-level separator. |
3030
| `subsep` | string | Field-level subseparator. |
3131
| `cross` | int32 | Specify count of crossed nodes/cells/fields of composite types with cardinality, such as list and map. |
32+
| `pattern` | string | Specify the pattern of scalar, list element, and map value. |
3233
{.table-striped .table-hover}
3334

3435
## Option `unique`
@@ -194,6 +195,8 @@ cardinality, such as list and map.
194195

195196
### union list field
196197

198+
> TODO: example illustrated.
199+
197200
Specify the count of union fields the list will cross and occupy
198201
(one list element for each field). It will also change this list
199202
field's layout from incell to horizontal.
@@ -202,5 +205,16 @@ field's layout from incell to horizontal.
202205
- Value > 0 means it is a horizontal list occupying N fields.
203206
- Value < 0 means it is a horizontal list occupying all following fields.
204207

205-
> TODO: example illustrated.
208+
## Option `pattern`
209+
210+
Specify the pattern of scalar field, list element, and map value.
211+
212+
### Wellknown version field
213+
214+
> For use cases, see [Excel wellknown types: Version →]({{< relref "../excel/wellknown-types/#version" >}})
215+
216+
Specify the dotted-decimal pattern of current cell. Each decimal
217+
number ranges from 0 to the corresponding part (MAX) of pattern.
218+
219+
Default pattern: `255.255.255`.
206220

‎content/en/docs/excel/metasheet.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -544,29 +544,33 @@ Example: two worksheets *ItemConf* and *ShopConf* in HelloWorld.xlsx:
544544

545545
### Single-column index
546546

547-
Format: `<ColumnName>[@IndexName]`.
547+
Format: `Column<ColumnX,ColumnY,...>[@IndexName]`.
548548

549-
The sign `@` is the separator between column name and index name. if `IndexName` is not set, it will be this column’s parent struct type name. One or more indexes can be specified by comma-separated rule.
549+
The sign `@` is the separator between column name and index name. if `IndexName` is not set, it will be this column’s parent struct type name. One or more indexes can be specified by comma-separated rule. The columns in the angle brackets `<>` specify the sorting columns which the index sort by.
550550

551551
Examples:
552552

553553
- `ID`
554554
- `ID@Item`
555+
- `ID<ID>@Item`: sort index by ID
556+
- `ID<Type,Priority>@Item`: sort index by Type and Priority
555557
- `ID, Name@AwardItem`
556558
- `ID@Item, Name@AwardItem`
557559

558560
### Multi-column index
559561

560-
Format: `([ColumnName1, ColumnName2, ColumnName3,...])[@IndexName]`.
562+
Format: ``.
561563

562564
Multi-column index (or composite index) is composed of **multiple columns in the same struct** (in list or map) to increase query speed.
563565

564-
The sign `@` is the separator between enclosed column names by parentheses and index name. if `IndexName` is not set, it will be this column’s parent struct type name. One or more indexes can be specified by comma-separated rule.
566+
The sign `@` is the separator between enclosed column names by parentheses and index name. if `IndexName` is not set, it will be this column’s parent struct type name. One or more indexes can be specified by comma-separated rule. The columns in the angle brackets `<>` specify the sorting columns which the index sort by.
565567

566568
Examples:
567569

568570
- `(ID,Name)`
569571
- `(ID,Name)@AwardItem`
572+
- `(ID,Name)<ID>@AwardItem`: sort index by ID
573+
- `(ID,Type)<Type,Priority>@Item`: sort index by Type and Priority
570574
- `ID@Item, (ID,Name)@AwardItem`: one single-column index and one multi-column index.
571575

572576
## Option `Patch`

‎content/en/docs/excel/wellknown-types.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -447,3 +447,126 @@ message ItemConf {
447447
```
448448

449449
{{< /details >}}
450+
451+
## Version
452+
453+
> See [Basics: Version →]({{< relref "../basics/wellknown-types/#version" >}})
454+
455+
A worksheet `ItemConf` in *HelloWorld.xlsx*:
456+
457+
{{< spreadsheet "HelloWorld.xlsx" ItemConf "@TABLEAU" >}}
458+
459+
{{< sheet colored>}}
460+
461+
| Version | CustomVersion | IncellVersion | HorizontalVersion1 | HorizontalVersion2 | HorizontalVersion3 |
462+
| --------------- | -------------- | -------------------------------- | ------------------- | ----------------------- | ------------------- |
463+
| version | version | {pattern:"99.999.99.999.99.999"} | []version | {pattern:"999.999.999"} | []version | {pattern:"999.999.999"} | version | version |
464+
| default version | custom version | incell version | horizontal version1 | horizontal version2 | horizontal version3 |
465+
| 1.0.3 | 1.2.3.4.5.6 | 1.2.3,4.5.6 | 1.0.0 | 1.2.3 | 2.0.3 |
466+
467+
{{< /sheet >}}
468+
469+
{{< sheet >}}
470+
471+
| | | |
472+
| --- | --- | --- |
473+
| | | |
474+
| | | |
475+
| | | |
476+
477+
{{< /sheet >}}
478+
479+
{{< /spreadsheet >}}
480+
481+
Generated:
482+
483+
{{< details "hello_world.proto" open >}}
484+
485+
```protobuf
486+
// --snip--
487+
option (tableau.workbook) = {name:"HelloWorld.xlsx" namerow:1 typerow:2 noterow:3 datarow:4};
488+
489+
message ItemConf {
490+
option (tableau.worksheet) = {name:"ItemConf"};
491+
492+
tableau.Version version = 1 [(tableau.field) = {name:"Version"}]; // default version
493+
tableau.Version custom_version = 2 [(tableau.field) = {name:"CustomVersion" prop:{pattern:"99.999.99.999.99.999"}}]; // custom version
494+
repeated tableau.Version incell_version_list = 3 [(tableau.field) = {name:"IncellVersion" layout:LAYOUT_INCELL prop:{pattern:"999.999.999"}}]; // incell version
495+
repeated tableau.Version horizontal_version_list = 4 [(tableau.field) = {name:"HorizontalVersion" layout:LAYOUT_HORIZONTAL prop:{pattern:"999.999.999"}}]; // horizontal version
496+
}
497+
```
498+
499+
{{< /details >}}
500+
501+
{{< details "ItemConf.json" >}}
502+
503+
```json
504+
{
505+
"version": {
506+
"str": "1.0.3",
507+
"val": "65539",
508+
"major": 1,
509+
"minor": 0,
510+
"patch": 3,
511+
"others": []
512+
},
513+
"customVersion": {
514+
"str": "1.2.3.4.5.6",
515+
"val": "10020300405006",
516+
"major": 1,
517+
"minor": 2,
518+
"patch": 3,
519+
"others": [
520+
4,
521+
5,
522+
6
523+
]
524+
},
525+
"incellVersionList": [
526+
{
527+
"str": "1.2.3",
528+
"val": "1002003",
529+
"major": 1,
530+
"minor": 2,
531+
"patch": 3,
532+
"others": []
533+
},
534+
{
535+
"str": "4.5.6",
536+
"val": "4005006",
537+
"major": 4,
538+
"minor": 5,
539+
"patch": 6,
540+
"others": []
541+
}
542+
],
543+
"horizontalVersionList": [
544+
{
545+
"str": "1.0.0",
546+
"val": "1000000",
547+
"major": 1,
548+
"minor": 0,
549+
"patch": 0,
550+
"others": []
551+
},
552+
{
553+
"str": "1.2.3",
554+
"val": "1002003",
555+
"major": 1,
556+
"minor": 2,
557+
"patch": 3,
558+
"others": []
559+
},
560+
{
561+
"str": "2.0.3",
562+
"val": "2000003",
563+
"major": 2,
564+
"minor": 0,
565+
"patch": 3,
566+
"others": []
567+
}
568+
]
569+
}
570+
```
571+
572+
{{< /details >}}

0 commit comments

Comments
 (0)