"textwrap" --- Περιτύλιγμα και γέμισμα κειμένου
***********************************************

**Πηγαίος κώδικας:** Lib/textwrap.py

======================================================================

Το module "textwrap" παρέχει μερικές συναρτήσεις ευκολίας, καθώς και
την "TextWrapper", την κλάση που κάνει όλη τη δουλειά. Αν απλά
περιτυλίγετε ή γεμίζετε ένα ή δύο κείμενα, οι συναρτήσεις ευκολίας θα
είναι αρκετές· διαφορετικά, θα πρέπει να χρησιμοποιήσετε ένα
στιγμιότυπο της "TextWrapper" για αποδοτικότητα.

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

   Περιτυλίγει την ενιαία παράγραφο στο *text* (μία συμβολοσειρά) έτσι
   ώστε κάθε γραμμή να έχει το πολύ *width* αριθμό χαρακτήρες.
   Επιστρέφει μια λίστα με τις γραμμές εξόδου, χωρίς τελικούς
   χαρακτήρες νέας γραμμής.

   Προαιρετικά ορίσματα λέξεων-κλειδιών αντιστοιχούν στις ιδιότητες
   στιγμιότυπου της "TextWrapper", που τεκμηριώνονται παρακάτω.

   Δείτε τη μέθοδο "TextWrapper.wrap()" για πρόσθετες λεπτομέρειες
   σχετικά με το πώς συμπεριφέρεται η "wrap()".

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

   Γεμίζει την ενιαία παράγραφο στο *text* και επιστρέφει μια μοναδική
   συμβολοσειρά που περιέχει την γεμισμένη παράγραφο. Η "fill()" είναι
   συντομογραφία για

      "\n".join(wrap(text, ...))

   Συγκεκριμένα, η "fill()" δέχεται ακριβώς τα ίδια ορίσματα
   λέξεων-κλειδιών με την "wrap()".

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

   Συμπτύξτε και περικόψτε το δοθέν *text* ώστε να χωράει στο δοθέν
   *width*.

   Αρχικά, ο χώρος στο *text* συμπτύσσεται (όλος ο χώρος
   αντικαθίσταται με μονά κενά). Αν το αποτέλεσμα χωράει στο *width*,
   επιστρέφεται. Διαφορετικά, αρκετές λέξεις απορρίπτονται από το
   τέλος ώστε οι υπόλοιπες λέξεις συν το *placeholder* να χωρούν μέσα
   στο *width*:

      >>> textwrap.shorten("Hello  world!", width=12)
      'Hello world!'
      >>> textwrap.shorten("Hello  world!", width=11)
      'Hello [...]'
      >>> textwrap.shorten("Hello world", width=10, placeholder="...")
      'Hello...'

   Προαιρετικά ορίσματα λέξεων-κλειδιών αντιστοιχούν στις ιδιότητες
   στιγμιότυπου της "TextWrapper", που τεκμηριώνονται παρακάτω.
   Σημειώστε ότι ο χώρος συμπτύσσεται πριν το κείμενο περαστεί στη
   συνάρτηση "fill()" της "TextWrapper", έτσι ώστε η αλλαγή της τιμής
   των "tabsize", "expand_tabs", "drop_whitespace" και
   "replace_whitespace" να μην έχει καμία επίδραση.

   Added in version 3.4.

