# O

`*ObjIdx`
  Holds an `idx` tree of objects created by `obj`.

`*Once`
  Holds an `idx` tree of already `load`ed source locations (as returned by `file`) See also `once`.

      : *Once
      -> (("lib/" "misc.l" . 11) (("lib/" "http.l" . 9) (("lib/" "form.l" . 11))))

`*OS`
  A global constant holding the name of the operating system. Possible values include `"Linux"`, `"Android"`, `"FreeBSD"`, `"OpenBSD"`, `"SunOS"`, `"Darwin"` or `"Cygwin"`. See also `*CPU` and `version`.

      : *OS
      -> "Linux"

`(obj (typ sym [hook] val ..) [var1 val1 ..]) -> obj`
`(obj typ any [var1 val1 ..]) -> obj`
  Finds or creates a database object, and initializes additional properties using the `varN` and `valN` arguments. In the first form, a `request` for `(typ sym [hook] val ..)` is called, while the second form uses `cache` to maintain objects without unique `+Key`s by indexing `*ObjIdx` with the `any` argument.

      : (obj ((+Item) nr 2) nm "Spare Part" sup `(db 'nr '+CuSu 2) inv 100 pr 1250)
      -> {B2}

`(object 'sym 'any ['sym2 'any2 ..]) -> obj`
  Defines `sym` to be an object with the value (or type) `any`. The property list is initialized with all optionally supplied key-value pairs. See also OO Concepts, `new`, `type` and `isa`.

      : (object 'Obj '(+A +B +C) 'a 1 'b 2 'c 3)
      -> Obj
      : (show 'Obj)
      Obj (+A +B +C)
         c 3
         b 2
         a 1
      -> Obj

`(oct 'num ['num]) -> sym`
`(oct 'sym) -> num`
  Converts a number `num` to an octal string, or an octal string `sym` to a number. In the first case, if the second argument is given, the result is separated by spaces into groups of such many digits. See also `bin`, `hex`, `hax` and `format`.

      : (oct 73)
      -> "111"
      : (oct "111")
      -> 73
      : (oct 1234567 3)
      -> "4 553 207"

`(off var ..) -> NIL`
  Stores `NIL` in all `var` arguments. See also `on`, `onOff`, `zero` and `one`.

      : (off A B)
      -> NIL
      : A
      -> NIL
      : B
      -> NIL

`(offset 'lst1 'lst2) -> cnt | NIL`
  Returns the `cnt` position of the tail list `lst1` in `lst2`, or `NIL` if it is not found. See also `index`, `sub?` and `tail`.

      : (offset '(c d e f) '(a b c d e f))
      -> 3
      : (offset '(c d e) '(a b c d e f))
      -> NIL

`(on var ..) -> T`
  Stores `T` in all `var` arguments. See also `off`, `onOff`, `zero` and `one`.

      : (on A B)
      -> T
      : A
      -> T
      : B
      -> T

`(once . prg) -> any`
  Executes `prg` once, when the current file is `load`ed the first time. Subsequent loads at a later time will not execute `prg`, and `once` returns `NIL`. See also `*Once`.

      (once
         (zero *Cnt1 *Cnt2)  # Init counters
         (load "file1.l" "file2.l") )  # Load other files

      `(once T)  # Ignore next time the rest of this file

`(one var ..) -> 1`
  Stores `1` in all `var` arguments. See also `zero`, `on`, `off` and `onOff`.

      : (one A B)
      -> 1
      : A
      -> 1
      : B
      -> 1

`(onOff var ..) -> flg`
  Logically negates the values of all `var` arguments. Returns the new value of the last symbol. See also `on`, `off`, `zero` and `one`.

      : (onOff A B)
      -> T
      : A
      -> T
      : B
      -> T
      : (onOff A B)
      -> NIL
      : A
      -> NIL
      : B
      -> NIL

`(open 'any ['flg]) -> cnt | NIL`
  Opens the file with the name `any` in read/write mode (or read-only if `flg` is non-`NIL`), and returns a file descriptor `cnt` (or `NIL` on error). A leading "`@`" character in `any` is substituted with the PicoLisp Home Directory, as it was remembered during interpreter startup. If `flg` is `NIL` and the file does not exist, it is created. The file descriptor can be used in subsequent calls to `in` and `out`. See also `close` and `poll`.

      : (open "x")
      -> 3

`(opid) -> pid | NIL`
  Returns the corresponding process ID when the current output channel is writing to a pipe, otherwise `NIL`. See also `ipid` and `out`.

      : (out '(cat) (call 'ps "-p" (opid)))
        PID TTY          TIME CMD
       7127 pts/3    00:00:00 cat
      -> T

`(opt) -> sym`
  Return the next command line argument ("option", as would be processed by `load`) as a string, and remove it from the remaining command line arguments. See also Invocation and `argv`.

      $ pil  -"de f () (println 'opt (opt))"  -f abc  -bye
      opt "abc"

`(or 'any ..) -> any`
  Logical OR. The expressions `any` are evaluated from left to right. If a non-`NIL` value is encountered, it is returned immediately. Else the result of the last expression is returned. See also `nor`, `and` and `unless`.

      : (or (= 3 3) (read))
      -> T
      : (or (= 3 4) (read))
      abc
      -> abc

`or/2`
  Pilog predicate that takes an arbitrary number of clauses, and succeeds if one of them can be proven. See also `not/1`.

      : (?
         (or
            ((equal 3 @X) (equal @X 4))
            ((equal 7 @X) (equal @X 7)) ) )
       @X=7
      -> NIL

`(out 'any . prg) -> any`
  Opens `any` as output channel during the execution of `prg`. The current output channel will be saved and restored appropriately. If the argument is `NIL`, standard output is used. If the argument is a symbol, it is used as a file name (opened in "append" mode if the first character is "`+`"). If it is a positive number, it is used as the descriptor of an open file. If it is a negative number, the saved output channel such many levels above the current one is used. Otherwise (if it is a list), it is taken as a command with arguments, and a pipe is opened for output. The (system dependent) exit status code of the child process is stored in the global variable `@@`. In all cases, `flush` is called when `prg` is done. See also `opid`, `call`, `in`, `err`, `ctl`, `pipe`, `poll`, `close` and `load`.

      : (out "a" (println 123 '(a b c) 'def))  # Write one line to file "a"
      -> def
      : (out '(lpr) (prinl "Hello"))  # Send line to line printer
      -> "Hello"

`(output exe . prg) -> any`
  Establishes an output stream, by redirecting the current output channel during the execution of `prg`. The current output channel will be saved and restored appropriately. `exe` is executed (in the context of the original output channel) whenever a character needs to be output by print calls in `prg`. That character is passed in the global variable `@@`, and the following character in the stream in `@@@` (single-character look-ahead). See also `input`, `out` and `pipe`.

      : (output (prin (uppc @@)) (prinl "abc"))
      ABC
      -> "abc"
      : (output (println @@ @@@) (prin "abc"))
      "a" "b"
      "b" "c"
      "c" NIL
      -> "abc"
      : (pack (make (output (link @@) (print '(+ 2 (* 3 4))))))
      -> "(+ 2 (* 3 4))"