Wanting to read only the first document in a file

[Takidoso]

Hi,
I'd like to read just the first document in a file that got several
yaml documents separated by thre hyphens "---".
The reason is, that I just need the first one using load instead of
loadAll, since I like to skip the rest.
I am getting this Exception


expected a single document in the stream
in "<reader>", line 1, column 1
but found another document
in "<reader>", line 2, column 1

at org.yaml.snakeyaml.composer.Composer.getSingleNode(Composer.java:
88)
at
org.yaml.snakeyaml.constructor.BaseConstructor.getSingleData(BaseConstructor.java:
114)
at org.yaml.snakeyaml.Loader.load(Loader.java:51)
at org.yaml.snakeyaml.Yaml.load(Yaml.java:164)
...

Well, what is the intention here for making sure that there is only
one document in the file?
the comment of the used routine is

/**
* Parse the first YAML document in a stream and produce the
corresponding
* Java object.
*
* @param io
* data to load from (BOM is respected and removed)
* @return parsed object

With this comment in mind, I don't understand this check giving me
above exception.

So the workatound is to laod all documents, I wanted to ommit in
first place.

is or will be there an alternative?

[Andrey]

Hello,
you do not need to load all the documents but you have to use the
interface which works properly with many documents in the stream. See
the test:
http://code.google.com/p/snakeyaml/source/browse/src/test/java/org/yaml/snakeyaml/YamlTest.java

As you can see even though the test calls loadAll() the documents are
parsed only when you ask for it.

When SnakeYAML reads the input steam it creates a buffer of incoming
bytes (for performance reasons). If you read only one document from
the stream the buffer may contain the bytes of the following
documents. Some streams do not support re-read which means that if you
read just one document and you wish to give the input stream to
somebody else it will be broken since the bytes are read (and lost) in
the SnakeYAML's buffer. SnakeYAML cannot read the exact amount of
bytes because in order to know where the document ends you need to
parse it.

JavaDoc may be improved. Can you may be suggest a better text ? Is
this better ?
Parse the only YAML document in a stream and produce the corresponding
Java object.

What the JavaDoc for loadAll() should say ?

I hope it helps,

-
Andrey

[Takidoso]

On 6 Okt., 10:37, Andrey <py4...@gmail.com> wrote:
> Hello,
> you do not need to load all the documents but you have to use the
> interface which works properly with many documents in the stream. See

> the test:http://code.google.com/p/snakeyaml/source/browse/src/test/java/org/ya...

>
> As you can see even though the test calls loadAll() the documents are
> parsed only when you ask for it.

Thanks for this hint, that helped a lot to understand, that the
iteator initiates loading the documents actually.

> JavaDoc may be improved. Can you may be suggest a better text ? Is
> this better ?
> Parse the only YAML document in a stream and produce the corresponding
> Java object.

well that sounds better, but dont forget to mention the
ComposerException if it is not the only one ;-)

may be something like this:
/**
* Parse the first and only YAML document in a stream and produce
the corresponding
* JavaBean.

*
* @param io
* data to load from (BOM is respected and removed)

* @return parsed JavaBean
* @throws ComposerException
* in case there are more documents in the stream
*/

All load methods that call getSingleData() should have this additional
hints in their comments

> What the JavaDoc for loadAll() should say ?

may be something like this:


/**
* Parse all YAML documents in a stream and produce corresponding
Java
* objects.
* For optimizational reasons the document iterator actually
triggers the reading and parsing
* of each document as soon its next()-method is called.
*
* @param yaml
* YAML data to load from (BOM is respected and
ignored)
* @return an iterator over the parsed Java objects in this stream
in proper
* sequence
* @throws (what ever Exception if there is something thrown)
*/

Thanks for your help

[Andrey]

I am not sure about mentioning exceptions. Loading a YAML document may
cause many exceptions. If we mention just one exception it may confuse
users.

You may look how the JavaDoc looks now:
http://code.google.com/p/snakeyaml/source/browse/src/main/java/org/yaml/snakeyaml/Yaml.java