textwrap.dedent(text)

   Αφαιρεί οποιοδήποτε κοινό αρχικό κενό από κάθε γραμμή στο *text*.

   Αυτό μπορεί να χρησιμοποιηθεί για να ευθυγραμμίσετε τις τριπλές
   παραθέσεις με την αριστερή άκρη της οθόνης, ενώ παρουσιάζονται στον
   πηγαίο κώδικα σε μορφή εσοχής.

   Σημειώστε ότι τα tab και τα κενά θεωρούνται και τα δύο ως κενό,
   αλλά δεν είναι ίσα: οι γραμμές ""  hello"" και ""\thello""
   θεωρούνται ότι δεν έχουν κοινό αρχικό κενό.

   Οι γραμμές που περιέχουν μόνο κενό αγνοούνται στην είσοδο και
   κανονικοποιούνται σε έναν μόνο χαρακτήρα νέας γραμμής στην έξοδο.

   Για παράδειγμα:

      def test():
          # end first line with \ to avoid the empty line!
          s = '''\
          hello
            world
          '''
          print(repr(s))          # prints '    hello\n      world\n    '
          print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

   Προσθέτει το *prefix* στην αρχή των επιλεγμένων γραμμών στο *text*.

   Οι γραμμές διαχωρίζονται καλώντας "text.splitlines(True)".

   Από προεπιλογή, το *prefix* προστίθεται σε όλες τις γραμμές που δεν
   αποτελούνται μόνο από κενό (συμπεριλαμβανομένων των χαρακτήρων
   τέλους γραμμής).

   Για παράδειγμα:

      >>> s = 'hello\n\n \nworld'
      >>> indent(s, '  ')
      '  hello\n\n \n  world'

   Το προαιρετικό όρισμα *predicate* μπορεί να χρησιμοποιηθεί για
   έλεγχο του ποια γραμμή θα έχει εσοχή. Για παράδειγμα, είναι εύκολο
   να προσθέσετε το *prefix* ακόμη και σε κενές γραμμές και γραμμές
   που περιέχουν μόνο κενό:

      >>> print(indent(s, '+ ', lambda line: True))
      + hello
      +
      +
      + world

   Added in version 3.3.

Οι "wrap()", "fill()" και "shorten()" λειτουργούν δημιουργώντας ένα
στιγμιότυπο της "TextWrapper" και καλώντας μια μόνο μέθοδο σε αυτό.
Αυτό το στιγμιότυπο δεν επαναχρησιμοποιείται, οπότε για εφαρμογές που
επεξεργάζονται πολλά κείμενα χρησιμοποιώντας "wrap()" και/ή "fill()",
μπορεί να είναι πιο αποδοτικό να δημιουργήσετε το δικό σας αντικείμενο
"TextWrapper".

Το κείμενο προτιμάται να περιτυλίγεται σε κενά και αμέσως μετά τις
παύλες σε λέξεις με παύλες· μόνο τότε θα σπάσουν οι μακριές λέξεις αν
είναι αναγκαίο, εκτός εάν η "TextWrapper.break_long_words" οριστεί σε
false.

