students_list_yaml_ligostaev 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13e5773e64d50df3e40fb1631027bed51c6874af405f4f51de6b3c99f67064f9
+  data.tar.gz: ef201b10620bbf2eb1e9538b76059f6e30c99cb196c8e6199ccb3db8fd295740
+SHA512:
+  metadata.gz: 91e6ab9aaa6e7c49848ed7af32c87354efd91439b981c9bb2dd684698da7981c419d80d3f11db56af2ba617b717c070f528cc019a7a758fe865097428b113bb1
+  data.tar.gz: 1dc0e16f13553b1645eb318cb48326e2497898f906db72d68171c5a32ed3e846be6174985d8b09eeb04f0690bc8af3d2f87fc6f9ed2f4d4192dde7f9317cfb8c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Laboratory Work 4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# students_list_yaml
+
+Простой гем для работы со списками студентов в YAML формате.
+
+## Установка
+
+```ruby
+gem 'students_list_yaml', path: './students_list_yaml_gem'
+```
+
+Или в Gemfile проекта:
+```ruby
+gemspec path: './students_list_yaml_gem'
+```
+
+## Использование
+
+```ruby
+require 'students_list_yaml'
+
+# Создать объект для работы с YAML файлом
+list = Students_list_YAML.new('students.yaml')
+
+# Получить количество студентов
+count = list.get_student_short_count
+
+# Получить студента по ID
+student = list.get_student_by_id(1)
+
+# Добавить студента
+new_student = Student.new(...)
+list.add_student(new_student)
+
+# Получить страницу (5 студентов, 1-я страница)
+page = list.get_k_n_student_short_list(5, 1)
+
+# Сортировать по фамилии и инициалам
+list.sort_by_last_name_initials
+```
+
+## Методы
+
+- `initialize(file_path)` - создать объект
+- `load_file()` - загрузить студентов из файла
+- `save_file()` - сохранить в файл
+- `get_student_by_id(id)` - получить студента по ID
+- `add_student(student)` - добавить студента
+- `replace_student_by_id(id, new_student)` - заменить студента
+- `remove_student_by_id(id)` - удалить студента
+- `sort_by_last_name_initials()` - сортировать
+- `get_student_short_count()` - количество студентов
+- `get_k_n_student_short_list(k, n)` - получить k студентов со страницы n
+
+## Зависимости
+
+Требует наличие классов:
+- Student
+- StudentShort
+- DataList
+- DataListStudentShort
+- AbstractStudentList
+
+Эти классы должны быть загружены перед использованием гема.

data/lib/abstract_student_list.rb

@@ -0,0 +1,227 @@
+require_relative 'student'
+require_relative 'student_short'
+require_relative 'data_list_student_short'
+
+# AbstractStudentList — базовый класс для конкретных реализаций хранения списка студентов (JSON, YAML).
+#
+# Содержит общую логику работы со списком студентов:
+# - преобразование хэша в объект Student и наоборот,
+# - добавление/удаление/замена записи по id,
+# - получение страницы StudentShort в виде DataListStudentShort,
+# - сортировка по фамилии + инициалам (last_name_initials),
+# - универсальный read_all/write_all (вызывают реализацию подкласса для записи/чтения массивов).
+#
+# @abstract
+# @example Создание подкласса
+#   class StudentListJSON < AbstractStudentList
+#     private
+#     def load_from_file(content)
+#       # реализация для JSON
+#     end
+#     
+#     def write_raw_array(array)
+#       # реализация для JSON
+#     end
+#   end
+#
+# @see StudentListJSON
+# @see StudentListYAML
+class AbstractStudentList
+  # Путь к файлу JSON/YAML
+  # @return [String]
+  attr_reader :path
+
+  # Открывает и при необходимости создает файл
+  #
+  # @param path [String] путь до файла
+  # @example
+  #   list = StudentListJSON.new('students.json')
+  def initialize(path)
+    @path = path
+    @array_list = []
+    ensure_file
+  end
+
+  # Читает все записи с файла
+  #
+  # @return [Array<Student>] массив объектов Student
+  # @example
+  #   students = list.read_all
+  #   students.each { |s| puts s.last_name_initials }
+  def read_all
+    file_content = File.read(@path)
+    if file_content.strip.empty?
+      @array_list = []
+      return @array_list
+    end
+    
+    parsed_array = load_from_file(file_content)
+    @array_list = parsed_array.map { |element| Student.new(**element) }
+    @array_list
+  end
+
+  # Записывает или перезаписывает всех студентов в файл
+  #
+  # @return [void]
+  # @example
+  #   students = list.read_all
+  #   list.write_all
+  def write_all
+    new_data = @array_list.map(&:to_hash)
+    write_raw_array(new_data)
+  end
+
+  # Получает объект класса Student по ID, или nil, если не найден
+  #
+  # @param id [Integer] идентификатор студента
+  # @return [Student, nil] объект Student или nil если не найден
+  # @example
+  #   student = list.get_student_by_id(1)
+  #   puts student.last_name if student
+  def get_student_by_id(id)
+    @array_list.find { |element| element.id == id }
+  end
+
+  # Получает список k по счету n объектов StudentShort в виде DataListStudentShort
+  #
+  # @param k [Integer] размер страницы
+  # @param n [Integer] номер страницы
+  # @param existing_data_list [DataListStudentShort, nil] если передан, 
+  #   то метод заполнит или заменит объекты в нем
+  # @return [DataListStudentShort] список студентов для отображения
+  # @example
+  #   data_list = list.get_k_n_student_short_list(5, 1)
+  #   data_list.elements.each { |s| puts s.last_name_initials }
+  def get_k_n_student_short_list(k, n, existing_data_list = nil)
+    sorted_students = @array_list.sort_by { |s| s.last_name_initials }
+    start_index = k * (n - 1)
+    selected_students = sorted_students[start_index, k] || []
+    student_shorts = selected_students.map { |student| StudentShort.from_student(student) }
+
+    if existing_data_list
+      existing_data_list.elements = student_shorts
+      existing_data_list
+    else
+      new_data_list = DataListStudentShort.new(student_shorts)
+      new_data_list
+    end
+  end
+
+  # Сортирует элементы по last_name_initials и сохраняет в файл
+  #
+  # @return [void]
+  # @example
+  #   list.sort_by_last_name_initials
+  #   # Теперь студенты отсортированы по ФИО
+  def sort_by_last_name_initials
+    @array_list.sort_by! { |student| student.last_name_initials }
+    write_all
+  end
+
+  # Добавляет объект класса Student в список, генерируя новый ID
+  #
+  # @param student [Student] студент
+  # @return [Student] добавленный объект с назначенным ID
+  # @raise [ArgumentError] если студент с такими данными уже существует
+  # @example
+  #   student = Student.new(first_name: 'Иван', last_name: 'Петров', git: 'https://github.com/ivanov')
+  #   added = list.add_student(student)
+  def add_student(student)
+    if duplicate?(student)
+      raise ArgumentError, "Студент с такими контактными данными уже существует"
+    end
+    existing_ids = @array_list.map(&:id).compact
+    new_id = existing_ids.empty? ? 1 : existing_ids.max + 1
+    student.instance_variable_set(:@id, new_id)
+    @array_list << student
+    write_all
+    student
+  end
+
+  # Заменяет элемент списка по ID на новый Student
+  #
+  # @param id [Integer] идентификатор заменяемого студента
+  # @param new_student [Student] новые данные студента
+  # @return [Boolean] true если заменено, false если id не найден
+  # @raise [ArgumentError] если новый студент дублирует существующего
+  # @example
+  #   new_student = Student.new(first_name: 'Обновленное', last_name: 'Имя', git: 'https://github.com/updated')
+  #   success = list.replace_by_id(1, new_student)
+  def replace_by_id(id, new_student)
+    index = @array_list.index { |student| student.id == id }
+    return false unless index
+    
+    if duplicate?(new_student, exclude: id)
+      raise ArgumentError, "Студент с такими контактными данными уже существует"
+    end
+    
+    new_student.instance_variable_set(:@id, id)
+    @array_list[index] = new_student
+    write_all
+    true
+  end
+
+  # Удаляет элемент по ID
+  #
+  # @param id [Integer] идентификатор удаляемого студента
+  # @return [Boolean] true если удалено, false если не найден
+  # @example
+  #   if list.delete_by_id(5)
+  #     puts "Студент с ID 5 удален"
+  #   end
+  def delete_by_id(id)
+    deleted = @array_list.reject! { |student| student.id == id }
+  end
+
+  # Возвращает количество элементов
+  #
+  # @return [Integer] количество студентов в списке
+  # @example
+  #   count = list.get_student_short_count
+  #   puts "Всего студентов: #{count}"
+  def get_student_short_count
+    @array_list.length
+  end
+
+  private
+
+  # Загружает данные из файла
+  #
+  # @abstract
+  # @param content [String] содержимое файла
+  # @return [Array<Hash>] массив данных
+  # @raise [NotImplementedError] если метод не реализован в подклассе
+  def load_from_file(content)
+    raise NotImplementedError, "load_from_file должен быть реализован в подклассе"
+  end
+
+  # Записывает массив в файл
+  #
+  # @abstract
+  # @param array [Array<Hash>] массив данных для записи
+  # @return [void]
+  # @raise [NotImplementedError] если метод не реализован в подклассе
+  def write_raw_array(array)
+    raise NotImplementedError, "write_raw_array должен быть реализован в подклассе"
+  end
+
+  # Проверяет существует ли дубликат студента
+  #
+  # @param student [Student] объект класса Student для проверки
+  # @param exclude [Integer, nil] ID студента исключаемого из проверки (при замене)
+  # @return [Boolean] true если найден дубликат, false если нет
+  def duplicate?(student, exclude: nil)
+    @array_list.any? do |other|
+      next if exclude && other.id == exclude
+      student == other
+    end
+  end
+
+  # Проверяет существует ли файл, в противном случае создает его с пустым массивом
+  #
+  # @return [void]
+  def ensure_file
+    return if File.exist?(@path) && File.size?(@path)
+    File.write(@path, '[]')
+  end
+end

data/lib/data_list.rb

@@ -0,0 +1,46 @@
+require_relative 'data_table'
+class DataList
+    def initialize(elements = [])
+        @elements = elements
+        @selected = []
+    end
+
+    attr_reader :elements
+
+    def elements=(new_elements)
+        @elements = new_elements
+        @selected.clear
+    end
+
+    def select(number)
+        if number >= 0 && number < @elements.size
+            @selected << number unless @selected.include?(number)
+        end
+    end
+
+    def get_selected
+        @selected.map { |index| @elements[index].id }
+    end
+
+    def clear_selected
+        @selected.clear
+    end
+
+    def get_names
+        ["№ по порядку"] + attribute_headers
+    end
+
+    def get_data
+        DataTable.new(student_arr)
+    end
+
+    private 
+
+    def attribute_headers
+        raise NotImplementedError, "метод attribute_headers должен быть реализован в подклассе"
+    end
+
+    def student_arr
+        raise NotImplementedError, "метод student_arr должен быть реализован в подклассе"
+    end 
+end

data/lib/data_list_student_short.rb

@@ -0,0 +1,21 @@
+require_relative 'data_list'
+require_relative 'student_short'
+require_relative 'data_table'
+
+class DataListStudentShort < DataList
+    private
+    def attribute_headers
+        ["ФИО", "Контакт", "Git"]
+    end
+
+    def student_arr
+        @elements.each_with_index.map do |student, index|
+            [
+                index + 1,                   
+                student.last_name_initials,  
+                student.contact || "",        
+                student.git || ""            
+            ]
+        end 
+    end
+end

data/lib/data_table.rb

