1 # Paths and Files
   2 
   3 Tomo supports a built-in syntax for file and directory paths, with some logic
   4 to help prevent or mitigate the risks of errors caused by string manipulations
   5 of file paths. Tomo does not have a built-in datatype to represent files
   6 specifically, but instead relies on Paths as the API to do filesystem
   7 operations.
   8 
   9 ## Syntax
  10 
  11 Paths are [domain-specific languages](langs.md) that have their own dedicated
  12 syntax. A path literal begins with either `/`, `.`, or `~` and continues until
  13 an unescaped space or the end of the line.
  14 
  15 ```tomo
  16 path := /tmp/foo
  17 path_with_spaces := ./file\ name.txt
  18 ```
  19 
  20 Paths also respect parenthesis balancing, so a closing parenthesis is not
  21 considered part of the path unless a corresponding opening parenthesis is also
  22 part of the path, which makes it easier to use paths in many cases:
  23 
  24 ```tomo
  25 paths := [(./foo), (./file(1).txt)]
  26 contents := (./baz.txt).read()!
  27 ```
  28 
  29 In the first example, the paths are parsed as `./foo` and `./file(1).txt`, not
  30 `./foo),` and `./file(1).txt)]`. Similarly, in the second example, the path is
  31 `./baz.txt`, not `./baz.txt).read()!`.
  32 
  33 ## Usage
  34 
  35 Paths come with a bunch of methods for doing filesystem operations. Broadly,
  36 they fall into three categories:
  37 
  38 - File reading and writing, e.g. `(./foo.txt).write("Hello world")!`
  39 - Filesystem traversal and metadata, e.g. `(/some/dir).children()!`
  40 - Path manipulation, e.g. `(./file.jpg).extension()`
  41 
  42 Operations that involve the filesystem will typically return a `Result` type,
  43 which is either `Success` or `Failure(reason)`. In the common case where you
  44 expect a file operation to succeed and do not want to explicitly account for
  45 the possibility of a file operation failing, you can use `!` as a suffix as a
  46 shorthand for "if this returns `Failure(reason)`, then fail and print the
  47 reason."
  48 
  49 ## Internal Representation
  50 
  51 Paths are internally represented as C-style NUL-terminated char strings. This
  52 makes it easy to use them with C APIs without any conversion. Paths do **not**
  53 perform any unicode normalization, unlike `Text`.
  54 
  55 # API
  56 
  57 [API documentation](../api/paths.md)