class textwrap.TextWrapper(**kwargs)

   Ο κατασκευαστής της "TextWrapper" δέχεται αρκετά προαιρετικά
   ορίσματα λέξεων-κλειδιών. Κάθε όρισμα λέξης-κλειδιού αντιστοιχεί σε
   μια ιδιότητα στιγμιότυπου, οπότε για παράδειγμα

      wrapper = TextWrapper(initial_indent="* ")

   είναι το ίδιο με

      wrapper = TextWrapper()
      wrapper.initial_indent = "* "

   Μπορείτε να επαναχρησιμοποιήσετε το ίδιο αντικείμενο "TextWrapper"
   πολλές φορές, και μπορείτε να αλλάξετε οποιαδήποτε από τις επιλογές
   του μέσω άμεσης ανάθεσης σε ιδιότητες στιγμιότυπου μεταξύ των
   χρήσεων.

   Οι ιδιότητες στιγμιότυπου της "TextWrapper" (και τα ορίσματα
   λέξεων-κλειδιών στον κατασκευαστή) είναι οι εξής:

   width

      (προεπιλογή: "70") Το μέγιστο μήκος των περιτυλιγμένων γραμμών.
      Εφόσον δεν υπάρχουν μεμονωμένες λέξεις στο εισαγόμενο κείμενο
      μεγαλύτερες από "width", η "TextWrapper" εγγυάται ότι καμία
      γραμμή εξόδου δεν θα είναι μεγαλύτερη από "width" χαρακτήρες.

   expand_tabs

      (προεπιλογή: "True") Αν είναι true, τότε όλοι οι χαρακτήρες tab
      στο *text* θα επεκταθούν σε κενά χρησιμοποιώντας τη μέθοδο
      "expandtabs()" του *text*.

   tabsize

      (προεπιλογή: "8") Αν "expand_tabs" είναι true, τότε όλοι οι
      χαρακτήρες tab στο *text* θα επεκταθούν σε μηδέν ή περισσότερα
      κενά, ανάλογα με την τρέχουσα στήλη και το δεδομένο μέγεθος tab.

      Added in version 3.3.

   replace_whitespace

      (προεπιλογή: "True") Αν είναι true, μετά την επέκταση των tab
      αλλά πριν το περιτύλιγμα, η μέθοδος "wrap()" θα αντικαταστήσει
      κάθε χαρακτήρα κενών με ένα μόνο κενό. Οι χαρακτήρες κενών που
      αντικαθίστανται είναι οι εξής: tab, νέα γραμμή, κάθετος,
      τροφοδότης μορφής και carriage return ("'\t\n\v\f\r'").

      Σημείωση:

        (προεπιλογή: "True") Αν το "expand_tabs" είναι false και το
        "replace_whitespace" είναι true, κάθε χαρακτήρας tab θα
        αντικατασταθεί από ένα μόνο κενό, το οποίο *δεν είναι* το ίδιο
        με την επέκταση των tab.

      Σημείωση:

        Αν το "replace_whitespace" είναι false, οι νέες γραμμές μπορεί
        να εμφανιστούν στη μέση μιας γραμμής και να προκαλέσουν
        παράξενα αποτελέσματα. Για αυτόν τον λόγο, το κείμενο θα
        πρέπει να διαχωρίζεται σε παραγράφους (χρησιμοποιώντας
        "str.splitlines()" ή παρόμοια) οι οποίες περιτυλίγονται
        ξεχωριστά.

   drop_whitespace

      (προεπιλογή: "True") Αν είναι true, το κενό στην αρχή και στο
      τέλος κάθε γραμμής (μετά το περιτύλιγμα αλλά πριν την εσοχή)
      αφαιρείται. Το κενό στην αρχή της παραγράφου, ωστόσο, δεν
      αφαιρείται αν ακολουθείται από μη κενό. Αν το κενό που
      αφαιρείται καταλαμβάνει ολόκληρη τη γραμμή, ολόκληρη η γραμμή
      αφαιρείται.

   initial_indent

      (προεπιλογή: "''") Συμβολοσειρά που θα προστεθεί στην αρχή της
      πρώτης γραμμής της περιτυλιγμένης εξόδου. Μετράει προς το μήκος
      της πρώτης γραμμής. Η κενή συμβολοσειρά δεν έχει εσοχή.

   subsequent_indent

      (προεπιλογή: "''") Συμβολοσειρά που θα προστεθεί στην αρχή όλων
      των γραμμών της περιτυλιγμένης εξόδου εκτός από την πρώτη.
      Μετράει προς το μήκος κάθε γραμμής εκτός από την πρώτη.

   fix_sentence_endings

      (προεπιλογή: "False") Αν είναι true, η "TextWrapper" προσπαθεί
      να ανιχνεύσει τα τέλη προτάσεων και να διασφαλίσει ότι οι
      προτάσεις διαχωρίζονται πάντα από ακριβώς δύο κενά. Αυτό είναι
      γενικά επιθυμητό για κείμενα σε γραμματοσειρά μονού διαστήματος.
      Ωστόσο, ο αλγόριθμος ανίχνευσης προτάσεων δεν είναι τέλειος:
      υποθέτει ότι ένα τέλος πρότασης αποτελείται από ένα πεζό γράμμα
      ακολουθούμενο από ένα από τα "'.'", "'!'" ή "'?'", πιθανώς
      ακολουθούμενο από ένα από τα "'"'" ή ""'"", ακολουθούμενο από
      ένα κενό. Ένα πρόβλημα με αυτόν τον αλγόριθμο είναι ότι δεν
      μπορεί να ανιχνεύσει τη διαφορά μεταξύ "Dr." στο

         [...] Dr. Frankenstein's monster [...]

      and "Spot." in

         [...] See Spot. See Spot run [...]

      "fix_sentence_endings" είναι false από προεπιλογή.

      Δεδομένου ότι ο αλγόριθμος ανίχνευσης προτάσεων βασίζεται στο
      "string.lowercase" για τον ορισμό του "πεζού γράμματος", και μια
      σύμβαση χρήσης δύο κενών μετά από μια τελεία για τον διαχωρισμό
      των προτάσεων στην ίδια γραμμή, είναι συγκεκριμένος για κείμενα
      στα αγγλικά.

   break_long_words

      (προεπιλογή: "True") Αν είναι true, τότε οι λέξεις μεγαλύτερες
      από "width" θα σπάσουν για να διασφαλιστεί ότι καμία γραμμή δεν
      θα είναι μεγαλύτερη από "width". Αν είναι false, οι μακριές
      λέξεις δεν θα σπάσουν, και μερικές γραμμές μπορεί να είναι
      μεγαλύτερες από "width". (Οι μακριές λέξεις θα τοποθετηθούν σε
      μια γραμμή από μόνες τους, για να ελαχιστοποιηθεί το ποσό κατά
      το οποίο ξεπερνάται το "width").

   break_on_hyphens

      (προεπιλογή: "True") Αν είναι true, το περιτύλιγμα θα συμβαίνει
      προτιμότερα σε κενά και αμέσως μετά τις παύλες σε σύνθετες
      λέξεις, όπως είναι συνηθισμένο στα αγγλικά. Αν είναι false, μόνο
      τα κενά θα θεωρούνται ως πιθανές καλές θέσεις για διακοπές
      γραμμής, αλλά πρέπει να ορίσετε το "break_long_words" σε false
      αν θέλετε πραγματικά αδιάσπαστες λέξεις. Η προεπιλεγμένη
      συμπεριφορά στις προηγούμενες εκδόσεις ήταν να επιτρέπεται πάντα
      η διάσπαση των λέξεων με παύλες.

   max_lines

      (προεπιλογή: "None") Αν δεν είναι "None", τότε η έξοδος θα
      περιέχει το πολύ *max_lines* γραμμές, με το *placeholder* να
      εμφανίζεται στο τέλος της εξόδου.

      Added in version 3.4.

   placeholder

      (προεπιλογή: "' [...]'") Συμβολοσειρά που θα εμφανίζεται στο
      τέλος του κειμένου εξόδου αν έχει περικοπεί.

      Added in version 3.4.

   Η "TextWrapper" παρέχει επίσης μερικές δημόσιες μεθόδους, παρόμοιες
   με τις συναρτήσεις ευκολίας σε επίπεδο module:

   wrap(text)

      Περιτυλίγει την ενιαία παράγραφο στο *text* (μία συμβολοσειρά)
      έτσι ώστε κάθε γραμμή να έχει το πολύ "width" χαρακτήρες. Όλες
      οι επιλογές περιτυλίγματος λαμβάνονται από τις ιδιότητες
      στιγμιότυπου της "TextWrapper" κλάσης. Επιστρέφει μια λίστα με
      τις γραμμές εξόδου, χωρίς τελικούς χαρακτήρες νέας γραμμής. Αν η
      περιτυλιγμένη έξοδος δεν έχει περιεχόμενο, η επιστρεφόμενη λίστα
      είναι κενή.

   fill(text)

      Γεμίζει την ενιαία παράγραφο στο *text* και επιστρέφει μια
      μοναδική συμβολοσειρά που περιέχει την γεμισμένη παράγραφο.
