OpenMode (Jython API documentation)
Date: 2020-03-21

org.python.modules._io

## Class OpenMode

- java.lang.Object
- - org.python.modules._io.OpenMode

-     public class OpenMode
      extends java.lang.Object

  An object able to check a file access mode provided as a String and represent it as boolean attributes and in a normalised form. Such a string is the the mode argument of the several open() functions available in Python and certain constructors for streams-like objects.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `boolean` | `appending` Whether this file is opened in appending mode ('a')
    `boolean` | `binary` Whether this file is opened in binary mode ('b')
    `boolean` | `invalid` Set true when any invalid symbol or combination is discovered
    `java.lang.String` | `message` Error message describing the way in which the mode is invalid, or null if no problem has been found.
    `java.lang.String` | `originalModeString` Original string supplied as the mode
    `boolean` | `other` Whether the mode contained some other symbol from the allowed ones
    `boolean` | `reading` Whether this file is opened for reading ('r')
    `boolean` | `text` Whether this file is opened in text mode ('t')
    `boolean` | `universal` Whether this file is opened in universal newlines mode ('U')
    `boolean` | `updating` Whether this file is opened for updating ('+')
    `boolean` | `writing` Whether this file is opened for writing ('w')

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `OpenMode(java.lang.String mode)` Decode the given string to an OpenMode object, checking for duplicate or unrecognised mode letters.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkValid()` Call `validate()` and raise an exception if the mode string is not valid, as signalled by either `invalid` or `other` being `true` after that call.
    `java.lang.String` | `forFileIO()` The mode string we need when constructing a `FileIO` initialised with the present mode.
    `java.lang.String` | `text()` The mode string that a text file should claim to have, when initialised with the present mode.
    `java.lang.String` | `toString()`
    `void` | `validate()` Adjust and validate the flags decoded from the mode string.
    `void` | `validate(java.lang.String encoding, java.lang.String errors, java.lang.String newline)` Perform additional validation of the flags relevant to text files.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### originalModeString

          public final java.lang.String originalModeString

      Original string supplied as the mode

    - #### reading

          public boolean reading

      Whether this file is opened for reading ('r')

    - #### writing

          public boolean writing

      Whether this file is opened for writing ('w')

    - #### appending

          public boolean appending

      Whether this file is opened in appending mode ('a')

    - #### updating

          public boolean updating

      Whether this file is opened for updating ('+')

    - #### binary

          public boolean binary

      Whether this file is opened in binary mode ('b')

    - #### text

          public boolean text

      Whether this file is opened in text mode ('t')

    - #### universal

          public boolean universal

      Whether this file is opened in universal newlines mode ('U')

    - #### other

          public boolean other

      Whether the mode contained some other symbol from the allowed ones

    - #### invalid

          public boolean invalid

      Set true when any invalid symbol or combination is discovered

    - #### message

          public java.lang.String message

      Error message describing the way in which the mode is invalid, or null if no problem has been found. This field may be set by the constructor (in the case of duplicate or unrecognised mode letters), by the `validate()` method, or by client code.

  - ### Constructor Detail

    - #### OpenMode

          public OpenMode(java.lang.String mode)

      Decode the given string to an OpenMode object, checking for duplicate or unrecognised mode letters. Valid letters are those in "rwa+btU". Errors in the mode string do not raise an exception, they simply generate an appropriate error message in `message`. After construction, a client should always call `validate()` to complete validity checks.
      Parameters:
        `mode` -

  - ### Method Detail

    - #### validate

          public void validate()

      Adjust and validate the flags decoded from the mode string. The method affects the flags where the presence of one flag implies another, then if the `invalid` flag is not already `true`, it checks the validity of the flags against combinations allowed by the Python `io.open()` function. In the case of a violation, it sets the `invalid` flag, and sets `message` to a descriptive message. The point of the qualification "if the `invalid` flag is not already `true`" is that the message should always describe the first problem discovered. If left blank, as in fact the constructor does, it will be filled by the generic message when `checkValid()` is finally called. Clients may override this method (by sub-classing) to express the validation correct in their context.

      The invalid combinations enforced here are those for the "raw" (ie non-text) file types:

      - `universal & (writing | appending)`,
      - `text & binary`,
      - `reading & writing`,
      - `appending & (reading | writing)`
      See also `validate(String, String, String)` for additional checks relevant to text files.

    - #### validate

          public void validate(java.lang.String encoding,
                               java.lang.String errors,
                               java.lang.String newline)

      Perform additional validation of the flags relevant to text files. If `invalid` is not already `true`, and the mode includes `binary`, then all the arguments to this call must be `null`. If the criterion is not met, then on return from the method, `invalid==true` and `message` is set to a standard error message. This is the standard additional validation applicable to text files. (By "standard" we mean the test and messages that CPython `io.open` uses.)
      Parameters:
        `encoding` - argument to `open()`
        `errors` - argument to `open()`
        `newline` - argument to `open()`

    - #### checkValid

          public void checkValid()
                          throws PyException

      Call `validate()` and raise an exception if the mode string is not valid, as signalled by either `invalid` or `other` being `true` after that call. If no more specific message has been assigned in `message`, report the original mode string.
      Throws:
        `PyException` - `ValueError` if the mode string was invalid.

    - #### forFileIO

          public java.lang.String forFileIO()

      The mode string we need when constructing a `FileIO` initialised with the present mode. Note that this is not the same as the full open mode because it omits the text-based attributes.
      Returns:
        "r", "w", or "a" with optional "+".

    - #### text

          public java.lang.String text()

      The mode string that a text file should claim to have, when initialised with the present mode. Note that this only contains text-based attributes. Since mode 't' has no effect, except to produce an error if specified with 'b', we don't reproduce it.
      Returns:
        "", or "U".

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

Jython homepage