Optional Flags

Character Length Flags

The Character Length Flags all pertain to setting the desired lengths for many of Ren'Py's potential text values. Not only does Ren'Py allow developers to render text, but developers can also render data, images, and other things within the text as well. Therefore, there are several flags that you can utilize to help line_brkr.py insert newlines into text in a desirable fashion. The following flags are ordered by relevance.

-t or --text-length

"set max length of text (in characters) before breaking line"

The -t or --text-length flag requires one argument; a number. This flag is the bread and butter of line_brkr.py as this flag lets the user set the maximum length of characters that line_brkr.py will allow before it inserts a newline into any desired Text Displayable text. To use this flag properly, the argument provided must be a non-negative whole number (0 -> ∞) else line_brkr.py will raise an Exception.

There are two types of values you can pass into line_brkr.py with the -t flag:

• 0 (DEFAULT VALUE): passing in 0 with the -t flag tells line_brkr.py that the Text Displayable text should remain unbroken. This means that any newlines within a Text Displayable will be removed.

• n (where n > 0): passing in n with the -t flag tells line_brkr.py that a newline will be inserted into the Text Displayable text when the text length exceeds n characters.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 10
  

  Tells line_brkr.py to begin breaking lines when the line exceeds 10 characters Therefore, this Text Displayable:

  show text "Lorem ipsum\ndolor     sit \n amet"
  pause
  

  Will become this after the program is done running:

  show text "Lorem\nipsum\ndolor sit\namet"
  pause
  

-d or --data-length

"set max length of interpolated data (in characters)"

The -d or --data-length flag requires one argument; a floating-point number. Ren'Py allows developers to Interpolate Data within their text. Because this data can have varying lengths, it is the responsibility of the user of line_brkr.py to specify what that length is. Thus, the -d or --data-length is used to define that length for line_brkr.py. To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

There are three types of values you can pass into line_brkr.py with the -d flag:

• -1: passing in -1 with the -d flag tells line_brkr.py that the Text Displayable data has the same length as the max text length. In other words, every block of interpolated data that line_brkr.py handles will be isolated on its own line.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 50 -d -1
  

  Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 50 characters long, and that we want to break text after it exceeds 50 characters. Therefore, this Text Displayable:

  $ data = "dolor"
  show text "Lorem ipsum [data] sit amet"
  pause
  

  Will become this after the program is done running:

  $ data = "dolor"
  show text "Lorem ipsum\n[data]\nsit amet"
  pause
  

• 0 (DEFAULT VALUE): passing in 0 with the -d flag tells line_brkr.py that the Text Displayable data has no length. This means that every block of interpolated data that line_brkr.py handles will have a length of 0.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25
  

  Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 0 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

  $ data = "dolor"
  show text "Lorem ipsum [data] sit amet"
  pause
  

  Will become this after the program is done running:

  $ data = "dolor"
  show text "Lorem ipsum [data] sit amet"
  pause
  

• n (where n > 0.0): passing in n with the -d flag tells line_brkr.py that the Text Displayable data is n characters long.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d 10
  

  Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 10 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

  $ data = "dolor"
  show text "Lorem ipsum [data] sit amet"
  pause
  

  Will become this after the program is done running:

  $ data = "dolor"
  show text "Lorem ipsum [data]\nsit amet"
  pause
  

  Do note that (where m = text length and n = data length) when n < m then the data will be surrounded by other text if possible, else if n > m then all interpolated data will be isolated to its own line.

  In other words, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d 500
  

  Is effectively the same as entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d -1
  

-i or --image-length

"set max length of in text images (in characters)"

The -i or --image-length flag requires one argument; a floating-point number. Of the many Ren'Py Text Tags, the image tag stands out because it grants the developers the ability to insert a custom image into their text. While this "image should be the height of a single line of text" its width is left undefined. Because this image can have varying widths, it is the responsibility of the user of line_brkr.py to specify what that width is. Thus, the -i or --image-length is used to define that image length for line_brkr.py. To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

• -1: passing in -1 with the -i flag tells line_brkr.py that all Text Displayable image tags have the same length as the max text length. In other words, every image tag that line_brkr.py handles will be isolated on its own line.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 50 -i -1
  

  Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 50 characters long, and that we want to break text after it exceeds 50 characters. Therefore, this Text Displayable:

  show text "Lorem ipsum {image=dolor.jpg} sit amet"
  pause
  

  Will become this after the program is done running:

  show text "Lorem ipsum\n{image=dolor.jpg}\nsit amet"
  pause
  

• 0 (DEFAULT VALUE): passing in 0 with the -d flag tells line_brkr.py that the Text Displayable image has no length. This means that every image tag that line_brkr.py handles will have a length of 0.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25
  

  Tells line_brkr.py that any image tag in any Text Displayable within script.rpy is 0 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

  show text "Lorem ipsum {image=dolor.jpg} sit amet"
  pause
  

  Will become this after the program is done running:

  show text "Lorem ipsum {image=dolor.jpg} sit amet"
  pause
  

• n (where n > 0.0): passing in n with the -d flag tells line_brkr.py that the Text Displayable image tag is n characters long.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i 10
  

  Tells line_brkr.py that any image tag in any Text Displayable within script.rpy is 10 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

  show text "Lorem ipsum {image=dolor.jpg} sit amet"
  pause
  

  Will become this after the program is done running:

  show text "Lorem ipsum {image=dolor.jpg}\nsit amet"
  pause
  

  Do note that (where m = text length and n = image length) when n < m then the image tag will be surrounded by other text if possible, else if n > m then all interpolated data will be isolated to its own line.

  In other words, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i 500
  

  Is effectively the same as entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i -1
  

-s or --space-length

"set max length of space characters (in pixels)"

The -s or --space-length flag requires one argument; a number. Of the many Ren'Py Text Tags, the space tag stands out because it grants the developers the ability to insert whitespace into their text without the need for many escaped space characters ('\ '). However, unlike escaped spaces, the space tag renders white space in pixels not characters. Given how varied the sizes of space characters can be, it is the responsibility of the user of line_brkr.py to specify what that character to pixel ratio is. Thus, the -s or --space-length is used to define how many pixels constitutes a single space character. In other words, space tag value / space length value = # of space characters. For example, a space tag {space=50} with a --space-length of 10 holds 5 characters worth of whitespace (50 / 10 = 5). To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

There are two types of values you can pass into line_brkr.py with the -s flag:

• 0 (DEFAULT VALUE): passing in 0 with the -s flag tells line_brkr.py that the Text Displayable space tag has no character to pixel ratio. This means that any space tag will be left as is.

• n (where n > 0): passing in n with the -s flag tells line_brkr.py that a single whitespace character is n pixels long.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -t 10 -s 10
  

  Tells line_brkr.py to begin breaking lines when the line exceeds 10 characters, and that single character of whitespace is 10 pixels wide. Therefore, this Text Displayable:

  show text "Lorem ipsum {space=200} dolor sit amet"
  pause
  

  Will become this after the program is done running:

  show text "Lorem\nipsum {space=60}\n{space=100}\n{space=40} dolor\nsit amet"
  pause
  

Note that line_brkr.py will split space tags if it can. Furthermore, this space tag splitting cannot be reset by line_brkr.py, so it is the responsibility of the user to manage this behavior if desired.

File Line Flags

The File Line Flags are used to control which lines line_brkr.py will process within the read file specified by the -r flag. This helps in the scenario where a user wants line_brkr.py to process certain lines of code instead of every possible line it can (the default behavior). There are two flags to chose from, the -x or --exclude-line flag and the -n or --include-line flag.

You cannot use both flags when running line_brkr.py or an Exception will be raised.

-x or --exclude-line

"if not using --include-line, set line(s) in file you want the program to exclude"

The -x or --exclude-line flag requires one argument; text in the format specified by File Line Argument Format. By default, line_brkr.py will process every possible Text Displayable in whatever read file you specify. However, sometimes a user may desire line_brkr.py to not process some lines. In those cases, I recommend using the -x flag. Unlike its inverse flag -n (or --include-line), -x tells line_brkr.py which lines to exclude when line_brkr.py processes the desired read file.

-n or --include-line

"if not using --exclude-line, set line(s) in file you want the program to include"

The -n or --include-line flag requires one argument; text in the format specified by File Line Argument Format. By default, line_brkr.py will process every possible Text Displayable in whatever read file you specify. However, sometimes a user may desire line_brkr.py to process only some lines, but not all of them. In those cases, I recommend using the -n flag. Unlike its inverse flag -x (or --exclude-line), -n tells line_brkr.py which lines to include when line_brkr.py processes the desired read file.

File Line Argument Format

To use the exclude flag (-x or --exclude-line) or include flag (-n or --include-line), the user must specify what line(s) they want to exclude/include when line_brkr.py processes the read file. To do this, the user must provide one of three possible values:

• n (where n > 0): passing in n with any File Line Flag tells line_brkr.py to exclude or include the file line depending on the flag preceding n.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -x 200
  

  Tells line_brkr.py to exclude line 200 from being processed. Likewise, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -n 200
  

  Tells line_brkr.py to include line 200 in the process.

• n-m (where n > 0 and n < m): passing in n-m with any File Line Flag tells line_brkr.py to exclude or include a range of lines. Therefore, any line greater than n and less than m will be excluded/included.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -x 150-300
  

  Tells line_brkr.py to exclude lines 150 through 300 from being processed. Likewise, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -n 150-300
  

  Tells line_brkr.py to include lines 150 through 300 in the process.

• a comma-delimited list of any of the previous values: passing in a list of lines, ranges of lines, or both with any File Line Flag tells line_brkr.py to exclude or include all lines or ranges in the process.

  For example, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -x 50,150-300,445
  

  Tells line_brkr.py to exclude line 50, lines 150 through 300, and line 445 from being processed. Likewise, entering this command:

  python line_brkr.py -r script.rpy -w newscript.rpy -n 50,150-300,445
  

  Tells line_brkr.py to include line 50, lines 150 through 300, and line 445 in the process.

There cannot be any spaces in the list, every value must be separated by a comma or errors may occur.