patterns

Lua's string library has powerful functions for matching and catching patterns. To use them you must learn Lua's notation for patterns. The expression

            i, j = s:find (p, n)

A pattern is simply a string. The following characters play a special role for patterns and are known as magic characters.

  (  )  .  %  +  -  *  ?  [  ]  ^  $

        i, j = ("woman"):find ("man$")
        print(i, " ", j) --> 3 5

    %a  any letter of the alphabet
    %A  any character not a letter of the alphabet
    %c  any control character
    %C  any character not a control character
    %d  any digit
    %D  any character not a digit
    %p  any punctuation symbol
    %P  any character not a punctuation symbol
    %s  any white space character
    %S  any character not a white space character
    %u  any uppercase letter
    %U  any character not an uppercase letter
    %w  any alphanumeric character
    %W  any non-alphanumeric character
    %x  any hexadecimal digit
    %X  any character not a hexadecimal digit
    %z  the character with ASCII code 0
    %Z  any character except ASCII NUL

The magic characters + - * and ? are used as modifiers after a character class, with the following meanings:

       +  longest sequence of at least one
       -  shortest sequence of zero or more
       *  longest sequence of zero or more
       ?  zero or one

The expression %b xy matches balanced strings that start with the character x and end with y. Typical uses are %b(), %b<>, %b%% and so on.

The expression %f  followed by a character class specified by square brackets matches a frontier between characters not in the class and characters in the class.

captures

Usually we want not only to find whether a pattern is matched in a string, but also, for each instance of a match, what the actual matching substrings are for some parts of the pattern. These substrings are called captures and we can indicate which parts of a pattern we wish to capture by enclosing them in parentheses, the only magic characters we have so far not explained. The captures are ordered by the position of the opening parenthesis. They can, of course, be nested. The find method returns the captures as extra results after the two indices, if it is successful.

    s = [[url="http://www.lua.org"]]
    i, j, adr = s:find [[url="(.*)"]]
    print(i, " ", j, " ", adr) --> 6 23 http://www.lua.org

         quoted = [[(["'])(.-)%1]] 

How do we cope with lots of matches? The iterator method gmatch  is used as follows:

  for x, y, . . . in s:gmatch (pat) do body end -- for

global substitution

The string method gsub is very powerful. In its simplest form

      s_new = s_old:gsub (pattern, replacement)

If file evaluates to the canonicalized name of a file that is not in the root directory of a filing system, we can obtain the directory it lies in as

           file:gsub ("%.[^%.]*$","")

MP3 example

Here is a short example program that pulls together lots of different ideas.

#! lua
-- Gavin Wraith (12/10/2007)
-- add /mp3 suffix to files of type 0x1ad
-- that do not already end in that suffix
-- in the arg[1] directory and all its subdirectories

local sep, suffix, sufpat = ".", "/mp3", "/[mM][pP]3$"
local warn = "Need a directory or an mp3 file, please"
local cmd = "rename %s %s"
local ampeg, dirtype = 0x1ad, 0x1000
local dir, filetype in riscos
local execute in os

local cmdlist = {}
local scan, addsuffix, action

addsuffix = \ (file)
  if not file:match (sufpat) then
   cmdlist[1 + #cmdlist] = cmd:format (file, file..suffix)
  end -- if
  end -- function

scan = \ (d)
  for leaf, kind in dir (d) do
   local func = action[kind]
   if func then func (d..sep..leaf) end -- if
  end -- for
    end -- function

action = { [ampeg] = addsuffix; [dirtype] = scan; }

--- main program
local d = arg[1]
local func = action[filetype (d)]
if func then func (d) else error (warn) end -- if
for _, rename in ipairs (cmdlist) do
 execute (rename)
end -- for

The comment  -- main program  shows where to start. We define a local variable  d  to be the value of  arg[1]  . Why bother? Why not just use  arg[1]  ? Because we want to avoid evaluating this expression more than once. Note that  d  is used twice, once in the next line, and again in the line after that. The next line defines a value  func  which is the value of the  action  table at the filetype of the filer object given by  arg[1]  . We see that the  action  table has two keys, one for MP3 files and another for directories. The idea is that  func  will be a function for dealing with the requisite filetype: if an MP3 file is given, then we want to use the function  addsuffix  and if it is a directory we want to use  scan In other words, rather than using conditional tests with lots of  if  statements, we prefer to use a jump table. This is more efficient, and easier to extend if we need to cater for more cases. This technique should be used in circumstances wherever you would use a  switch  statement if you were programming in C or a  CASE  statement if you were programming in BBC Basic. But what happens if the value given by  d  is neither an MP3 file nor a directory? In that case  func  will not be defined, i.e. it will be  nil . So, in the next line, we apply  func  if it is defined and give a warning otherwise. Finally, we execute all the renaming commands which have been gathered into the list  cmdlist  by the calls to the  addsuffix  function.

An important point is that the three variables  scan, addsuffix, action  are all declared local before they are defined. That is because their definitions are mutually recursive;  scan  depends on  action and  action  depends on  scan  and  addsuffix . This arrangement can be taken as a template for scanning directories recursively. The local variable  dir  has the value  riscos.dir  which gives iteration over directories (this is particular to RiscLua - it is not standard Lua).