An API to generate badges and place them in markdown readme files automatically using shields.io.

README.md

README Sample

This file is to be used with the example.lua file.

Here, we use Markdown's ability to use shortlink images:

Testing results: ![shield_build] ![shield_tests]

Version information: ![shield_dev_version]

Some projects might link to their latest released versions using the shields.io GitHub API: ![shield_release_version] ![shield_prerelease_version]

These links (visible only in plaintext view) are automatically updated by badges.lua. [shield_build]: https://img.shields.io/badge/build-unknown-lightgrey.svg?style=flat-square [shield_tests]: https://img.shields.io/badge/tests-0/0-lightgrey.svg?style=flat-square [shield_dev_version]: https://img.shields.io/badge/development-1.0.0-orange.svg?style=flat-square

These links are not automatically updated, but you can use them as a template with your own repository to have badges that fit in: [shield_release_version]: https://img.shields.io/github/release/lua-carbon/carbon.svg?style=flat-square [shield_prerelease_version]: https://img.shields.io/github/tag/lua-carbon/carbon.svg?style=flat-square&label=prerelease

badges.lua

--[[
	badges.lua

	A simple API to generate badges and place them in Markdown-driven readme files automatically.
]]

local badges = {
	readme_path = "readme.md",

	shields = {
		build = "[shield_build]: https://img.shields.io/badge/build-%s-%s.svg?style=flat-square",
		tests = "[shield_tests]: https://img.shields.io/badge/tests-%s/%s-%s.svg?style=flat-square",
		dev_version = "[shield_dev_version]: https://img.shields.io/badge/development-%s-orange.svg?style=flat-square"
	},

	updaters = {
		-- Unit test results
		function(self, body, data)
			local tests = data.tests or {}
			local pass = tests.pass or 0
			local fail = tests.fail or 0

			local pass_word = "unknown"
			local pass_color = "lightgrey"
			if (fail == 0 and pass > 0) then
				pass_word = "passing"
				pass_color = "green"
			elseif (fail > 0) then
				pass_word = "failing"
				pass_color = "red"
			end

			local total = pass + fail
			local ratio = pass / total
			local tests_color =
				ratio ~= ratio and "lightgrey" or -- NaN: zero tests
				ratio == 1.0 and "brightgreen" or
				ratio >= 0.5 and "yellow" or
				"red"

			return body
				:gsub("%[shield_build%]:[^\n]*", self.shields.build:format(pass_word, pass_color))
				:gsub("%[shield_tests%]:[^\n]*", self.shields.tests:format(pass, total, tests_color))
		end,

		-- Current dev version
		function(self, body, data)
			return body
				:gsub("%[shield_dev_version%]:[^\n]*", self.shields.dev_version:format((data.version:gsub("%-", "--"))))
		end
	}
}

function badges:update_readme_body(body, data)
	for i, updater in ipairs(self.updaters) do
		body = updater(self, body, data)
	end

	return body
end

--[[
	Updates readme with all results from testing and the likes.
	status structure:
		tests (table):
			pass (number)
			fail (number)
		version (string)
]]
function badges:update_readme(data)
	local path = self.readme_path
	local handle = assert(io.open(path, "r"))
	local body = handle:read("*a")
	handle:close()

	local updated = self:update_readme_body(body, data)

	local handle = assert(io.open(path, "w"))
	handle:write(updated)
	handle:close()
end

return badges

example.lua

--[[
badges.lua sample
See https://github.com/lua-carbon/carbon for how these badges can look on a real project.
]]

local badges = require("badges")
badges.readme_path = "README.md" -- Small configuration

local function main()
	local MyLib = require("MyLib")

	print("Test Suite for MyLib " .. MyLib._VERSION)

	local pass, fail = 0, 0

	-- Run your tests here and set the total number of passing tests as 'pass'
	-- and the number of failing tests as 'fail'.

	print("Tests complete!")

	-- Small pretty way to report test results.
	print(("Result:\n%-2d pass\n%-2d fail\noverall: %s"):format(
		pass,
		fail,
		fail == 0 and "PASS" or "FAIL"
	))

	-- Call badges.update_readme with our result data
	-- Badges will be updated automatically.
	badges:update_readme {
		tests = {
			pass = pass,
			fail = fail,
		},
		version = MyLib._VERSION
	}
	print("README updated successfully!")
end

main()