Smalltalk › Pharo › Pharo Smalltalk Developers

Improving doc of XMLParser

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

stepharo

Improving doc of XMLParser

Hi monty

Yesterday one student ask me to import in Moose an XML document.
I spent more than 15 min trying....

What would have really help is the following (could you add it into the
class comment):
Many of the comment do not help because are scarce and not precise enough.

To use a SaxHandler subclass it

SAXHandler subclass: #MySAXHandler
instanceVariableNames: ''
classVariableNames: ''
category: 'MyXMLImporter'

and redefine the method corresponding the notification you want for example:

MySAXHandler>>startElement: aQualifiedName attributes: aDictionary

self halt.

Then to use it simply do

| h |
h := MySAXHandler new
on: FileSystem workingDirectory / 'FILMS.XML'.
h parseDocument.
^ h

Your method startElement: aQualifiedName attributes: aDictionary should
get invoked.

I really think that having a tutorial on XML parser ***use*** is cruelly
needed.

Stef

Sven Van Caekenberghe-2

Re: Improving doc of XMLParser

Stef,

I hope/plan to be able to add that to my talk at the pharo days.

Sven

> On 11 Mar 2016, at 13:55, stepharo <[hidden email]> wrote:
>
> Hi monty
>
> Yesterday one student ask me to import in Moose an XML document.
> I spent more than 15 min trying....
>
> What would have really help is the following (could you add it into the class comment):
> Many of the comment do not help because are scarce and not precise enough.
>
> To use a SaxHandler subclass it
>
>
>
> SAXHandler subclass: #MySAXHandler
> instanceVariableNames: ''
> classVariableNames: ''
> category: 'MyXMLImporter'
>
> and redefine the method corresponding the notification you want for example:
>
> MySAXHandler>>startElement: aQualifiedName attributes: aDictionary
>
> self halt.
>
> Then to use it simply do
>
> | h |
> h := MySAXHandler new
> on: FileSystem workingDirectory / 'FILMS.XML'.
> h parseDocument.
> ^ h
>
> Your method startElement: aQualifiedName attributes: aDictionary should get invoked.
>
>
> I really think that having a tutorial on XML parser ***use*** is cruelly needed.
>
>
>
> Stef
>
>
>
>
>
>

monty-3

Re: Improving doc of XMLParser

In reply to this post by stepharo

The class comment (and other) could be better; it assumes you already know SAX-style parsing. I will improve it.

