Native OS Files

TIPI typically looks for files to be in TIFILES format. However, there are features built into TIPI that allow read and sometimes write access to native os files.

Text files

If a host os file is named ending in .txt, .TXT, .xb, .XB, .tb, .TB, .bas, .BAS, .b99, or .B99, then TIPI will allow opening and reading the file as DISPLAY VARIABLE 80.

BASIC / XB source files

If a host os file is named ending in .xb, .XB, .tb, .TB, .bas, .BAS, .b99, or .B99, then TIPI will allow loading the file as a PROGRAM IMAGE file even though it is ascii text. It will be converted to BASIC bytecode by xbas99 and in the case of .tb or .TB files it will first be pre-processed by Tidbit.

If a program image is saved on TIPI and the name used ends in /xb, /XB, /bas, /BAS, /b99, or /B99, then the file will be saved as a ascii text file as well.

Other

Files with none of the above name patterns will appear to the TI-99/4A as DISPLAY FIXED 128 files. The final record will be padded with 0 when read.

Classic99 ?W, and ?X support

Classic99 introduces an option to modify when native files are written. Some of that is supported by TIPI.

?W - write text

Example path name:

TIPI.?W.SOMEDIR.SOMEFILE

This will create a file on the TIPI. drive in the SOMEDIR directory named SOMEFILE. The file will not have the TIFILES header. Each record will be written as a single line to the file. This is only valid for files opened in DISPLAY mode (not INTERNAL). If the file is of FIXED record length then the lines will be padded (with spaces 0x20 in TI BASIC).

By default, the end-of-line character used when writing files in this mode is MS Windows CR + LF format. If you want Unix end of line, see the HOST_EOL setting in PI.CONFIG

If you want to set the native text file behavior to be the default for all files in some set of directories, see the NATIVE_TEXT_DIRS setting in PI.CONFIG

?X - force headerless

Example path name:

TIPI.?X.SOMEDIR.SOMEFILE

This will write the file without encapsulating in a TIFILES format FIAD. With this, records will be written as provided to the file. No end-of-line is automatically appended. It is then possible to create binary file formats for other platforms.

JSON Support

Native files, via local devices such as TIPI. and DSK1., or the PI.http://... and PI.https://... handlers can be opened in a structured JSON mode that eases consuming of JSON data from internet services.

Using the device option ?J, such as PI.?J.http://example.com/json will cause TIPI to parse the file data as a json structure.

Example (TIDBIT style XB):

MAIN:
	URL$="https://api.open-meteo.com/v1/forecast?latitude=32.46&longitude=-86.46&current_weather=true&temperature_unit=fahrenheit&windspeed_unit=mph&precipitation_unit=inch"
READDATA:
	OPEN #1:"PI.?J."&URL$,DISPLAY ,VARIABLE 254
	PRINT #1:"current_weather.temperature"
	LINPUT #1:TEMP$
	PRINT #1:"current_weather.winddirection"
	LINPUT #1:WD$
	PRINT #1:"current_weather.windspeed"
	LINPUT #1:WS$
	CLOSE #1
SHOW:
	PRINT "Temp: "&TEMP$
	PRINT "Wind speed: "&WS$
	PRINT "Direction: "&WD$

This works best if opened in the default APPEND mode. Each write to the file will use the value written as a JMESPath query expression. The result of the query will be made available to the 4A as the set of records that can be read. Each write will query the original data, and set a new set of records, and reset the current record counter to 0.

If the result of the query is still a more complex JSON object, then the records available to read are a compact form with any object keys ordered.

TIPI takes JMESPath one step further to make this data easier to extract. Simple strings, numbers, and booleans are presented in DISPLAY mode to the 4A without adornments such as surrounding quotes.

The URL in the above example returns data in the form of:

{
  "latitude":12.3456789,
  "longitude":12.3456789,
  "generationtime_ms":0.2345655987548828,
  "utc_offset_seconds":0,
  "timezone":"GMT",
  "timezone_abbreviation":"GMT",
  "elevation":67.0,
  "current_weather":{
    "temperature":50.6,
    "windspeed":12.0,
    "winddirection":66.0,
    "weathercode":3,
    "is_day":1,
    "time":"2023-04-08T23:00"
  }
}

When the JMESPath query expression current_weather.temperature is written, the next record read will return 50.6.

If the result of the query is an array, then the elements of the array are presented to the 4A as the subsequent records to be read. For instance if you have the following JSON:

{
  "fun": [ "one", 2, { "name": "three" }, [ "nested", "array" ] ]
}

If you then query for fun, you will get the following records:

one
2
{"name":"three"}
["nested","array"]

JMESPath query expressions also have the power to transform or rearrange the data. A smart TI programmer should be able to combine that with the parsing logic of TI BASIC's DISPLAY records, to produce results that are easy to consume.

If the result of the query is an error, such as for a malformed query expression, then the records available to read are the error message.

References

For details on xbas99, see the xdt99 suite: https://github.com/endlos99/xdt99

For details on Tidbit, see https://github.com/dnotq/tidbit

For details on JMESPath, see https://jmespath.org/tutorial.html