View source for 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.

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

<code lang="python">
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)
</code>

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 <code>getEntityList</code> to get an EntityList object or <code>getEntities</code> to get a normal list of entities.

<code lang="python">
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
</code>

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.

<code lang="python">
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)
</code>

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.

You can use getElement method to get an element at given position.

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

 
<code lang="python">
from mozilla.l10n.object import EntityList, L10nObject, L10nPackage

l10nPackage = L10nPackage()
l10nPackage.name = 'Test package'

l10nObject = L10nObject()
l10nObject.name = 'test.dtd'

l10nObject2 = L10nObject()
l10nObject2.name = 'test2.dtd'

l10nPackage.addObject(l10nObject)
l10nPackage.addObject(l10nObject2)
</code>

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