@@ -0,0 +1,21 @@
+class DataTable
+    def initialize(two_dimensional_array)
+        @data = two_dimensional_array
+    end 
+
+    def get(row, col)
+        raise IndexError, "Индекс строки вне диапазона" if row < 0 || row >= rows_count
+        raise IndexError, "Индекс столбца вне диапазона" if col < 0 || col >= cols_count
+        @data[row][col]
+    end
+
+    def rows_count
+        @data.length
+    end
+
+    def cols_count
+        return 0 if @data.empty?
+        @data[0].length
+    end
+end
+

data/lib/student.rb

@@ -0,0 +1,113 @@
+require_relative 'super_student.rb'
+
+class Student < SuperStudent
+    include Comparable
+    attr_reader :last_name, :first_name, :patronymic, :git
+    
+    def initialize(id: nil, last_name:, first_name:, patronymic: nil, phone: nil, telegram: nil, email: nil, git: nil) 
+      raise ArgumentError, "Неверный формат гита #{git}" unless self.class.valid_git?(git)
+      super(id:id, git: git)
+      self.last_name = last_name
+      self.first_name = first_name
+      self.patronymic = patronymic
+      self.contact = {phone: phone, telegram: telegram, email: email}
+    end
+
+    def <=>(other)
+        [first_name, last_name, patronymic || nil] <=> [other.first_name, other.last_name, other.patronymic || nil]
+    end
+
+    def contact
+        if @telegram && !@telegram.empty?
+            "telegram - #{@telegram}"
+        elsif @email && !@email.empty?
+            "email - #{@email}"
+        elsif @phone && !@phone.empty? 
+            "phone - #{@phone}"
+        else
+            nil
+        end
+    end
+
+    def contact=(contacts)
+        contacts.each do |type, value|
+            validator = "valid_#{type}?".to_sym
+            raise ArgumentError, "Неверный формат #{type}" unless self.class.send(validator, value)
+            instance_variable_set("@#{type}", value)
+        end
+    end
+
+    def last_name_initials
+        initials = "#{last_name} #{first_name[0]}."
+        initials += " #{patronymic[0]}." if patronymic
+        initials
+    end
+
+    def self.validated_attr_writer(attribute, validation_method)
+        define_method("#{attribute}=") do |value|
+            raise ArgumentError unless self.class.send(validation_method, value)
+            instance_variable_set("@#{attribute}", value)
+        end
+    end
+
+    validated_attr_writer :first_name, :valid_name?
+    validated_attr_writer :last_name, :valid_name?
+    validated_attr_writer :patronymic, :valid_name?
+    validated_attr_writer :git, :valid_git?
+
+    def to_s
+        info = []
+        info << "ID: #{@id}" if @id
+        info << "Фамилия: #{@last_name}"
+        info << "Имя: #{@first_name}"
+        info << "Отчество: #{@patronymic}" if @patronymic
+        info << "Телефон: #{@phone}" if @phone
+        info << "Телеграм: #{@telegram}" if @telegram
+        info << "Почта: #{@email}" if @email
+        info << "Гит: #{@git}" if @git
+        info.join("\n")
+    end
+
+    def self.valid_name?(name)
+        name.nil? || name.is_a?(String) && name.match?(/^([А-ЯЁ][а-яё\-]+|[A-Z][a-z\-]+)$/)
+    end
+
+    def self.valid_phone?(phone)
+        phone.nil? || (phone.is_a?(String) && phone.match?(/^(\+7|8)?[\s\-\(]?(\d{3})[\s\-\)]?(\d{3})[\s\-]?(\d{2})[\s\-]?(\d{2})$/)) 
+    end
+
+    def self.valid_telegram?(telegram)
+        telegram.nil? || (telegram.is_a?(String) && telegram.match?(/^@[a-zA-Z0-9_]{5,32}$/))
+    end
+
+    def self.valid_email?(email)
+        email.nil? || (email.is_a?(String) && email.match?(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/))
+    end
+
+    def self.valid_git?(git)
+        git.nil? || (git.is_a?(String) && git.match?(/^https:\/\/(github|gitlab)\.com\/[a-zA-Z0-9_-]+\/?$/))
+    end
+
+
+    def to_hash
+        hash = {
+            id: @id,
+            first_name: @first_name,
+            last_name: @last_name
+        }
+        hash[:patronymic] = @patronymic if @patronymic
+        hash[:phone] = @phone if @phone && !@phone.empty?
+        hash[:telegram] = @telegram if @telegram && !@telegram.empty?
+        hash[:email] = @email if @email && !@email.empty?
+        hash[:git] = @git if @git
+        hash
+    end
+
+    def ==(other)
+        return false unless other.is_a?(Student)
+            @phone == other.instance_variable_get(:@phone) &&
+            @telegram == other.instance_variable_get(:@telegram) &&
+            @email == other.instance_variable_get(:@email) &&
+            @git == other.git
+    end
+end

