Skip to content

Commit ea5b12a

Browse files
SalathielGeneseSalathielGenese
committedNov 1, 2022
feat: update instructions for maven 4
1 parent b1f26f3 commit ea5b12a

File tree

4 files changed

+220
-165
lines changed

4 files changed

+220
-165
lines changed
 

‎README.api.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# API
2+
3+
Using [`httpie`](https://httpie.io/):
4+
```shell
5+
# You can also pass as many HTML content as you want
6+
# Response will be of 'application/json' content type
7+
http -vf :8080/convert \
8+
extension='.js' \
9+
contents[]='<hr/>' \
10+
contents[]='<button disabled>click me, please :sob:</button>'
11+
12+
HTTP/1.1 200
13+
Content-Type: application/json
14+
15+
{
16+
"status": "SUCCESS"
17+
"content": [
18+
{
19+
"content": "const targetElement_000 = document.querySelector(`:root > body`);\r\n\r\n\r\nconst hr_000 = document.createElement('hr');\r\ntargetElement_000.appendChild(hr_000);\r\n",
20+
"filename": "inline.0.js"
21+
},
22+
{
23+
"content": "const targetElement_001 = document.querySelector(`:root > body`);\r\n\r\n\r\nconst button_000 = document.createElement('button');\r\nbutton_000.setAttribute(`disabled`, `true`);\r\nconst text_000 = document.createTextNode(`click me, please :sob:`);\r\nbutton_000.appendChild(text_000);\r\ntargetElement_001.appendChild(button_000);\r\n",
24+
"filename": "inline.1.js"
25+
}
26+
]
27+
}
28+
```
29+
30+
Or, give the following two files contents:
31+
> ```json
32+
> { "extension": ".js" } // ./multipart-options.json
33+
> ```
34+
>
35+
> ```html
36+
> <!DOCTYPE html>
37+
> <!-- ./sample.html -->
38+
> <html>
39+
> <head>
40+
> ...
41+
> ...
42+
> ...
43+
> ```
44+
45+
```shell
46+
# You can call the API with multiple **files** and at most one **options**
47+
# Response will be of 'multipart/form-data' content type
48+
http -vf :8080/convert/files \
49+
'files@./sample.html;type=multipart/form-data' \
50+
'options@multipart-options.json;type=application/json'
51+
52+
HTTP/1.1 200
53+
Content-Type: multipart/form-data;boundary=3N0wqEqnb7AC3WD8M1cYYG-vLfHDND_JdE90
54+
55+
--3N0wqEqnb7AC3WD8M1cYYG-vLfHDND_JdE90
56+
Content-Disposition: form-data; name="0.sample.html.js"
57+
Content-Type: application/octet-stream
58+
Content-Length: 4156
59+
60+
const targetElement_000 = document.querySelector(`:root > body`);
61+
[... truncated for brievity]
62+
```
63+
64+
---
65+
66+
After starting the `jsgenerator-api` as described in the [README.md](./README.md), you can read:
67+
68+
+ OpenAPI spec. at: [http://localhost:8080/openapi.yaml](http://localhost:8080/openapi.yaml)
69+
+ OpenAPI UI at: [http://localhost:8080](http://localhost:8080)
70+
71+
Two endpoints are exposed:
72+
+ `POST /convert`
73+
+ `POST /convert/files`
74+
75+
Both accept options as follow:
76+
```json
77+
{
78+
"targetElementSelector": ":root > body",
79+
"pattern": "inline-filename-pattern",
80+
"variableNameStrategy": "TYPE_BASED",
81+
"variableDeclaration": "LET",
82+
"extension": ".extension",
83+
"contents": [
84+
"string"
85+
]
86+
}
87+
```
88+
> **NOTE:** The `"content"` field is mandatory for `POST /convert` and forbidden for `POST /convert/files`

‎README.cli.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Command Line Interface
2+
3+
```shell
4+
let targetElement_000 = document.querySelector(`:root > body`);
5+
6+
7+
let div_000 = document.createElement('div');
8+
let text_000 = document.createTextNode(`I am a `);
9+
div_000.appendChild(text_000);
10+
11+
let strong_000 = document.createElement('strong');
12+
let text_001 = document.createTextNode(`tea pot`);
13+
strong_000.appendChild(text_001);
14+
div_000.appendChild(strong_000);
15+
targetElement_000.appendChild(div_000);
16+
```
17+
18+
---
19+
20+
`jsgenerator` has several options that can be used in a console here is an example of use below
21+
22+
```text
23+
Usage: jsgenerator [-htV] [-e=<extension>] [--inline-pattern=<inlinePattern>]
24+
[-k=<variableDeclaration>] [--path-pattern=<pathPattern>]
25+
[-s=<targetElementSelector>]
26+
[--stdin-pattern=<stdinPattern>]
27+
[--variable-name-generation-strategy=<builtinVariableNameStra
28+
tegy>] [-i=<inlineContents>...]... [<paths>...]
29+
Translating files, stdin or inline from HTML to JS
30+
[<paths>...] file paths to translate content, parsed as HTML
31+
-e, --ext=<extension> output files' extension
32+
-h, --help Show this help message and exit.
33+
-i, --inline=<inlineContents>...
34+
args as HTML content, not files
35+
--inline-pattern=<inlinePattern>
36+
Pattern for inline output filename
37+
-k, --keyword=<variableDeclaration>
38+
variable declaration keyword
39+
--path-pattern=<pathPattern>
40+
pattern for path-based output filenames
41+
-s, --selector=<targetElementSelector>
42+
Target element selector
43+
--stdin-pattern=<stdinPattern>
44+
pattern for stdin output filenames
45+
-t, --tty output to stdin, not files
46+
-V, --version Print version information and exit.
47+
--variable-name-generation-strategy=<builtinVariableNameStrategy>
48+
Variable names generation strategy
49+
```

‎README.md

+83-165
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@
99
# Table of Contents
1010
- [About](#about)
1111
- [Getting Started](#getting-started)
12-
- [Clients](#clients)
13-
- [Stack](#stack)
12+
- [Requirements](#requirements)
13+
- [Modules](#modules)
14+
- [Architecture](#architecture)
15+
- [Compiling](#compiling)
16+
- [Running](#running)
17+
- [Packaging](#packaging)
1418
- [Contribute](#contribute)
1519

1620
![From Html to Js through Java](illustrations/html_java_js.png)
@@ -36,197 +40,111 @@ We would like to give credit to [jsoup](https://jsoup.org/) / [jsoup GitHub Repo
3640

3741
![How does it work in a nutshell ?](illustrations/jsgenerator_intro.png)
3842

39-
## Getting Started
43+
# Getting Started
4044

41-
**CLI**
45+
## Requirements
4246

43-
jsgenerator has several options that can be used in a console here is an example of use below
44-
45-
```shell
46-
$ jsgenerator --tty --inline '<div>I am a <strong>tea pot</strong></div>'
47-
48-
let div_000 = document.createElement('div');
49-
let text_000 = document.createTextNode(`I am a `);
50-
div_000.appendChild(text_000);
47+
+ JDK 17
48+
> **Because we use modern JavaFX**
49+
>
50+
> **NOTE:** For native build (CLI, for eg.), we use GraalVM with JDK 17.
51+
>
52+
> Recent versions of GraalVM are not bundling `native-image` CLI by default.
53+
> We are required to install is manually, by running:
54+
> ```shell
55+
> # Where `gu` is an executable bundled with GraalVM
56+
> gu install native-image
57+
> ```
58+
+ Maven 4
59+
> Because of its unique features over maven 3:
60+
> namely, multi module dependency resolution under common parent, when running a maven goal only on some child
61+
+ Spring 5.3.22
62+
> A framework to bootstrap dependency injection and inversion of control for our modules
63+
+ Spring Boot 2.7.3
64+
> Leverage convention over configuration and autoconfiguration discovery to enforce consistent a behaviour
65+
> throughout our frontends
5166
52-
let strong_000 = document.createElement('strong');
53-
let text_001 = document.createTextNode(`tea pot`);
54-
strong_000.appendChild(text_001);
55-
div_000.appendChild(strong_000);
56-
document.appendChild(div_000);
57-
```
67+
## Modules
5868
59-
## Clients
69+
The project takes advantage of Maven multimodule capabilities to enforce a consistent versioning and releases and,
70+
the specific Maven 4 features to deliver a seamless developer experience.
6071
61-
**CLI**
6272
```text
63-
Usage: jsgenerator [-htV] [-e=<extension>] [--inline-pattern=<inlinePattern>]
64-
[-k=<variableDeclaration>] [--path-pattern=<pathPattern>]
65-
[-s=<targetElementSelector>]
66-
[--stdin-pattern=<stdinPattern>]
67-
[--variable-name-generation-strategy=<builtinVariableNameStra
68-
tegy>] [-i=<inlineContents>...]... [<paths>...]
69-
Translating files, stdin or inline from HTML to JS
70-
[<paths>...] file paths to translate content, parsed as HTML
71-
-e, --ext=<extension> output files' extension
72-
-h, --help Show this help message and exit.
73-
-i, --inline=<inlineContents>...
74-
args as HTML content, not files
75-
--inline-pattern=<inlinePattern>
76-
Pattern for inline output filename
77-
-k, --keyword=<variableDeclaration>
78-
variable declaration keyword
79-
--path-pattern=<pathPattern>
80-
pattern for path-based output filenames
81-
-s, --selector=<targetElementSelector>
82-
Target element selector
83-
--stdin-pattern=<stdinPattern>
84-
pattern for stdin output filenames
85-
-t, --tty output to stdin, not files
86-
-V, --version Print version information and exit.
87-
--variable-name-generation-strategy=<builtinVariableNameStrategy>
88-
Variable names generation strategy
73+
js-generator:
74+
|- jsgenerator-api
75+
|- jsgenerator-web
76+
|- jsgenerator-cli
77+
\- jsgenerator-desktop
8978
```
9079
91-
**API**
80+
## Architecture
9281

93-
Start it with:
94-
```shell
95-
java -jar jsgenerator-api/target/jsgenerator-api-0.0.1-SNAPSHOT.jar
96-
```
82+
| THE MODULE | ITS CONTENT && DEPENDENCIES | PACKAGING |
83+
|------------------------------------|-------------------------------------|-----------|
84+
| js-generator | Bill of Material, global properties | POM |
85+
| jsgenerator-core | Core API, Spring Boot auto-conf | JAR |
86+
| jsgenerator-slim-api | jsgenerator-core, spring-web | JAR |
87+
| jsgenerator-slim-cli | jsgenerator-core, picocli | JAR |
88+
| [jsgenerator-api](./README.api.md) | jsgenerator-slim-api | FAT JAR |
89+
| [jsgenerator-cli](./README.cli.md) | jsgenerator-slim-cli | FAT JAR |
9790

98-
Visit OpenAPI spec. at: [http://localhost:8080/openapi.yaml](http://localhost:8080/openapi.yaml)
99-
100-
Visit OpenAPI UI at: [http://localhost:8080](http://localhost:8080)
101-
102-
> Two endpoints are exposed:
103-
> + `POST /convert`
104-
> + `POST /convert/files`
105-
>
106-
> Both accept options as follow:
107-
> ```json
108-
> {
109-
> "targetElementSelector": ":root > body",
110-
> "pattern": "inline-filename-pattern",
111-
> "variableNameStrategy": "TYPE_BASED",
112-
> "variableDeclaration": "LET",
113-
> "extension": ".extension",
114-
> "contents": [
115-
> "string"
116-
> ]
117-
> }
118-
> ```
119-
> **NOTE:** The `content` field in options is mandatory for `POST /convert` and forbidden for `POST /convert/files`
120-
121-
Here follow some example with [`httpie`](https://httpie.io/)
122-
> ```json
123-
> { "extension": ".js" } // ./multipart-options.json
124-
> ```
125-
>
126-
> ```html
127-
> <!DOCTYPE html>
128-
> <!-- ./sample.html -->
129-
> <html>
130-
> <head>
131-
> ...
132-
> ...
133-
> ...
134-
> ```
91+
> **NOTE:** FAT JAR packaged modules are mere wrappers around slim modules. The separation is important because then,
92+
> the test modules can use slim JARs as dependencies, unlike FAT JARs. This has to do with how "normal" vs. FAT JARs
93+
> are laid out.
13594
136-
```shell
137-
# You can call the API with multiple **files** and at most one **options**
138-
# Response will be of 'multipart/form-data' content type
139-
http -vf :8080/convert/files \
140-
'files@./sample.html;type=multipart/form-data' \
141-
'options@multipart-options.json;type=application/json'
142-
143-
HTTP/1.1 200
144-
Content-Type: multipart/form-data;boundary=3N0wqEqnb7AC3WD8M1cYYG-vLfHDND_JdE90
145-
146-
--3N0wqEqnb7AC3WD8M1cYYG-vLfHDND_JdE90
147-
Content-Disposition: form-data; name="0.sample.html.js"
148-
Content-Type: application/octet-stream
149-
Content-Length: 4156
150-
151-
const targetElement_000 = document.querySelector(`:root > body`);
152-
[... truncated for brievity]
153-
```
154-
```shell
155-
# You can also pass as many HTML content as you want
156-
# Response will be of 'application/json' content type
157-
http -vf :8080/convert \
158-
extension='.js' \
159-
contents[]='<hr/>' \
160-
contents[]='<button disabled>click me, please :sob:</button>'
161-
162-
HTTP/1.1 200
163-
Content-Type: application/json
164-
165-
{
166-
"status": "SUCCESS"
167-
"content": [
168-
{
169-
"content": "const targetElement_000 = document.querySelector(`:root > body`);\r\n\r\n\r\nconst hr_000 = document.createElement('hr');\r\ntargetElement_000.appendChild(hr_000);\r\n",
170-
"filename": "inline.0.js"
171-
},
172-
{
173-
"content": "const targetElement_001 = document.querySelector(`:root > body`);\r\n\r\n\r\nconst button_000 = document.createElement('button');\r\nbutton_000.setAttribute(`disabled`, `true`);\r\nconst text_000 = document.createTextNode(`click me, please :sob:`);\r\nbutton_000.appendChild(text_000);\r\ntargetElement_001.appendChild(button_000);\r\n",
174-
"filename": "inline.1.js"
175-
}
176-
]
177-
}
178-
```
95+
## Compiling
17996

180-
**WEB**
97+
```shell
98+
# Clone the git repository
99+
git clone git@github.com:osscameroon/js-generator.git
181100

182-
> ***TODO:** Not yet implemented.*
101+
# Move at the project root
102+
cd js-generator
183103

184-
**DESKTOP**
104+
# Compile & test all the modules
105+
mvn clean test
106+
```
185107

186-
> ***TODO:** Not yet implemented.*
108+
## Running
187109

188-
**CODE API**
110+
> Compiling the whole project before running child modules is advised.
111+
>
112+
> To set up you IDE runner, follow this IntelliJ example:
113+
>
114+
> ![](illustrations/intellij-maven-runner-configuration.png)
189115
190-
> ***TODO:** Not yet implemented.*
191-
> See [Wiki](https://github.com/osscameroon/js-generator/wiki).
116+
API Server
117+
```shell
118+
# After starting the server, visit http://localhost:8080
119+
mvn --projects jsgenerator-api spring-boot:run
120+
```
192121

193-
# Stack
122+
Command Line Interface (CLI)
123+
```shell
124+
# After reading the help, play out with different CLI options
125+
mvn --projects jsgenerator-cli spring-boot:run -Dspring-boot.run.arguments=--help
194126

195-
+ JDK 17
196-
> NOTE: For native build (CLI, for eg.), we use GraalVM with JDK 17.
197-
>
198-
> Recent versions of GraalVM are not bundling `native-image` CLI by default.
199-
> We are required to install is manually, by running:
200-
> ```shell
201-
> # Where `gu` is an executable bundled with GraalVM
202-
> gu install native-image
203-
> ```
204-
+ Maven 3
205-
+ Spring 5.3.22
206-
+ Spring Boot 2.7.3
127+
# For example:
128+
mvn --projects :jsgenerator-cli spring-boot:run \
129+
-Dspring-boot.run.arguments="--tty --inline '<div>I am a <strong>tea pot</strong></div>'"
130+
```
207131

208-
# Contribute
132+
## Packaging
209133

210134
```shell
211-
# 1. Clone
212-
git clone git@github.com:osscameroon/js-generator.git
213-
214-
# 2. Move to root directory
215-
cd js-generator
216-
217-
# 3. Tests & Build
135+
# Will compile all the modules into JAR (or FAT JAR - see the table above)
218136
mvn clean package
219137

220-
# 4. Build Native CLI (Requires GraalVM JDK 17, and a Linux-friendly shell, like Cmder)
221-
./cli-build.sh # if provided, first argument will be the file name (useful for version tagging)
222-
223-
# 5. Browse through code
224-
# 6. Run CLI with --help and play with it
225-
# 7. Fork the project, build, test, open a pull request
138+
# Additionally, build CLI into native executable (require GraalVM - see requirements above)
139+
./cli-build.sh
226140
```
227141

142+
# Contribute
143+
228144
All your contributions are welcome!
145+
229146
Do not hesitate to open an issue on this repository and/or create a pull request (PR).
147+
230148
In order to create a PR, just fork first.
231149

232150
**[We started from the bottom 4 years ago](https://github.com/opensourcecameroon/jsGenerator), now we are here, we believe we will continue moving forward together 😊.**

‎illustrations/intellij-maven-runner-configuration.png

58.7 KB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.