~ubuntu-branches/ubuntu/precise/libyaml-tiny-perl/precise

« back to all changes in this revision

Viewing changes to .pc/necessary_typos.patch/README

Committer: Bazaar Package Importer
Author(s): John Lightsey
Date: 2010-07-20 07:02:42 UTC
mfrom: (1.1.11 upstream) (4.1.7 sid)
Revision ID: james.westby@ubuntu.com-20100720070242-q4diqd0xhvppucuo

Tags: 1.43-1

* New upstream release
* Update standards version to 3.9.0.0

files added:
.pc

.pc/.version

.pc/applied-patches

.pc/necessary_typos.patch

.pc/necessary_typos.patch/README

.pc/necessary_typos.patch/lib

.pc/necessary_typos.patch/lib/YAML

.pc/necessary_typos.patch/lib/YAML/Tiny.pm

debian/patches

debian/patches/necessary_typos.patch

debian/patches/series

debian/source

debian/source/format

xt/meta.t

xt/pmv.t

xt/pod.t

files removed:
t/97_meta.t

t/98_pod.t

t/99_pmv.t

files modified:
Changes

MANIFEST

META.yml

Makefile.PL

README

debian/changelog

debian/control

lib/YAML/Tiny.pm

t/02_basic.t

t/03_regression.t

t/lib/Test.pm

Show diffs side-by-side

added added

removed removed

.pc/necessary_typos.patch/README

NAME

YAML::Tiny - Read/Write YAML files with as little code as possible

PREAMBLE

The YAML specification is huge. Really, really huge. It contains all the

functionality of XML, except with flexibility and choice, which makes it

easier to read, but with a formal specification that is more complex

than XML.

The original pure-Perl implementation YAML costs just over 4 megabytes

of memory to load. Just like with Windows .ini files (3 meg to load) and

CSS (3.5 meg to load) the situation is just asking for a YAML::Tiny

module, an incomplete but correct and usable subset of the

functionality, in as little code as possible.

Like the other "::Tiny" modules, YAML::Tiny will have no non-core

dependencies, not require a compiler, and be back-compatible to at least

perl 5.005_03, and ideally 5.004.

SYNOPSIS

#############################################

# In your file

---

rootproperty: blah

section:

one: two

three: four

Foo: Bar

empty: ~

#############################################

# In your program

use YAML::Tiny;

# Create a YAML file

my $yaml = YAML::Tiny->new;

# Open the config

$yaml = YAML::Tiny->read( 'file.yml' );

# Reading properties

my $root = $yaml->[0]->{rootproperty};

my $one = $yaml->[0]->{section}->{one};

my $Foo = $yaml->[0]->{section}->{Foo};

# Changing data

$yaml->[0]->{newsection} = { this => 'that' }; # Add a section

$yaml->[0]->{section}->{Foo} = 'Not Bar!'; # Change a value

delete $yaml->[0]->{section}; # Delete a value or section

# Add an entire document

$yaml->[1] = [ 'foo', 'bar', 'baz' ];

# Save the file

$yaml->write( 'file.conf' );

DESCRIPTION

YAML::Tiny is a perl class for reading and writing YAML-style files,

written with as little code as possible, reducing load time and memory

overhead.

Most of the time it is accepted that Perl applications use a lot of

memory and modules. The ::Tiny family of modules is specifically

intended to provide an ultralight and zero-dependency alternative to

many more-thorough standard modules.

This module is primarily for reading human-written files (like simple

config files) and generating very simple human-readable files. Note that

I said human-readable and not geek-readable. The sort of files that your

average manager or secretary should be able to look at and make sense

of.

YAML::Tiny does not generate comments, it won't necesarily preserve the

order of your hashes, and it will normalise if reading in and writing

out again.

It only supports a very basic subset of the full YAML specification.

Usage is targetted at files like Perl's META.yml, for which a small and

easily-embeddable module is extremely attractive.

Features will only be added if they are human readable, and can be

written in a few lines of code. Please don't be offended if your request

