From b49f7e22dd2b34d2118b1f0e20271eb863352598 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 7 Oct 2018 01:29:41 -0400 Subject: [PATCH] doc: Add an index of valid properties to awful.spawn and awful.rules. --- awesomeConfig.cmake | 25 ++++- docs/06-appearance.md.lua | 173 ++--------------------------------- docs/_parser.lua | 37 ++++---- docs/build_rules_index.lua | 30 ++++++ docs/common/rules_index.ldoc | 72 +++++++++++++++ docs/load_ldoc.cmake | 26 +++--- lib/awful/rules.lua | 18 ++-- 7 files changed, 170 insertions(+), 211 deletions(-) create mode 100644 docs/build_rules_index.lua create mode 100644 docs/common/rules_index.ldoc diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index c22698beb..1d4a4e5e0 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -367,7 +367,26 @@ add_custom_command( OUTPUT ${BUILD_DIR}/docs/06-appearance.md COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua ${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( @@ -394,9 +413,13 @@ add_custom_target(generate_awesomerc DEPENDS ${SOURCE_DIR}/awesomerc.lua ${BUILD_DIR}/docs/06-appearance.md ${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_files.lua ${SOURCE_DIR}/awesomerc.lua + ${awesome_c_configure_files} + ${awesome_lua_configure_files} ) diff --git a/docs/06-appearance.md.lua b/docs/06-appearance.md.lua index 48fe4325e..cfb583b90 100644 --- a/docs/06-appearance.md.lua +++ b/docs/06-appearance.md.lua @@ -1,174 +1,14 @@ #! /usr/bin/lua local args = {...} +local parser = require("docs._parser") local gio = require("lgi").Gio local gobject = require("lgi").GObject local glib = require("lgi").GLib -local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME -local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE +local paths = parser.get_all_files("./lib/", "lua", parser.get_all_files("./", "c")) --- Like pairs(), but iterate over keys in a sorted manner. Does not support --- 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 { - "", - element:match("[. ](.+)"), - "" - } -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 = " " - - for _, column in ipairs(columns) do - line = line..""..entry[column].."" - end - - table.insert(lines, line.."\n") - end - - return [[

- - - - ]] .. table.concat(lines) .. "
NameDescription
\n" -end +local beautiful_vars = parser.parse_files(paths, "beautiful") local override_cats = { ["border" ] = true, @@ -200,7 +40,7 @@ local function create_sample(entries) " 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) for _, v in ipairs(cat) do table.insert(ret, " -- theme."..v.name.." = nil") @@ -217,6 +57,7 @@ local function create_sample(entries) return table.concat(ret, '\n') end + -- Create the file local filename = args[1] @@ -229,8 +70,9 @@ f:write[[ Beautiful is where Awesome theme variables are stored. +

]] -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") @@ -241,6 +83,5 @@ f:close() --TODO add some linting to direct undeclared beautiful variables --TODO re-generate all official themes --TODO generate a complete sample theme ---TODO also parse C files. -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/docs/_parser.lua b/docs/_parser.lua index 85abfc854..a75d8daf5 100644 --- a/docs/_parser.lua +++ b/docs/_parser.lua @@ -88,30 +88,24 @@ function module.path_to_html(path) error("Cannot figure out if module or class: " .. tostring(path)) end -local function get_link(file, element) +local function get_link(file, element, element_name) return table.concat { "", - element:match("[. ](.+)"), + element_name, "" } end -local function parse_files(property_name, matcher) - local exp1 = "--[ ]*@".. property_name .." ([^ \n]*)" - local exp2 = matcher or "--[ ]*".. property_name ..".(.+)" +local function parse_files(paths, property_name, matcher, name_matcher) + local exp1 = "[-*]*[ ]*@".. property_name .." ([^ \n]*)" + local exp2 = matcher or "[-*]*[ ]*".. property_name ..".(.+)" + local exp3 = name_matcher or "[. ](.+)" 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) -- Find all @beautiful doc entries @@ -133,12 +127,11 @@ local function parse_files(property_name, matcher) 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 + if line:sub(1,2) ~= "--" and line:sub(1,2) ~= " *" then break else params = params.."\n"..line @@ -168,7 +161,8 @@ local function parse_files(property_name, matcher) return ret end -local function create_table(entries, columns) +local function create_table(entries, columns, prefix) + prefix = prefix or "" local lines = {} for _, entry in ipairs(entries) do @@ -178,14 +172,15 @@ local function create_table(entries, columns) line = line..""..entry[column].."" end - table.insert(lines, line.."\n") + table.insert(lines, prefix..line.."\n") end - return [[

- - - - ]] .. table.concat(lines) .. "
NameDescription
\n" + return [[-- +]]..prefix..[[ +]]..prefix..[[ +]]..prefix..[[ +]]..prefix..[[ +]] .. table.concat(lines) .. prefix .."
NameDescription
\n" end module.create_table = create_table diff --git a/docs/build_rules_index.lua b/docs/build_rules_index.lua new file mode 100644 index 000000000..1e9341c4e --- /dev/null +++ b/docs/build_rules_index.lua @@ -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 diff --git a/docs/common/rules_index.ldoc b/docs/common/rules_index.ldoc new file mode 100644 index 000000000..b4fc76c44 --- /dev/null +++ b/docs/common/rules_index.ldoc @@ -0,0 +1,72 @@ +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
NameDescription
placementThe client default placement on the screen
honor\_paddingWhen applying the placement, honor the screen padding
honor\_workareaWhen applying the placement, honor the screen work area
tagThe client default tag
tagsThe client default tags
new\_tagCreate a new tag for this client
switch\_to\_tagsUnselect the current tags and select this client tags
focusDefine if the client should grab focus by default
titlebars\_enabledShould this client have a titlebar by default
callbackA function to call when this client is ready
markedIf a client is marked or not
is\_fixedReturn if a client has a fixed size or not
immobilizedIs the client immobilized horizontally?
immobilizedIs the client immobilized vertically?
floatingThe client floating state
xThe x coordinates
yThe y coordinates
widthThe width of the client
heightThe height of the client
dockableIf the client is dockable
requests\_no\_titlebarIf the client requests not to be decorated with a titlebar
shapeSet the client shape
windowThe X window id
nameThe client title
skip\_taskbarTrue if the client does not want to be in taskbar
typeThe window type
classThe client class
instanceThe client instance
pidThe client PID, if available
roleThe window role, if available
machineThe machine client is running on
icon\_nameThe client name when iconified
iconThe client icon as a surface
icon\_sizesThe available sizes of client icons
screenClient screen
hiddenDefine if the client must be hidden, i
minimizedDefine it the client must be iconify, i
size\_hints\_honorHonor size hints, e
border\_widthThe client border width
border\_colorThe client border color
urgentThe client urgent state
contentA cairo surface for the client window content
opacityThe client opacity
ontopThe client is on top of every other windows
aboveThe client is above normal windows
belowThe client is below normal windows
fullscreenThe client is fullscreen or not
maximizedThe client is maximized (horizontally and vertically) or not
maximized\_horizontalThe client is maximized horizontally or not
maximized\_verticalThe client is maximized vertically or not
transient\_forThe client the window is transient for
group\_windowWindow identification unique to a group of windows
leader\_windowIdentification unique to windows spawned by the same command
size\_hintsA table with size hints of the client
motif\_wm\_hintsThe motif WM hints of the client
stickySet the client sticky, i
modalIndicate if the client is modal
focusableTrue if the client can receive the input focus
shape\_boundingThe client's bounding shape as set by awesome as a (native) cairo surface
shape\_clipThe client's clip shape as set by awesome as a (native) cairo surface
shape\_inputThe client's input shape as set by awesome as a (native) cairo surface
client\_shape\_boundingThe client's bounding shape as set by the program as a (native) cairo surface
client\_shape\_clipThe client's clip shape as set by the program as a (native) cairo surface
startup\_idThe FreeDesktop StartId
validIf the client that this object refers to is still managed by awesome
first\_tagThe first tag of the client
diff --git a/docs/load_ldoc.cmake b/docs/load_ldoc.cmake index a783e7db4..161d49e02 100644 --- a/docs/load_ldoc.cmake +++ b/docs/load_ldoc.cmake @@ -1,23 +1,23 @@ # To avoid copy pasting, some documentation is stored in reusable files 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 + file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc") -# Get the documentation file list -file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc") + foreach(doc_file_name ${doc_files}) + # Read the file + file(READ "${path}/${doc_file_name}" doc_file_content) -foreach(doc_file_name ${doc_files}) - # Read the file - file(READ "${path}/${doc_file_name}" doc_file_content) + # Remove the file extension + string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name}) - # Remove the file extension - string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name}) + # There is a trailing \n, remove it or it cannot be included in existing blocks + string(REGEX REPLACE "\n$" "" doc_file_content "${doc_file_content}") - # There is a trailing \n, remove it or it cannot be included in existing blocks - string(REGEX REPLACE "\n$" "" doc_file_content "${doc_file_content}") - - # Create a new variable usable from lua files - set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}") + # Create a new variable usable from lua files + set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}") + endforeach() endforeach() # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua index f16741879..6b5684201 100644 --- a/lib/awful/rules.lua +++ b/lib/awful/rules.lua @@ -8,17 +8,15 @@ -- to add random properties that will be later accessible as `c.property_name` -- (where `c` is a valid client object) -- --- In addition to the existing properties, the following are supported: +-- Applicable client properties +-- === -- --- * placement --- * honor_padding --- * honor_workarea --- * tag --- * new_tag --- * switch_to_tags (also called switchtotag) --- * focus --- * titlebars_enabled --- * callback +-- The table below holds the list of default client properties along with +-- some extra properties that are specific to the rules. Note that any property +-- can be set in the rules and interpreted by user provided code. This table +-- only represent those offered by default. +-- +--@DOC_rules_index_COMMON@ -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou