Human-readable text syntax
The preserves.text module implements the Preserves human-readable text syntax.
The main entry points are functions stringify, parse, and parse_with_annotations.
>>> stringify(Record(Symbol('hi'), [1, [2, 3]]))
'<hi 1 [2 3]>'
>>> parse('<hi 1 [2 3]>')
#hi(1, (2, 3))
Formatter(format_embedded=lambda : x, indent=None, with_commas=False, trailing_comma=False, include_annotations=True)
Bases: TextCodec
Printer (and indenting pretty-printer) for producing human-readable syntax from
Preserves Value
s.
>>> f = Formatter()
>>> f.append({'a': 1, 'b': 2})
>>> f.append(Record(Symbol('label'), ['field1', ['field2item1', 'field2item2']]))
>>> print(f.contents())
{"a": 1 "b": 2} <label "field1" ["field2item1" "field2item2"]>
>>> f = Formatter(indent=4)
>>> f.append({'a': 1, 'b': 2})
>>> f.append(Record(Symbol('label'), ['field1', ['field2item1', 'field2item2']]))
>>> print(f.contents())
{
"a": 1
"b": 2
}
<label "field1" [
"field2item1"
"field2item2"
]>
Parameters:
Name | Type | Description | Default |
---|---|---|---|
format_embedded |
function accepting an Embedded.embeddedValue and
returning a |
lambda : x
|
|
indent |
int | None
|
|
None
|
with_commas |
bool
|
|
False
|
trailing_comma |
bool
|
|
False
|
include_annotations |
bool
|
|
True
|
Attributes:
Name | Type | Description |
---|---|---|
indent_delta |
int
|
indentation per nesting-level |
chunks |
list[str]
|
fragments of output |
Source code in preserves/text.py
490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 |
|
append(v)
Extend self.chunks
with at least one chunk, together making up the text
representation of v
.
Source code in preserves/text.py
560 561 562 563 564 565 566 567 568 569 |
|
contents()
Returns a str
constructed from the join of the chunks in self.chunks
.
Source code in preserves/text.py
511 512 513 |
|
is_indenting()
Returns True
iff this Formatter is in pretty-printing
indenting mode.
Source code in preserves/text.py
515 516 517 518 |
|
Parser(input_buffer='', include_annotations=False, parse_embedded=lambda : x)
Bases: TextCodec
Parser for the human-readable Preserves text syntax.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
input_buffer |
str
|
initial contents of the input buffer; may subsequently be extended by calling extend. |
''
|
include_annotations |
bool
|
if |
False
|
parse_embedded |
function accepting a |
lambda : x
|
Normal usage is to supply input text, and keep calling next until a ShortPacket exception is raised:
>>> d = Parser('123 "hello" @x []')
>>> d.next()
123
>>> d.next()
'hello'
>>> d.next()
()
>>> d.next()
Traceback (most recent call last):
...
preserves.error.ShortPacket: Short input buffer
Alternatively, keep calling try_next until it yields
None
, which is not in the domain of Preserves Value
s:
>>> d = Parser('123 "hello" @x []')
>>> d.try_next()
123
>>> d.try_next()
'hello'
>>> d.try_next()
()
>>> d.try_next()
For convenience, Parser implements the iterator interface, backing it with try_next, so you can simply iterate over all complete values in an input:
>>> d = Parser('123 "hello" @x []')
>>> list(d)
[123, 'hello', ()]
>>> for v in Parser('123 "hello" @x []'):
... print(repr(v))
123
'hello'
()
Supply include_annotations=True
to read annotations alongside the annotated values:
>>> d = Parser('123 "hello" @x []', include_annotations=True)
>>> list(d)
[123, 'hello', @#x ()]
If you are incrementally reading from, say, a socket, you can use extend to add new input as if comes available:
>>> d = Parser('123 "he')
>>> d.try_next()
123
>>> d.try_next() # returns None because the input is incomplete
>>> d.extend('llo"')
>>> d.try_next()
'hello'
>>> d.try_next()
Attributes:
Name | Type | Description |
---|---|---|
input_buffer |
str
|
buffered input waiting to be processed |
index |
int
|
read position within |
Source code in preserves/text.py
132 133 134 135 136 137 |
|
extend(text)
Appends text
to the remaining contents of self.input_buffer
, trimming already-processed
text from the front of self.input_buffer
and resetting self.index
to zero.
Source code in preserves/text.py
139 140 141 142 143 |
|
next()
Reads the next complete Value
from the internal buffer, raising
ShortPacket if too few bytes are available, or
DecodeError if the input is invalid somehow.
Source code in preserves/text.py
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 |
|
try_next()
Like next, but returns None
instead of raising
ShortPacket.
Source code in preserves/text.py
404 405 406 407 408 409 410 411 412 |
|
parse(text, **kwargs)
Yields the first complete encoded value from text
, passing kwargs
through to the
Parser constructor. Raises exceptions as per
next.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
text |
str
|
encoded data to decode |
required |
Source code in preserves/text.py
423 424 425 426 427 428 429 430 431 432 |
|
parse_with_annotations(bs, **kwargs)
Like parse, but supplying include_annotations=True
to the
Parser constructor.
Source code in preserves/text.py
434 435 436 437 |
|
stringify(v, **kwargs)
Convert a single Value
v
to a string. Any supplied kwargs
are passed on to the
underlying Formatter constructor.
Source code in preserves/text.py
621 622 623 624 625 626 |
|
Created: March 16, 2023