Silme:Tutorial:L10nObject

L10nObject

If you're building an entity list in a memory, or you're storing the data in a database Entity and EntityList objects are everything you need, so just head over to Verbatim::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.

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

Verbatim 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.

from mozilla.l10n.object import String, Entity, L10nObject

l10nObject = L10nObject()

entity1 = Entity('example.id','Test value') l10nObject.addEntity(entity1)

l10nObject.addString("\n\n")

entity2 = Entity('example.id2','Test value2') l10nObject.addEntity(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 Verbatim project are:

• We reduce the number of string 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 getEntityList to get an EntityList object or getEntities to get a normal list of entities.

from mozilla.l10n.object import L10nObject

for item in L10nObject: # you iterate through a set of items, like commnts, strings and entities (and potentially others)

 pass

for entity in L10nObject.getEntities(): # you iterate through entities

 pass

In the example above, you don't need EntityList object, so using getEntities is OK. In most cases it's better to use getEntityList() 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.

from mozilla.l10n.object import String, Comment Entity, L10nObject

l10nObject = L10nObject()

entity1 = Entity('example.id','Test value') l10nObject.addElement(entity1)

l10nObject.addElement("\n\n")

comment = Comment() comment.addElement("\nImportant note") comment.addElement(Entity("commented.id", "This entity is commented out")) l10nObject.addElement(comment)

entity2 = Entity('example.id2','Test value2') l10nObject.addElement(entity2)

addElement method is a wrapper for addString, addComment and addEntity 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.

Of course you can use getElement method to get an element at given position.

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.