Minor code and documentation updates

Author: docelic

CRYSTAL-WISHLIST.md

@@ -101,7 +101,7 @@ Matches are:
 
 https://github.com/crystal-lang/crystal/issues/10231
 
-The issue has since been resolved by HertzDevil, but is not yet the default.
+The issue has since been resolved by @HertzDevil, but is not yet the default.
 To have the fix applied, you must invoke crystal with `crystal run -Dpreview_overload_order ...`.
 
 ## Type-safe `#==` operator:
@@ -125,10 +125,13 @@ For example, to have an operator like `#==?` that behaves like the current `#==`
 arguments are not comparable). And then to change `#==` to a type-safe version so that it produces an
 error when there is no comparison defined between its arguments.
 
+@straight-shoota added this item (although with a different proposed solution) to the wishlist
+for the next Crystal major version (TODO: find a reference to it).
+
 ## API to expose a method to kill Fiber from outside code.
 
-This supposedly exists in non-public API, but maybe it does not exist
-at all?
+This supposedly exists in non-public API, but I did not find it, be it public
+or not.
 
 ## Ability to create a Proc and partial from a method with named args:
 
@@ -144,7 +147,7 @@ ppf = pf.partial(b: 10)
 
 ```
 
-A workaround exists in https://github.com/crystal-lang/crystal/issues/11099
+A workaround was developed by @HertzDevil in https://github.com/crystal-lang/crystal/issues/11099
 
 ## Better subclassing in Procs:
 

benchmarks/cells-vs-arrays.cr

@@ -34,6 +34,20 @@ require "../src/crysterm"
 # changing this part requires a lot of changes. See patches/2-separate-arrays.patch
 # as a good base to finish the work.
 
+# Actually, both above and in the new tests:
+#                                              user     system      total        real
+# class Cell                               1.278690   0.000000   1.278690 (  1.284420)
+# struct Cell                              0.948687   0.000000   0.948687 (  0.952492)
+# separate arrays, combined access yx      0.475821   0.000000   0.475821 (  0.477786)
+# separate arrays, separate access yx      0.548495   0.000000   0.548495 (  0.550808)
+# separate arrays, combined access xy      1.662603   0.000000   1.662603 (  1.669242)
+# separate arrays, separate access xy      1.654704   0.000000   1.654704 (  1.661381)
+# separate 1d arrays, combined access yx   1.282447   0.000000   1.282447 (  1.287833)
+# separate 1d arrays, combined access xy   1.288152   0.000000   1.288152 (  1.293539)
+#
+# it appears the winning option is row 2, which is two separate arrays (1 for attrs,
+# 1 for chars) using combined access, e.g. attrs[width * y + x].
+
 xs = 2000
 ys = 600
 reps = 1000000

documentation/positioning.md

@@ -1,5 +1,8 @@
 # Positioning and sizing in Blessed
 
+NOTE: This document explains how positioning and sizing works in Blessed. The functionality in
+Crysterm is roughly the same or more flexible.
+
 ## Positioning basics / intro
 
 For every widget, Blessed can get, set, and/or calculate its absolute and
@@ -19,7 +22,7 @@ specify `top` and `height`. The same goes for `left`/`right` and `width`, of cou
 
 Normally, position or size is specified as integer value, or is left null for auto-calculation.
 However, in certain cases (listed below) it can be specified as a string containing values 'center',
-'half', or 'xx%' (for a percentage of parent).
+'half', or 'xx%+-amount' (for a percentage of parent, plus or minus a certain value).
 
 1. 'center' makes the widget 50% the size of parent and equally spaced from top and bottom or left and right (i.e. centered).
 1. 'half' equals to half of parent's width or height (i.e. "50%"), without centering.
@@ -35,7 +38,7 @@ bottom border in the parent widget). This is because percentages of parent refer
 not the size remaining after accounting for decorations (borders and padding).
 The solution is same as above, set `height: "100%-2"`.
 
-Finally, not directly related, but important are variables called xi, xl, yi, and yl.
+Finally, not directly related but important, are variables called xi, xl, yi, and yl.
 Those ones do correspond to reference (0,0) on the top-left of the screen.
 
 xi...xl specifies the column range in which the widget is rendered. E.g. a widget at position `left: 10`
@@ -60,7 +63,7 @@ These are offsets "R"elative to the parent widget (or to the screen if the widge
 
 When rleft, rtop, rright or rbottom are set, the following takes place:
 
-If the desired value is identical to the old value, the function exits.
+In Blessed, if the desired value is identical to the old value, the function exits.
 
 If the desired value is not identical to the old value (which is stored in `self.position.*`),
 Blessed does the following:
@@ -71,14 +74,14 @@ Blessed does the following:
 - Sets `self.position.* = value` (e.g. `self.position.left = 30`)
 - Returns the (possibly casted) value that was set
 
-Note from the above that values assigned to l/t/r/b are not kept in properties
+Take note above that values assigned to l/t/r/b are not kept in properties
 of the same name, but setting e.g. `rleft=(value)` actually saves the value to
 `self.position.left`.
 
-Thus, it is these fields in `self.position.*` that contains values directly as
-specified by user (e.g. 30, "center", "30%" etc.)
+Thus, it is these fields in `self.position.*` that contain values directly as
+specified by user (e.g. 30, "center", "30%" etc.).
 
-See more in `lib/widgets/element.js:1369` if interested.
+See more in Blessed's `lib/widgets/element.js:1369` if interested.
 
 ### Getters
 
@@ -97,7 +100,7 @@ based on absolute coordinates. The code is simple:
 
 ### Setters
 
-Setting `width` and `height` behaves the same as setting "r" fields:
+Setting `width` and `height` works the same like setting "r" fields described above:
 
 - If value is an integer passed as a string, casts to int
 - Emits `Resize` event on self
@@ -123,7 +126,7 @@ If left or top value is 'center', then widget's size will be first set to 50% of
 The largest possible space (width or height) is calculated while taking all restrictions into account. In other words, the calculated space
 is limited by the size of parent, amount of parent's "i" values (inner thickness, explained below), and the current widget's desired left/top/right/bottom values.
 
-Therefore, a value of null is very different from setting "100%". Setting 100% or any percentage translates to direct percentage of parent's size,
+Therefore, a value of null is very different from setting "100%". Setting 100% or any other percentage translates to direct percentage of parent's size,
 without accounting for "i" or desired left/top/right/bottom values.
 
 ## Absolute position
@@ -135,7 +138,7 @@ without accounting for "i" or desired left/top/right/bottom values.
 
 ### Setters
 
-There is no place to store the absolute and relative position separately among widget's data (in `self.position.*`).
+There is no place in widgets' properties to store the absolute and relative position separately (in `self.position.*`).
 
 Setting "a" values works similarly to the "r" values. Blessed just subtracts
 the parent's value from the current widget's value to convert absolute to
@@ -161,21 +164,21 @@ of the render. These coordinates are in essence the same as position and size in
 should match 1:1. The only exception/problem is if a widget is moved somehow and lpos values are not
 updated.
 
-But, as Blessed's author says: "However, if we can guarantee that lpos is good and up to date, it can
-be more accurate than the calculated position.
+But, as Blessed's author says:
 
+"However, if we can guarantee that lpos is good and up to date, it can be more accurate than the
+calculated position.
 If the element is being rendered, it's guaranteed that the parent will have been rendered first, in
 which case we can use the parent's lpos instead of recalculating its position (since that might be
-wrong because it doesn't handle content shrinkage)".
-
-Thus, all getter functions have an optional parameter `get`, which defaults to false. When it is
-false, we simply use parent widget to access its width/height, "a" values and "i" values.
+wrong because it doesn't handle content shrinkage)."
 
-When value of `get` is true, then Blessed does not use parent directly, but looks up its
+Thus, all getter functions have an optional parameter `get`, which defaults to false:
+- When it is false, we simply use parent widget to access its width/height, "a" values and "i" values.
+- When value of `get` is true, then Blessed does not use parent directly, but looks up its
 lpos. It returns parent's lpos as-is if its `aleft` (and implicitly all other 'a' values) are
 filled in. If they are not filled in, Blessed first produces them and then returns the lpos object
-which can be used in place of the parent. It produces "a" values based on screen width/height and
-xi...xl, yi...yl values that are/must be already present.
+which can be used in place of parent's calculated values. It produces "a" values based on screen
+width/height and xi...xl, yi...yl values that are/must be already present.
 
 All position-related functions use `get=false`.
 
@@ -235,3 +238,9 @@ them all inside `position` hash. If they're given separately, Blessed packs them
 
 One can also specify `shrink = true` on a widget. This causes widget to render in minimal
 necessary box to accommodate its content.
+
+## Changes in Crysterm
+
+In Crysterm borders can be more than 1 cell big and can be set for each side separately.
+
+Similarly, shadow size and sides can be chosen and set individually for each side.

examples/chat.cr

@@ -90,7 +90,7 @@ class MyProg
         end
       end
       chat.scroll_to chat.get_content.lines.size
-      sleep rand 2
+      sleep (rand 2).seconds
       lag.filled = rand 100
       s.render
     end

examples/colorchart.cr

@@ -33,7 +33,7 @@ end
 
 spawn do
   loop do
-    sleep 1
+    sleep 1.seconds
     s.render
   end
 end

examples/hello.cr

@@ -43,7 +43,7 @@ class MyProg
 
   spawn do
     loop do
-      sleep 2
+      sleep 2.seconds
       b.clear_last_rendered_position
       b.top = rand(s.aheight - b.aheight - 1) + 1
       b.left = rand(s.awidth - b.awidth)

examples/tech-demo.cr

@@ -209,7 +209,7 @@ module Crysterm
       end
       i += 1
       Fiber.yield
-      sleep 0.2
+      sleep 0.2.seconds
     end
   end
 

small-tests/button.cr

@@ -22,7 +22,7 @@ class X
 
     i.on(::Crysterm::Event::Press) do
       STDERR.puts "Pressed; exiting in 2 seconds"
-      sleep 2
+      sleep 2.seconds
       exit
     end
 

small-tests/elements.cr

@@ -34,7 +34,7 @@ class X
 
     i.on(::Crysterm::Event::Press) do
       STDERR.puts "Pressed; exiting in 2 seconds"
-      sleep 2
+      sleep 2.seconds
       exit
     end
 

small-tests/pine.cr

@@ -18,7 +18,7 @@ module Crysterm
 
   s.render
 
-  sleep 2
+  sleep 2.seconds
 
   sbar.status.set_content "[Already at {underline}bottom{/underline} of list]"