Add Complete Tutorials

README.md

@@ -1,59 +1,54 @@
-# **http**
-## **Overview**
-
-The `http` Fortran package provides a **simple and convenient** way to make HTTP requests and retrieve responses. It aims to **simplify** the process of interacting with web services by providing a high-level API.
-
-___
-## **Features**
-
- The package includes the following features:
-
- 1. #### **Sending HTTP Requests:**
-    - **`GET`**: Retrieve data from the server.
-    - **`POST`**: Submit data to be processed by the server.
-    - **`PUT`**: Replace or create resources on the server.
-    - **`DELETE`**: Remove resources from the server.
-    - **`PATCH`**: Partial updates to resources.
-    - **`HEAD`**: Retrieve response headers without the response content.
-
- 2. #### **Data Support:**
-    - Send any type of data with requests, including support for `file` uploads and `form data`.
-
- 3. #### **Response Handling:**
-    - Retrieve response `content`.
-    - Get the HTTP `status code` returned by the server.
-    - Fetch the `length` of the response content.
-    - Access response `headers`.
-
- 4. #### **Custom Headers:**
-    - Include `custom headers` in requests to the server.
-
- 5. #### **Error Handling:**
-    - Detect and handle unsuccessful requests gracefully, with informative `error messages`.
-
- 6. #### **Request Timeout:**
-    - Set a maximum time allowed for a request to complete, improving responsiveness.
-
- 7. #### **Authentication:**
-    - Authenticate requests to protected resources using standard authentication methods.
-
-## **Installation**
-
- Before building the `http-client` library, ensure that you have the necessary dependencies installed. On Ubuntu, you need to install the curl development headers. Use the following command:
+# http-client
+
+http-client is Fortran library to make HTTP requests.
+It simplifies interacting with web services by providing a high-level and
+user-friendly interface.
+
+## Features
+
+* HTTP request methods:
+  - `GET`: Retrieve data from the server.
+  - `POST`: Create new data the server.
+  - `PUT`: Replace an existing resource on the server.
+  - `DELETE`: Delete a resource from the server.
+  - `PATCH`: Partially update a resource on the server.
+  - `HEAD`: Get response headers without the response content.
+* Supported data types:
+  - URL encoded fields
+  - HTTP form data
+  - File uploads
+* Response handling:
+  - Retrieve response body (content).
+  - Get the HTTP status code returned by the server.
+  - Access response headers.
+* Setting custom request headers
+* Error handling with informative error messages
+* Setting request timeouts
+* Basic HTTP authentication
+
+## Installation
+
+Before building the http-client library, ensure that you have the necessary
+dependencies installed. On Ubuntu, you need to install the curl development
+headers. Use the following command:
 
 ```
 sudo apt install -y libcurl4-openssl-dev
 ```
 
- To use `http-client` within your fpm project, add the following to your package `fpm.toml` file:
+To use http-client as a dependency in your fpm project, add the following to
+your the fpm.toml file of your package:
 
 ```toml
 [dependencies]
 http = { git = "https://github.com/fortran-lang/http-client.git" }
 stdlib = "*"
 ```
-## **Usage Example**
-The following example demonstrates how to use the http package to make a **Simple GET request** and process the response
+
+## Example use
+
+The following example demonstrates how to use http-client to make a simple `GET`
+request and process the response:
 
 ```fortran
 program simple_get
@@ -78,7 +73,9 @@ program simple_get
 end program simple_get
 
 ```
-### Ouptut : 
+
+Ouptut: 
+
 ```
  Response Code    :          200
  Response Length  :                    83
@@ -90,100 +87,114 @@ end program simple_get
   "completed": false
 }
 ```
