Create a gist now

Instantly share code, notes, and snippets.

@LPGhatguy /README.md
Last active Aug 29, 2015

What would you like to do?
An API to generate badges and place them in markdown readme files automatically using shields.io.

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
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
--[[
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()
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment