Skip to content

README.md

Latest commit

 

History

History
355 lines (255 loc) · 8.81 KB

README.md

File metadata and controls

355 lines (255 loc) · 8.81 KB

AFC - Advanced Foundation Classes

License: LGPL v2.1

AFC (Advanced Foundation Classes) is a comprehensive C library providing foundation classes for modern application development. Originally "Amiga Foundation Classes," AFC now targets Linux and open source platforms with a robust set of reusable components.

✨ What is AFC?

AFC is a suite of C classes designed to ease project development by providing standardized, well-tested building blocks for common programming tasks. Think of it as a foundational library that bridges the gap between raw C and higher-level languages, offering:

  • Dynamic string handling with bounds checking
  • Data structures (arrays, lists, trees, hash tables, dictionaries)
  • Networking (TCP/IP clients/servers, HTTP, FTP, SMTP, POP3)
  • Database abstraction layer (MySQL, PostgreSQL support)
  • Web development tools (CGI manager, HTTP client)
  • File operations and directory management
  • Threading support
  • Memory tracking for leak detection
  • Regular expressions and text parsing

🚀 Quick Start

Installation

Prerequisites

  • GCC or compatible C compiler
  • GNU Make
  • OpenSSL development libraries (for networking features)

On Debian/Ubuntu:

sudo apt-get install build-essential libssl-dev

On Red Hat/Fedora/CentOS:

# For modern systems (Fedora 22+, RHEL 8+, CentOS 8+)
sudo dnf install gcc make openssl-devel

# For older systems (RHEL 7, CentOS 7)
sudo yum install gcc make openssl-devel

Build and Install

# Clone the repository
git clone https://github.com/fsoft72/afc.git
cd afc

# Build the library
make

# Install (requires root)
sudo make install

By default, AFC installs to /usr/local/lib with headers in /usr/local/include/afc.

Your First AFC Program

#include <afc/afc.h>

int main(void) {
    // Initialize AFC
    AFC *afc = afc_new();
    
    // Create a dynamic string
    char *str = afc_string_new(50);
    afc_string_copy(str, "Hello, AFC!", ALL);
    
    printf("String: %s\n", str);
    printf("Length: %lu\n", afc_string_len(str));
    
    // Cleanup
    afc_string_delete(str);
    afc_delete(afc);
    
    return 0;
}

Compile with afc-config (installed with AFC):

gcc -o hello hello.c $(afc-config --cflags --libs)

Or manually specify flags:

gcc -o hello hello.c -I/usr/local/include -L/usr/local/lib -lafc

💡 Key Features

Standardized API

All AFC classes follow consistent naming conventions:

  • afc_<class>_new() - Create objects
  • afc_<class>_delete() - Destroy objects
  • afc_<class>_<action>() - Perform operations
  • afc_<class>_set_tags() - Configure with tag system

Memory Safety

AFC includes built-in memory tracking to detect leaks:

AFC *afc = afc_new();

// Enable memory tracking
afc_set_tags(afc, 
    AFC_TAG_SHOW_MALLOCS, (void *)TRUE,
    AFC_TAG_SHOW_FREES, (void *)TRUE,
    AFC_TAG_END);

// Your code here - all mallocs are tracked

afc_delete(afc);  // Reports any leaks

Dynamic Strings

Powerful string operations with automatic memory management:

char *str = afc_string_new(10);

afc_string_copy(str, "Hello", ALL);
afc_string_add(str, " World", ALL);
afc_string_upper(str);  // "HELLO WORLD"

// Format strings
afc_string_make(str, "Number: %d", 42);

// String manipulation
afc_string_trim(str);
afc_string_substr(str, 0, 5);

afc_string_delete(str);

Data Structures

Rich collection of data structures:

// Dynamic Arrays
Array *arr = afc_array_new();
afc_array_add(arr, my_data, AFC_ARRAY_ADD_TAIL);
void *item = afc_array_item(arr, index);

// Dictionaries (Hash Tables)
Dictionary *dict = afc_dictionary_new();
afc_dictionary_set(dict, "key", value);
void *val = afc_dictionary_get(dict, "key");

// Lists
NodeMaster *list = afc_nodemaster_new();
afc_nodemaster_add(list, data, AFC_NODEMASTER_ADD_TAIL);
afc_nodemaster_sort(list, compare_func);

Networking Made Easy

// HTTP Client
HttpClient *http = afc_http_client_new();
afc_http_client_get(http, "http://example.com/api/data");
char *response = afc_http_client_get_body(http);

// SMTP Email
Smtp *smtp = afc_smtp_new();
afc_smtp_connect(smtp, "smtp.example.com", 25);
afc_smtp_send_mail(smtp, "from@example.com", "to@example.com", 
                   "Subject", "Message body");

// TCP Server
InetServer *server = afc_inet_server_new();
afc_inet_server_bind(server, 8080);
afc_inet_server_listen(server, handle_connection);

Database Abstraction

Work with databases through a unified API:

// Connect to database
DBIManager *dbi = afc_dbi_manager_new();
afc_dbi_manager_connect(dbi, "mysql://localhost/mydb", "user", "pass");

// Execute queries
afc_dbi_manager_query(dbi, "SELECT * FROM users WHERE id = ?", user_id);

// Fetch results
while (afc_dbi_manager_fetch_row(dbi)) {
    char *name = afc_dbi_manager_get_field(dbi, "name");
    printf("User: %s\n", name);
}

Tag-Based Configuration

Flexible parameter passing without breaking API compatibility:

StringNode *list = afc_string_node_new();

afc_string_node_set_tags(list,
    AFC_STRING_NODE_TAG_DISCARD_ZERO_LEN, (void *)TRUE,
    AFC_STRING_NODE_TAG_CASE_SENSITIVE, (void *)FALSE,
    AFC_TAG_END);

Exception Handling

C-style exception handling with cleanup guarantees:

int my_function(void) {
    TRY(int)
    
    char *data = afc_malloc(size);
    if (!data) {
        RAISE(AFC_LOG_ERROR, AFC_ERR_NO_MEMORY, 
              "Failed to allocate", "allocation");
    }
    
    // Do work...
    
    RETURN(AFC_ERR_NO_ERROR);
    
    EXCEPT
        // Handle errors
    
    FINALLY
        // Always executed - cleanup here
        if (data) afc_free(data);
    
    ENDTRY
}

📚 Documentation

  • INSTALL - Detailed installation instructions
  • CHANGES.md - Version history and changelog

🏗️ Available Classes

Core

  • AFC - Base object with logging and memory tracking
  • MemTracker - Memory leak detection
  • Base64 - Base64 encoding/decoding

Strings & Text

  • String - Dynamic strings with bounds checking
  • StringNode / StringList - Lists of strings
  • ReadArgs - Template-based string parsing
  • RegExp - Regular expression support

Data Structures

  • Array - Dynamic arrays
  • NodeMaster / List - Linked lists
  • Dictionary - Hash-based key-value store
  • Hash - Generic hash tables
  • BTree, AVLTree, BinTree - Tree structures
  • CircularList - Circular buffers

Networking (Linux only)

  • InetClient / InetServer - TCP/IP networking
  • HttpClient - HTTP client
  • FtpClient - FTP client
  • Smtp - SMTP email client
  • Pop3 - POP3 email client

Database (Linux only)

  • DBIManager - Database abstraction layer
  • MySQL and PostgreSQL drivers

File & System (Linux only)

  • FileOps - File operations (copy, move, chmod, etc.)
  • DirMaster - Directory scanning and management

Web Development

  • CGIManager - CGI application support

Utilities

  • DateHandler - Date manipulation
  • MD5 - MD5 hashing
  • Threader - Multi-threading support (Linux only)
  • CmdParser - Custom language parser (Linux only)

Plugin System (Linux only)

  • DynamicClass / DynamicClassMaster - Plugin architecture

🔧 Building Tests

AFC includes comprehensive tests for all modules:

# Build and run all tests for a module
cd src/test_area/string
make
./test_01

# Or from src directory
make string.test

🖥️ Platform Support

  • Linux: Full feature support
  • MinGW/Windows: Limited support (no networking, database, or threading)

📄 License

AFC is released under the GNU Lesser General Public License v2.1 (LGPL v2.1).

This means you can:

  • Use AFC in both open source and commercial projects
  • Link against AFC libraries without licensing restrictions on your code
  • Modify AFC itself (changes to AFC must remain LGPL)

See LICENSE for the complete license text.

🤝 Contributing

Contributions are welcome! Please:

  1. Read the Development Guidelines
  2. Follow existing code conventions
  3. Write tests for new features
  4. Keep changes minimal and focused
  5. Update documentation for API changes

📧 Support

For questions, bug reports, or contributions, please open an issue on GitHub.

🌟 Why AFC?

  • Battle-tested: Used in production applications
  • Well-documented: Comprehensive documentation and examples
  • Memory-safe: Built-in leak detection and bounds checking
  • Consistent API: Easy to learn, predictable patterns
  • Zero dependencies: Only standard C libraries (except OpenSSL for networking)
  • Portable: Works on Linux and other Unix-like systems
  • LGPL licensed: Use freely in commercial projects

Start building better C applications today with AFC! 🚀