DocTreeClient

DocTreeClient provides a simple API for accessing document collections that have been processed and stored by the doctree module. It allows you to:

List available collections
List pages, files, and images within collections
Check if specific pages, files, or images exist
Get file paths for pages, files, and images
Retrieve content of pages

The client works with Redis as a backend storage system, where document collections are indexed and their metadata is stored.

Usage

Creating a Client

import freeflowuniverse.herolib.web.doctreeclient

// Create a new DocTreeClient instance
mut client := doctreeclient.new()!

Working with Collections

// List all available collections
collections := client.list_collections()!
println('Available collections: ${collections}')

// Check if a collection exists by trying to list its pages
if client.page_exists('my_collection', 'some_page') {
    println('Collection and page exist')
}

Working with Pages

// List all pages in a collection
pages := client.list_pages('my_collection')!
println('Pages in collection: ${pages}')

// Check if a specific page exists
if client.page_exists('my_collection', 'introduction') {
    println('Page exists')
}

// Get the file path for a page
page_path := client.get_page_path('my_collection', 'introduction')!
println('Page path: ${page_path}')

// Get the content of a page
content := client.get_page_content('my_collection', 'introduction')!
println('Page content: ${content}')

Working with Files

// List all files in a collection
files := client.list_files('my_collection')!
println('Files in collection: ${files}')

// Check if a specific file exists
if client.file_exists('my_collection', 'document.pdf') {
    println('File exists')
}

// Get the file path
file_path := client.get_file_path('my_collection', 'document.pdf')!
println('File path: ${file_path}')

Working with Images

// List all images in a collection
images := client.list_images('my_collection')!
println('Images in collection: ${images}')

// Check if a specific image exists
if client.image_exists('my_collection', 'diagram.png') {
    println('Image exists')
}

// Get the image path
image_path := client.get_image_path('my_collection', 'diagram.png')!
println('Image path: ${image_path}')

Complete Example

Here's a complete example that demonstrates how to use DocTreeClient with a document collection:

module main

import freeflowuniverse.herolib.web.doctreeclient
import freeflowuniverse.herolib.data.doctree

fn main() {
    // First, populate Redis with doctree data
    mut tree := doctree.new(name: 'example_docs')!

    // Scan a git repository containing documentation
    tree.scan(
        git_url: 'https://github.com/example/docs'
        git_pull: true
    )!

    // Export the doctree to Redis and local filesystem
    tree.export(
        destination: '/tmp/docs_export'
        reset: true
    )!
    
    // Create a DocTreeClient instance
    mut client := doctreeclient.new()!
    
    // List all collections
    collections := client.list_collections()!
    println('Available collections: ${collections}')
    
    // Use the first collection
    if collections.len > 0 {
        collection_name := collections[0]
        
        // List pages in the collection
        pages := client.list_pages(collection_name)!
        println('Pages in collection: ${pages}')
        
        // Get content of the first page
        if pages.len > 0 {
            page_name := pages[0]
            content := client.get_page_content(collection_name, page_name)!
            println('Content of ${page_name}:')
            println(content)
        }
        
        // List and display images
        images := client.list_images(collection_name)!
        println('Images in collection: ${images}')
        
        // List and display other files
        files := client.list_files(collection_name)!
        println('Files in collection: ${files}')
    }
}

Error Handling

DocTreeClient provides specific error types for different failure scenarios:

pub enum DocTreeError {
    collection_not_found
    page_not_found
    file_not_found
    image_not_found
}

You can handle these errors using V's error handling mechanisms:

// Example of error handling
page_content := client.get_page_content('my_collection', 'non_existent_page') or {
    if err.msg.contains('page_not_found') {
        println('The page does not exist')
        return
    }
    println('An error occurred: ${err}')
    return
}

How It Works

DocTreeClient works with Redis as its backend storage:

The doctree module processes document collections and stores metadata in Redis
Collection paths are stored in the 'doctree:meta' hash
Page, file, and image paths within a collection are stored in 'doctree:{collection_name}' hashes
DocTreeClient provides methods to access this data and retrieve the actual content from the filesystem