c0data 0.3.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/c0/body.rb CHANGED
@@ -5,23 +5,40 @@ module C0
5
5
  # EOT, or the inside of a nested level. Everything it returns is a shared
6
6
  # byteslice of the original buffer.
7
7
  #
8
+ # Parse is validate: `Body.new(bytes)` applies the whole grammar to the
9
+ # bytes and raises a C0::SyntaxError on malformed input. The navigators then
10
+ # report the **result model**: a dead element (`␇` before it) is dropped with
11
+ # everything it holds. SUB makes the element after it a child of the element
12
+ # before, at that code's grain (DESIGN.md "Subordinates"): `␚␝s` is a
13
+ # subsection one deeper than the group before it, and `␞a␟b␚␟c` is two
14
+ # units with `c` a sub-unit of `b`, not a unit of the record; a record's
15
+ # sub-units are reached through `Record#unit`.
16
+ #
8
17
  # Records before the first GS of a file form an unnamed group; records and
9
- # groups before the first FS form an unnamed file. Enumerates the groups of
10
- # the first file.
18
+ # groups before the first FS form the unnamed leading file. Enumerates the
19
+ # groups of the first file.
11
20
  class Body
12
21
  include Enumerable
13
22
 
14
23
  attr_reader :buf, :start, :stop
15
24
 
16
- def initialize(buf, start = 0, stop = nil)
25
+ # Parse `buf` (or its [start, stop) range) as a body: no SYN, heading or
26
+ # EOT. Pass `validate: false` only for a range already checked as part of
27
+ # a larger parse (the inside of a level, a document's body).
28
+ def initialize(buf, start = 0, stop = nil, validate: true)
17
29
  @buf = C0.to_bin(buf)
18
30
  @start = start
19
31
  @stop = stop || @buf.bytesize
32
+ Ext.body_read(@buf, @start, @stop) if validate
20
33
  end
21
34
 
22
- # The files, in order (at least one: the unnamed leading file).
35
+ # A body over an already-validated range.
36
+ def self.view(buf, start, stop) = new(buf, start, stop, validate: false)
37
+
38
+ # The files, in order. The unnamed leading file is reported when it has
39
+ # content or no FS follows it.
23
40
  def files
24
- @files ||= Ext.files(@buf, @start, @stop).map { |ns, ne, s, e| FileView.new(@buf, ns, ne, s, e) }
41
+ @files ||= Ext.files(@buf, @start, @stop).map { |ns, ne, s, e, leading| FileView.new(@buf, ns, ne, s, e, leading) }
25
42
  end
26
43
 
27
44
  # All groups of all files, in order.
@@ -70,22 +87,27 @@ module C0
70
87
  def first_file = files[0]
71
88
  end
72
89
 
73
- # A file within a body: its name and groups. Enumerates the groups.
90
+ # A file within a body: its name and groups. The file before the first FS
91
+ # is the unnamed `leading?` file. Enumerates the groups.
74
92
  class FileView
75
93
  include Enumerable
76
94
 
77
95
  attr_reader :start, :stop
78
96
 
79
- def initialize(buf, name_start, name_end, start, stop)
97
+ def initialize(buf, name_start, name_end, start, stop, leading = false)
80
98
  @buf = buf
81
99
  @name_start = name_start
82
100
  @name_end = name_end
83
101
  @start = start
84
102
  @stop = stop
103
+ @leading = leading
85
104
  end
86
105
 
87
106
  def name = @buf.byteslice(@name_start, @name_end - @name_start)
88
107
 
108
+ # Whether this is the unnamed file before the first FS.
109
+ def leading? = @leading
110
+
89
111
  def groups
90
112
  @groups ||= Ext.groups(@buf, @start, @stop).map { |d, ns, ne, s, e| Group.new(@buf, d, ns, ne, s, e) }
91
113
  end
@@ -103,8 +125,9 @@ module C0
103
125
  def raw = @buf.byteslice(@start, @stop - @start)
104
126
  end
105
127
 
