Módulo:String

[ máis información | ver o historial | purgar | crear as instrucións | ver as instrucións ]
Indicacións de uso do módulo
Aínda non se redactaron as instrucións sobre como usar este módulo.
Engadir a explicación sobre o seu uso.
[ máis información | ver o historial | purgar | crear as instrucións | ver as instrucións ]
Os editores poden probar cambios no mesmo en Módulo:String/probas.
Por favor, engade as categorías na subpáxina de documentación e os interwikis no Wikidata. Ver as subpáxinas deste módulo.
--[[  
Este módulo está destinado a proporcionar acceso ás funcións de cadena (string) básicas.
]]

local str = {}

--[[
len

Parametros
    s: A cadea a encontrar a súa lonxitude 

]]
function str.len( frame )
    local new_args = str._getParameters( frame.args, {'s'} );
    local s = new_args['s'] or '';
    return mw.ustring.len( s )
end

--[[
sub

Parámetros
    s: A cadea onde extraer a subcadena 
    i: A cadea onde extraer a subcadena.
    j: Índice final da subcadena, por defecto a lonxitude total, ata o último carácter.
    
]]
function str.sub( frame )
    local new_args = str._getParameters( frame.args, { 's', 'i', 'j' } );
    local s = new_args['s'] or '';
    local i = tonumber( new_args['i'] ) or 1;
    local j = tonumber( new_args['j'] ) or -1;
    
    local len = mw.ustring.len( s );

    -- Convertir negativos para la comprobación de rango
    if i < 0 then
        i = len + i + 1;
    end
    if j < 0 then
        j = len + j + 1;
    end
    
    if i > len or j > len or i < 1 or j < 1 then
        return str._error( 'Índice fóra do rango da cadea' );
    end
    if j < i then
        return str._error( 'Índices da cadea non ordenados' );
    end
    
    return mw.ustring.sub( s, i, j )
end

--[[
match

Parámetros
   s: cadea onde se fai a búsqueda 
   pattern: patrón ou cadea a buscar. 
   start: índice da cadena onde empezar a buscar, por defecto 1, o primer carácter. 
   match: se se atopan múltiples coincidencias, especifica cal delas devolver. Por defecto é 1, l
       a primeira coincidencia atopada. Un número negativo conta dende o final, polo tanto 
       match = -1 é a última coincidencia. 
   plain: indica se o patrón debe interpretarse como texto limpio, por defecto 'false'. nomatch: en caso de 
       non atopar ninguhna coincidencia, devolve o valor de "nomatch" en lugar dun erro. 
       Se o número match ou o índice start están fóra do rango da cadea, entón a función xera un erro. 
       Tamén xera un erro se non atopa ningunha coincidencia. 
       Co parámetro global ignore_errors = true suprímese o    
       erro e devolve unha cadea baleira.
]]
function str.match( frame )
    local new_args = str._getParameters( frame.args, {'s', 'pattern', 'start', 'match', 'plain', 'nomatch'} );
    local s = new_args['s'] or '';
    local start = tonumber( new_args['start'] ) or 1;
    local plain_flag = str._getBoolean( new_args['plain'] or false );
    local pattern = new_args['pattern'] or '';
    local match_index = math.floor( tonumber(new_args['match']) or 1 );
    local nomatch = new_args['nomatch'];
    
    if s == '' then
        return str._error( 'A cadea onde buscar está baleira' );
    end
    if pattern == '' then
        return str._error( 'A cadea de búsqueda está baleira ' );
    end
    if math.abs(start) < 1 or math.abs(start) > mw.ustring.len( s ) then
        return str._error( 'Índice d\'inicio fóra do rango da cadena ' );
    end
    if match_index == 0 then
        return str._error( 'Número de coincidencias fóra de rango' );
    end
    if plain_flag then
        pattern = str._escapePattern( pattern );
    end
    
    local result
    if match_index == 1 then
        -- Atopar a primeira coincidencia é un caso sinxelo.
        result = mw.ustring.match( s, pattern, start )
    else
        if start > 1 then
            s = mw.ustring.sub( s, start );
        end
        
        local iterator = mw.ustring.gmatch(s, pattern);
        if match_index > 0 then
            -- Búsqueda cara a adiante
            for w in iterator do
                match_index = match_index - 1;
                if match_index == 0 then
                    result = w;
                    break;
                end
            end    
        else
            -- Inverte búsqueda
            local result_table = {};
            local count = 1;
            for w in iterator do
                result_table[count] = w;
                count = count + 1;
            end
            
            result = result_table[ count + match_index ];            
        end
    end        
    
    if result == nil then
        if nomatch == nil then
            return str._error( 'Ningunha coincidencia atopada' );
        else
            return nomatch;
        end
    else
        return result;
    end
end

--[[
pos

Parámetros
   target: Cadea onde buscar. 
   pos: Índice do carácter a devolver. 
]]
function str.pos( frame )
    local new_args = str._getParameters( frame.args, {'target', 'pos'} );
    local target_str = new_args['target'] or '';
    local pos = tonumber( new_args['pos'] ) or 0;

    if pos == 0 or math.abs(pos) > mw.ustring.len( target_str ) then
        return str._error( 'Índice fora do rango da cadena' );
    end    
    
    return mw.ustring.sub( target_str, pos, pos );
