att

Author: mateusmoutinho

README.md

@@ -1,174 +1,178 @@
-# LuaBear 🐻
+# LuaBear: HTTP Client Library for Lua
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Lua Version](https://img.shields.io/badge/Lua-5.1%2B-blue.svg)](https://www.lua.org/)
-[![Release](https://img.shields.io/github/v/release/OUIsolutions/Lua-Bear)](https://github.com/OUIsolutions/Lua-Bear/releases)
-[![Downloads](https://img.shields.io/github/downloads/OUIsolutions/Lua-Bear/total)](https://github.com/OUIsolutions/Lua-Bear/releases)
+LuaBear is a powerful and easy-to-use HTTP client library for Lua, designed to make HTTP requests and handle responses with a simple and intuitive API. It supports sending and receiving data in various formats, including JSON, binary, and file streams, and allows for custom headers and flexible request options.
 
-> A simple, powerful HTTP client library for Lua
+## Features
+- Simple HTTP(S) requests (GET, POST, etc.)
+- Read response as string, chunked, or JSON
+- Send data as string, JSON, binary, or file stream
+- Custom request headers
+- Easy integration with Lua projects
 
-## 📋 Overview
+## Installation
+To install the lib, just download the lib [Lib Download](https://github.com/OUIsolutions/Lua-Bear/releases/download/0.1.0/luaBear.zip)
+in the root of your project, and run with:
 
-LuaBear is a user-friendly HTTP client library that makes sending web requests in Lua simple and straightforward. Whether you're a beginner or experienced developer, LuaBear provides an easy way to interact with web services and APIs.
+```lua
+local luabear  = require("luaBear.luaBear")
 
-## ✨ Features
+```
 
-- ✅ **Simple HTTP/HTTPS requests** (GET, POST, PUT, DELETE, etc.)
-- ✅ **Flexible response handling** - read as string, chunks, or JSON
-- ✅ **Multiple data formats** - send text, JSON, binary data, or files
-- ✅ **Custom headers** - set any HTTP headers you need
-- ✅ **Beginner-friendly API** - intuitive interface for new users
 
-## 🚀 Installation
 
-### Option 1: Direct Download (Recommended for Beginners)
+#### Installation from Command
+if you prefer to install with a command, just type:
+```shell
+ curl -L -o Lua-Bear.zip https://github.com/OUIsolutions/Lua-Bear/releases/download/0.1.0/luaBear.zip && unzip Lua-Bear.zip && rm Lua-Bear.zip
+```
 
-1. Download the library package:
-   ```
-   mkdir -p luaBear
-   curl -L -o luaBear/luaBear.lua https://github.com/OUIsolutions/Lua-Bear/releases/download/0.1.2/luaBear.lua
-   curl -L -o luaBear/luaBear.so https://github.com/OUIsolutions/Lua-Bear/releases/download/0.1.2/luaBear.so
-   ```
 
-4. Use in your Lua project:
-   ```lua
-   local luabear = require("luaBear.luaBear")
-   ```
+#### Build from scratch
 
-### Option 2: Manual Download
+For building from scratch you need to have Darwin installed on your machine. To install Darwin:
+```bash
+curl -L https://github.com/OUIsolutions/Darwin/releases/download/0.020/darwin.out -o darwin.out && chmod +x darwin.out &&  sudo  mv darwin.out /usr/bin/darwin
+```
 
-1. Download the library from [GitHub Releases](https://github.com/OUIsolutions/Lua-Bear/releases/download/0.1.0/luaBear.zip)
-2. Extract the ZIP file to your project directory
-3. Import in your code:
-   ```lua
-   local luabear = require("luaBear.luaBear")
-   ```
+You'll also need Docker (default) or Podman installed on your system.
 
-### Option 3: Build from Source
+Then you can build the project in the root directory of the project:
 
-Prerequisites:
-- Install Darwin build tool:
-  ```
-  curl -L https://github.com/OUIsolutions/Darwin/releases/download/0.020/darwin.out -o darwin.out && chmod +x darwin.out && sudo mv darwin.out /usr/bin/darwin
-  ```
+Using Docker (default):
+```bash
+darwin run_blueprint build/  --mode folder build_release
+```
 
-Build steps:
-1. Clone the repository
-2. Navigate to the project directory
-3. Run:
-   ```
-   darwin run_blueprint build/ --mode folder build_release
-   ```
+Using Podman:
+```bash
+darwin run_blueprint build/  --mode folder build_release --provider podman
+```
 
-## 📚 Quick Start Guide
 
-### Making a Simple GET Request
+## Basic Usage
 
+### Simple GET Request
 ```lua
--- Import the library
-local luabear = require("luaBear.luaBear")
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({url="https://example.com/"})
 
--- Make a simple GET request
-local response = luabear.fetch({url = "https://example.com/"})
-
--- Check status code
-print("Status code:", response.status_code)
-
--- Print response headers
+print("status code:", response.status_code)
 for header_name, header_value in pairs(response.headers) do
-    print(header_name .. ": " .. header_value)
+    print(header_name .. ":" .. header_value)
 end
-
--- Print response body
 print(response.read_body())
 ```
 
-## 📖 Common Examples
-
-### Reading a JSON Response
-
+### Reading Response in Chunks
 ```lua
-local luabear = require("luaBear.luaBear")
-local response = luabear.fetch({url = "https://jsonplaceholder.typicode.com/todos/1"})
-local data = response.read_body_json()
-
--- Access JSON data easily
-print("User ID:", data.userId)
-print("Title:", data.title)
-print("Completed:", data.completed)
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({url="https://example.com/"})
+while true do
+    local chunk = response.read_body_chunk(1024)
+    if not chunk then break end
+    print(chunk)
+end
 ```
 
-### Sending Form Data (POST)
+### Reading JSON Response
+```lua
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({url="https://jsonplaceholder.typicode.com/todos/1"})
+local body = response.read_body_json()
+print(body["userId"], body["title"], body["completed"])
+```
 
+### Sending String Data (POST)
 ```lua
-local luabear = require("luaBear.luaBear")
+local luabear  = require("luaBear.luaBear")
 local response = luabear.fetch({
-    url = "https://httpbin.org/post",
-    method = "POST",
-    body = {
-        username = "bearuser",
-        password = "bearpassword"
-    }
+    url="http://localhost:3001/",
+    method="POST",
+    body="Hello, LuaBear!",
 })
 print(response.read_body())
 ```
 
-### Uploading a File
-
+### Sending JSON Data (POST)
 ```lua
-local luabear = require("luaBear.luaBear")
+local luabear  = require("luaBear.luaBear")
+luabear.nil_code = "nil" -- set the nil code to avoid errors with nil values
 local response = luabear.fetch({
-    url = "https://httpbin.org/post",
-    method = "POST",
-    body = luabear.file_stream("test.png")
+    url="http://localhost:3001/",
+    method="POST",
+    body={username="LuaBear", password="secret", email="nil"},
 })
 print(response.read_body())
 ```
 
-## 📝 API Reference
-
-### Main Functions
-
-#### `luabear.fetch(options)`
-Makes an HTTP request with the given options.
-
-**Parameters:**
-- `options.url` (string): Target URL (required)
-- `options.method` (string): HTTP method like "GET", "POST" (default: "GET")
-- `options.body` (string/table/stream): Request body data
-- `options.headers` (table): Custom HTTP headers
-
-**Returns:**
-A response object with:
-- `status_code`: HTTP status code (e.g., 200, 404)
-- `headers`: Table of response headers
-- `read_body()`: Returns full response as string
-- `read_body_chunk(size)`: Returns response in chunks
-- `read_body_json()`: Parses and returns JSON response as table
-
-#### `luabear.file_stream(filename)`
-Creates a file stream for uploading files.
-
-**Parameters:**
-- `filename` (string): Path to the file
-
-**Returns:**
-A file stream object to be used with `fetch()`
-
-## 🧪 More Examples
-
-Check the `examples/` directory for complete working examples:
-- Basic requests: `read_all.lua`
-- Chunked reading: `read_chunk.lua`
-- JSON handling: `read_json.lua`, `sending_json.lua`
-- Binary data: `sending_binary.lua`
-- File uploads: `sending_file.lua`
-- Custom headers: `setting_headers.lua`
-
-## 📄 License
+### Sending Binary Data (POST)
+```lua
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({
+    url="http://localhost:3000/",
+    method="POST",
+    body=io.open("test.png", "rb"):read("*a"),
+})
+print(response.read_body())
+```
 
-This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.
+### Sending File Stream (POST)
+```lua
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({
+    url="http://localhost:3000/",
+    method="POST",
+    body=luabear.file_stream("test.png")
+})
+print(response.read_body())
+```
 
-## 🤝 Contributing
+### Setting Custom Headers
+```lua
+local luabear  = require("luaBear.luaBear")
+local response = luabear.fetch({
+    url="http://localhost:3001/",
+    method="POST",
+    headers={
+        username="your username",
+        password="your password"
+    }
+})
+print(response.read_body())
+```
 
-Contributions are welcome! Feel free to open issues or submit pull requests.
+## API Reference
+
+### `luabear.fetch(options)`
+Performs an HTTP request.
+- `options.url` (string): The URL to request (required)
+- `options.method` (string): HTTP method (default: "GET")
+- `options.body` (string/table/stream): Request body (optional)
+- `options.headers` (table): Custom headers (optional)
+
+Returns a `response` object:
+- `response.status_code`: HTTP status code
+- `response.headers`: Table of response headers
+- `response.read_body()`: Reads the full response body as a string
+- `response.read_body_chunk(size)`: Reads the response body in chunks of `size` bytes
+- `response.read_body_json()`: Parses the response body as JSON and returns a Lua table
+
+### `luabear.file_stream(filename)`
+Returns a file stream object for use as a request body (for large/binary files).
+
+### `luabear.nil_code`
+Set this to a string to represent `nil` values in JSON encoding (useful for APIs that require explicit nulls).
+
+## Examples
+See the `examples/` directory for more usage examples:
+- `read_all.lua`: Basic GET request and print all response
+- `read_chunk.lua`: Read response in chunks
+- `read_json.lua`: Parse JSON response
+- `sending_str.lua`: Send string data
+- `sending_json.lua`: Send JSON data
+- `sending_binary.lua`: Send binary data
+- `sending_file.lua`: Send file stream
+- `setting_headers.lua`: Custom headers
+
+## License
+See [LICENSE](/LICENSE).