Module contacts: Contacts Database

This module allows to read and manipulate the contacts stored on the phone.

In the phone's database, a contact is identified by its id, an integer number.

• Contact Fields
• contacts.add
• contacts.delete
• contacts.find
• contacts.findnr
• contacts.get
• contacts.labels
• contacts.new
• contacts.own
• contacts.set

Contact Fields

In m, a contact is represented as an array whose elements are the fields of the contact. Fields are identified by their (array) keys. m recognizes the following keys, with the corresponding data type:

Key	Meaning
adr	Address (street)
birth	Birthday
cell	Cellphone number
company	Company name
country	Country
email	e-mail address
extadr	Additional address
extname	Additional name
fax	Fax number
fname	First name
loc	Locality (city)
name	(Family) name

  

Key	Meaning
note	Contact note
pager	Pager number
phone	Voice phone number
pict	Picture image data
po	Post Office
region	Region
ring	Ringtone file name
text	Free text
title	Job Title
url	Website URL
video	Video phone number
zip	Post Code

Key names are not case sensitive.

The order of fields in the array describing a contact is arbitrary. Arrays returned by functions in this module always start with the two fields name and fname, if these fields exist.

Address and phone number fields can have one of the following suffices:

Suffix	Meaning
.home	Home address or phone
.work	Work address or phone

For instance, phone.home refers to the home phone number, phone.work to the work phone number. phone without suffix is unspecified.

Most fields are represented as strings. There are two exceptions:

• birth: The birthday is stored as a number indicating the seconds since year zero. This is the format used by module time.
• pict: The picture is stored as an array containing the image data, typically in JPEG format. Example functions to load or store a the picture of a contact c:

  use io function loadpict(file, c)   f=io.open(file);   s=io.read(f, io.size(f)); // read whole file   io.close(f);   c["pict"]=code(s) // string to byte array end function storepict(c, file)   if c["pict"]#null then     s=char(c["pict"]); // byte array to string     f=io.create(file);     io.write(f, s);     io.close(f)   end end

The functions of this module throw ExcInvalidParam if a contact array has no keys, or ErrBadName if a contact array has a key which is not in the above table.

contacts.add

Add a contact to the database, and return its id. The contact must be an array with keys from the above tables.

c=["name": "Shakespeare",    "fname": "William",    "loc.home": "Stratford-upon-Avon"],    "loc.work": "London",    "birth": time.num("1564-04-23")]; contacts.add(c) → 114

contacts.delete

Delete the contact with the given id.

Throws ErrNotFound if there is no such contact.

// delete the contact added in the add example contacts.delete(114)

contacts.find

Searches the contact database for entries matching text considering the fields specified in keys, and returns the ids of the matching contacts sorted by the fields specified in sort:

• If text=null, all entries are returned, and keys is ignored.
• If text#null, searches the contact database for all entries matching the words in text when considering the fields defined by keys. Both text and all fields from the database are split into words (sequences of characters or digits) before comparing them. An entry matches if all of the words in text are found in any of the fields considered. Words can also be abbreviated: William matches both W or Will in the search text.
  If keys defines a single field, it can be a string, otherwise it must be an array of strings.
• If sort=[], the ids are sorted by their ascending numeric value.
• If sort is a string, the ids are sorted by the corresponding field.
• If sort is an array, the ids are sorted by the corresponding fields, from highest to lowest sort order.

// get the number of contacts in the database print len(contacts.find()) → 104 // print these contacts, sorted by name and first name for id in contacts.find(null,null,["name", "fname"]) do   c=contacts.get(id);   print c[1], c[0] end → ... William Shakespeare ... // Will matches William; so does W print contacts.find("Will Shakespeare") → [114] print contacts.find("W. Shakespeare") → [114] // get the ids of everybody living or working in London print contacts.find("London", "loc") → [45,67,89,90,91,114] // Stratford-upon-Avon is considered three words, // so Avon matches print contacts.find("Avon", "loc") → [114]