-In this example, we make a GET request to the URL https://jsonplaceholder.typicode.com/todos/1 to retrieve JSON data. If the request is successful, we print the ***response code, content length, method, and content***. If the request fails, we print the ***error message***.
-
-## **Getting Started Guides**
-> ### ***The Complete Tutorial Guide is <u> Currently in progress</u> and will be available soon.***
-1. ### **Installation** 👋
-    - Installing Dependencies (Ubuntu)
-    - Setting up the Package in your Project
-
-2. ### **Making HTTP Requests** 🚀
-    - **Sending `GET` Requests**
-        - *Accessing Response `Content`*
-        - *Retrieving `Status Codes`*
-        - *Getting Response `Headers`*
-        - *Extracting `Content Length`*
-    - **Sending `POST` Requests**
-        - *Sending `Data` with Requests*
-        - *Sending `Form Data`*
-        - *Uploading `File`*
-    - **Sending `PUT` Requests**
-    - **Sending `PATCH` Requests**
-    - **Sending `DELETE` Requests**
-    - **Sending `HEAD` Requests**
-
-3. ### **Customizing Requests** ✏️
-    - Sending Custom **Headers**
-    - Setting Request **Timeout**
-    - **Authentication** Option
-
-4. ### **Error Handling** 🤨
-    - Handling Unsuccessful Requests
-    - Displaying Error Messages
-
-5. ### **Real Projects** 🤖
-    -  **GitHub organization analyzer** : Retrieve valuable information about the organization repositories
-
-
-## **Contributing to project**
-Thank you for your interest in contributing to the `http` Fortran package! Contributions from the community are valuable in improving and enhancing the functionality of the package. This section provides a guide on how to get the code, build the library, and run examples and tests.
-
-### **Get the code**
+
+In this example, we make a `GET` request to the URL
+https://jsonplaceholder.typicode.com/todos/1 to retrieve JSON data.
+If the request is successful, we print the response code, content length,
+method, and content. If the request fails, we print the error message.
+
+## Getting Started Guides
+
+To begin your journey with our package, dive into the comprehensive tutorial
+available here: [tutorial.md](./tutorial/tutorial.md)**.
+
+## Projects using http-client
+
+* [github-org-analyzer](https://github.com/rajkumardongre/github-org-analyzer):
+An example mini-project to demonstrate the use of http-client by downloading
+and parsing data from the GitHub API.
+* [fortran-xkcd](https://github.com/rajkumardongre/fortran-xkcd/tree/http_client_version):
+An fpm example project that displays the latest xkcd comic inside an X window.
+As a limitation, only images in PNG format are supported.
+The alt text will be printed to console.
+* [foropenai](https://github.com/gha3mi/foropenai): A Fortran library to access
+* the OpenAI API.
+
+If you're using http-client in your Fortran project and would like to be
+included on this list, we welcome you to contribute by creating a pull request
+(PR) and adding your project details. 
+
+## Contributing to project
+
+Thank you for your interest in http-client! Contributions from the community
+are esential for improving the package. This section provides a guide on how to
+get the code, build the library, and run examples and tests.
+
+### Get the code
+
 To get started, follow these steps:
 
 Clone the repository using Git:
+
 ```
 git clone https://github.com/fortran-lang/http-client
 cd http-client
 ```
-### **Prerequisites**
-Before building the library, ensure that you have the necessary dependencies installed. On `Ubuntu`, you need to install the curl development headers. Use the following command:
+
+### Prerequisites
+
+Before building the library, ensure that you have the necessary dependencies
+installed. On Ubuntu, you need to install the curl development headers.
+Use the following command:
+
 ```
 sudo apt install -y libcurl4-openssl-dev
 ```
-### **Build the library**
 
-The `http` package uses **fpm** as the build system. Make sure you have fpm `version 0.8.x` or later installed. To build the library, execute the following command within the project directory:
+### Build the library
+
+http-client uses **fpm** as the build system. Make sure you have fpm-0.8.x or
+later installed. To build the library, run the following command within the
+project directory:
+
 
 ```
 fpm build
 ```
-### **Run examples**
-The http package provides example programs that demonstrate its usage. To run the examples, use the following command:
+
+### Run examples
+
+http-client provides example programs that demonstrate its use. To run the
+examples, use the following command:
 
 ```
 fpm run --example <example name>
 ```
-Executing this command will execute the example programs, allowing you to see the package in action and understand how to utilize its features.
 
-### **Run tests**
- The http package includes a test suite to ensure its functionality is working as expected. To run the tests, execute the following command:
+Executing this command will execute the example programs, allowing you to see
+the package in action and understand how to utilize its features.
+
+### Run tests
+
+http-client includes a test suite to ensure its functionality is working as
+expected. To run the tests, type:
+
 ```
 fpm test
 ```
-Running the tests will validate the behavior of the package and help identify any issues or regressions.
 
-### **Generating API Documentation**
+Running the tests will validate the behavior of the package and help identify
+any issues or regressions.
 
-Before generating API documentation, ensure that you have FORD installed on your system.
+### Generating API Documentation
 
-**Installation link**: [https://github.com/Fortran-FOSS-Programmers/ford#installation](https://github.com/Fortran-FOSS-Programmers/ford#installation)
+Before generating API documentation, ensure that you have FORD
+[installed on your system](https://github.com/Fortran-FOSS-Programmers/ford#installation).
 
 Once FORD is set up, execute the following command to build the API documentation:
 
 ```bash
 ford ford.md
 ```
 
-### **Supported compilers**
+### Supported compilers
 
 http-client is known to work with the following compilers:
 
 * GFortran 11 & 12 (tested in CI)
 * Intel OneAPI ifx v2023.1.0 and ifort classic v2021.9.0
 
-### **Contributing guidelines**
+### Contributing guidelines
 
 When contributing to the http Fortran package, please keep the following guidelines in mind:
 
@@ -194,6 +205,6 @@ When contributing to the http Fortran package, please keep the following guideli
 * Make sure to test your changes and ensure they do not introduce regressions or break existing functionality.
 * Submit a pull request with your changes, providing a clear explanation of the problem you are solving and the approach you have taken.
 
-We appreciate your contributions and look forward to your valuable input in improving the http Fortran package.
+We appreciate your contributions and look forward to your valuable input in improving http-client.
 
-Happy coding!
+Happy coding!👋

fpm.toml

@@ -19,5 +19,5 @@ implicit-external = false
 source-form = "free"
 
 [dependencies]
-fortran-curl = {git = "https://github.com/interkosmos/fortran-curl.git"}
+fortran-curl = {git = "https://github.com/interkosmos/fortran-curl.git", tag = "0.5.0"}
 stdlib = "*"

src/http/http_request.f90

@@ -43,6 +43,7 @@ module http_request
         type(pair_type), allocatable :: file
             !! Used to store information about files to be sent in HTTP requests.
         integer(kind=int64) :: timeout
+            !! **`Timeout`** value for the request in **seconds**.
         type(pair_type), allocatable :: auth
             !! Stores the username and password for Authentication
     end type request_type

test/test_get.f90

@@ -22,9 +22,8 @@ program test_get
       pair_type('Set-Cookie', 'Theme-Light'), &
       pair_type('Set-Cookie', 'Auth-Token: 12345'), &
       pair_type('User-Agent', 'my user agent') &
-      ]
+    ]
 
-    ! res = request(url='https://reqres.in/api/users/1', header=request_header)
     res = request(url='https://dummyjson.com/products/1', header=request_header)
 
     msg = 'test_get: '