awesomewm-mirrors
/
awesome
mirror of https://github.com/awesomeWM/awesome.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: Add an index of valid properties to awful.spawn and awful.rules.

This commit is contained in:
Emmanuel Lepage Vallee 2018-10-07 01:29:41 -04:00
parent 62c95d5fe6
commit b49f7e22dd
7 changed files with 170 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
awesomeConfig.cmake
View File

@ -367,7 +367,26 @@ add_custom_command(
OUTPUT ${BUILD_DIR}/docs/06-appearance.md OUTPUT ${BUILD_DIR}/docs/06-appearance.md
COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua
${BUILD_DIR}/docs/06-appearance.md ${BUILD_DIR}/docs/06-appearance.md
DEPENDS lgi-check-run ${SOURCE_DIR}/docs/06-appearance.md.lua DEPENDS
lgi-check-run
${SOURCE_DIR}/docs/06-appearance.md.lua
${SOURCE_DIR}/docs/_parser.lua
)
add_custom_command(
OUTPUT ${BUILD_DIR}/docs/common/rules_index.ldoc
COMMAND lua ${SOURCE_DIR}/docs/build_rules_index.lua
${BUILD_DIR}/docs/common/rules_index.ldoc
# Cheap trick until the ldoc `configure_file` is ported to be a build
# step rather than part of cmake.
COMMAND ${CMAKE_COMMAND} -E copy ${BUILD_DIR}/docs/common/rules_index.ldoc
${SOURCE_DIR}/docs/common/rules_index.ldoc
DEPENDS
lgi-check-run
${SOURCE_DIR}/docs/build_rules_index.lua
${SOURCE_DIR}/docs/_parser.lua
) )
add_custom_command( add_custom_command(
@ -394,9 +413,13 @@ add_custom_target(generate_awesomerc DEPENDS
${SOURCE_DIR}/awesomerc.lua ${SOURCE_DIR}/awesomerc.lua
${BUILD_DIR}/docs/06-appearance.md ${BUILD_DIR}/docs/06-appearance.md
${SOURCE_DIR}/docs/05-awesomerc.md.lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua
${SOURCE_DIR}/docs/build_rules_index.lua
${BUILD_DIR}/docs/common/rules_index.ldoc
${SOURCE_DIR}/docs/sample_theme.lua ${SOURCE_DIR}/docs/sample_theme.lua
${SOURCE_DIR}/docs/sample_files.lua ${SOURCE_DIR}/docs/sample_files.lua
${SOURCE_DIR}/awesomerc.lua ${SOURCE_DIR}/awesomerc.lua
${awesome_c_configure_files}
${awesome_lua_configure_files}
) )

173
docs/06-appearance.md.lua
View File

@ -1,174 +1,14 @@
#! /usr/bin/lua #! /usr/bin/lua
local args = {...} local args = {...}
local parser = require("docs._parser")
local gio = require("lgi").Gio local gio = require("lgi").Gio
local gobject = require("lgi").GObject local gobject = require("lgi").GObject
local glib = require("lgi").GLib local glib = require("lgi").GLib
local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME local paths = parser.get_all_files("./lib/", "lua", parser.get_all_files("./", "c"))
local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE
-- Like pairs(), but iterate over keys in a sorted manner. Does not support local beautiful_vars = parser.parse_files(paths, "beautiful")
-- modifying the table while iterating.
local function sorted_pairs(t)
-- Collect all keys
local keys = {}
for k in pairs(t) do
table.insert(keys, k)
end
table.sort(keys)
-- return iterator function
local i = 0
return function()
i = i + 1
if keys[i] then
return keys[i], t[keys[i]]
end
end
end
-- Recursive file scanner
local function get_all_files(path, ext, ret)
ret = ret or {}
local enumerator = gio.File.new_for_path(path):enumerate_children(
table.concat({name_attr, type_attr}, ",") , 0, nil, nil
)
for file in function() return enumerator:next_file() end do
local file_name = file:get_attribute_as_string(name_attr)
local file_type = file:get_file_type()
if file_type == "REGULAR" and file_name:match(ext or "") then
table.insert(ret, enumerator:get_child(file):get_path())
elseif file_type == "DIRECTORY" then
get_all_files(enumerator:get_child(file):get_path(), ext, ret)
end
end
return ret
end
local function path_to_module(path)
for _, module in ipairs {
"awful", "wibox", "gears", "naughty", "menubar", "beautiful"
} do
local match = path:match("/"..module.."/([^.]+).lua")
if match then
return module.."."..match:gsub("/",".")
end
end
error("Cannot figure out module for " .. tostring(path))
end
local function path_to_html(path)
local mod = path_to_module(path):gsub(".init", "")
local f = assert(io.open(path))
while true do
local line = f:read()
if not line then break end
if line:match("@classmod") then
f:close()
return "../classes/".. mod ..".html"
end
if line:match("@module") or line:match("@submodule") then
f:close()
return "../libraries/".. mod ..".html"
end
end
f:close()
error("Cannot figure out if module or class: " .. tostring(path))
end
local function get_link(file, element)
return table.concat {
"<a href='",
path_to_html(file),
"#",
element,
"'>",
element:match("[. ](.+)"),
"</a>"
}
end
local all_files = get_all_files("./lib/", "lua")
table.sort(all_files)
local beautiful_vars = {}
-- Find all @beautiful doc entries
for _,file in ipairs(all_files) do
local f = io.open(file)
local buffer = ""
for line in f:lines() do
local var = line:gmatch("--[ ]*@beautiful ([^ \n]*)")()
-- There is no backward/forward pattern in lua
if #line <= 1 then
buffer = ""
elseif #buffer and not var then
buffer = buffer.."\n"..line
elseif line:sub(1,3) == "---" then
buffer = line
end
if var then
-- Get the @param, @see and @usage
local params = ""
for line in f:lines() do
if line:sub(1,2) ~= "--" then
break
else
params = params.."\n"..line
end
end
local name = var:gmatch("[ ]*beautiful.(.+)")()
if not name then
print("WARNING:", var,
"seems to be misformatted. Use `beautiful.namespace_name`"
)
else
table.insert(beautiful_vars, {
file = file,
name = name,
link = get_link(file, var),
desc = buffer:gmatch("[- ]+([^\n.]*)")() or "",
mod = path_to_module(file),
})
end
buffer = ""
end
end
end
local function create_table(entries, columns)
local lines = {}
for _, entry in ipairs(entries) do
local line = " <tr>"
for _, column in ipairs(columns) do
line = line.."<td>"..entry[column].."</td>"
end
table.insert(lines, line.."</tr>\n")
end
return [[<br \><br \><table class='widget_list' border=1>
<tr style='font-weight: bold;'>
<th align='center'>Name</th>
<th align='center'>Description</th>
</tr>]] .. table.concat(lines) .. "</table>\n"
end
local override_cats = { local override_cats = {
["border" ] = true, ["border" ] = true,
@ -200,7 +40,7 @@ local function create_sample(entries)
" local theme = {}" " local theme = {}"
} }
for name, cat in sorted_pairs(categorize(entries)) do for name, cat in parser.sorted_pairs(categorize(entries)) do
table.insert(ret, "\n -- "..name) table.insert(ret, "\n -- "..name)
for _, v in ipairs(cat) do for _, v in ipairs(cat) do
table.insert(ret, " -- theme."..v.name.." = nil") table.insert(ret, " -- theme."..v.name.." = nil")
@ -217,6 +57,7 @@ local function create_sample(entries)
return table.concat(ret, '\n') return table.concat(ret, '\n')
end end
-- Create the file -- Create the file
local filename = args[1] local filename = args[1]
@ -229,8 +70,9 @@ f:write[[
Beautiful is where Awesome theme variables are stored. Beautiful is where Awesome theme variables are stored.
<br /><br />
]] ]]
f:write(create_table(beautiful_vars, {"link", "desc"})) f:write(parser.create_table(beautiful_vars, {"link", "desc"}))
f:write("\n\n## Sample theme file\n\n") f:write("\n\n## Sample theme file\n\n")
@ -241,6 +83,5 @@ f:close()
--TODO add some linting to direct undeclared beautiful variables --TODO add some linting to direct undeclared beautiful variables
--TODO re-generate all official themes --TODO re-generate all official themes
--TODO generate a complete sample theme --TODO generate a complete sample theme
--TODO also parse C files.
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

37
docs/_parser.lua
View File

@ -88,30 +88,24 @@ function module.path_to_html(path)
error("Cannot figure out if module or class: " .. tostring(path)) error("Cannot figure out if module or class: " .. tostring(path))
end end
local function get_link(file, element) local function get_link(file, element, element_name)
return table.concat { return table.concat {
"<a href='", "<a href='",
module.path_to_html(file), module.path_to_html(file),
element, element,
"'>", "'>",
element:match("[. ](.+)"), element_name,
"</a>" "</a>"
} }
end end
local function parse_files(property_name, matcher) local function parse_files(paths, property_name, matcher, name_matcher)
local exp1 = "--[ ]*@".. property_name .." ([^ \n]*)" local exp1 = "[-*]*[ ]*@".. property_name .." ([^ \n]*)"
local exp2 = matcher or "--[ ]*".. property_name ..".(.+)" local exp2 = matcher or "[-*]*[ ]*".. property_name ..".(.+)"
local exp3 = name_matcher or "[. ](.+)"
local ret = {} local ret = {}
local paths = get_all_files("./lib/", "lua")
assert(paths)
for _, f in ipairs(get_all_files("./", "c")) do
table.insert(paths, f)
end
table.sort(paths) table.sort(paths)
-- Find all @beautiful doc entries -- Find all @beautiful doc entries
@ -133,12 +127,11 @@ local function parse_files(property_name, matcher)
buffer = line buffer = line
end end
if var then if var then
-- Get the @param, @see and @usage -- Get the @param, @see and @usage
local params = "" local params = ""
for line in f:lines() do for line in f:lines() do
if line:sub(1,2) ~= "--" then if line:sub(1,2) ~= "--" and line:sub(1,2) ~= " *" then
break break
else else
params = params.."\n"..line params = params.."\n"..line
@ -168,7 +161,8 @@ local function parse_files(property_name, matcher)
return ret return ret
end end
local function create_table(entries, columns) local function create_table(entries, columns, prefix)
prefix = prefix or ""
local lines = {} local lines = {}
for _, entry in ipairs(entries) do for _, entry in ipairs(entries) do
@ -178,14 +172,15 @@ local function create_table(entries, columns)
line = line.."<td>"..entry[column].."</td>" line = line.."<td>"..entry[column].."</td>"
end end
table.insert(lines, line.."</tr>\n") table.insert(lines, prefix..line.."</tr>\n")
end end
return [[<br \><br \><table class='widget_list' border=1> return [[--<table class='widget_list' border=1>
<tr style='font-weight: bold;'> ]]..prefix..[[<tr style='font-weight: bold;'>
<th align='center'>Name</th> ]]..prefix..[[ <th align='center'>Name</th>
<th align='center'>Description</th> ]]..prefix..[[ <th align='center'>Description</th>
</tr>]] .. table.concat(lines) .. "</table>\n" ]]..prefix..[[</tr>
]] .. table.concat(lines) .. prefix .."</table>\n"
end end
module.create_table = create_table module.create_table = create_table