contacts.findnr

Retrieves the ids of the entries matching the given phone number. Only the last digits digits in number are considered when comparing. The minimum for digits is 7.

This function is much faster than find, and more useful, as it only looks at digits, and the end of the phone numbers.

Throws ExcValueOutOfRange if digits is out of range.

print contacts.findnr("+41(079)7654321", 9) → [28]

contacts.get

Get fields of the contact with id id. If keys=null, returns all fields defined for the contact. If keys#null, returns only the fields specified in keys. keys can be a single string specifying a single field, or an array specifying multiple fields.

If they exist, the fields name and/or fname are at the beginning of the returned array.

Throws ErrNotFound if there is no contact with this id; throws ErrArgument if there are more than 32 keys specified.

c=contacts.get(114); print c → [Shakespeare,William,Stratford-upon-Avon,London, 49365849600] print time.str(c["birth"]) → 1564-04-23 00:00:00 print contacts.get(114, ["name", "fname"]) → [Shakespeare,William] c=contacts.get(114, "loc"); print c → [Stratford-upon-Avon,London] print keys(c) → [loc.home,loc.work]

contacts.labels

Get labels for the fields. Labels are language dependent. keys is interpreted as follows:

• If keys=null, returns all standard labels.
• If keys is a string, returns the label(s) for the corresponding field(s).
• If keys is an array, returns the labels for the corresponding fields.

Suffices (.home, .work) can be used as keys, but not as field suffices: labels() throws ErrBadName in this case.

If they exist, the labels for name and/or fname are at the beginning of the returned array.

The label array has the same keys as a contact.

l=contacts.labels(); print l → [Last name,First name,Tel. (home),Mobile (home),Fax (home),E-mail (home),Web addr. (home), Street (home),...<46>] l["title"] → Job title // print a contact with all its labels c=contacts.get(114); for k in keys(c) do   print l[k], "-", c[k] end → Last name - Shakespeare First name - William City (home) - Stratford-upon-Avon City (business) - London Birthday - 49365849600 // get all work related labels print contacts.labels([".work"]) → [Tel. (business),Mobile (business),Fax (business),E-mail (business),Web addr. (bus.),Street (business),...<12>] contacts.labels("phone.work") → ErrBadName thrown

contacts.new

Returns the list of contacts modified since the specified point in time. time is the number of seconds since year 0 UTC. See also module time.

// get the entries changed within the last ten minutes print contacts.new(time.utc()-10*60) → [114]

contacts.own

There is a single contact in the database which can be marked as own contact, indicating the owner of the phone (or any other particular person). Some phones can use this information to quickly send a vCard[11] of the phone owner.

Without an argument, the id of this contact is returned. With an argument, the own contact id is set to id, and the old one is returned.

Returns -1 if no own contact has been set, or it has been deleted.

Throws ErrNotFound if there is no contact with this id.

// if there is no owner, make it the first Shakespeare if contacts.own()=-1 then   ids=contacts.find("Shakespeare");   if len(ids)>0 then     contacts.own(ids[0])   end end

contacts.set

Updates the contact with id id, updating or adding fields in array contact. contact must be an array with keys from the above tables.

Fields already existing in the database are updated, the other fields are added. Fields not in the array are not modified. Fields which are null in the array are removed from the contact.

// Replace all +41 1 numbers by +41 44 const fields=["phone", "fax", "cell", "pager"]); for id in contacts.find() do   c=contacts.get(id, fields);   m=false;   for i=0 to len(c)-1 do     // field could be null or too short     if c[i]!=null then       n=trim(c[i]);       if len(n)>=11 then         // replace +411 by +4144         if substr(n,0,4)="+411" then           c[i]="+4144" + substr(n, 4); m=true         // replace +41 1 by +41 44         elsif substr(n,0,5)="+41 1" then           c[i]="+41 44" + substr(n, 5); m=true         end       end     end   end;   if m then     contacts.set(id, c)   end end