modules/cldc-compact/src/main/java/cc/squirreljme/jvm/mle/TerminalShelf.java

   1 // -*- Mode: Java; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // ---------------------------------------------------------------------------
   9
  10 package cc.squirreljme.jvm.mle;
  11
  12 import cc.squirreljme.jvm.mle.brackets.PipeBracket;
  13 import cc.squirreljme.jvm.mle.constants.PipeErrorType;
  14 import cc.squirreljme.jvm.mle.constants.StandardPipeType;
  15 import cc.squirreljme.jvm.mle.exceptions.MLECallError;
  16 import cc.squirreljme.runtime.cldc.annotation.Api;
  17 import cc.squirreljme.runtime.cldc.annotation.SquirrelJMEVendorApi;
  18 import org.intellij.lang.annotations.MagicConstant;
  19 import org.jetbrains.annotations.Blocking;
  20 import org.jetbrains.annotations.CheckReturnValue;
  21 import org.jetbrains.annotations.NonBlocking;
  22 import org.jetbrains.annotations.NotNull;
  23 import org.jetbrains.annotations.Range;
  24
  25 /**
  26  * This contains the shell for printing to the console and otherwise.
  27  *
  28  * @since 2020/06/14
  29  */
  30 @SuppressWarnings("UnstableApiUsage")
  31 @SquirrelJMEVendorApi
  32 public final class TerminalShelf
  33 {
  34         /**
  35          * Not used.
  36          *
  37          * @since 2002/06/14
  38          */
  39         private TerminalShelf()
  40         {
  41         }
  42
  43         /**
  44          * Returns the number of available bytes for reading, if it is known.
  45          *
  46          * @param __fd The descriptor to close.
  47          * @return The number of bytes ready for immediate reading, will be
  48          * zero if there are none. For errors one of {@link PipeErrorType}.
  49          * @throws MLECallError If {@code __fd} is not valid.
  50          * @since 2020/11/22
  51          */
  52         @SquirrelJMEVendorApi
  53         @MagicConstant(valuesFromClass = PipeErrorType.class,
  54                 intValues = {0, -1})
  55         @NonBlocking
  56         @CheckReturnValue
  57         public static native int available(@NotNull PipeBracket __fd)
  58                 throws MLECallError;
  59
  60         /**
  61          * Closes the output of the current process.
  62          *
  63          * @param __fd The pipe to close.
  64          * @return One of {@link PipeErrorType}.
  65          * @throws MLECallError If {@code __fd} is not valid.
  66          * @since 2020/07/02
  67          */
  68         @SquirrelJMEVendorApi
  69         @MagicConstant(valuesFromClass = PipeErrorType.class)
  70         @Blocking
  71         @CheckReturnValue
  72         public static native int close(@NotNull PipeBracket __fd)
  73                 throws MLECallError;
  74
  75         /**
  76          * Flushes the stream.
  77          *
  78          * @param __fd The pipe to flush.
  79          * @return One of {@link PipeErrorType}.
  80          * @throws MLECallError If {@code __fd} is not valid.
  81          * @since 2018/12/08
  82          */
  83         @SquirrelJMEVendorApi
  84         @MagicConstant(valuesFromClass = PipeErrorType.class)
  85         @Blocking
  86         @CheckReturnValue
  87         public static native int flush(@NotNull PipeBracket __fd)
  88                 throws MLECallError;
  89
  90         /**
  91          * Returns the pipe to a standardized input/output pipe that is shared
  92          * across many systems.
  93          *
  94          * @param __fd The {@link StandardPipeType} to get the pipe of.
  95          * @return The pipe to the given pipe.
  96          * @throws MLECallError If the standard pipe does not exist or is not
  97          * valid.
  98          * @since 2022/03/19
  99          */
 100         @SquirrelJMEVendorApi
 101         public static native PipeBracket fromStandard(
 102                 @MagicConstant(valuesFromClass = StandardPipeType.class) int __fd)
 103                 throws MLECallError;
 104
 105         /**
 106          * Reads from the given pipe into the output buffer.
 107          *
 108          * @param __fd The pipe to read from.
 109          * @param __b The bytes to read into.
 110          * @param __o The offset.
 111          * @param __l The length.
 112          * @return One of {@link PipeErrorType} or the number of read bytes.
 113          * @throws MLECallError If {@code __fd} is not valid, the offset and/or
 114          * length are negative or exceed the buffer size, or {@code __b} is
 115          * {@code null}.
 116          * @since 2018/12/05
 117          */
 118         @SquirrelJMEVendorApi
 119         @MagicConstant(valuesFromClass = PipeErrorType.class)
 120         @Range(from = -2, to = Integer.MAX_VALUE)
 121         @Blocking
 122         @CheckReturnValue
 123         public static native int read(@NotNull PipeBracket __fd,
 124                 @NotNull byte[] __b,
 125                 @Range(from = 0, to = Integer.MAX_VALUE) int __o,
 126                 @Range(from = 0, to = Integer.MAX_VALUE) int __l)
 127                 throws MLECallError;
 128
 129         /**
 130          * Writes the character to the console output.
 131          *
 132          * @param __fd The pipe to write to.
 133          * @param __c The byte to write, only the lowest 8-bits are used.
 134          * @return One of {@link PipeErrorType} or {@code 1} on success.
 135          * @throws MLECallError If {@code __fd} is not valid.
 136          * @since 2018/09/21
 137          */
 138         @SquirrelJMEVendorApi
 139         @MagicConstant(valuesFromClass = PipeErrorType.class,
 140                 intValues = {1})
 141         @Range(from = -2, to = 1)
 142         @Blocking
 143         @CheckReturnValue
 144         public static native int write(@NotNull PipeBracket __fd,
 145                 @Range(from = 0, to = 255) int __c)
 146                 throws MLECallError;
 147
 148         /**
 149          * Writes the given bytes to the console output.
 150          *
 151          * @param __fd The pipe to write to.
 152          * @param __b The bytes to write.
 153          * @param __o The offset.
 154          * @param __l The length.
 155          * @return One of {@link PipeErrorType} or {@code __l} on success.
 156          * @throws MLECallError If {@code __fd} is not valid, the offset and/or
 157          * length are negative or exceed the buffer size, or {@code __b} is
 158          * {@code null}.
 159          * @since 2018/12/05
 160          */
 161         @SquirrelJMEVendorApi
 162         @MagicConstant(valuesFromClass = PipeErrorType.class,
 163                 intValues = {1})
 164         @Range(from = -2, to = Integer.MAX_VALUE)
 165         @Blocking
 166         @CheckReturnValue
 167         public static native int write(@NotNull PipeBracket __fd,
 168                 @NotNull byte[] __b,
 169                 @Range(from = 0, to = Integer.MAX_VALUE) int __o,
 170                 @Range(from = 0, to = Integer.MAX_VALUE) int __l)
 171                 throws MLECallError;
 172 }