1<?php
2
3namespace Masterminds\HTML5\Parser;
4
5/**
6 * Interface for stream readers.
7 *
8 * The parser only reads from streams. Various input sources can write
9 * an adapater to this InputStream.
10 *
11 * Currently provided InputStream implementations include
12 * FileInputStream and StringInputStream.
13 *
14 * @deprecated since 2.4, to remove in 3.0. Use a string in the scanner instead.
15 */
16interface InputStream extends \Iterator
17{
18    /**
19     * Returns the current line that is being consumed.
20     *
21     * TODO: Move this to the scanner.
22     */
23    public function currentLine();
24
25    /**
26     * Returns the current column of the current line that the tokenizer is at.
27     *
28     * Newlines are column 0. The first char after a newline is column 1.
29     *
30     * @TODO Move this to the scanner.
31     *
32     * @return int The column number.
33     */
34    public function columnOffset();
35
36    /**
37     * Get all characters until EOF.
38     *
39     * This consumes characters until the EOF.
40     */
41    public function remainingChars();
42
43    /**
44     * Read to a particular match (or until $max bytes are consumed).
45     *
46     * This operates on byte sequences, not characters.
47     *
48     * Matches as far as possible until we reach a certain set of bytes
49     * and returns the matched substring.
50     *
51     * @see strcspn
52     *
53     * @param string $bytes Bytes to match.
54     * @param int    $max   Maximum number of bytes to scan.
55     *
56     * @return mixed Index or false if no match is found. You should use strong
57     *               equality when checking the result, since index could be 0.
58     */
59    public function charsUntil($bytes, $max = null);
60
61    /**
62     * Returns the string so long as $bytes matches.
63     *
64     * Matches as far as possible with a certain set of bytes
65     * and returns the matched substring.
66     *
67     * @see strspn
68     *
69     * @param string $bytes A mask of bytes to match. If ANY byte in this mask matches the
70     *                      current char, the pointer advances and the char is part of the
71     *                      substring.
72     * @param int    $max   The max number of chars to read.
73     */
74    public function charsWhile($bytes, $max = null);
75
76    /**
77     * Unconsume one character.
78     *
79     * @param int $howMany The number of characters to move the pointer back.
80     */
81    public function unconsume($howMany = 1);
82
83    /**
84     * Retrieve the next character without advancing the pointer.
85     */
86    public function peek();
87}
88