README.adoc 4.08 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
7
name, in 71 https://en.wiktionary.org/wiki/Appendix:Months_of_the_year[languages].
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
22

```html
Siltaar's avatar
Siltaar committed
23
<script src="month_nb.js" type="text/javascript"></script>
Siltaar's avatar
Siltaar committed
24
<script type="text/javascript">
Siltaar's avatar
doc    
Siltaar committed
25
26
month_nb_json = {};
fetch("month_nb.json").then(r => r.json()).then(json => month_nb_json = json);
Siltaar's avatar
Siltaar committed
27
</script>
Siltaar's avatar
Siltaar committed
28
```
Siltaar's avatar
Siltaar committed
29

Siltaar's avatar
Siltaar committed
30
A working expliciter approach :
Siltaar's avatar
Siltaar committed
31
32
33
34
35
36
37
38
39

```html
<script src="month_nb.js" type="text/javascript"></script>
<script type="text/javascript">
fetch("month_nb.json").then(r => r.json()).then(month_nb_json => {
month_nb('août', month_nb_json);
});
</script>
```
Siltaar's avatar
Siltaar committed
40

Siltaar's avatar
Siltaar committed
41
Modern method, using `async`/`await` :
Siltaar's avatar
Siltaar committed
42
43
44
45
46

```javascript
(async () => {
	"use strict"
	let month_nb_json = await fetch("js/month_nb/month_nb.json")
Siltaar's avatar
Siltaar committed
47
	month_nb_json = await month_nb_json.json()
Siltaar's avatar
Siltaar committed
48
49
50
51
	month_nb('août')
})()
```

Siltaar's avatar
Siltaar committed
52
53
54
== Architecture

`month_nb.js` only contains a loop going through a JSON tree data structure
55
56
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
57
`month_nb.json` file.
Siltaar's avatar
Siltaar committed
58

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

63
An experimental *Python implementation* is provided with currently 53
64
working languages (only).
65

Siltaar's avatar
Siltaar committed
66

Siltaar's avatar
Siltaar committed
67
== Supported languages
Siltaar's avatar
Siltaar committed
68

69
`month_nb.js` works for 71 languages (including most living written languages),
Siltaar's avatar
merge    
Siltaar committed
70
and it would be 73 if it was not for those two ambiguities :
Siltaar's avatar
Siltaar committed
71
72
but there two ambiguities :

Siltaar's avatar
Siltaar committed
73
74
75
- 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

76
77
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
78

Siltaar's avatar
Siltaar committed
79
80
81

== Character encoding considerations

Siltaar's avatar
Siltaar committed
82
Currently the `month_nb.json` tree data structure is filled with UTF-8
Siltaar's avatar
Siltaar committed
83
84
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
85
86
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
87
88

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

Siltaar's avatar
Siltaar committed
92

93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
== 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
110
111
== Running tests

Siltaar's avatar
Siltaar committed
112
To test `month_nb.js` against the language definition file, run :
Siltaar's avatar
Siltaar committed
113
114

```sh
115
$ node test_month_nb.js
Siltaar's avatar
Siltaar committed
116
117
```

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

121
It will display various informations about the working and broken languages.
Siltaar's avatar
Siltaar committed
122
123


Siltaar's avatar
Siltaar committed
124
== Who uses it ?
Siltaar's avatar
Siltaar committed
125
126
127
128

`month_nb` have been initially developped for https://www.meta-press.es/[Meta-Press.es].


Siltaar's avatar
Siltaar committed
129
130
== TODO

Siltaar's avatar
Siltaar committed
131
132
=== Update according to Wiktionary evolution

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

Siltaar's avatar
Siltaar committed
138

Siltaar's avatar
Siltaar committed
139
140
141
=== Node packaging

Make a NodeJS package out of it.