1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<!--
SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
SPDX-License-Identifier: BSD-2-Clause
-->
# media-type-version - extract the format version from a media type string
\[[Home][ringlet-home] | [GitLab][gitlab] | [PyPI][pypi] | [crates.io][crates-io] | [Python API][ringlet-api-python] | [ReadTheDocs][readthedocs]\]
## Overview
The `media-type-version` library is designed to be used as the first step in
parsing structured data, e.g. configuration files, serialized classes, etc.
The caller extracts the media type string (e.g. a JSON `"mediaType": "..."` key) and
passes it in for parsing.
The caller then decides what to do with the extracted version information -
is this version supported, what fields are expected to be there, should any
extraneous fields produce errors, and so on.
The media type string is expected to be in a `<prefix>.vX.Y<suffix>` format, with
a fixed prefix and suffix.
The prefix will usually be a vendor-specific media type.
The version part consists of two unsigned integer numbers.
The suffix, if used, may correspond to the file format.
A sample media type string identifying a TOML configuration file for
a text-processing program could be
`vnd.ringlet.textproc.publync.config/publync.v0.2+toml`
## The library
The `media-type-version` library provides a single function, `extract()`, that
parses a media type string, strips the specified prefix and suffix, and looks for
a `.vX.Y` version string left.
It then returns the (`X`, `Y`) version tuple.
Python example:
``` py
mtv_cfg: Final = media_type_version.Config(
log=logging.Logger(...),
prefix="vnd.acme/thing",
suffix="+toml",
)
ver_major, ver_minor = media_type_version.extract(mtv_cfg, "vnd.acme/thing.v3.12+toml")
```
Rust example:
``` rust
use media_type_version::{Config as MTVConfig, Error as MTVError, Version as MTVersion};
let cfg = MTVConfig::builder()
.prefix("vnd.acme/thing")
.suffix("+toml")
.build()
.map_err(MTVError::into_owned_error)?;
assert_eq!(
media_type_version::extract(&cfg, "vnd.acme/thing.v3.12+toml").as_tuple(),
(3, 12)
);
```
## The mtv-extract tool
The `media-type-version` library also provides a command-line tool
called `mtv-extract` that can be used to extract format versions from
various sources.
The `mtv-extract` tool supports the following top-level command-line options:
- `-q`: quiet operation; only display warnings and error messages
- `-v`: verbose operation; display diagnostic output
### The "features" subcommand
The `features` subcommand will display a single line of output starting with
the prefix "Features: " and containing a space-separated list of "name=version" pairs.
This output format is intended to be machine-readable, so that other programs may
examine it using e.g. [the feature-check library and command-line tool][feature-check].
### The "lines" subcommand
The `lines` subcommand will read a series of strings from the specified files,
parse them as media-type strings with the specified prefix and suffix, and
output a line consisting of two tab-separated numbers for each parsed string:
``` sh
$ { echo vnd.acme/thing.v3.47; echo vnd.acme/thing.v42.616; } | mtv-extract -q lines -p vnd.acme/thing -- -
3 47
42 616
$
```
The `lines` subcommand supports the following command-line options:
- `-p prefix` (required): the prefix to strip from the media type string
- `-s suffix`: the optional suffix to strip from the media type string
## Supported features
The `features` subcommand of the `mtv-extract` tool, as well as the `FEATURES`
constant in both the Python and Rust implementations, may currently list
the following features:
### media-type-version
The version of the `media-type-version` library itself.
### cmd-features
#### 0.1
The command-line tool supports the `features` subcommand with the output format
described above.
### cmd-lines
#### 0.1
The command-line tool supports the `lines` subcommand with the mandatory prefix
option and the optional suffix one.
It requires at least one file name to read from, and it supports `-` for reading from
the standard input stream.
### extract
#### 0.1
The library supports the `extract()` function.
It accepts a `Config` parameter containing the prefix and suffix strings, and
a string parameter to parse.
The string must contain a ".vX.Y" version specification between the prefix and the suffix.
## Contact
The `media-type-version` library was written by [Peter Pentchev][roam].
It is developed in [a GitLab repository][gitlab].
This documentation is hosted at [Ringlet][ringlet-home] with a copy at [ReadTheDocs][readthedocs].
[roam]: mailto:roam@ringlet.net "Peter Pentchev"
[crates-io]: https://crates.io/crates/media-type-version "The media-type-version Rust crates.io page"
[feature-check]: https://devel.ringlet.net/misc/feature-check/ "The feature-check library and command-line tool"
[gitlab]: https://gitlab.com/ppentchev/media-type-version "The media-type-version GitLab repository"
[pypi]: https://pypi.org/project/media-type-version/ "The media-type-version Python Package Index page"
[readthedocs]: https://media-type-version.readthedocs.io/ "The media-type-version ReadTheDocs page"
[ringlet-api-python]: https://devel.ringlet.net/devel/media-type-version/api/python/ "The Python API reference"
[ringlet-home]: https://devel.ringlet.net/devel/media-type-version/ "The Ringlet media-type-version homepage"
|
