feat: add file reader interface

Author: wgtmac

src/iceberg/file_format.h

@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+/// \file iceberg/file_format.h
+/// File format used by Iceberg.
+
+#include "iceberg/iceberg_export.h"
+
+namespace iceberg {
+
+/// \brief File format type
+enum class ICEBERG_EXPORT FileFormatType {
+  kParquet,
+  kAvro,
+  kOrc,
+  kPuffin,
+  kMetadata,
+};
+
+}  // namespace iceberg

src/iceberg/file_reader.h

@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+/// \file iceberg/file_reader.h
+/// Reader interface for file formats like Parquet, Avro and ORC.
+
+#include <functional>
+#include <variant>
+
+#include "iceberg/arrow_c_data.h"
+#include "iceberg/result.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief Base reader class to read data from different file formats.
+class ICEBERG_EXPORT Reader {
+ public:
+  virtual ~Reader() = default;
+
+  /// \brief Read next data from file.
+  ///
+  /// \return std::monostate if the reader has no more data, otherwise `ArrowArray` or
+  /// `StructLike` depending on the data layout by the reader implementation.
+  using Data =
+      std::variant<std::monostate, ArrowArray, std::reference_wrapper<const StructLike>>;
+  virtual Result<Data> Next() = 0;
+
+  enum class DataLayout { kArrowArray, kStructLike };
+
+  /// \brief Get the data layout returned by `Next()` of the reader.
+  virtual DataLayout data_layout() const = 0;
+};
+
+/// \brief Wrapper of `Reader` to always return `StructLike`.
+///
+/// If the data layout of the wrapped reader is `ArrowArray`, the data will be converted
+/// to `StructLike`; otherwise, the data will be returned as is without any cost.
+class ICEBERG_EXPORT StructLikeReader : public Reader {
+ public:
+  explicit StructLikeReader(std::unique_ptr<Reader> reader);
+
+  /// \brief Always read data into `StructLike` or monostate if no more data.
+  Result<Data> Next() final;
+
+  DataLayout data_layout() const final { return DataLayout::kStructLike; }
+};
+
+/// \brief Wrapper of `Reader` to always return `ArrowArray`.
+///
+/// If the data layout of the wrapped reader is `StructLike`, the data will be converted
+/// to `ArrowArray`; otherwise, the data will be returned as is without any cost.
+class ICEBERG_EXPORT BatchReader : public Reader {
+ public:
+  explicit BatchReader(std::unique_ptr<Reader> reader);
+
+  /// \brief Always read data into `ArrowArray` or monostate if no more data.
+  Result<Data> Next() final;
+
+  DataLayout data_layout() const final { return DataLayout::kArrowArray; }
+};
+
+}  // namespace iceberg

src/iceberg/manifest_reader.h

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+/// \file iceberg/manifest_reader.h
+/// Data reader interface for manifest files.
+
+#include <memory>
+#include <span>
+
+#include "iceberg/file_reader.h"
+
+namespace iceberg {
+
+/// \brief Read manifest entries from a manifest file.
+class ICEBERG_EXPORT ManifestReader {
+ public:
+  virtual Result<std::span<std::unique_ptr<class ManifestEntry>>> Entries() const = 0;
+
+ private:
+  std::unique_ptr<StructLikeReader> reader_;
+};
+
+/// \brief Read manifest files from a manifest list file.
+class ICEBERG_EXPORT ManifestListReader {
+ public:
+  virtual Result<std::span<std::unique_ptr<class ManifestFile>>> Files() const = 0;
+
+ private:
+  std::unique_ptr<StructLikeReader> reader_;
+};
+
+}  // namespace iceberg

src/iceberg/type_fwd.h

@@ -101,6 +101,7 @@ struct SnapshotRef;
 struct StatisticsFile;
 struct TableMetadata;
 
+enum class FileFormatType;
 enum class SnapshotRefType;
 enum class TransformType;