Difference between revisions of "Silme:Tutorial:L10nObject"

From Braniecki's Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== 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]].
+
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.
 
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.
Line 7: Line 7:
 
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.
 
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.
+
Think of L10nObject as a complex version of EntityList with the context around entities while EntityList is a pure content you care about.
  
Verbatim library covers this by offering you two classes - Entity and Comment, and letting you add a string to L10nObject.
+
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.
 
Since we described Entity class in the previous chapter, I'll focus on how we work with Comments and strings here.
  
Line 17: Line 19:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import String, Entity, L10nObject
+
import silme.core
  
l10nObject = L10nObject()
+
l10nobject = silme.core.L10nObject()
  
entity1 = Entity('example.id','Test value')
+
entity1 = silme.core.Entity('example.id','Test value')
l10nObject.addEntity(entity1)
+
l10nobject.add_entity(entity1)
  
l10nObject.addString("\n\n")
+
l10nobject.add_string("\n\n")
  
entity2 = Entity('example.id2','Test value2')
+
entity2 = silme.core.Entity('example.id2','Test value2')
l10nObject.addEntity(entity2)
+
l10nobject.add_entity(entity2)
 
</code>
 
</code>
  
 
In the above example we've added two entities to an L10nObject, but in the middle we separated them with a string.
 
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:
+
Two important paradigms about strings in Silme 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 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.
 
* 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.
+
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.
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import L10nObject
+
import silme.core
  
for item in L10nObject: # you iterate through a set of items, like commnts, strings and entities (and potentially others)
+
for item in l10nobject: # you iterate through a set of items, like commnts, strings and entities (and potentially others)
 
   pass
 
   pass
  
for entity in L10nObject.getEntities(): # you iterate through entities  
+
for entity in l10nobject.get_entities(): # you iterate through entities  
 
   pass
 
   pass
 
</code>
 
</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.
+
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 ==
Line 56: Line 58:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import String, Comment Entity, L10nObject
+
import silme.core
  
l10nObject = L10nObject()
+
l10nobject = silme.core.L10nObject()
  
entity1 = Entity('example.id','Test value')
+
entity1 = silme.core.Entity('example.id','Test value')
l10nObject.addElement(entity1)
+
l10nobject.add_element(entity1)
  
l10nObject.addElement("\n\n")
+
l10nobject.add_element("\n\n")
  
comment = Comment()
+
comment = silme.core.Comment()
comment.addElement("\nImportant note")
+
comment.add_element("\nImportant note")
comment.addElement(Entity("commented.id", "This entity is commented out"))
+
comment.add_element(silme.core.Entity("commented.id", "This entity is commented out"))
l10nObject.addElement(comment)
+
l10nobject.add_element(comment)
  
entity2 = Entity('example.id2','Test value2')
+
entity2 = silme.core.Entity('example.id2','Test value2')
l10nObject.addElement(entity2)
+
l10nobject.add_element(entity2)
 
</code>
 
</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.
+
''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.
 +
 
 +
== Object ==
 +
 
 +
Object is the simples class we use. It's a class with two properties, name and source of the object.
  
Of course you can use getElement method to get an element at given position.
+
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.
 +
 
 +
<code lang="python">
 +
import silme.core
 +
 
 +
object = silme.core.Object('readme.txt')
 +
object.source = u'the source of this object file'
 +
</code>
 +
 
 +
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.
 +
 
 +
 +
<code lang="python">
 +
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)
 +
</code>
  
 
== Advanced topics ==
 
== 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.
 
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 [[Silme:Tutorial:IOClient|next chapter]], we'll talk about how we can read those objects into memory from various sources and how to write them back.

Latest revision as of 13:38, 16 February 2009

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.

Object

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