106
- # A group: its depth (GS count; 0 for the unnamed leading group), name,
107
- # optional header row and records. Enumerates the records.
128
+ # A group: its depth (one plus its SUB prefix: `␝a` 1, `␚␝b` 2; 0 for the
129
+ # unnamed leading group), name, optional header row and records. Enumerates
130
+ # the records.
108
131
  class Group
109
132
  include Enumerable
110
133
 
@@ -146,7 +169,7 @@ module C0
146
169
  headers.index(needle)
147
170
  end
148
171
 
149
- # The live records (header row, notes, commits and dead elements skipped).
172
+ # The live records: header row, notes, commits and dead records skipped.
150
173
  def records
151
174
  @records ||= Ext.group_records(@buf, @start, @stop).map { |s, e| Record.new(@buf, s, e) }
152
175
  end
@@ -170,8 +193,58 @@ module C0
170
193
 
171
194
  Table = Group
172
195
 
196
+ # One unit as written: its raw value bytes (layout included) and its
197
+ # sub-units (`␞a␟b␚␟c`: `b` holds the sub-unit `c`), each a Unit with
198
+ # sub-units of its own (`␞a␚␟b␚␚␟c`: `a` holds `b` holds `c`).
199
+ class Unit
200
+ attr_reader :raw, :subs
201
+
202
+ def initialize(raw, subs = [])
203
+ @raw = raw
204
+ @subs = subs
205
+ end
206
+
207
+ # A unit from the extension's [start, end, subs] tree over `buf`.
208
+ def self.from_tree(buf, tree)
209
+ s, e, subs = tree
210
+ new(buf.byteslice(s, e - s), subs.map { |t| from_tree(buf, t) })
211
+ end
212
+
213
+ # The logical value. Raises C0::Error on a level or a reference.
214
+ def value = C0.value(@raw)
215
+
216
+ # One of C0::UnitType.
217
+ def type = Ext.unit_type(@raw, 0, @raw.bytesize)
218
+
219
+ def level? = type == UnitType::LEVEL
220
+
221
+ def ref? = type == UnitType::REF
222
+
223
+ # Whether the unit holds sub-units.
224
+ def subs? = !@subs.empty?
225
+
226
+ # The unit as a nested level (a Body). Raises C0::Error when it is not one.
227
+ def level
228
+ b = C0.to_bin(@raw)
229
+ ls, le = Ext.unit_level(b, 0, b.bytesize)
230
+ Body.view(b, ls, le)
231
+ end
232
+
233
+ def ==(other) = other.is_a?(Unit) && other.raw == @raw && other.subs == @subs
234
+
235
+ alias eql? ==
236
+
237
+ def hash = [@raw, @subs].hash
238
+
239
+ def inspect = "#<C0::Unit #{@raw.inspect}#{@subs.empty? ? '' : " subs=#{@subs.inspect}"}>"
240
+ end
241
+
173
242
  # A record: positional or keyed, never mixed. Zero-copy accessors.
174
- # Enumerates the logical values of a positional record.
243
+ #
244
+ # A sub-unit is not a unit of the record: `field_count`, `fields`, `values`
245
+ # and `pairs` see the units only; `unit(n)` and `unit(key)` give a unit with
246
+ # its `subs`, `units` every positional unit so. Enumerates the logical
247
+ # values of a positional record.
175
248
  class Record
176
249
  include Enumerable
177
250
 
@@ -186,66 +259,84 @@ module C0
186
259
  # The record's bytes (after its RS, trailing layout excluded).
187
260
  def raw = @buf.byteslice(@start, @stop - @start)
188
261
 
189
- # Whether the record is keyed (its first live unit is an SOH).
262
+ # Whether the record is keyed (it holds a keyed unit, live or dead).
190
263
  def keyed? = Ext.record_keyed(@buf, @start, @stop)
191
264
 
192
265
  # ---- positional ---------------------------------------------------------
193
266
 
194
- # Raw bytes of unit n (its layout included), or of the unit under a key
195
- # (last wins); nil when there is none.
267
+ # Raw bytes of unit n (its layout included, its sub-units excluded), or
268
+ # of the unit under a key (last wins); nil when there is none.
196
269
  def field(index_or_key)
