diff --git a/README.md b/README.md index 8b5fda0..6b865fb 100644 --- a/README.md +++ b/README.md @@ -22,50 +22,57 @@ COGNAC generate 4 files: ### cognac_gen.sh -cognac_gen.sh is the script that generate evrything, it's a shellscript, that call sub-shellscript, +cognac_gen.sh is the script that generate everything, it's a shell script, that call sub-shell script, and a few C binaries that are compiled by the Makefile. (see bin/) -It take 3 arguments, a source file, a destination file, and a language. -The language is here because some keyword can be interpreted diferently depending of the wanted language. +It takes 3 arguments, a source file, a destination file, and a language. +The language is here because some keyword can be interpreted differently depending on the wanted language. -it use a file call osc-api.json which is the openapi represent as json. -For Outscale api, we take the yaml source, and convert them to json using yq. +It uses a file call osc-api.json which is the OpenAPI represent as json. +For Outscale API, we take the yaml source, and convert it to json using yq. -When generated API Call, COGNAC assume that the openapi file have some componant named CallRequest, -So if the api have a call named `CreatePony`, it should have a `#/components/schemas/CreatePonyRequest`. +When generated API Call, COGNAC assume that the OpenAPI file have some components named CallRequest, +So if the API have a call named `CreatePony`, it should have a `#/components/schemas/CreatePonyRequest`. -*Note: 2 versions of yq exist, one in python and one in go, default yq depend of the distribution. On Arch base the python is the default one, on debian-base it's the go, cognac handle both, but in order to use the go version you need to pass `--yq-go` to `./configure`* +*Note: 2 versions of yq exist, one in python and one in go, default yq depend on the distribution. On Arch base the python is the default one, on Debian-base it's the go, cognac handle both, but in order to use the go version you need to pass `--yq-go` to `./configure`* ### Example with a new api. -let's say you have an api, that is not outscale api, and want to generate a cli, from it. -you have only an url with a yaml file. let's say `https://ponyapi.yolo` +You have an API, that is not outscale api, and want to generate a CLI, from it. +You have only an UNL with a yaml file, let's say `https://ponyapi.yolo` The API Request componant are not call "XRequest" but "XInput". -the irst step is to configure the Makefile to handle the cli name `pony-cli`, and tell Makefile how to get the api, and change the `Input` to `request`. +The first step is to configure the Makefile to handle the CLI name `pony-cli`, and tell Makefile how to get the API, and change the `Input` to `request`. -to do so, you first call `./configure --cli-name=pony-cli --api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json'` +To do so, you first call +```bash +./configure --cli-name=pony-cli --api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json' +``` `-cli-name=pony-cli` set the generated binary name to `pony-cli` -`--api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json'` -is the script that will be use to get the api-file. -it first get the api in yaml using `curl -s https://ponyapi.yolo` -convert it to json using `| yq $(YQ_ARG)`, Note the usage of `$(YQ_ARG)`, so the configure can handle go version of yq. -Then rename all componant named `XInput` into `XRequest`. +```bash +--api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json' +``` +Is the script that will be used to get the api-file. -doing so you can now use the Makefile, but you should also check `./configure --help` which contain some useful options. -`--wget-json-search` and `--compile-json-c` are 2 useful otpions as json-search is not easy to install, and a recent version of `json-c` is require if you want to support color. -Now you can simple call `make` which will generate everyfile, and compile the cli for you. -It will also create a C sdk, which will be made of 2 files: `osc-sdk.c` and `osc-sdk.h`. +First, it retrieves the API in yaml using `curl -s https://ponyapi.yolo` +Then convert it to json using `| yq $(YQ_ARG)`, *Note the usage of `$(YQ_ARG)`, so ./configure can handle go version of yq* +Finally, rename all component named `XInput` into `XRequest`. -If you want more controll on the generation, you can call make rules yourself, so `make main.c osc_sdk.c osc_sdk.h pony-cli-completion.bash pony-cli` +Doing so you can now use the Makefile, but you should also check `./configure --help` which contain some useful options. +`--wget-json-search` and `--compile-json-c` are 2 useful options as json-search is not easy to install, and a recent version of `json-c` is required if you want to support colour. + +Now you can simply call `make` which will generate every file, and compile the CLI for you. +It will also create a C SDK, which will be made of 2 files: `osc-sdk.c` and `osc-sdk.h`. + +If you want more control on the generation, you can call make rules yourself, so `make main.c osc_sdk.c osc_sdk.h pony-cli-completion.bash pony-cli` ## Dependency -Non exaustive list: +Non-exhaustive list: - GNU sed - bash - jq @@ -80,7 +87,7 @@ Non exaustive list: Open Pull Requests and Issues are welcome. If you want to add binary in bin/ please try to make it easy to compile. -That mean don't add dependancies that are not alerady require by a cli. +That mean, don't add dependencies that are not already require by a CLI. ## Do You Want To Know More? @@ -88,15 +95,15 @@ That mean don't add dependancies that are not alerady require by a cli. ### Unix philosophy, and COGNAC Paradigms. -Most peoples have hear the sentence "Do One Thing and Do It Well", and hear that's how Unix is and how Unix should be. +Most peoples have hear the sentence "Do One Thing and Do It Well", and heard that's how Unix is and how Unix should be. -I personally don't know how much this true nor a good idea, and like most peoples I use to pretend to understand this, but did not, I don't know if I got it now, but I have a far better understand of what it use to. +I personally don't know how much this true nor a good idea, and like most peoples I use to pretend to understand this, but did not, I don't know if I got it now, but I have a far better understand of what it uses to. -How so ? you didn't ask. By reading source from some unix OS. -And when I read a complet [shell](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s1/sh.c), the whole source of [ls](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s6/ls.c), or a fully running [cat](https://github.com/klange/toaruos/blob/master/apps/cat.c), I got hit by the reallisation that most of thoses programes take less line of code, that I would need to write half of an interface in any OOP. +How so ? You didn't ask. By reading source from some Unix OS. +When I read a complete [shell](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s1/sh.c), the whole source of [ls](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s6/ls.c), or a fully running [cat](https://github.com/klange/toaruos/blob/master/apps/cat.c), I got hit by the realisation that most of those programmes take less line of code, that I would need to write half of an object interface in any language. -But it kind of made sense, program was made to interact together, and where we tend to see a program as a whole project, a program on unix use to do only one thing, and do it well. -You don't need modularity if writing a whole program annew is faster than creating an interface, and as program are made to interact together, it's not completelly wrong to see cat/grep/wc or any unix program as an object, inheriting some text handling class. +But it kind of made sense, programmes were made to interact together, and where we tend to see a program as a whole project, a program on Unix use to do only one thing, and do it well. +You don't need modularity in your program if writing a whole program anew is faster than creating an interface, and as program are made to interact together, it's not completely wrong to see cat/grep/wc or any Unix program as an object, inheriting some text handling class. COGNAC is bash, and as sure try to follow this idea. @@ -104,13 +111,13 @@ It use lot of small program interactive together, and is complet by a few utilit Makefile was create to... make files, and so Makefile is use that way. -Scripts use by the makefile, do the job of creating the file, and the makefile check that they have been create, and that there's no need to rebuild them. +Scripts use by the makefile, do the job of creating the file, and the makefile check that they have been created, and that there's no need to rebuild them. ### Templating the templating system cognac is homemade, it read SRC file and generate DEST file -it use multiple keywork, each sourouding by 4 underscore (example: `____api_version____`) -as an example you can look at [lib.h](./lib.h) or [main_tpl.c](./main_tpl.c) +it uses multiple keyword, each surrounded by 4 underscore (example: `____api_version____`) +as an example, you can look at [lib.h](./lib.h) or [main_tpl.c](./main_tpl.c) Some rules support multiples languages sure as `____func_code____`, which will generate functions calls, and some are not. (like `____functions_proto____` which for now support only C)