end

--[[
find

Parámetros
    source: Cadea onde buscar. 
    target: Cadea a buscar ou patrón de búsqueda. 
    start: Índice da cadea fonte onde empezar a buscar, por defecto 1, o primer carácter. 
    plain: Indica se a búsqueda debe interpretarse como texto limpio, do contrario como patrón Lua. 
        Por defecto é 'true'.
]]
function str.find( frame )
    local new_args = str._getParameters( frame.args, {'source', 'target', 'start', 'plain' } ); 
    local source_str = new_args['source'] or '';
    local pattern = new_args['target'] or '';
    local start_pos = tonumber(new_args['start']) or 1;
    local plain = new_args['plain'] or true;
        
    if source_str == '' or pattern == '' then
        return 0;
    end    
    
    plain = str._getBoolean( plain );

    local start = mw.ustring.find( source_str, pattern, start_pos, plain )
    if start == nil then
        start = 0
    end
    
    return start
end

--[[
replace

Parámetros
    source: Cadea onde buscar 
    pattern: Cadea de búsqueda ou patrón a buscar 
    replace: Texto de substitución 
    count: Número de ocurrencias a substituír, por defecto todas. 
    plain: Indica si a búsqueda debe interpretarse como texto limpio, do contrario como patrón Lua. Por 
        defecto é 'true' 
]]
function str.replace( frame )
    local new_args = str._getParameters( frame.args, {'source', 'pattern', 'replace', 'count', 'plain' } ); 
    local source_str = new_args['source'] or '';
    local pattern = new_args['pattern'] or '';
    local replace = new_args['replace'] or '';
    local count = tonumber( new_args['count'] );
    local plain = new_args['plain'] or true;
        
    if source_str == '' or pattern == '' then
        return source_str;
    end    
    plain = str._getBoolean( plain );

    if plain then
        pattern = str._escapePattern( pattern );
        replace = mw.ustring.gsub( replace, "%%", "%%%%" ); --Sólo es necesario secuencias de escape.
    end
    
    local result;

    if count ~= nil then
        result = mw.ustring.gsub( source_str, pattern, replace, count );
    else
        result = mw.ustring.gsub( source_str, pattern, replace );
    end        

    return result;
end

function str.mayuscula(frame) -- Convierte en mayúsculas la primera letra que aparece en la edición de una cadena
    local s = frame.args[1] or '';
    if s  ~= '' then        
        local cambio = {};
        local modo = {};
        if string.find(s, '|') ~= nil then -- Enlaces con etiqueta
            modo = string.upper(string.match(s,'(|%a)'));
            cambio = string.gsub(s,'|%a', modo,1);
        elseif string.find(s, '[[]') ~= nil then -- Enlaces sin etiqueta
            modo = string.upper(string.match(s,'^(..%a)'));
            cambio = string.gsub(s,'^..%a', modo,1);
        elseif string.match(s,'^%a') ~= nil then -- Sin enlace
           modo = string.upper(string.match(s,'^(%a)'));
           cambio = string.gsub(s,'^%a', modo, 1);
        else
           cambio = s;
        end
        return cambio;
    end
end

--[[
Función de axuda que enche a lista de argumentos, para que o usuario poida utilizar unha combinación de
 parámetros con nome e sen nombre. Isto é importante porque os parámetros con nome non funcionan igual 
 que os parámetros sen nome cando se encadenan recortes, e cuando se trata de cadeas
 ás veces débese conservar ou quitar espazos en branco dependendo da aplicación. 
]]
function str._getParameters( frame_args, arg_list )
    local new_args = {};
    local index = 1;
    local value;
    
    for i,arg in ipairs( arg_list ) do
        value = frame_args[arg]
        if value == nil then
            value = frame_args[index];
            index = index + 1;
        end
        new_args[arg] = value;
    end
    
    return new_args;
end        

--[[
Función de axuda para controlar as mensaxes de error.
]]
function str._error( error_str )
    local frame = mw.getCurrentFrame();
    local error_category = frame.args.error_category or 'Erros detectados polo módulo String';
    local ignore_errors = frame.args.ignore_errors or false;
    local no_category = frame.args.no_category or false;
    
    if str._getBoolean(ignore_errors) then
        return '';
    end
    
    local error_str = '<strong class="error">Erro do módulo String: ' .. error_str .. '</strong>';
    if error_category ~= '' and not str._getBoolean( no_category ) then
        error_str = '[[Categoría:Wikipedia:' .. error_category .. ']]' .. error_str;
    end        
    
    return error_str;
end

--[[
Función de axuda para interpretar cadeas booleanas.
]]
function str._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( 'Ningún valor booleano atopado' );
    end    
    return boolean_value
end

--[[
Función de axuda que escapa a todos os caracteres de patrón para que puedan ser tratados
como texto sen formato.
]]
function str._escapePattern( pattern_str )
    return mw.ustring.gsub( pattern_str, "([%(%)%.%%%+%-%*%?%[%^%$%]])", "%%%1" );
end

return str