STh!"^dZddlZddlmZdZddZdZdZd Zd Z d Z d Z d Z dZ dZy)u Implements support for grapheme clusters and cells (columns on screen). Graphemes are sequences of codepoints, which are interpreted together based on the Unicode standard. Grapheme clusters are sequences of graphemes, glued together by Zero Width Joiners. These graphemes may occupy one or two cells on screen, depending on their glyph size. Support for these cool chars, like Emojis 😃, was so damn hard to implement because: 1. Python don't know chars that occupy two columns on screen, nor grapheme clusters that are rendered as a single char (wide or not), it only understands codepoints; 2. Alive-progress needs to visually align all frames, to keep its progress bars' lengths from spiking up and down while running. For this I must somehow know which chars are wide and counterbalance them; 3. To generate all those cool animations, I need several basic operations, like len, iterating, indexing, slicing, concatenating and reversing, which suddenly don't work anymore, since they do not know anything about these new concepts of graphemes and cells! Argh. 4. As the first step, I needed to parse the codepoints into Unicode graphemes. I tried to parse them myself, but soon realized it was tricky and finicky, in addition to changing every year... 5. Then I looked into some lib dependencies, tested several, created the validate tool to help me test some Unicode versions, and chose one lib to use; 6. I finally implemented the operations I needed, to the best of my current knowledge, but it still wouldn't work. So I tried several spinners to check their alignments, until I finally realized what was wrong: I actually needed to align cells, not lengths nor even graphemes! Look this for example: Note that in your editor both strings below are perfectly aligned, although they have 6 and 16 as their Python lengths!!! How come? Graphemes didn't help either, 6 and 3 respectively... Then how does the editor know that they align? I'm not sure exactly, but I created this "cell" concept to map this into, and finally they both have the same: 6 cells!! 💡😜 string \ length python graphemes cells nonono 6 6 6 🏴󠁧󠁢󠁥󠁮󠁧󠁿👉🏾🏴󠁧󠁢󠁥󠁮󠁧󠁿 16 3 6 7. With that knowledge, I implemented "wide" marks on graphemes (so I could know whether a grapheme glyph would occupy 1 or 2 cells on screen), and refactored all needed operations. It seemed fine but still didn't work... I then realized that my animations made those wide chars dynamically enter and leave the frame, which can split strings AT ANY POINT, even between the two cells of wide-graphemes, yikes!!! To make the animations as fluid as always, I had to continue moving only one cell per tick time, so somehow I would have to draw "half" flags and "half" smiling- face-with-smiling-eyes!! 8. So, I had to support printing "half-graphemes", so I could produce frames in an animation with always the same sizes!! This has led me to implement a fixer for dynamically broken graphemes, which detects whether the head or tail cells were missing, and inserted a space in its place! 9. It worked! But I would have to run that algorithm throughout the whole animation, in any and all displayed frame, in real time... I feared for the performance. I needed something that could cache and "see" all the frames at once, so I could equalize their sizes only once!! So I created the cool spinner compiler, an ingenious piece of software that generates the entire animation ahead of time, fixes all the frames, and leverages a super light and fast runner, which is able to "play" this compiled artifact!! 10. Finally, I refactored the frame spinner factory, the simplest one to test the idea, and WOW... It worked!!! The joy of success filled me.......... 11. To make the others work, I created the check tool, another ingenious software, which allowed me to "see" a spinner's contents, in a tabular way, directly from the compiled data! Then I could visually ensure whether ALL generated frames of ALL animations I could think of, had the exact same size; 12. A lot of time later, everything was working! But look at that, the spinner compiler has enabled me to make several improvements in the spinners' codes themselves, since it ended up gaining other cool functionalities like reshaping and transposing data, or randomizing anything playing! The concepts of "styling" and "operational" parameters got stronger with new commands, which enabled simpler compound animations, without any code duplication! And this has culminated in the creation of the newer sequential and alongside spinners, way more advanced than before, with configurations like intermixing and pivoting of cycles! 13. Then, it was time I moved on to the missing components in this new Cell Architecture: the bar, title, exhibit, and of course the alive_bar rendering itself... All of them needed to learn this new architecture: mainly change ordinary strings into tuples of cells (marked graphemes)... 14. And finally... Profit!!! Only no, this project only feels my soul, not my pocket... But what a ride! 😅 N)sanitizeu︎c\|}|j|jtd|D]a}|dk(r|j||}n,|dk(r"t |}||kr||z}ndt |d|}}|jt |c|r||z |kr|j|||z S)a&Print a tuple of fragments of tuples of cells on the terminal, until a given number of cols is achieved, slicing over cells when needed. Spaces used to be inserted automatically between fragments, but not anymore. Args: fragments (Tuple[Union[str, Tuple[str, ...]]): the fragments of message cols (int): maximum columns to use term: the terminal to be used last_line_len (int): if the fragments fit within the last line, send a clear end line Returns: the number of actually used cols. N r)writecarriage_returnfilterclear_end_linelen fix_cells join_cells) fragmentscolsterm last_line_len availablefragmentlengths _/home/www/backend.miabetepe.com/venv/lib/python3.12/site-packages/alive_progress/utils/cells.py print_cellsrNs IJJt##$4+ ) t     *I !^ ]F"V# &'8JY3G)H8  :h'( ) )M9 I& ) c6djt|S)zyBeware, this looses the cell information, converting to a simple string again. Don't use unless it is a special case.)join strip_marks)rs rr r us 77;x( ))rct|dS)zCombine several fragments of cells into one. Remember that the fragments get a space between them, so this is mainly to avoid it when not desired.sum)rs r combine_cellsr {s y" rcl|dtk7xr't|dkDxstj|dvS)uTry to detect wide chars. This is tricky, I've seen several graphemes that have Neutral width (and thus use one cell), but actually render as two cells, like shamrock and heart ☘️❤️. I've talked to George Nachman, the creator of iTerm2, which has explained to me [1] the fix would be to insert a space after these cases, but I can't possibly know if this behavior is spread among all terminals, it probably has to do with the Unicode version too, so I'm afraid of fixing it. Use the `alive_progress.tools.print_chars` tool, and check the section around `0x1f300` for more examples. [1]: https://gitlab.com/gnachman/iterm2/-/issues/9185 Args: g (str): the grapheme sequence to be tested r)WF)VS_15r unicodedataeast_asian_width)gs ris_wider)s5$ R5E> [s1vzZ[-I-I!-LPZ-Z[rc||s|S|ddnd}|dt|drdnd}g||t||rdnd|S)z9Fix truncated cells, removing whole clusters when needed.rN) rr")r)bool)charsstartends rr r sY  Ah&FBE"I)geBi.@&bC BU BU4;Srd; Bc BBrc<ttt|SN)mark_graphemessplit_graphemesrtexts rto_cellsr6s /(4.9 ::rc0ddlm}t||S)Nr) graphemes)graphemer8tuple)r5r8s rr3r3s" 4 !!rc(td|DdS)Nc3BK|]}|gt|rdndyw)r1rNr)).0r(s r z!mark_graphemes..s B!5g5Bsrr)gss rr2r2s BrBB GGrcd|DS)Nc3&K|] }|s| ywr1r)r>cs rr?zstrip_marks..s "!A "sr)r-s rrrs "u ""rc&td|DS)Nc32K|]}t|ywr1r=)r>xs rr?zhas_wide..s(awqz(s)anyr4s rhas_widerHs (4( ((r)r)__doc__r&rrr%rr r r)r r6r3r2rrHrrrrJsODL$N* \*C;" H#)r