Helpo:Lua/Signoĉenoj

	Programado Modulo en Vikio; Certa ŝablono; Signoĉenoj; Ligiloj; Ĉirkaŭaĵo; Internaciigo; Koderoj; ; Fontokodo+antaŭrigardo;
	VP:LUA Moduloj; Organizado; Funkcioj kaj vikitekstoj; Petoj;
Kategorioj
	Ŝablonoj ; Moduloj ;
Ŝablonoj
	{{LuaModuleDoc}} por la dokumentado de modulo, por aranĝi la keston kun ligiloj; {{Modula statuso}} por la dokumentadoj de modulo, por indiki la evoluan statuson de modulo; {{Kun Lua-modulo}} por la dokumentado de ŝablono, kiu uzas Lua-modulon aŭ eĉ entute baziĝas sur modulo; {{Uzanto Projekto/Lua}} por uzantopaĝoj;
Vidu ankaŭ
	Lua; mw:Manual; 5.1 Manual germane; ; enwiki;
Komentoj
↑ (per {{Kun Lua-modulo}}) ; ↑ (per {{LuaModuleDoc}}) ;
	v • d • r

Ĉi tiu artikolo estas redaktata de Tlustulimu.

Por eviti la riskon de redaktokonflikto, ne redaktu la artikolon. Kontrolu la kronologion kaj forigu la ŝablonon, se necese.

Ĉi tiu helpopaĝo donas por Lua-programmistoj mallongan referencon pri la traktado de signoĉenoj en la Lua-programado.

ASCII kaj Unikodo

La Vikiaj projektoj estas skribataj en kompleta Unikodo, sed Lua tamen laboras nur kun 8-bit-kodo (ISO 8859-1).

Se la serĉa modelo limigas sin al ASCII, oni povas labori iomete pli efike kun la ASCII-funkcioj kaj respektivaj modeloj, ĉar la transformado de UTF-8 forfalas. La 8-bit-parto trans ASCII ne estas sencoplene uzebla, ĉar ĉi tie kuŝas la UTF-8-kodigoj.
Ĝenerala, ajnaj signoĉenoj de la Vikia teksto devas esti perlaborataj per la Ustring-funkcioj por Unikodo.

String-funkcioj (mallonga referenco)

→ Scribunto (angle):

Ĉiam estas donataj la funkcioj por ASCII kaj Unikodo; lasta kun mw.ustring.*().

Parametroj

La parametroj signifas:

s – ekira signoĉeno
- !!! Certigu datumtipon string !!!
pattern – Serĉa modelo
- Povas enhavi krampajn parojn (captures), kiuj estas ordigataj en grupojn al la rezultaj variabloj.
c – signo-kodo (ASCII aŭ codepoint)
i – starta indekso; -1: lasta signo.
- Komenciĝas per 1.
- Negativa: nombri ekde la fino.
j – fina indekso.
- Pozicio de la lasta signo; nombri ekde 1, inklude.
- Negativa: nombri ekde fino; -1: ĝis la fino
n – nombro (nedeviga)
init – starta indekso (nedeviga); povas esti negativa kaj tiam estas nombrata ekde la fino
plain – pattern ne kiel pattern-sintakso, sed litere (nedeviga)

La indeksaj numeroj ĉiam validas laŭ signoj; tio estas ĉe la ASCII-versio bajtoj.

Se Unikoda signoĉeno ne estas kodata ĝuste laŭ UTF-8, estas redonataj nil de mw.ustring.*. Tio ne estas atendebla de Vikia teksto, se oni mem ne ruinigis ĝin antaŭe.
Alie la redona valoro estas la nova signoĉeno resp. la demandita nombro en bajtoj resp. Unikodaj signoj.

Mallonga referenco

