README.adoc 3.84 KB
Newer Older
Siltaar's avatar
Siltaar committed
1
2
3
4
= month_nb : get the number of a month from its name
:experimental: yes
:toc:
:toc-title: Index
Siltaar's avatar
Siltaar committed
5
6

`month_nb.js` is a small utility which knows the corresponding number of a month
Siltaar's avatar
Siltaar committed
7
name, no matter which language among the 69 supported https://en.wiktionary.org/wiki/Appendix:Months_of_the_year[ones].
Siltaar's avatar
Siltaar committed
8

Siltaar's avatar
Siltaar committed
9
== Usage
Siltaar's avatar
Siltaar committed
10
11

```javascript
Siltaar's avatar
Siltaar committed
12
>> month_nb('août');
Siltaar's avatar
Siltaar committed
13
14
15
8
```

Siltaar's avatar
Siltaar committed
16
17
18
The function returns a month number from a given litteral case-insensitive month
name or abbreviation. It returns `undefined` if no corresponding number is found.

Siltaar's avatar
Siltaar committed
19
20
To use it, include the `month_nb.js` file and define a `month_nb_json` variable
containing the `month_nb.json` instantiated object :
Siltaar's avatar
Siltaar committed
21

Siltaar's avatar
Siltaar committed
22
23
24
25
```javascript
(async () => {
	"use strict"
	let month_nb_json = await fetch("js/month_nb/month_nb.json")
Siltaar's avatar
Siltaar committed
26
	month_nb_json = await month_nb_json.json()
27
28
	month_nb('août') <1>
	month_nb('août', month_nb_json) <1>
Siltaar's avatar
Siltaar committed
29
30
})()
```
31
32
<1> both are equivalent

Siltaar's avatar
Siltaar committed
33

Siltaar's avatar
Siltaar committed
34
35
36
== Architecture

`month_nb.js` only contains a loop going through a JSON tree data structure
37
38
made of regular expression strings as keys (for the nodes), sub-objects for
branchs and numbers for leafs. The data structure itself resides in the
Siltaar's avatar
doc    
Siltaar committed
39
`month_nb.json` file.
Siltaar's avatar
Siltaar committed
40

Siltaar's avatar
Siltaar committed
41
This clear separation between code and data is wanted to ease the re-use of
Siltaar's avatar
doc    
Siltaar committed
42
`month_nb.json` data structure with other languages, to reimplement a
Siltaar's avatar
Siltaar committed
43
`month_nb` feature.
Siltaar's avatar
Siltaar committed
44

45
An experimental *Python implementation* is provided with currently 53
46
working languages (only).
47

Siltaar's avatar
Siltaar committed
48

Siltaar's avatar
Siltaar committed
49
== Supported languages
Siltaar's avatar
Siltaar committed
50

Christopher's avatar
Christopher committed
51
52
`month_nb.js` works for 72 languages (including most living written languages),
and it would be 74 if it was not for those two ambiguities :
Siltaar's avatar
Siltaar committed
53

Siltaar's avatar
Siltaar committed
54
55
56
- Croatian : _listopad_ fails to return 10 as it is 11 in Czech and Polish
- Slovenian : _prosinec_ fails to return 1, as it is 12 in Croatian and Czech

57
58
Support for those languages has been postponed : Cherokee, Hawaiian, Lezgi,
Navajo, Ojibwe, Old English, Old High German, Old Norse, Sinhalese.
Siltaar's avatar
Siltaar committed
59

Siltaar's avatar
Siltaar committed
60
61
62

== Character encoding considerations

Siltaar's avatar
Siltaar committed
63
Currently the `month_nb.json` tree data structure is filled with UTF-8
Siltaar's avatar
Siltaar committed
64
65
characters (like "é"). It's easy to read but can prove complicated to edit,
specifically with right-to-left characters mixed with left-to-right ones, or
Siltaar's avatar
Siltaar committed
66
67
with aggregating characters (combining in one symbol) separated by copy/pastes
and than end up aggregating with a closing parenthesis or a quote.
Siltaar's avatar
Siltaar committed
68
69

Converting every UTF-8 character to the `\u00E9` form might help other
Siltaar's avatar
Siltaar committed
70
71
programming languages to re-use it (but would complicate the maintenance of
the tree).
Siltaar's avatar
Siltaar committed
72

Siltaar's avatar
Siltaar committed
73

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
== Update month definitions

To update the definitions, download a new copy of `Appendix:Months_of_the_year`
and run the `phantomjs_gen_def.js` script :

```sh
$ cd month_definitions
$ wget https://en.wiktionary.org/wiki/Appendix:Months_of_the_year
$ phantomjs phantomjs_gen_def.js <1>
```
<1> `phantomjs` is from the eponymous Debian package.

Then clean the `.json` file from error logging of phantomjs, and add the
"numeric" first line (that you can copy from the previous `.json` definition
file).


Siltaar's avatar
Siltaar committed
91
92
== Running tests

Siltaar's avatar
Siltaar committed
93
To test `month_nb.js` against the language definition file, run :
Siltaar's avatar
Siltaar committed
94
95

```sh
96
$ node --experimental-json-modules test_month_nb.mjs
Siltaar's avatar
Siltaar committed
97
98
```

99
100
The `node` v15.8.0 command comes from the `nodejs` package on Arch-based
distributions such as Artix Linux.
Siltaar's avatar
Siltaar committed
101

102
It will display various informations about the working and broken languages.
Siltaar's avatar
Siltaar committed
103
104


Siltaar's avatar
Siltaar committed
105
== Who uses it ?
Siltaar's avatar
Siltaar committed
106

Siltaar's avatar
typo    
Siltaar committed
107
`month_nb` was initially developped for https://www.meta-press.es/[Meta-Press.es].
Siltaar's avatar
Siltaar committed
108

Siltaar's avatar
Siltaar committed
109
110
== TODO

Siltaar's avatar
Siltaar committed
111
112
=== Update according to Wiktionary evolution

Siltaar's avatar
Siltaar committed
113
114
The Wiktionary snapshot page of
https://en.wiktionary.org/wiki/Appendix:Months_of_the_year[Appendix:Months_of_the_year]
115
used is from 2019-09-18. 14 languages were added since the 2013 version of the
116
initial release of `month_nb`, they are not all supported yet.
Siltaar's avatar
Siltaar committed
117

Siltaar's avatar
Siltaar committed
118

Siltaar's avatar
Siltaar committed
119
120
121
=== Node packaging

Make a NodeJS package out of it.
122
123
124

== Support

Siltaar's avatar
Siltaar committed
125
Please consider supporting this work via the https://www.meta-press.es/pages/a_propos.html#_you_can_support_this_work[Meta-Press.es] project.