data/lib/student_short.rb

@@ -0,0 +1,25 @@
+require_relative 'student.rb'
+require_relative 'super_student.rb'
+
+class StudentShort < SuperStudent
+    attr_reader :id, :last_name_initials, :contact, :git
+
+    def initialize(id:, last_name_initials:, contact: nil, git: nil)
+        super(id: id, git: git)
+        @last_name_initials = last_name_initials
+        @contact = contact
+    end
+
+    def self.from_student(student)
+        raise ArgumentError, "Отсутствует ID" unless student.id
+        new(
+            id: student.id,
+            last_name_initials: student.last_name_initials,
+            contact: student.contact,
+            git: student.git
+        )
+    end
+     def to_s
+        short_info
+    end
+end

data/lib/students_list_yaml.rb

@@ -0,0 +1,31 @@
+require 'yaml'
+
+module StudentsListYaml
+  VERSION = "1.0.0"
+end
+
+require_relative 'super_student'
+require_relative 'student'
+require_relative 'student_short'
+require_relative 'data_table'
+require_relative 'data_list'
+require_relative 'data_list_student_short'
+require_relative 'abstract_student_list'
+
+class Students_list_YAML < AbstractStudentList
+  def initialize(path)
+    super(path)
+  end
+
+  private
+
+  def load_from_file(content)
+    array = YAML.safe_load(content, permitted_classes: [Symbol], symbolize_names: true)
+    raise RuntimeError, "Файл должен содержать YAML массив" unless array.is_a?(Array)
+    array
+  end
+
+  def write_raw_array(array)
+    File.write(@path, array.to_yaml)
+  end
+end

data/lib/super_student.rb

@@ -0,0 +1,36 @@
+class SuperStudent
+    
+    attr_reader :id, :git
+
+    def initialize(id: nil, git: nil)
+        @id = id
+        @git = git
+    end
+
+    def short_info
+        info = []
+        info << "ID: #{id}" if id
+        info << "ФИО: #{last_name_initials}"
+        info << "Контакт: #{contact}" if contact
+        info << "Гит: #{git}" if git
+        info.join("\n")
+    end
+
+    def has_git?
+        !@git.nil? && !@git.empty?
+    end
+
+    def has_contact?
+        !contact.nil? && !contact.empty?
+    end
+
+    protected
+    
+    def last_name_initials
+        raise NotImplementedError
+    end
+
+    def contact
+        raise NotImplementedError
+    end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: students_list_yaml_ligostaev
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ligostaev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Provides Students_list_YAML class for managing student data with YAML
+  persistence. Includes support for student records with validation, sorting, and
+  pagination.
+email:
+- contact@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/abstract_student_list.rb
+- lib/data_list.rb
+- lib/data_list_student_short.rb
+- lib/data_table.rb
+- lib/student.rb
+- lib/student_short.rb
+- lib/students_list_yaml.rb
+- lib/super_student.rb
+homepage: https://github.com/ligostaev/students_list_yaml_gem
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: YAML-based storage for student lists
+test_files: []