string.byte( s, i, j )
s:byte( i, j )
mw.ustring.byte( s, i, j )
mw.ustring.codepoint( s, i, j ): Ĉiu bajto/signo en unuopa variablo; r1, r2, r3, r4 = s:byte( i, j )
mw.ustring.byteoffset( s, l, i ): Bajta pozicio de Unikoda signo
string.char( c1, c2, c3, ... )
mw.ustring.char( c1, c2, c3, ... ): Krei signoĉenon el la donitaj kodoj
string.find( s, pattern, init, plain )
s:find( pattern, init, plain )
mw.ustring.find( s, pattern, init, plain ): Pozicioj de la pattern en s; nedeviga ekde pozicio init; r1, r2, r3 = s:find( pattern ); Vidu ankaŭ match(); Aparteco: Malplena krampa paro en pattern estas ebla; liveras la pozicion de ĉi tiu trafo.
string.format( format, p1, p2, ... )
mw.ustring.format( format, p1, p2, ... ): Strukturi argumentojn en limigita C-stilo (printf); Vidu malsupre
mw.ustring.gcodepoint( s, i, j ): Iteraciilo por for-iteracio tra ĉiu signo
string.gmatch( s, pattern )
s:gmatch( pattern )
mw.ustring.gmatch( s, pattern ): Iteraciilo por for-iteracio
string.gsub( s, pattern, replace, n )
s:gsub( pattern, replace, n )
mw.ustring.gsub( s, pattern, replace, n ): Anstataŭigi (substitui) pattern per replace.; n nedeviga; defaŭlte: ĉiuj
mw.ustring.isutf8( s ): true se la UTF-8-kodigo estas valida.
string.len( s )
s:len()
mw.ustring.len( s ): Longeco de la signoĉeno; s:len() estas la sama kiel #s
string.lower( s )
s:lower()
mw.ustring.lower( s ): Minuskloj
string.match( s, pattern, init )
s:match( pattern, init )
mw.ustring.match( s, pattern, init ): r1, r2, r3 = s:match( pattern ); Enhavo de krampoj de la pattern en s; sen krampoj r1=s; Nedevige ekde pozicio init; Vidu ankaŭ find()
string.rep( s, n )
s:rep( n )
mw.ustring.rep( s, n ): (Repeat) n ripetoj de s
string.reverse( s )
s:reverse(): Signoĉeno malantaŭen
string.sub( s, i, j )
s:sub( i, j )
mw.ustring.sub( s, i, j ): Subĉeno substring: parta signoĉeno de i ĝis j.; Kaj i kaj j povas esti negativaj kaj tiam nombras ekde la fino.; j estas nedeviga kaj havas -1 kiel defaŭlton.
mw.ustring.toNFC( s ): Normigo C
mw.ustring.toNFD( s ): Normigo D
string.upper( s )
s:upper()
mw.ustring.upper( s ): Majuskloj
mw.ustring.maxPatternLength: 10000 (Majo 2013)
mw.ustring.maxStringLength: 2048000 (Majo 2013)

.format()

→ Scribunto (angle)

La du funkcioj

string.format( spec, p1, p2, ... )
mw.ustring.format( spec, p1, p2, ... )

strukturas siajn argumentojn p1, p2 ktp.

Ĉe tio estas

spec signoĉeno el la poste menciataj specifikatoroj.
- Krom la specifikatoroj povas esti enŝovata ajna teksto, kondiĉe ke ĝi ne enhavas procentajn signojn.
Ĉiu specifado devas havi rilatan valoron p_i el la parametra listo.

La strukturiga specifado spec por la unuopaj valoroj estas konforma al parto de Programlingvo C (printf).

La principa strukturo de la specifado por unuopa valoro estas

% f w .p s c

kun la nedevigaj indikoj

f – flags
w – width (kampa larĝo)
p – precision
s – size
c – conversion (kodlitero, deviga) por la datumtipo; aŭ %% por la montrado de unuopa procenta signo.

La specifado do komenciĝas kun la procenta signo kaj finiĝas kun la kodlitero; la pli detalaj indikoj inter tio estas liberaj.

Kiel flags ekzistas: '-', '+', ' ', '#', '0'.
Por entjeroj estas subtenataj kampolarĝo ĝis 99. '*' ne estas disponebla.
Por entjeroj estas subtenataj precisions ĝis 99 unterstützt. '*' ne estas disponebla.
Length modifiers ne estas subtenataj.
Kiel kodliteroj por conversion estas rekonataj 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%' kaj la Lua-propra 'q'.
Positional specifiers (kiel "%2$s") ne estas subtenataj.

La kodlitero 'q' estas kiel 's', sed strukturas la signoĉenon je maniero, kiu poste povas esti relegata de Lua-interpretilo: Inkludita en " kaj en interno konvene escaped.

Pattern

La Pattern principe konformas al la disvastiĝintaj regulaj esprimoj kun kelkaj apartaĵoj:

Kodŝanĝado per % kaj tiel same la markado de la specifikatoroj.
Ene de la rektaj krampoj por signaroj estas eblaj ankaŭ specifikatoroj.
Povas esti provizataj nur unuopaj signoj, specifikatoroj aŭ en rektajn krampojn metitaj signo-difinoj kun indiko pri ripeto * ? + -. Ĉe esprimoj metitaj en rondajn krampojn (captures) tio ne eblas.
Ne ekzistas disjunkcio | (Pipe).
La punkto . inkludas linisaltojn.
Por komenco kaj fino staras ^ kaj $ – en la interno tamen kiel tute normalaj signoj. Aliaj limsignoj kiel \b ne ekzistas.
Ekzistas non-greedy indiko pri ripeto - (streketo-minuso), kiu provas liveri tiel malmulte da signoj kiel eblas.
- En "ababab" liveras "a.-b" nur "ab", dum ke "a.*b" rezultigus la tutan "ababab".
Ne ekzistas {n,m} por la nombro de la signoj.
Ne ekzistas globala markado por ignorata uskleco.
„Balancita esprimo“ povas esti trovata per %bxy, ĉe kio x kaj y estas signoj. %b() ekzemple efikas, se la rondaj krampoj aperas pare.
%1 ĝis %9 devas same kiel la respektive numeritaj antaŭirantaj esprimoj troviĝi en rondaj krampoj.

Egala estas la signaro en rektaj krampoj [Liste] kaj ties negado [^Liste] same kiel la notado A-Z ktp. por aro inter du signokodoj.

Pattern por ASCII

→ Scribunto (angle)

La signoj estas ordigataj en klasojn kaj havas ĉiam specifikatoron. Per tio ĉiam estas priskribata tuta aro.

x	estas la signo mem, se ĝi ne estas unu el la signoj kun specifa signifo: `^$()%.[]*+-?`
`.`	(Punkto) ĉiuj signoj, inklude de linisaltoj
`%a`	ĉiuj ASCII literoj
`%c`	ĉiu ASCII stirsignoj (nur Tab kaj linisaltoj en Vikia teksto)
`%d`	ĉiuj ciferoj
`%l`	ĉiuj ASCII minuskloj
`%p`	ĉiuj kromsignoj de la interpunkcio
`%s`	ĉiu ASCII whitespace
`%u`	ĉiuj ASCII majuskloj
`%w`	ĉiuj ASCII alfanumeraj signoj
`%x`	ĉiuj sesdekumaj ciferoj
`%z`	ASCII NUL (zero byte) ne en Vikia teksto
`%A`	ĉiuj signoj ne en `%a`
`%C`	ĉiuj signoj ne en `%c`
`%D`	ĉiuj signoj ne en `%d`
`%L`	ĉiuj signoj ne en `%l`
`%P`	ĉiuj signoj ne en `%p`
`%S`	ĉiuj signoj ne en `%s`
`%U`	ĉiuj signoj ne en `%u`
`%W`	ĉiuj signoj ne en `%w`
`%X`	ĉiuj signoj ne en `%x`
`%Z`	ĉiuj signoj ne en `%z`
`%x`	Se x ne estas alfanumera signo, ĝi estas la signo x mem. Tiel tio estas la normala maniero, prezenti la signojn kun specifa signifo. Apliko al alia kromsigno estas nedamaĝa.

Pattern por Unikodo

→ Scribunto (angle)

La esenca diferenco al ASCII-pattern estas, ke la signoklasoj reprezentas la Unikodajn trajtojn.

	General Category
`%a`	Letter
`%c`	Control
`%d`	Decimal Number
`%l`	Lowercase Letter
`%p`	Punctuation
`%s`	Separator	aldone \t, \n, \r, \v, \f
`%u`	Uppercase Letter
`%w`	Letter Decimal Number
`%x`		aldone de tutlarĝaj versioj de Hex.

La signoj principe estas interpretataj kiel Unikodaj signoj, ne kiel bajtoj. Per tio eblas aroj kiel [０-９] aŭ „Pattern“ kiel %b«», kaj ripetaj signoj funkcias ĝuste.

mw.text

→ Scribunto (angle)

Plia helpa biblioteko per Scribunto, por povi fari malgrandajn manipuladojn de signoĉenoj.

Sub „signo“ ĉi tie estas komprenata Unikodo.

mw.text.decode( s, decodeNamedEntities )

Anstataŭigas HTML-subtenatajn signojn per signokodoj