197
- s, e = index_or_key.is_a?(Integer) ? units[index_or_key] : keyed_range(index_or_key)
270
+ s, e = index_or_key.is_a?(Integer) ? unit_ranges[index_or_key] : keyed_range(index_or_key)
198
271
  s && @buf.byteslice(s, e - s)
199
272
  end
200
273
 
201
- # Number of positional units (0 for a keyed record).
202
- def field_count = units.size
274
+ # Number of positional units of the result (0 for a keyed record).
275
+ def field_count = unit_ranges.size
203
276
 
204
277
  alias size field_count
205
278
 
206
- def fields = units.map { |s, e| @buf.byteslice(s, e - s) }
279
+ def fields = unit_ranges.map { |s, e| @buf.byteslice(s, e - s) }
280
+
281
+ # Every positional unit with its sub-units (empty for a keyed record).
282
+ def units
283
+ @units ||= Ext.record_units_with_subs(@buf, @start, @stop).map { |t| Unit.from_tree(@buf, t) }
284
+ end
285
+
286
+ # Unit n (or the unit under a key, last wins) with its sub-units; nil
287
+ # when there is none.
288
+ def unit(index_or_key)
289
+ return units[index_or_key] if index_or_key.is_a?(Integer)
290
+
291
+ needle = C0.to_bin(index_or_key)
292
+ found = nil
293
+ pair_trees.each do |ks, ke, vs, ve, subs|
294
+ found = [vs, ve, subs] if @buf.byteslice(ks, ke - ks) == needle
295
+ end
296
+ found && Unit.from_tree(@buf, found)
297
+ end
207
298
 
208
299
  # Logical value of unit n, or nil when there is none.
209
300
  def value(index)
210
- s, e = units[index]
301
+ s, e = unit_ranges[index]
211
302
  s && Ext.value(@buf, s, e)
212
303
  end
213
304
 
214
- def values = units.map { |s, e| Ext.value(@buf, s, e) }
305
+ def values = unit_ranges.map { |s, e| Ext.value(@buf, s, e) }
215
306
 
216
307
  def each(&) = values.each(&)
217
308
 
218
309
  # Unit n (or the unit under a key) as a nested level. Raises C0::Error when
219
310
  # it is not one; nil for a key with no unit.
220
311
  def level(index_or_key)
221
- s, e = index_or_key.is_a?(Integer) ? units[index_or_key] : keyed_range(index_or_key)
312
+ s, e = index_or_key.is_a?(Integer) ? unit_ranges[index_or_key] : keyed_range(index_or_key)
222
313
  return nil if s.nil? && !index_or_key.is_a?(Integer)
223
314
  raise KeyError, "no unit #{index_or_key}" if s.nil?
224
315
 
225
316
  ls, le = Ext.unit_level(@buf, s, e)
226
- Body.new(@buf, ls, le)
317
+ Body.view(@buf, ls, le)
227
318
  end
228
319
 
229
320
  # Unit n as a flat list: a level holding at most one positional record.
230
321
  # Raises C0::Error for any other level.
231
322
  def list(index)
232
- s, e = units[index]
323
+ s, e = unit_ranges[index]
233
324
  raise KeyError, "no unit #{index}" if s.nil?
234
325
 
235
326
  Ext.unit_list(@buf, s, e).map { |is, ie| Ext.value(@buf, is, ie) }
236
327
  end
237
328
 
238
- # Unit n as a Reference.
329
+ # Unit n as a Reference. Raises C0::Error when it is not one.
239
330
  def ref(index)
240
- s, e = units[index]
331
+ s, e = unit_ranges[index]
241
332
  raise KeyError, "no unit #{index}" if s.nil?
242
333
 
243
- Reference.new(Ext.unit_ref(@buf, s, e).map { |rs, re| @buf.byteslice(rs, re - rs) })
334
+ Reference.from_ext(@buf, Ext.unit_ref(@buf, s, e))
244
335
  end
245
336
 
246
337
  # ---- keyed --------------------------------------------------------------
247
338
 
248
- # Keys in written order (duplicates included).
339
+ # Keys in written order (duplicates included; dead units skipped).
249
340
  def keys = pair_ranges.map { |ks, ke, _, _| @buf.byteslice(ks, ke - ks) }
