Ecosyste.ms: Awesome

**For me I just need parsing the first comment block of a single textfile or every textfile with a defined file-extension in a folder, doesn't matter if \*.js, \*.h, \*.hpp or whatever**

Fileheader_docu_ parse a single file or recursive directories for files with defined extensions (e.g.: *.c, *.cpp, *.h, *.js, *.ts).

Parsing will be done by the defined parser plugin (e.g.: gh_markdown, doxygen).

Writing the header docu will be done by the defined writer pluging (e.g.: json, gh_markdown).

The future default writer plugin will be adoc (ASCIIdoc) so fileheader_docu can be used as an export task (binary) to doctoolchain.

*scanned / collected Meta data:*_*

(depends on parser-/writer plug-ins and inifile configuration)

- FILE
- TITLE
- AUTHOR
- BRIEF"
- VERSION
- DATE
- DESC
- DESCRIPTION
- LICENSE
- COPYRIGHT
- SOURCE
- COMMENT
- SYNTAX
- DEPENDENCIES
- HISTORY

*scanned / collected file attributes:*

- FILE_Name
- FILE_baseFileName
- FILE_completeSuffix
- FILE_baseDirName
- FILE_created_localtime
- FILE_LastModified_localtime
- FILE_lastModified_humanUTC
- FILE_lastModified_stringUTC
- FILE_lastModified_timeUTC
- FILE_lastModified_timeUtcOffset
- FILE_lastModified_timeZAbbreviation
- FILE_Perm_Numeric
- FILE_Perm_AlphaNumeric
- FILE_Size
- FILE_SHA256_Hash
- FILE_Scan_localTime
- FILE_Scan_UTCcurrent

### built with

- GNU/Linux 5.15.0-69-generic x86_64 and QT 6.5 C++17 (g++).
- macOS Ventura (13.3, arm64-apple-darwin22.4.0) and QT 6.5 C++17 (clang++)
- Windows 10 and QT 6.5 C++17 (MinGW_64)

**There are other, older versions:**

- written in QT5 with C++17 : header_docu QT5 C++17

- written in plain C++20 : header_docu CPP C++20

### docs-as-code approach:

see:

- docs-as-code
- docToolchain (user site)
- docToolchain (Github)

## Getting Started

**tested with:**

- GNU/Linux with Kernel 5.15 and g++ 11.3.0
- MacOS Ventura (13.3, arm64-apple-darwin22.4.0) and clang++ 14.0.3
- Win10pro and MinGW_64

### Prerequisites

- the Linux AppImage should run on most newer x86_64 Linux system
- the MacOS application package should be installable at least under MacOS Ventura
- the Windows Setup.exe should be installable at under Win10 and Win11

(for compiling and linking):

- PC or Laptop with Windows, MacOS or Linux \*\_^
- installed C++ compiler like g++ or clang++ with C++17 support
- developer tools with cmake

#### DEPENDENCIES:

**cxxopts**

a lightweight C++ option parser library, supporting the standard GNU style syntax for options.
https://github.com/jarro2783/cxxopts

**inifile-cpp**

inifile-cpp is a simple and easy to use single header-only ini file en- and decoder for C++.
https://github.com/Rookfighter/inifile-cpp

**OpenSSL**

OpenSSL - a robust, commercial-grade, full-featured toolkit for general-purpose cryptography and secure communication.
https://www.openssl.org/

OpenSSL (Library tested: OpenSSL 3.0.2 15 Mar 2022; Linux: openssl-dev) is needed for creating SHA2-256Bit Hashes for strings and files.

### Installation

1. Clone the repo
```sh
git clone https://github.com/Zheng-Bote/header_docu_qt/.git
```
2. install
- not yet implemented

(back to top)

### configuration and build

#### Linux

1. rename CMakeList.txt_linux to CMakeList.txt
2. configure your QT project to C++17 and cmake
3. adjust your Inifile to Linux filesystem

#### MacOs

1. rename CMakeList.txt_macos to CMakeList.txt
2. configure your QT project to C++17 and clang
3. adjust your Inifile to MacOs filesystem

(back to top)

## Usage

***Tip***

with configured inifile several file-extensions can be parsed during one runtime.

### SYNTAX:

```
file header parser
Usage:
./Fileheader_Docu-x86_64.AppImage [OPTION...]

-a, --auto run with default Inifile
-c, --create create Inifile
-d, --dir arg parse directory
-e, --ext arg file extension to search for. E.g.:
<*.h> | <*.hpp> | <*.c> | <*.cpp>
-f, --file arg parse
-i, --ini arg use Inifile (default: ./Fileheader_Docu-x86_64.AppImage.ini)
-l, --listini list Inifile (optional with --ini )
-o, --out arg output directory
-p, --parser arg how to parse the input (use --plugins to list available plugins):
e.g.: |
--plugins list available plugins
-w, --writer arg output type (use --plugins to list available plugins):
e.g.: | | | | |
-v, --version Print program and version
-h, --help Print help
```

#### EXAMPLES:

*create default Inifile*
```
./Fileheader_Docu-x86_64.AppImage --create
```
*list/show the given Inifile*
```
./Fileheader_Docu-x86_64.AppImage --listini --ini
```
_list available Plug-Ins_
```
./Fileheader_Docu-x86_64.AppImage --plugins
Parser Plug-Ins:
================
Plugin Name:........doxygen
Version:............doxygen header parser-v1.0.0
Plugin Name:........gh_markdown
Version:............Github Markdown parser-v1.0.0

Writer Plug-Ins:
================
Plugin Name:........gh_markdown
Version:............Github Markdown writer-v1.1.0
Plugin Name:........json_cyclonedx
Version:............json CycloneDX (spdx) writer-v0.1.0
Plugin Name:........json_spdx
Version:............json spdx writer-v1.0.0
Plugin Name:........json
Version:............json writer-v1.0.0
```
_parse folder recursively for files with extension *.cpp, write to target folder with parser plug-in doxygen and writer plug-in json_
```
./Fileheader_Docu-x86_64.AppImage --dir ./ESP32_libs --ext *.cpp --out ./ESP32_libs/docu --parser doxygen --writer json
```

*default: run with inifile ./Fileheader_Docu-x86_64.AppImage.ini*
```
./Fileheader_Docu-x86_64.AppImage -a
./Fileheader_Docu-x86_64.AppImage --auto
```

### RETURN:

2023-04-03 18:22:57 : 5 Files parsed with header parser gh_markdown. Output stored with format json in folder ./ESP32_libs/docu

exit(0)

### Plug-Ins

current available plug-ins:

*Parser Plug-Ins*
- gh_markdown (https://github.com/Zheng-Bote/hd_ghmd_parser_plugin)
- doxygen (https://github.com/Zheng-Bote/hd_doxygen_parser_plugin)

*Writer Plug-Ins*
- gh_markdown (https://github.com/Zheng-Bote/hd_ghmd_writer_plugin)
- json (https://github.com/Zheng-Bote/hd_json_writer_plugin)
- json_spdx (https://github.com/Zheng-Bote/hd_spdx_writer_plugin) => useable, but still under construction
- json_cyclonedx (https://github.com/Zheng-Bote/hd_json_CycloneDX_writer_plugin)

### HISTORY:

> | Version | Date | Developer | Comments |
> | ------- | ---------- | --------- | ---------------------------------- |
> | 1.0.0 | 2023-04-07 | RZheng | created |
> | 1.1.0 | 2023-04-25 | RZheng | cleaned output |
> | 1.2.0 | 2023-04-26 | RZheng | list available Plug-Ins |
> | 1.3.0 | 2023-04-29 | RZheng | MacOS support (without threads) |
> | 1.3.0 | 2023-04-30 | RZheng | Windows support |

## Roadmap:

- [x] quick and dirty commandline parser (see QT5 C++17)

- [x] migrate QT commandline to vanilla cxx (see CPP, C++20)

- [x] create final commandline, plugin-based (this one)

- [x] create optional md file[s]

- [x] create optional Github md file[s]

- [x] create optional ASCIIdoc (adoc) file[s]

- [x] create optional JSON file[s]

- [x] create optional csv file[s]

- [x] create optional HTML5 file[s]

- [x] get SHA2-256 filehash

- [x] file last modified time

- [x] file permissions

- [x] save output results in separared file[s] or in one file

- [x] performance improvements for single outfiles (threaded)

- [x] runable Linux AppImage

- [x] installable MacOS package

- [x] installable Windows package

- [x] create optional SBOM (spdx) json file[s] => writer plug-in

- [ ] upload optional SBOM (spdx) json to RDBMS => writer plug-in

Maybe a Kanban board will be established (soon)

(back to top)

## Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

(back to top)

## License

Distributed under the MIT License. See `LICENSE.txt` for more information.

(back to top)

## Contact

ZHENG Robert Zhèng Bó Tè 郑伯特

Project Link: [https://github.com/Zheng-Bote/header_docu_qt/](https://github.com/Zheng-Bote/header_docu_qt/)

## Screenshots and Samples

**Default Inifile**

```
[Input]
# folder with files to parse
Dir=/Volume/500GB/Dev/C/Arduino_ESP32_libs
# file extensions to parse
Extensions=*.h, *.hpp, *.c, *.cpp
# default parser plug-in
Parser_Plugin=doxygen

[Meta]
# file attributes
Attributes=FILE_PERM, LAST_MODIFIED, FILE_SIZE, FILE_HASH_SHA256
# header attributes to parse
Metadata=TITLE, BRIEF, DESC, AUTHOR, LICENSE, VERSION, COPYRIGHT, SOURCE, COMMENT, SYNTAX, HISTORY, DEPENDENCIES

[Output]
# output folder
Dir=/Volume/500GB/Dev/C/Arduino_ESP32_libs/Docu
# output type => deprecated -> Writer_Plugin
Filetype=.json
# all parsed results in one single file (true), or one output file for each parsed file (singleFile=false)
singleFile=false
# default writer plug-in
Writer_Plugin=json

[Plugins]
# plug-ins folder for parser
parserDir=/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser
# plug-ins folder for output writer
writerDir=/Volume/500GB/Dev/QT/header_docu_qt/Plugins/writer
```

**Plugin-Loader**

Plug-In loader-test

wrong identifier:
> Q_DECLARE_INTERFACE(Plugin, "org.somewhere.my_plugin");

```
Loading... "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Loaded: "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Plugin Constructed
Could not cast: "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Loading... "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so"
qt.core.plugin.loader: /Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so: failed to map to memory: Das Argument ist ungültig
Error: "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so" Error: "The file '/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so' is not a valid Qt plugin."
Plugins ParserDir has no valid plugins
program criterias missmatch
Plugin Deconstructed
```

correct identifier:
> Q_DECLARE_INTERFACE(Plugin, "net.hase-zheng.header_docu_plugin");

```
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Plugin Constructor
Test from Plugin: "Test: header_docu plugin"
Plugin Name: "gh_markdown"
Plugin Version: "Github Markdown parser-v0.3.0"
Plugin Deconstructed
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Plugin Constructor
Test from Plugin: "json" : "Test: header_docu plugin"
Plugin Name: "json"
Plugin Version: "json writer-v0.3.0"
Plugin Deconstructed
```

**STDOUT**

```
"2023-04-25 19:17:12" : "./header_docu_qt" - "01.01.00" started
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_doxygen_parser_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_doxygen_parser_plugin.so"
Test from "doxygen" Plugin: "Test: header_docu plugin"
Plugin Name: "doxygen"
Plugin Version: "doxygen header parser-v1.0.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Test from "gh_markdown" Plugin: "Test: header_docu plugin"
Plugin Name: "gh_markdown"
Plugin Version: "Github Markdown parser-v1.0.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_ghmd_writer_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_ghmd_writer_plugin.so"
Test from "gh_markdown" Plugin: "Test: header_docu plugin"
Plugin Name: "gh_markdown"
Plugin Version: "Github Markdown writer-v1.1.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Loaded: "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Test from Plugin: "json" : "Test: header_docu plugin"
Plugin Name: "json"
Plugin Version: "json writer-v1.0.0"
"2023-04-25 19:17:13" : 840 File(s) parsed with "doxygen" header parser. Output stored with format "json" in folder: "/media/zb_bamboo/500GB/Dev/C/ESP32/Arduino_ESP32_libs/Docu"
```

### the end

:vulcan_salute:

(back to top)