Normo: Nur lt, gt, amp, quot, nbsp
Nedeviga decodeNamedEntities signifas: Uzi difinon laŭ HTML5. Estas ege pli multaj ol jam estas konataj en HTML4/XHTML. Ili ne povas esti uzataj en Vikia teksto, estas eble ja aperas aliloke.

mw.text.encode( s, charset )

Kodŝanĝado por HTML: anstataŭigas signokodojn per HTML-subtenataj signoj.

Normo: '<', '>', '&', '"' kaj la nerompebla spaceto estas anstataŭataj per la nomitaj lt, gt, amp, quot, nbsp. Eblaj pliaj aĵo estas numeraj.
Nedeviga charset estas aro, kiu taŭgus, stari ĉe pattern en rektaj krampoj.
Defaŭlto estas "<>&\"' " kun nerompeblaj spacetoj je la fino.

Vidu ankaŭ mw.text.nowiki()

mw.text.listToText( list, separator, conjunction )

Ĉiuj elementoj de table ligi unu al alia, similas al table.concat().

list estas table.

Defaŭltoj por la nedevigaj pliaj parametroj estas:

separator pri MediaWiki:comma-separator kiel komo kaj interspaca signo: »⧼MediaWiki:comma-separator⧽«
conjuction pri MediaWiki:and ligas kun MediaWiki:word-separator kiel: »⧼MediaWiki:comma-separator⧽⧼MediaWiki:word-separator⧽«

mw.text.nowiki( s )

Kodŝanĝado por Vikia teksto: anstataŭigas signokodojn per HTML-subtenataj signoj.

Ĉiu apero: '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
Komenco de s aŭ rekte post linisalto: '#', '*', ':', ';'
La „magiaj vortoj“ "://", "ISBN ", "RFC "

Vidu ankaŭ mw.text.encode()

mw.text.split( s, pattern, plain )

Generas tabelon (sequence) el la signoĉeno s per segmentado (Tokenizer).

pattern estas la esprimo, kiu disigas la elementojn unu de alia.

Ĉe malplena signoĉeno por pattern ĉiu signo estas skribata unuope en la tabelon.

Nedeviga plain efikas la laŭliteran serĉadon de pattern, ne per la specifa sintakso.

mw.text.gsplit( s, pattern, plain )

Iteracia funkcio por for analoge al mw.text.split()

mw.text.tag( name, attrs, content )

Generas HTML-etikedon kun la nomo name.

La nedeviga, sed ofte sencoplena attrs estas table kun la asignado k=v.
Se la nedeviga content estas donata kiel signoĉeno (aŭ number), la elemento ankaŭ estas provizataj kun end-tag post content; alie ĝi estas nur start-tag.
Kodoprezento ne okazas aŭtomate; kondiĉe ke dezirata kaj necesa, ĝi devas esti konvene okazigata per mw.text.encode().
Ĉe content =false estas generata unary tag.

Ĉi tiu funkco validas nur por HTML-etikedoj kiel nuraj signoĉenoj. Etikedo de Vikia etendilo kiel <ref> devas esti generata per frame:extensionTag().

mw.text.trim( s, charset )

Forigas interspacajn signojn kaj linisaltojn je la komenco kaj fino de s.

La nedeviga charset estas signoĉeno, kiu povas stari inter la rektaj krampoj de pattern kiel [set].

La defaŭlto estas: "\t\r\n\f "

mw.text.truncate( text, length, ellipsis, adjustLength )

Fortranĉas la signoĉenon s je la longo length.

Ĉe tio estas aligata al fortranĉita signoĉeno la ellasa markigo ellipsis.

Se length estas negativa, tiam estas prenata la valoro kaj la komenco de s fortranĉata; alie la fino.
Se la nedeviga ellipsis ne estas donata, tiam estas uzata »⧼MediaWiki:ellipsis⧽«. Por aligi nenion, devas esti donata eksplike malplena signoĉeno.

Se la nedeviga adjustLength estas uzata kun true, la valoro de length estas la kompleta longo inklude de ellipsis.

mw.text.unstrip( s )

Forigas la MediaWiki-internajn strip markers.

Ĉi tiu funkcio ne estu uzata en la normala Lua-programado, ĉar rompo povus okazi.

[1] (per {{Kun Lua-modulo}})

[2] (per {{LuaModuleDoc}})

[lua-helpo 1]

[lua-helpo 2]