I have been working on a tutorial that shows the usage of XMLParser and related libs (like XPath or XMLParserStAX). It is being structured like a chapter and formatted with Pillar, so it could go in one of your books (but not PBE, it's too specific for it).

Also, instead of:

> h := MySAXHandler new
> on: FileSystem workingDirectory / 'FILMS.XML'.
> h parseDocument.

You just want:

result := MySAXHandler parseFileNamed: 'FILMS.XML'.

or if you want to configure it before parsing, you can use an on*: constructor + parseDocument:

result :=
(MySAXHandler onFileNamed: 'FILMS.XML')
"...configure the instance here.."
parseDocument.

> Sent: Friday, March 11, 2016 at 7:55 AM
> From: stepharo <[hidden email]>
> To: "Pharo Development List" <[hidden email]>
> Subject: [Pharo-dev] Improving doc of XMLParser
>
> Hi monty
>
> Yesterday one student ask me to import in Moose an XML document.
> I spent more than 15 min trying....
>
> What would have really help is the following (could you add it into the
> class comment):
> Many of the comment do not help because are scarce and not precise enough.
>
> To use a SaxHandler subclass it
>
>
>
> SAXHandler subclass: #MySAXHandler
> instanceVariableNames: ''
> classVariableNames: ''
> category: 'MyXMLImporter'
>
> and redefine the method corresponding the notification you want for example:
>
> MySAXHandler>>startElement: aQualifiedName attributes: aDictionary
>
> self halt.
>
> Then to use it simply do
>
> | h |
> h := MySAXHandler new
> on: FileSystem workingDirectory / 'FILMS.XML'.
> h parseDocument.
> ^ h
>
> Your method startElement: aQualifiedName attributes: aDictionary should
> get invoked.
>
>
> I really think that having a tutorial on XML parser ***use*** is cruelly
> needed.
>
>
>
> Stef
>
>
>
>
>
>
>

stepharo

Re: Improving doc of XMLParser

Le 11/3/16 15:36, monty a écrit :
> The class comment (and other) could be better; it assumes you already know SAX-style parsing. I will improve it.
>
> I have been working on a tutorial that shows the usage of XMLParser and related libs (like XPath or XMLParserStAX).

EXCELLENT!!!!!!!!
> It is being structured like a chapter and formatted with Pillar, so it could go in one of your books (but not PBE, it's too specific for it).
Superb. Yes there will be other books :) It would fit perfectly with the
PullParser chapter

Could you publish that in the squarebraket github repo?
In PharoProgress for example
Where can I read it? I'm eager to read it because I want to help this
person.
I produced a PullXMLParser out of Hernan blog I should add missing examples.
https://github.com/SquareBracketAssociates/PharoInProgress/tree/master/XMLPullParser

>
> Also, instead of:
>
>> h := MySAXHandler new
>> on: FileSystem workingDirectory / 'FILMS.XML'.
>> h parseDocument.
> You just want:
>
> result := MySAXHandler parseFileNamed: 'FILMS.XML'.
>
> or if you want to configure it before parsing, you can use an on*: constructor + parseDocument:
>
> result :=
> (MySAXHandler onFileNamed: 'FILMS.XML')
> "...configure the instance here.."
> parseDocument.

Yes I did it like that because I had to change the onFileNamed: because
I do not know why but in the moose
version I used there was a DNU related to asXMLHandleFile or something
like that.

>
>> Sent: Friday, March 11, 2016 at 7:55 AM
>> From: stepharo <[hidden email]>
>> To: "Pharo Development List" <[hidden email]>
>> Subject: [Pharo-dev] Improving doc of XMLParser
>>
>> Hi monty
>>
>> Yesterday one student ask me to import in Moose an XML document.
>> I spent more than 15 min trying....
>>
>> What would have really help is the following (could you add it into the
>> class comment):
>> Many of the comment do not help because are scarce and not precise enough.
>>
>> To use a SaxHandler subclass it
>>
>>
>>
>> SAXHandler subclass: #MySAXHandler
>> instanceVariableNames: ''
>> classVariableNames: ''
>> category: 'MyXMLImporter'
>>
>> and redefine the method corresponding the notification you want for example:
>>
>> MySAXHandler>>startElement: aQualifiedName attributes: aDictionary
>>
>> self halt.
>>
>> Then to use it simply do
>>
>> | h |
>> h := MySAXHandler new
>> on: FileSystem workingDirectory / 'FILMS.XML'.
>> h parseDocument.
>> ^ h
>>
>> Your method startElement: aQualifiedName attributes: aDictionary should
>> get invoked.
>>
>>
>> I really think that having a tutorial on XML parser ***use*** is cruelly
>> needed.
>>
>>
>>
>> Stef
>>
>>
>>
>>
>>
>>
>>
>

stepharo

Re: Improving doc of XMLParser

In reply to this post by stepharo

Monty

What would be really gorgeous is to revisite the method comments with
the idea that people
do not know SAX.

characters: aString
"This call corresponds to the Java SAX call
characters(char[] ch, int start, int length)."

was not really useful to me. I got no idea about it. So I started to
redefine all the methods and put break put in them.... It was not really
welcoming.
I think that Pharo internal documentation should really improve because
we cannot rely on
Stack Overflow. And this means that people in that case prefer to
develop in a language where they can find solutions instead of crawling.

This is why the example effort should be also pushed further.

Stef