Silme:Tutorial:L10nObject

[This is a part of silme tutorial]

L10nObject

If you're building an entity list in memory, or you're storing the data in a database, Entity and EntityList objects are everything you need, so just head over to Silme:Tutorial:IOClient.

But if you happen to store your l10n lists in any kind of file format like DTD, XLIFF, Gettext or properties, you need a representation of this kind of objects and we all know that there's much more inside those files than EntityList can cover.

L10nObject is a class that extends EntityList and offers a way to store and manipulate the whole complex text object that contains an EntityList inside.

Think of L10nObject as a complex version of EntityList with the context around entities while EntityList is a pure content you care about.

In the most basic example we can identify three elements each L10n file is made of. Entity, string and comment.

Silme library covers this by offering you two classes - Entity and Comment, and letting you add a string to L10nObject. Since we described Entity class in the previous chapter, I'll focus on how we work with Comments and strings here.

String

String can be added to L10nObject in the very same way as entity.

 import silme.core
 
 l10nobject = silme.core.L10nObject()
 
 entity1 = silme.core.Entity('example.id','Test value')
 l10nobject.add_entity(entity1)
 
 l10nobject.add_string("\n\n")
 
 entity2 = silme.core.Entity('example.id2','Test value2')
 l10nobject.add_entity(entity2)

In the above example we've added two entities to an L10nObject, but in the middle we separated them with a string. Two important paradigms about strings in Silme project are:

• We reduce the number of strings if possible. It means that we're concatenating strings if they're one next to each other.
• We convert all strings to unicode.

Since L10nObject is extending EntityList, all methods described for EntityList will work here, with one difference. L10nObject may contain several other object types, so when you want to iterate through L10nObject and you care only of entities, use a method get_entitylist to get an EntityList object or get_entities to get a normal list of entities.

 import silme.core
 
 for item in l10nobject: # you iterate through a set of items, like commnts, strings and entities (and potentially others)
   pass
 
 for entity in l10nobject.get_entities(): # you iterate through entities 
     pass

In the example above, you don't need EntityList object, so using get_entities is OK. In most cases it's better to use get_entitylist() through.

Comment

Comment in every text file is an object that may contain all the structures that the file can handle, except of comment itself.

In Verbatim, Comment class extends L10nObject and forbids adding a Comment to itself.

 import silme.core
 
 l10nobject = silme.core.L10nObject()
 
 entity1 = silme.core.Entity('example.id','Test value')
 l10nobject.add_element(entity1)
 
 l10nobject.add_element("\n\n")
 
 comment = silme.core.Comment()
 comment.add_element("\nImportant note")
 comment.add_element(silme.core.Entity("commented.id", "This entity is commented out"))
 l10nobject.add_element(comment)

 entity2 = silme.core.Entity('example.id2','Test value2')
 l10nobject.add_element(entity2)

add_element() method is a wrapper for add_string(), add_comment and add_entity methods, and you can use those instead if you wish. Bear in mind that comment will raise an exception if you try to add another comment to itself, and that addString will concatenate itself to the previous string if will be added next to it.

You can use get_element() method to get an element at given position.

Blob

Blob is the simples class we use. It's a class with two properties, name and source of the object.

It's usually used only when loading an L10nPackage from some source and when a file that is inside cannot be parsed as l10n file.

In such cases we want to make sure that we will not loose it and we just store it as a silme.core.Object.

 import silme.core
 
 object = silme.core.Object('readme.txt')
 object.source = u'the source of this object file'

You will not use any objects of this kind for a while, so don't bother too much about it.

L10nPackage

When we go one step beyond L10nObjects or EntityLists, you have a recursive collections of them, which we call L10nPackages and in case of a hard drive structure is called a directory or a zip package or a database.

L10nPackage is a very simple container and can contain a list of EntityLists/L10nObjects and L10nPackages.

 import silme.core
 
 l10npackage = silme.core.L10nPackage('Test package')
 
 l10nobject = silme.core.L10nObject('test.dtd')
 
 l10nobject2 = silme.core.L10nObject('test2.dtd')
 
 l10npackage.add_object(l10nobject)
 l10npackage.add_object(l10nobject2)

Advanced topics

You may extend the list of objects L10nObject is made of by creating additional classes that will represent separate elements of L10n structure. This may be a Doctype class, or a list of file contributors etc. We'll build such example later while talking about format reader/writers.

In the next chapter, we'll talk about how we can read those objects into memory from various sources and how to write them back.