badges

README

badges

go package for generate badges in repositories

Usage

Install the command:

go install github.com/cdvelop/badges/cmd/badges@latest

Then, you can use it in your project's root directory:

badges

This will generate a docs/img/badges.svg file and update your README.md with the badges.

You can also customize the behavior with flags:

badges -test-status="Failing" -coverage=50

Available flags

• -module-name: Module name (default: "testmodule")
• -test-status: Test status (default: "Passing")
• -coverage: Coverage percentage (default: "85")
• -race-status: Race status (default: "Clean")
• -vet-status: Vet status (default: "OK")
• -license: License type (default: "MIT")
• -readme: Readme file (default: "README.md")

Documentation

Index

• type Badge
• type BadgesHandler
  • func NewBadgeHandler(args ...string) *BadgesHandler
  • func (h *BadgesHandler) BadgeMarkdown() string
  • func (h *BadgesHandler) BuildBadges() ([]string, error)
  • func (h *BadgesHandler) Err() error
  • func (h *BadgesHandler) GenerateSVG() ([]byte, int, error)
  • func (h *BadgesHandler) OutputFile() string
  • func (h *BadgesHandler) ReadmeFile() string

Types

type Badge

type Badge struct {
	Label string // The text displayed on the left side of the badge.
	Value string // The text displayed on the right side of the badge.
	Color string // The background color for the value part of the badge (e.g., "#4c1" or "green").
}

Badge represents a single badge with a label, value, and color. This is the primary struct used to define a badge's appearance and content.

For example, to create a "Go version" badge, you might use:

b := Badge{
  Label: "Go",
  Value: "1.18",
  Color: "#007d9c",
}

type BadgesHandler

type BadgesHandler struct {
	// contains filtered or unexported fields
}

BadgesHandler is responsible for creating and managing a collection of badges. It handles parsing input arguments, generating the SVG image, and preparing the necessary markdown to embed the badges in a file.

The handler is configured using a series of string arguments, where each argument defines a badge in the "label:value:color" format.

Special commands can be passed as arguments to control the output:

• "output_svgfile:path/to/your.svg": Specifies the output file for the SVG image.
• "readmefile:path/to/your/README.md": Specifies the markdown file to be updated.

func NewBadgeHandler

func NewBadgeHandler(args ...string) *BadgesHandler

NewBadgeHandler creates and initializes a new BadgesHandler.

It takes a variadic slice of strings as input. Each string can be a badge definition ("label:value:color") or a special command.

Example:

handler := NewBadgeHandler(
  "Go:1.18:#007d9c",
  "Tests:Passing:#4c1",
  "output_svgfile:docs/badges.svg",
)

func (*BadgesHandler) BadgeMarkdown

func (h *BadgesHandler) BadgeMarkdown() string

BadgeMarkdown generates the markdown snippet for embedding the badge image. The snippet is an HTML `<a>` tag containing an `<img>` tag, which is compatible with most markdown renderers.

Example output:

<a href="docs/img/badges.svg"><img src="docs/img/badges.svg" alt="Project Badges" title="..."></a>

func (*BadgesHandler) BuildBadges

func (h *BadgesHandler) BuildBadges() ([]string, error)

BuildBadges generates the SVG image, writes it to the specified output file, and returns a slice of strings intended for updating a markdown file.

The returned slice contains the following elements in order: 1. sectionID: The ID of the markdown section to update. 2. afterLine: The line number after which the content should be inserted. 3. content: The markdown content to be inserted. 4. readmeFile: The path to the markdown file to be updated.

This method centralizes the core logic of badge generation and file I/O.

func (*BadgesHandler) Err

func (h *BadgesHandler) Err() error

Err returns any error that occurred during the initialization or processing of the BadgesHandler. It's important to check this error before proceeding with badge generation.

func (*BadgesHandler) GenerateSVG

func (h *BadgesHandler) GenerateSVG() ([]byte, int, error)

GenerateSVG creates an SVG image from the configured badges.

It returns the SVG content as a byte slice, the number of badges included, and an error if the generation fails. This method is typically called by BuildBadges, but it can be used directly if you only need the SVG data.

Example of a generated SVG for two badges ("License:MIT:blue" and "Go:1.22:blue"):

<?xml version="1.0" encoding="UTF-8"?> <svg xmlns="http://www.w3.org/2000/svg" width="168" height="20" viewBox="0 0 168 20">

<!-- Badge: License -->
<g transform="translate(0, 0)">
  <rect x="0" y="0" width="58" height="20" fill="#6c757d"/>
  <rect x="58" y="0" width="46" height="20" fill="blue"/>
  <text x="29" y="14" text-anchor="middle" font-family="sans-serif" font-size="11" fill="white">License</text>
  <text x="81" y="14" text-anchor="middle" font-family="sans-serif" font-size="11" fill="white">MIT</text>
</g>
<!-- Badge: Go -->
<g transform="translate(109, 0)">
  <rect x="0" y="0" width="34" height="20" fill="#6c757d"/>
  <rect x="34" y="0" width="25" height="20" fill="blue"/>
  <text x="17" y="14" text-anchor="middle" font-family="sans-serif" font-size="11" fill="white">Go</text>
  <text x="46" y="14" text-anchor="middle" font-family="sans-serif" font-size="11" fill="white">1.22</text>
</g>

</svg>

func (*BadgesHandler) OutputFile

func (h *BadgesHandler) OutputFile() string

OutputFile returns the configured path for the output SVG file. This is the destination where the generated SVG image will be saved.

func (*BadgesHandler) ReadmeFile

func (h *BadgesHandler) ReadmeFile() string

ReadmeFile returns the configured path for the markdown file to be updated.