is refused. Someone has to draw the line, and for YAML::Tiny that

someone is me.

If you need something with more power move up to YAML (4 megabytes of

memory overhead) or YAML::Syck (275k, but requires libsyck and a C

compiler).

To restate, YAML::Tiny does not preserve your comments, whitespace, or

the order of your YAML data. But it should round-trip from Perl

structure to file and back again just fine.

YAML TINY SPECIFICATION

100

This section of the documentation provides a specification for "YAML

101

Tiny", a subset of the YAML specification.

102

103

It is based on and described comparatively to the YAML 1.1 Working Draft

104

2004-12-28 specification, located at

105

<http://yaml.org/spec/current.html>.

106

107

Terminology and chapter numbers are based on that specification.

108

109

1. Introduction and Goals

110

The purpose of the YAML Tiny specification is to describe a useful

111

subset of the YAML specification that can be used for typical

112

document-oriented uses such as configuration files and simple data

113

structure dumps.

114

115

Many specification elements that add flexibility or extensibility are

116

intentionally removed, as is support for complex datastructures, class

117

and object-orientation.

118

119

In general, YAML Tiny targets only those data structures available in

120

JSON, with the additional limitation that only simple keys are

121

supported.

122

123

As a result, all possible YAML Tiny documents should be able to be

124

transformed into an equivalent JSON document, although the reverse is

125

not necesarily true (but will be true in simple cases).

126

127

As a result of these simplifications the YAML Tiny specification should

128

be implementable in a relatively small amount of code in any language

129

that supports Perl Compatible Regular Expressions (PCRE).

130

131

2. Introduction

132

YAML Tiny supports three data structures. These are scalars (in a

133

variety of forms), block-form sequences and block-form mappings.

134

Flow-style sequences and mappings are not supported, with some minor

135

exceptions detailed later.

136

137

The use of three dashes "---" to indicate the start of a new document is

138

supported, and multiple documents per file/stream is allowed.

139

140

Both line and inline comments are supported.

141

142

Scalars are supported via the plain style, single quote and double

143

quote, as well as literal-style and folded-style multi-line scalars.

144

145

The use of explicit tags is not supported.

146

147

The use of "null" type scalars is supported via the ~ character.

148

149

The use of "bool" type scalars is not supported.

150

151

However, serializer implementations should take care to explicitly

152

escape strings that match a "bool" keyword in the following set to

153

prevent other implementations that do support "bool" accidentally

154

reading a string as a boolean

155

156

y|Y|yes|Yes|YES|n|N|no|No|NO

157

158

|on|On|ON|off|Off|OFF

159

160

The use of anchors and aliases is not supported.

161

162

The use of directives is supported only for the %YAML directive.

163

164

3. Processing YAML Tiny Information

165

Processes

166

167

The YAML specification dictates three-phase serialization and

168

three-phase deserialization.

169

170

The YAML Tiny specification does not mandate any particular methodology

171

or mechanism for parsing.

172

173

Any compliant parser is only required to parse a single document at a

174

time. The ability to support streaming documents is optional and most

175

likely non-typical.

176

177

Because anchors and aliases are not supported, the resulting

178

representation graph is thus directed but (unlike the main YAML

179

specification) acyclic.

180

181

Circular references/pointers are not possible, and any YAML Tiny

182

serializer detecting a circular reference should error with an

183

appropriate message.

184

185

Presentation Stream

186

187

YAML Tiny is notionally unicode, but support for unicode is required if

188

the underlying language or system being used to implement a parser does

189

not support Unicode. If unicode is encountered in this case an error

190

should be returned.

191

192

Loading Failure Points

193

194

YAML Tiny parsers and emitters are not expected to recover from adapt to

195

errors. The specific error modality of any implementation is not

196

dictated (return codes, exceptions, etc) but is expected to be

197

consistant.

198

199

4. Syntax

200

Character Set

201

202

YAML Tiny streams are implemented primarily using the ASCII character

203

set, although the use of Unicode inside strings is allowed if support by

204

the implementation.

205

206

Specific YAML Tiny encoded document types aiming for maximum

207

compatibility should restrict themselves to ASCII.

208

209

The escaping and unescaping of the 8-bit YAML escapes is required.

210

211

The escaping and unescaping of 16-bit and 32-bit YAML escapes is not

212

required.

213

214

Indicator Characters

215

216

Support for the "~" null/undefined indicator is required.

217

218

Implementations may represent this as appropriate for the underlying

219

language.

220

221

Support for the "-" block sequence indicator is required.

222

223

Support for the "?" mapping key indicator is not required.

224

225

Support for the ":" mapping value indicator is required.

226

227

Support for the "," flow collection indicator is not required.

228

229

Support for the "[" flow sequence indicator is not required, with one

230

exception (detailed below).

231

232

Support for the "]" flow sequence indicator is not required, with one

233

exception (detailed below).

234

235

Support for the "{" flow mapping indicator is not required, with one

236

exception (detailed below).

237

238

Support for the "}" flow mapping indicator is not required, with one

239

exception (detailed below).

240

241

Support for the "#" comment indicator is required.

242

243

Support for the "&" anchor indicator is not required.

244

245

Support for the "*" alias indicator is not required.

246

247

Support for the "!" tag indicator is not required.

248

249

Support for the "|" literal block indicator is required.

250

251

Support for the ">" folded block indicator is required.

252

253

Support for the "'" single quote indicator is required.

254

255

Support for the """ double quote indicator is required.

256

257

Support for the "%" directive indicator is required, but only for the

258

special case of a %YAML version directive before the "---" document

259

header, or on the same line as the document header.

260

261

For example:

262

263

%YAML 1.1

264

---

265

- A sequence with a single element

266

267

Special Exception:

268

269

To provide the ability to support empty sequences and mappings, support

270

for the constructs [] (empty sequence) and {} (empty mapping) are

271

required.

272

273

For example,

274

275

%YAML 1.1

276

# A document consisting of only an empty mapping

277

--- {}

278

# A document consisting of only an empty sequence

279

--- []

280

# A document consisting of an empty mapping within a sequence

281

- foo

282

- {}

283

- bar

284

285

Syntax Primitives

286

287

Other than the empty sequence and mapping cases described above, YAML

288

Tiny supports only the indentation-based block-style group of contexts.

289

290

All five scalar contexts are supported.

291

292

Indentation spaces work as per the YAML specification in all cases.

293

294

Comments work as per the YAML specification in all simple cases. Support

295

for indented multi-line comments is not required.

296

297

Seperation spaces work as per the YAML specification in all cases.

298

299

YAML Tiny Character Stream

300

301

The only directive supported by the YAML Tiny specification is the %YAML

302

language/version identifier. Although detected, this directive will have

303

no control over the parsing itself.

304

305

The parser must recognise both the YAML 1.0 and YAML 1.1+ formatting of

306

this directive (as well as the commented form, although no explicit code

307

should be needed to deal with this case, being a comment anyway)

308

309

That is, all of the following should be supported.

310

311

--- #YAML:1.0

312

- foo

313

314

%YAML:1.0

315

---

316

- foo

317

318

% YAML 1.1

319

---

320

- foo

321

322

Support for the %TAG directive is not required.

323

324

Support for additional directives is not required.

325

326

Support for the document boundary marker "---" is required.

327

328

Support for the document boundary market "..." is not required.

329

330

If necesary, a document boundary should simply by indicated with a "---"

331

marker, with not preceding "..." marker.

332

333

Support for empty streams (containing no documents) is required.

334

335

Support for implicit document starts is required.

336

337

That is, the following must be equivalent.

338

339

# Full form

340

%YAML 1.1

341

---

342

foo: bar

343

344

# Implicit form

345

foo: bar

346

347

Nodes

348

349

Support for nodes optional anchor and tag properties are not required.

350

351

Support for node anchors is not required.

352

353

Support for node tags is not required.

354

355

Support for alias nodes is not required.

356

357

Support for flow nodes is not required.

358

359

Support for block nodes is required.

360

361

Scalar Styles

362

363

Support for all five scalar styles are required as per the YAML

364

specification, although support for quoted scalars spanning more than

365

one line is not required.

366

367

Support for the chomping indicators on multi-line scalar styles is

368

required.

369

370

Collection Styles

371

372

Support for block-style sequences is required.

373

374

Support for flow-style sequences is not required.

375

376

Support for block-style mappings is required.

377

378

Support for flow-style mappings is not required.

379

380

Both sequences and mappings should be able to be arbitrarily nested.

381

382

Support for plain-style mapping keys is required.

383

384

Support for quoted keys in mappings is not required.

385

386

Support for "?"-indicated explicit keys is not required.

387

388

Here endeth the specification.

389

390

Additional Perl-Specific Notes

391

For some Perl applications, it's important to know if you really have a

392

number and not a string.

393

394

That is, in some contexts is important that 3 the number is distinctive

395

from "3" the string.

396

397

Because even Perl itself is not trivially able to understand the

398

difference (certainly without XS-based modules) Perl implementations of

399

the YAML Tiny specification are not required to retain the

400

distinctiveness of 3 vs "3".

401

402

METHODS

403

new

404

The constructor "new" creates and returns an empty "YAML::Tiny" object.

405

406

read $filename

407

The "read" constructor reads a YAML file, and returns a new "YAML::Tiny"

408

object containing the contents of the file.

409

410

Returns the object on success, or "undef" on error.

411

412

When "read" fails, "YAML::Tiny" sets an error message internally you can

413

recover via "YAML::Tiny->errstr". Although in some cases a failed "read"

414

will also set the operating system error variable $!, not all errors do

415

and you should not rely on using the $! variable.

416

417

read_string $string;

418

The "read_string" method takes as argument the contents of a YAML file

419

(a YAML document) as a string and returns the "YAML::Tiny" object for

420

it.

421

422

write $filename

423

The "write" method generates the file content for the properties, and

424

writes it to disk to the filename specified.

425

426

Returns true on success or "undef" on error.

427

428

write_string

429

Generates the file content for the object and returns it as a string.

430

431

errstr

432

When an error occurs, you can retrieve the error message either from the

433

$YAML::Tiny::errstr variable, or using the "errstr()" method.

434

435

FUNCTIONS

436

YAML::Tiny implements a number of functions to add compatibility with

437

the YAML API. These should be a drop-in replacement, except that

438

YAML::Tiny will not export functions by default, and so you will need to

439

explicitly import the functions.

440

441

Dump

442

my $string = Dump(list-of-Perl-data-structures);

443

444

Turn Perl data into YAML. This function works very much like

445

Data::Dumper::Dumper().

446

447

It takes a list of Perl data strucures and dumps them into a serialized

448

form.

449

450

It returns a string containing the YAML stream.

451

452

The structures can be references or plain scalars.

453

454

Load

455

my @documents = Load(string-containing-a-YAML-stream);

456

457

Turn YAML into Perl data. This is the opposite of Dump.

458

459

Just like Storable's thaw() function or the eval() function in relation

460

to Data::Dumper.

461

462

It parses a string containing a valid YAML stream into a list of Perl

463

data structures.

464

465

freeze() and thaw()

466

Aliases to Dump() and Load() for Storable fans. This will also allow

467

YAML::Tiny to be plugged directly into modules like POE.pm, that use the

468

freeze/thaw API for internal serialization.

469

470

DumpFile(filepath, list)

471

Writes the YAML stream to a file instead of just returning a string.

472

473

LoadFile(filepath)

474

Reads the YAML stream from a file instead of a string.

475

476

SUPPORT

477

Bugs should be reported via the CPAN bug tracker at

478

479

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>

480

481

AUTHOR

482

Adam Kennedy <adamk@cpan.org>

483

484