30
docs/build_rules_index.lua Normal file
View File

@ -0,0 +1,30 @@
#! /usr/bin/lua
local args = {...}
local parser = require("docs._parser")
local files = {"./objects/client.c", "./lib/awful/client.lua"}
local matcher, matcher2 = "(.*)", ".*"
-- The client function comes from 5 different files, but all of those are
-- merged into one documentation page (aka, awful.client doesn't have content
-- anymore). This override the path so the parser doesn't have to be aware of it
function parser.path_to_html()
return "../classes/client.html#client."
end
local clientruleproperty = parser.parse_files(files, "clientruleproperty", matcher, matcher2)
for _, prop in ipairs(parser.parse_files(files, "property", matcher, matcher2)) do
table.insert(clientruleproperty, prop)
end
-- Create the file
local filename = args[1]
local f = io.open(filename, "w")
f:write(parser.create_table(clientruleproperty, {"link", "desc"}, "-- "))
f:close()
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

72
docs/common/rules_index.ldoc Normal file
View File

@ -0,0 +1,72 @@
--<table class='widget_list' border=1>
-- <tr style='font-weight: bold;'>
-- <th align='center'>Name</th>
-- <th align='center'>Description</th>
-- </tr>
-- <tr><td><a href='../classes/client.html#client.placement'>placement</a></td><td>The client default placement on the screen</td></tr>
-- <tr><td><a href='../classes/client.html#client.honor_padding'>honor\_padding</a></td><td>When applying the placement, honor the screen padding</td></tr>
-- <tr><td><a href='../classes/client.html#client.honor_workarea'>honor\_workarea</a></td><td>When applying the placement, honor the screen work area</td></tr>
-- <tr><td><a href='../classes/client.html#client.tag'>tag</a></td><td>The client default tag</td></tr>
-- <tr><td><a href='../classes/client.html#client.tags'>tags</a></td><td>The client default tags</td></tr>
-- <tr><td><a href='../classes/client.html#client.new_tag'>new\_tag</a></td><td>Create a new tag for this client</td></tr>
-- <tr><td><a href='../classes/client.html#client.switch_to_tags'>switch\_to\_tags</a></td><td>Unselect the current tags and select this client tags</td></tr>
-- <tr><td><a href='../classes/client.html#client.focus'>focus</a></td><td>Define if the client should grab focus by default</td></tr>
-- <tr><td><a href='../classes/client.html#client.titlebars_enabled'>titlebars\_enabled</a></td><td>Should this client have a titlebar by default</td></tr>
-- <tr><td><a href='../classes/client.html#client.callback'>callback</a></td><td>A function to call when this client is ready</td></tr>
-- <tr><td><a href='../classes/client.html#client.marked'>marked</a></td><td>If a client is marked or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.is_fixed'>is\_fixed</a></td><td>Return if a client has a fixed size or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.immobilized'>immobilized</a></td><td>Is the client immobilized horizontally?</td></tr>
-- <tr><td><a href='../classes/client.html#client.immobilized'>immobilized</a></td><td>Is the client immobilized vertically?</td></tr>
-- <tr><td><a href='../classes/client.html#client.floating'>floating</a></td><td>The client floating state</td></tr>
-- <tr><td><a href='../classes/client.html#client.x'>x</a></td><td>The x coordinates</td></tr>
-- <tr><td><a href='../classes/client.html#client.y'>y</a></td><td>The y coordinates</td></tr>
-- <tr><td><a href='../classes/client.html#client.width'>width</a></td><td>The width of the client</td></tr>
-- <tr><td><a href='../classes/client.html#client.height'>height</a></td><td>The height of the client</td></tr>
-- <tr><td><a href='../classes/client.html#client.dockable'>dockable</a></td><td>If the client is dockable</td></tr>
-- <tr><td><a href='../classes/client.html#client.requests_no_titlebar'>requests\_no\_titlebar</a></td><td>If the client requests not to be decorated with a titlebar</td></tr>
-- <tr><td><a href='../classes/client.html#client.shape'>shape</a></td><td>Set the client shape</td></tr>
-- <tr><td><a href='../classes/client.html#client.window'>window</a></td><td>The X window id</td></tr>
-- <tr><td><a href='../classes/client.html#client.name'>name</a></td><td>The client title</td></tr>
-- <tr><td><a href='../classes/client.html#client.skip_taskbar'>skip\_taskbar</a></td><td>True if the client does not want to be in taskbar</td></tr>
-- <tr><td><a href='../classes/client.html#client.type'>type</a></td><td>The window type</td></tr>
-- <tr><td><a href='../classes/client.html#client.class'>class</a></td><td>The client class</td></tr>
-- <tr><td><a href='../classes/client.html#client.instance'>instance</a></td><td>The client instance</td></tr>
-- <tr><td><a href='../classes/client.html#client.pid'>pid</a></td><td>The client PID, if available</td></tr>
-- <tr><td><a href='../classes/client.html#client.role'>role</a></td><td>The window role, if available</td></tr>
-- <tr><td><a href='../classes/client.html#client.machine'>machine</a></td><td>The machine client is running on</td></tr>
-- <tr><td><a href='../classes/client.html#client.icon_name'>icon\_name</a></td><td>The client name when iconified</td></tr>
-- <tr><td><a href='../classes/client.html#client.icon'>icon</a></td><td>The client icon as a surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.icon_sizes'>icon\_sizes</a></td><td>The available sizes of client icons</td></tr>
-- <tr><td><a href='../classes/client.html#client.screen'>screen</a></td><td>Client screen</td></tr>
-- <tr><td><a href='../classes/client.html#client.hidden'>hidden</a></td><td>Define if the client must be hidden, i</td></tr>
-- <tr><td><a href='../classes/client.html#client.minimized'>minimized</a></td><td>Define it the client must be iconify, i</td></tr>
-- <tr><td><a href='../classes/client.html#client.size_hints_honor'>size\_hints\_honor</a></td><td>Honor size hints, e</td></tr>
-- <tr><td><a href='../classes/client.html#client.border_width'>border\_width</a></td><td>The client border width</td></tr>
-- <tr><td><a href='../classes/client.html#client.border_color'>border\_color</a></td><td>The client border color</td></tr>
-- <tr><td><a href='../classes/client.html#client.urgent'>urgent</a></td><td>The client urgent state</td></tr>
-- <tr><td><a href='../classes/client.html#client.content'>content</a></td><td>A cairo surface for the client window content</td></tr>
-- <tr><td><a href='../classes/client.html#client.opacity'>opacity</a></td><td>The client opacity</td></tr>
-- <tr><td><a href='../classes/client.html#client.ontop'>ontop</a></td><td>The client is on top of every other windows</td></tr>
-- <tr><td><a href='../classes/client.html#client.above'>above</a></td><td>The client is above normal windows</td></tr>
-- <tr><td><a href='../classes/client.html#client.below'>below</a></td><td>The client is below normal windows</td></tr>
-- <tr><td><a href='../classes/client.html#client.fullscreen'>fullscreen</a></td><td>The client is fullscreen or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.maximized'>maximized</a></td><td>The client is maximized (horizontally and vertically) or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.maximized_horizontal'>maximized\_horizontal</a></td><td>The client is maximized horizontally or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.maximized_vertical'>maximized\_vertical</a></td><td>The client is maximized vertically or not</td></tr>
-- <tr><td><a href='../classes/client.html#client.transient_for'>transient\_for</a></td><td>The client the window is transient for</td></tr>
-- <tr><td><a href='../classes/client.html#client.group_window'>group\_window</a></td><td>Window identification unique to a group of windows</td></tr>
-- <tr><td><a href='../classes/client.html#client.leader_window'>leader\_window</a></td><td>Identification unique to windows spawned by the same command</td></tr>
-- <tr><td><a href='../classes/client.html#client.size_hints'>size\_hints</a></td><td>A table with size hints of the client</td></tr>
-- <tr><td><a href='../classes/client.html#client.motif_wm_hints'>motif\_wm\_hints</a></td><td>The motif WM hints of the client</td></tr>
-- <tr><td><a href='../classes/client.html#client.sticky'>sticky</a></td><td>Set the client sticky, i</td></tr>
-- <tr><td><a href='../classes/client.html#client.modal'>modal</a></td><td>Indicate if the client is modal</td></tr>
-- <tr><td><a href='../classes/client.html#client.focusable'>focusable</a></td><td>True if the client can receive the input focus</td></tr>
-- <tr><td><a href='../classes/client.html#client.shape_bounding'>shape\_bounding</a></td><td>The client's bounding shape as set by awesome as a (native) cairo surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.shape_clip'>shape\_clip</a></td><td>The client's clip shape as set by awesome as a (native) cairo surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.shape_input'>shape\_input</a></td><td>The client's input shape as set by awesome as a (native) cairo surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.client_shape_bounding'>client\_shape\_bounding</a></td><td>The client's bounding shape as set by the program as a (native) cairo surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.client_shape_clip'>client\_shape\_clip</a></td><td>The client's clip shape as set by the program as a (native) cairo surface</td></tr>
-- <tr><td><a href='../classes/client.html#client.startup_id'>startup\_id</a></td><td>The FreeDesktop StartId</td></tr>
-- <tr><td><a href='../classes/client.html#client.valid'>valid</a></td><td>If the client that this object refers to is still managed by awesome</td></tr>
-- <tr><td><a href='../classes/client.html#client.first_tag'>first\_tag</a></td><td>The first tag of the client</td></tr>
-- </table>

4
docs/load_ldoc.cmake
View File

@ -1,8 +1,7 @@
# To avoid copy pasting, some documentation is stored in reusable files # To avoid copy pasting, some documentation is stored in reusable files
set(SHAPE_FILE "${SOURCE_DIR}/docs/common/${SHAPE_NAME}.lua") set(SHAPE_FILE "${SOURCE_DIR}/docs/common/${SHAPE_NAME}.lua")
set(path "${SOURCE_DIR}/docs/common/") foreach(path ${BUILD_DIR}/docs/common/;${SOURCE_DIR}/docs/common/)
# Get the documentation file list # Get the documentation file list
file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc") file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc")
@ -19,5 +18,6 @@ foreach(doc_file_name ${doc_files})
# Create a new variable usable from lua files # Create a new variable usable from lua files
set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}") set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}")
endforeach() endforeach()
endforeach()
# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

18
lib/awful/rules.lua
View File

@ -8,17 +8,15 @@
-- to add random properties that will be later accessible as `c.property_name` -- to add random properties that will be later accessible as `c.property_name`
-- (where `c` is a valid client object) -- (where `c` is a valid client object)
-- --
-- In addition to the existing properties, the following are supported: -- Applicable client properties
-- ===
-- --
-- * placement -- The table below holds the list of default client properties along with
-- * honor_padding -- some extra properties that are specific to the rules. Note that any property
-- * honor_workarea -- can be set in the rules and interpreted by user provided code. This table
-- * tag -- only represent those offered by default.
-- * new_tag --
-- * switch_to_tags (also called switchtotag) --@DOC_rules_index_COMMON@
-- * focus
-- * titlebars_enabled
-- * callback
-- --
-- @author Julien Danjou &lt;julien@danjou.info&gt; -- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2009 Julien Danjou -- @copyright 2009 Julien Danjou