Module:ShaderDoc

Documentation for this module may be created at Module:ShaderDoc/doc

--[[

This module provides several functions used in the "Shader_Documentation" template

]]

local shader_doc = {}

--[[
sbo_toggles

Takes a list of names and converts them to a list of template parameters,
setting them to 1.

Usage:
{{#invoke:ShaderDoc|sbo_toggles|toggle_1,toggle_2,toggle_3,etc}}

parameters:
    [1]: A list of comma separated names
]]
function shader_doc.sbo_toggles( frame )
    local toggles = frame.args[1] or '';

    local toggle_list = mw.text.split( toggles, ',' );
    local result = '';

    for _, toggle in ipairs( toggle_list ) do
        local trimmed_toggle = mw.text.trim(toggle);
        if #trimmed_toggle > 0 then
            result = result .. '|| ' .. trimmed_toggle .. '=1\n';
        end
    end

    return result
end

--[[
shader_link_list

This function produces a bullet list of links to shaders

Usage:
{{#invoke:ShaderDoc|shader_link_list|game=game_name|shaders=shader_a,shader_b,shader_c,etc}}

parameters:
    game: The shader link prefix
    shaders: A comma separated list of shaders to list
]]
function shader_doc.shader_link_list( frame )
    local game = frame.args['game'];
    local shaders = frame.args['shaders'];

    if game == nil then
        return shader_doc._error( 'Game not specified' );
    end

    if shaders == nil then
        return shader_doc._error( 'Shaders not specified' );
    end

    local shader_list = mw.text.split( shaders, ',' );
    local result = '';

    for _, shader in ipairs( shader_list ) do
        local trimmed_shader = mw.text.trim(shader);

        if #trimmed_shader > 0 then
            result = result .. '* [[' .. game .. ' Shaders - ' .. trimmed_shader .. '|' .. trimmed_shader .. ']]\n';
        end
    end

    return result;

end

--[[
shader_table

This function converts comma separated items to a list row

Usage:
{{#invoke:ShaderDoc|technical_features|cell1,cell2,cell3}}

info:
commas (,) = seperate items
underscores (_) before commas = span to the next cell
semicolons (;) = seperate rows
backslash  (\) before any of these 4: escape
]]
function shader_doc.shader_table( frame )
    local contents = frame.args[1];

    if contents == nil then
        return shader_doc._error( 'No contents' );
    end

    if #contents > 0 and string.sub(contents, -1) ~= ';' then
        contents = contents .. ';';
    end

    local current_cell_text = '';
    local span_length = 0;
    local current_row = {};
    local rows = {};
    local escaped = false;

    for cp in mw.ustring.gcodepoint( contents ) do
        local char = mw.ustring.char( cp );
        local skip = false;

        if span_length > 0 then
            if char == '_' then
                span_length = span_length + 1;
                skip = true;
            elseif char ~= ',' and char ~= ';' then
                for i = 1,span_length,1 do
                    current_cell_text = current_cell_text .. '_'
                end
                span_length = 0;
            end
        end

        if escaped and not skip then
            escaped = false;
            current_cell_text = current_cell_text .. char;
            skip = true;
        end

        if not skip then
            if char == '\\' then
                escaped = true;
            elseif char == '_' then
                span_length = 1;
            elseif char == ',' or char == ';' then
                
                table.insert(current_row, {
                    ['text'] = current_cell_text,
                    ['span_length'] = span_length
                });

                span_length = 0;
                current_cell_text = '';

                if char == ';' then
                    table.insert(rows, current_row);
                    current_row = {};
                end
            else
                current_cell_text = current_cell_text .. char;
            end
        end
    end

    local result = '';
    
    for i, row in ipairs(rows) do
        result = result .. '|-\n';
        for j, cell in ipairs(row) do
            if j == 1 then
                result = result .. '!';
            else
                result = result .. '|';
            end

            span_length = cell['span_length'];
            if span_length > 0 then
                result = result .. 'colspan="' .. (span_length + 1) .. '"|';
            end

            current_cell_text = mw.text.trim(cell['text']);

            if #current_cell_text == 0 then
                current_cell_text = 'N/A';
            end

            if j == 1 then
                current_cell_text = '<code>' .. current_cell_text .. '</code>';
            end

            result = result .. current_cell_text .. '\n';
        end
    end

    return result;
end

--[[
technical_features

This function produces single column table rows with code formatting.

Usage:
{{#invoke:ShaderDoc|technical_features|feature_a,feature_b,feature_c,etc}}

parameters:
    features: A comma separated list of technical features
]]
function shader_doc.technical_features( frame )
    local features = frame.args[1];

    if features == nil then
        return shader_doc._error( 'Features not specified' );
    end

    local feature_list = mw.text.split( features, ',' );
    local result = '';

    for _, feature in ipairs( feature_list ) do
        local trimmed_feature = mw.text.trim(feature);
        if #trimmed_feature > 0 then
            result = result .. '|-\n|<code>' .. trimmed_feature .. '</code>\n';
        end
    end

    return result;
end

--[[
Helper function to handle error messages.
]]
function shader_doc._error( error_str )
	local frame = mw.getCurrentFrame();
	local error_category = frame.args.error_category or 'Errors reported by Module String';
	local ignore_errors = frame.args.ignore_errors or false;
	local no_category = frame.args.no_category or false;

	if shader_doc._getBoolean(ignore_errors) then
		return '';
	end

	local error_str = '<strong class="error">String Module Error: ' .. error_str .. '</strong>';
	if error_category ~= '' and not shader_doc._getBoolean( no_category ) then
		error_str = '[[Category:' .. error_category .. ']]' .. error_str;
	end

	return error_str;
end

--[[
Helper Function to interpret boolean strings
]]
function shader_doc._getBoolean( boolean_str )
	local boolean_value;

	if type( boolean_str ) == 'string' then
		boolean_str = boolean_str:lower();
		if boolean_str == 'false' or boolean_str == 'no' or boolean_str == '0'
				or boolean_str == '' then
			boolean_value = false;
		else
			boolean_value = true;
		end
	elseif type( boolean_str ) == 'boolean' then
		boolean_value = boolean_str;
	else
		error( 'No boolean value found' );
	end
	return boolean_value
end

return shader_doc;