250
341
 
251
342
  # [key, logical value] pairs in written order.
@@ -266,10 +357,12 @@ module C0
266
357
 
267
358
  private
268
359
 
269
- def units = @units ||= Ext.record_units(@buf, @start, @stop)
360
+ def unit_ranges = @unit_ranges ||= Ext.record_units(@buf, @start, @stop)
270
361
 
271
362
  def pair_ranges = @pair_ranges ||= Ext.record_pairs(@buf, @start, @stop)
272
363
 
364
+ def pair_trees = @pair_trees ||= Ext.record_pairs_with_subs(@buf, @start, @stop)
365
+
273
366
  def keyed_range(key)
274
367
  needle = C0.to_bin(key)
275
368
  found = nil
@@ -280,35 +373,62 @@ module C0
280
373
  end
281
374
  end
282
375
 
283
- # A reference: a group name, or a path of two or three segments
284
- # (group, record id, field name).
376
+ # A reference (DESIGN.md "References"): a group written plain, `␅tags`, or
377
+ # a **pattern**, `␅␐␝tags␞001␟label␘`: the level that is one branch of the
378
+ # target with its values left out, reported as the Body it is written as.
379
+ # `path` linearises either form into its steps (file, group names, record
380
+ # id, field name, then an inner pattern's steps). Resolution is not
381
+ # implemented.
285
382
  class Reference
383
+ # The group name of a plain reference, or nil for a pattern.
384
+ attr_reader :name
385
+ # The pattern's body (the inside of its level), or nil for a plain reference.
386
+ attr_reader :pattern
387
+ # The steps in walking order.
286
388
  attr_reader :path
287
389
 
288
- def initialize(path)
390
+ def initialize(name, pattern, path, group_name = nil)
391
+ @name = name
392
+ @pattern = pattern
289
393
  @path = path
394
+ @group_name = group_name
290
395
  end
291
396
 
292
397
  # Parse a raw unit (ENQ …). Raises C0::Error when it is not a reference.
293
398
  def self.parse(raw)
294
399
  b = C0.to_bin(raw)
295
- new(Ext.unit_ref(b, 0, b.bytesize).map { |s, e| b.byteslice(s, e - s) })
400
+ from_ext(b, Ext.unit_ref(b, 0, b.bytesize))
401
+ end
402
+
403
+ # A reference from the extension's description of a unit of `buf`.
404
+ def self.from_ext(buf, desc)
405
+ name_range, pattern_range, steps, group_range = desc
406
+ new(name_range && buf.byteslice(name_range[0], name_range[1] - name_range[0]),
407
+ pattern_range && Body.view(buf, pattern_range[0], pattern_range[1]),
408
+ steps.map { |s, e| buf.byteslice(s, e - s) },
409
+ group_range && buf.byteslice(group_range[0], group_range[1] - group_range[0]))
296
410
  end
297
411
 
298
- def group = @path[0]
412
+ def pattern? = !@pattern.nil?
299
413
 
300
- def record = @path[1]
414
+ # Whether the reference names a group as a whole: a plain name, or a
415
+ # pattern that is a bare group line (`␅␐␝tags␘`).
416
+ def group? = !@group_name.nil?
301
417
 
302
- def field = @path[2]
418
+ # The group named when `group?`, else nil.
419
+ def group_name = @group_name
303
420
 
304
- def group? = @path.size == 1
421
+ # The group named. Raises C0::Error when the reference is a pattern into a group.
422
+ def group = @group_name || raise(Error, "reference is a pattern, not a group")
305
423
 
306
- def ==(other) = other.is_a?(Reference) && other.path == @path
424
+ def ==(other) = other.is_a?(Reference) && other.name == @name && other.pattern&.raw == @pattern&.raw
307
425
 
308
426
  alias eql? ==
309
427
 
310
- def hash = @path.hash
428
+ def hash = [@name, @pattern&.raw].hash
311
429
 
312
430
  def to_s = @path.join("/")
431
+
432
+ def inspect = "#<C0::Reference #{@name ? @name.inspect : "pattern #{to_s.inspect}"}>"
313
433
  end
