Getting Started

This guide will help you get started with Censor quickly. We'll cover installation and a simple usage example.

Installation

Install Censor using Go modules:

go get -u github.com/vpakhuchyi/censor

Basic Usage

Here's a simple example that demonstrates the core functionality of Censor:

package main

import (
    "fmt"

    "github.com/vpakhuchyi/censor"
)

func main() {
    // Create a new Censor instance with default configuration.
    c := censor.New()

    // Define a struct with sensitive data.
    type User struct {
        ID       string `censor:"display"` // Will be visible.
        Email    string                    // Will be masked.
        Password string                    // Will be masked.
    }

    // Create a user.
    user := User{
        ID:       "123",
        Email:    "user@example.com",
        Password: "secret123",
    }

    // Process the data.
    masked := c.Any(user)

    // Print the result.
    fmt.Printf("%+v\n", masked)
    // Output: {"ID": "123","Email": "[CENSORED]","Password": "[CENSORED]"}
}

Using Regular Expressions

Censor supports masking values that match specific regular expression patterns. This is useful when you need to mask sensitive data that follows a particular format, such as email addresses, credit card numbers, or other structured sensitive information.

While regular expressions are compiled once during Censor's initialization for optimal performance, keep in mind that each string processed by Censor will be matched against all registered patterns. This introduces some processing overhead, so consider the performance impact when defining multiple patterns.

package main

import (
    "fmt"
    "log/slog"

    "github.com/vpakhuchyi/censor"
)

type email struct {
    Text string `censor:"display"`
}

func main() {
    // This regular expression matches email addresses.
    const emailPattern = `(?P<email>[\w.%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,4})`

    // This regular expression matches IBANs.
    const ibanPattern = `([A-Z]{2}[0-9]{27})`

    cfg := censor.Config{
        General: censor.General{
            OutputFormat: censor.OutputFormatJSON,
        },
        Encoder: censor.EncoderConfig{
            // We can add exclude patterns to censor to make sure that the values that match the pattern will be masked.
            ExcludePatterns: []string{emailPattern, ibanPattern},
            MaskValue:       censor.DefaultMaskValue,
        },
    }

    // Create a new instance of censor.Processor with the specified configuration and set it as a global processor.
    // This allows us to use the global instance from the censor package without needing to pass it as a dependency.
    censor.SetGlobalInstance(censor.NewWithOpts(censor.WithConfig(&cfg)))

    const msg = `Here are the details of your account: email=user.example.email@ggmail.com, IBAN=UA123456789123456789123456789`

    v := email{Text: msg}

    fmt.Println(censor.Any(v))
    // Output: {"Text": "Here are the details of your account: email=[CENSORED], IBAN=[CENSORED]"}
}

Next Steps

Ready to explore more? Check out these guides:

1. Configuration - Customize Censor's behavior
2. Type Support - Learn about supported Go types
3. Logger Integration - Integrate with logging frameworks
4. Examples - See practical examples

Getting Help

• Open an issue if you find a bug
• Start a discussion for questions and ideas

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.