314
434
  end
data/lib/c0/builder.rb CHANGED
@@ -6,7 +6,7 @@ module C0
6
6
  # file adds the Ruby conveniences.
7
7
  #
8
8
  # buf = C0::Builder.build do |b|
9
- # b.syn(shape: "tabular")
9
+ # b.syn(version: "1")
10
10
  # b.group("users", %w[name amount]) do
11
11
  # b.record("Alice", "1502.30")
12
12
  # b.record("Bob", "340.00")
@@ -17,32 +17,37 @@ module C0
17
17
  # Two layers. The primitives are one method per code (`fs`, `gs`, `rs`,
18
18
  # `us`, `sub`, `soh`, `dle`, `can`, `bel`, `enq`, `syn`, `eot`, `etb`, `em`);
19
19
  # each writes its code and, when given, what grammatically follows it, so a
20
- # chain reads like the bytes (`sub` is C0-DIFF only: `rs("old").sub("new")`
21
- # writes a replace-all, ␞old␚new; in a data body SUB is an error):
20
+ # chain reads like the bytes. `sub` is bare: the element after the next
21
+ # separator is subordinate to the one before it, at that grain (before GS a
22
+ # subsection, before US a sub-unit). `enq` takes a group name, or a block
23
+ # writing a pattern (`␅␐ … ␘`):
22
24
  #
23
25
  # b.rs("Alice").us("1502.30") # ␞Alice␟1502.30
24
26
  # b.rs.soh("host").us("localhost").soh("port").us("5432") # ␞␁host␟localhost␁port␟5432
25
27
  # b.gs("users").soh.rs("name").us("amount") # ␝users␁␞name␟amount
26
28
  # b.bel.gs("old") # ␇␝old, a dead group
29
+ # b.rs("old").sub.us("new") # ␞old␚␟new, new a sub-unit of old
30
+ # b.gs("intro", depth: 2) # ␚␝intro, a subsection
31
+ # b.rs.enq("tags").us.enq { b.gs("tags").rs("001") } # ␞␅tags␟␅␐␝tags␞001␘
27
32
  #
28
- # The composed methods (`file`, `group`, `header`, `record`, `field`, `map`,
29
- # `key`, `level`, `list`, `ref`, `note`) are built on the primitives and
30
- # cannot write ill-formed output. The primitives write what you spell;
31
- # well-formedness is then yours to keep. Both layers share the record state,
32
- # so they mix: `b.rs("a").field("b")` writes ␞a␟b.
33
+ # The composed methods (`file`, `group`, `header`, `record`, `field`,
34
+ # `sub_unit`, `map`, `key`, `level`, `list`, `ref`, `note`) are built on
35
+ # the primitives and cannot write ill-formed output. The primitives write
36
+ # what you spell; well-formedness is then yours to keep. Both layers share
37
+ # the record state, so they mix: `b.rs("a").field("b")` writes ␞a␟b.
33
38
  #
34
39
  # Values are byte-transparent and written in their one spelling: plain when
35
40
  # they can be, text (STX … ETX) otherwise, with only the seven codes escaped;
36
41
  # there is no STX/ETX primitive, so everything written stays canonical.
37
- # Names (file, group, header, key, reference segment, ETB payload) must be
42
+ # Names (file, group, header, key, reference step, ETB payload) must be
38
43
  # plain, or a C0::BuildError is raised before anything is written. Every
39
44
  # method returns the builder, so calls chain.
40
45
  #
41
46
  # A record is opened by `record` or `rs` (or implicitly by the first `field`,
42
- # `key`, `level`, `list` or `ref`) and ended by the next structural call.
43
- # Keyed units written right after `syn` belong to the heading. Inside
44
- # `level { }` (or between `dle` and `can`) the builder is at the top of a
45
- # fresh body.
47
+ # `sub_unit`, `key`, `level`, `list` or `ref`) and ended by the next
48
+ # structural call. Keyed units written right after `syn` belong to the
49
+ # heading. Inside `level { }`, `ref { }`, `enq { }` (or between `dle` and
50
+ # `can`) the builder is at the top of a fresh body.
46
51
  class Builder
47
52
  # Drive a fresh builder and return its bytes.
48
53
  def self.build
data/lib/c0/diff.rb ADDED
@@ -0,0 +1,193 @@
1
+ # frozen_string_literal: true
2
+
3
+ module C0
4
+ # C0DIFF (DIFF.md): atomic multi-file edits with anchored patterns. A diff
5
+ # is an ordinary document of `shape` `diff`: files of records, each record
6
+ # a pattern of units, with `old␚␟new` (the sub-unit of `old`) as the
7
+ # substitution. Parsing and applying run in the C core (c0_diff.h).
8
+ #
9
+ # diff = C0::Diff.build do |d|
10
+ # d.file("greeting.txt") do
11
+ # d.record { |r| r.anchor("Hello "); r.sub("world", "universe"); r.anchor("!") }
12
+ # end
13
+ # end
14
+ # C0::Diff.apply(diff, { "greeting.txt" => "Hello world!" })
15
+ # # => { "greeting.txt" => "Hello universe!" }
16
+ #
17
+ # A record's search text (its anchors and olds) must match exactly once
18
+ # from the previous record's match to the end of the file. Everything the
19
+ # text diff does not use (keyed units, levels, references, header rows, GS,
20
+ # dead records or file lines, two sub-units on one unit, a sub-unit of a
21
+ # sub-unit, an empty search text, `␟␚␟`, the same path twice) is refused
22
+ # with a C0::Diff::Error; malformed bytes (SUB before RS, FS or SOH among
23
+ # them) raise the usual C0::SyntaxError. There is no replace-all.
24
+ module Diff
25
+ # C0::Diff::Error < C0::Error is defined by the extension.
26
+
27
+ # One unit of a pattern: an anchor (`new` nil) or a substitution `old␚␟new`
28
+ # (`new` the sub-unit of `old`).
29
+ Unit = Struct.new(:old, :new) do
30
+ def anchor? = new.nil?
31
+
32
+ def substitution? = !new.nil?
33
+ end
34
+
35
+ # One record: an anchored pattern. With no substitution it is an assertion.
36
+ Pattern = Struct.new(:units) do
37
+ # What the file must hold, once: anchors and olds.
38
+ def search = units.map(&:old).join.b
39
+
40
+ # What it will hold: each sub-unit in place of the unit that holds it.
41
+ def replacement = units.map { |u| u.new || u.old }.join.b
42
+
43
+ def assertion? = units.all?(&:anchor?)
44
+ end
45
+
46
+ # A file's records, in order.
47
+ FileEdit = Struct.new(:path, :records)
48
+
49
+ module_function
50
+
51
+ # Parse a diff document (with or without its SYN heading) into FileEdits,
52
+ # refusing everything DIFF.md lists under "What a diff may not hold".
53
+ def parse(diff)
54
+ Ext.diff_parse(C0.to_bin(diff)).map do |path, records|
55
+ FileEdit.new(path, records.map { |units| Pattern.new(units.map { |o, n| Unit.new(o, n) }) })
56
+ end
57
+ end
58
+
59
+ # Apply a diff to in-memory files: a Hash (or pairs) of path => content.
60
+ # Everything is validated first; raises without producing anything on any
61
+ # error. Returns a new Hash with every input file, edited or unchanged,
62
+ # each content in the encoding of its input.
63
+ def apply(diff, files)
64
+ pairs = files.to_a
65
+ inputs = pairs.map { |path, content| [C0.to_bin(path.to_s), C0.to_bin(content)] }
66
+ outputs = Ext.diff_apply(C0.to_bin(diff), inputs)
67
+ out = {}
68
+ pairs.each_with_index do |(path, content), i|
69
+ enc = content.is_a?(String) ? content.encoding : Encoding::BINARY
70
+ out[path] = outputs[i][1].force_encoding(enc)
71
+ end
72
+ out
73
+ end
74
+
75
+ # Apply a diff to files on disk under `base_dir`, atomically: every file is
76
+ # validated before any is written, and each is written via a temporary
77
+ # file and rename. A path that leaves `base_dir` is refused.
78
+ def apply_files(diff, base_dir = ".")
79
+ diff = C0.to_bin(diff)
80
+ base = File.expand_path(base_dir)
81
+ inputs = parse(diff).map do |edit|
82
+ path = edit.path.dup.force_encoding(Encoding::UTF_8)
83
+ target = File.expand_path(path, base)
84
+ unless target.start_with?(base + File::SEPARATOR)
85
+ raise Error, "path escapes the target directory: #{path}"
86
+ end
87
+ raise Error, "no such file: #{path}" unless File.file?(target)
88
+
89
+ [path, File.binread(target)]
90
+ end
91
+ apply(diff, inputs).each do |path, content|
92
+ target = File.expand_path(path, base)
93
+ tmp = "#{target}.c0diff.tmp"
94
+ File.binwrite(tmp, content)
95
+ File.rename(tmp, target)
96
+ end
97
+ nil
98
+ end
99
+
100
+ # Drive a fresh DiffBuilder and return its bytes.
101
+ def build(heading: true, &) = DiffBuilder.build(heading: heading, &)
102
+ end
103
+
104
+ # Writes a C0DIFF document over a C0::Builder: `␖␁shape␟diff`, then files
105
+ # (`file`) of records (`record`, `replace`, `insert_after`, `delete`,
106
+ # `assert`), notes and an optional `eot`. Every method returns the builder.
107
+ class DiffBuilder
108
+ def self.build(heading: true)
109
+ d = new(heading: heading)
110
+ yield d
111
+ d.bytes
112
+ end
113
+
114
+ def initialize(heading: true)
115
+ @b = Builder.new
116
+ @b.syn(shape: "diff") if heading
117
+ end
118
+
119
+ # FS and the path (a name); the block writes the file's records.
120
+ def file(path)
121
+ @b.fs(path)
122
+ yield self if block_given?
123
+ self
124
+ end
125
+
126
+ # One anchored pattern: the block gets a PatternBuilder (`anchor`, `sub`).
127
+ def record
128
+ @b.rs
129
+ yield PatternBuilder.new(@b) if block_given?
130
+ self
131
+ end
132
+
133
+ # One record: anchor, old␚␟new, anchor (empty anchors are omitted).
134
+ def replace(context_before, old_text, new_text, context_after = "")
135
+ record do |r|
136
+ r.anchor(context_before) unless context_before.empty?
137
+ r.sub(old_text, new_text)
138
+ r.anchor(context_after) unless context_after.empty?
139
+ end
140
+ end
141
+
142
+ # One record: insert `text` after `anchor` (`␞anchor␟␚␟text`).
143
+ def insert_after(anchor, text)
144
+ record do |r|
145
+ r.anchor(anchor)
146
+ r.sub("", text)
147
+ end
148
+ end
149
+
150
+ # One record: remove `old_text`, found once after the cursor, between optional anchors.
151
+ def delete(old_text, context_before = "", context_after = "")
152
+ replace(context_before, old_text, "", context_after)
153
+ end
154
+
155
+ # One record: assert that `text` is present once; nothing changes.
156
+ def assert(text) = record { |r| r.anchor(text) }
157
+
158
+ # BEL and a note (a hunk kept without applying goes in one).
159
+ def note(text)
160
+ @b.note(text)
161
+ self
162
+ end
163
+
164
+ def eot
165
+ @b.eot
166
+ self
167
+ end
168
+
169
+ # The diff's bytes so far (a binary String).
170
+ def bytes = @b.bytes
171
+
172
+ alias to_s bytes
173
+ end
174
+
175
+ # The units of one diff record: `anchor(text)` and `sub(old, new)`.
176
+ class PatternBuilder
177
+ def initialize(builder)
178
+ @b = builder
179
+ end
180
+
181
+ # An anchor: text the file holds and keeps.
182
+ def anchor(text)
183
+ @b.field(text)
184
+ self
185
+ end
186
+
187
+ # A substitution, `old␚␟new`: the unit `old` with the sub-unit `new`.
188
+ def sub(old_text, new_text)
189
+ @b.field(old_text).sub_unit(new_text)
190
+ self
191
+ end
192
+ end
193
+ end