Module: Vips::Yard

Defined in:

lib/vips/image.rb

Overview

This module generates yard comments for all the dynamically bound vips operations.

Regenerate with something like:

$ ruby > methods.rb
require "vips"; Vips::Yard.generate
^D

Constant Summary

MAP_GO_TO_RUBY =

map gobject's type names to Ruby

{
  "gboolean" => "Boolean",
  "gint" => "Integer",
  "gdouble" => "Float",
  "gfloat" => "Float",
  "gchararray" => "String",
  "VipsImage" => "Vips::Image",
  "VipsInterpolate" => "Vips::Interpolate",
  "VipsConnection" => "Vips::Connection",
  "VipsSource" => "Vips::Source",
  "VipsTarget" => "Vips::Target",
  "VipsSourceCustom" => "Vips::SourceCustom",
  "VipsTargetCustom" => "Vips::TargetCustom",
  "VipsArrayDouble" => "Array<Double>",
  "VipsArrayInt" => "Array<Integer>",
  "VipsArrayImage" => "Array<Image>",
  "VipsArrayString" => "Array<String>"
}

NO_GENERATE =

these have hand-written methods, see above

["scale", "bandjoin", "composite", "ifthenelse"]

ALIAS =

these are aliased (appear under several names)

["crop"]

Class Method Summary

• .generate ⇒ Object
• .generate_operation(introspect) ⇒ Object
• .gtype_to_ruby(gtype) ⇒ Object

  turn a gtype into a ruby type name.

Class Method Details

.generate ⇒ Object

# File 'lib/vips/image.rb', line 1722

def self.generate
  alias_gtypes = {}
  ALIAS.each do |name|
    gtype = Vips.type_find "VipsOperation", name
    alias_gtypes[gtype] = name
  end

  generate_class = lambda do |gtype, _|
    name = if alias_gtypes.key? gtype
      alias_gtypes[gtype]
    else
      Vips.nickname_find gtype
    end

    if name
      begin
        # can fail for abstract types
        introspect = Vips::Introspect.get_yard name
      rescue Vips::Error
        nil
      end

      generate_operation(introspect) if introspect
    end

    Vips.vips_type_map gtype, generate_class, nil
  end

  puts "module Vips"
  puts "  class Image"
  puts ""

  generate_class.call(GObject.g_type_from_name("VipsOperation"), nil)

  puts "  end"
  puts "end"
end

.generate_operation(introspect) ⇒ Object

# File 'lib/vips/image.rb', line 1654

def self.generate_operation introspect
  return if (introspect.flags & OPERATION_DEPRECATED) != 0
  return if NO_GENERATE.include? introspect.name

  method_args = introspect.method_args
  required_output = introspect.required_output
  optional_input = introspect.doc_optional_input
  optional_output = introspect.doc_optional_output

  print "# @!method "
  print "self." unless introspect.member_x
  print "#{introspect.name}("
  print method_args.map { |x| x[:yard_name] }.join(", ")
  print ", " if method_args.length > 0
  puts "**opts)"

  puts "#   #{introspect.description.capitalize}."

  method_args.each do |details|
    yard_name = details[:yard_name]
    gtype = details[:gtype]
    blurb = details[:blurb]

    puts "#   @param #{yard_name} [#{gtype_to_ruby(gtype)}] #{blurb}"
  end

  puts "#   @param opts [Hash] Set of options"
  optional_input.each do |arg_name, details|
    yard_name = details[:yard_name]
    gtype = details[:gtype]
    rtype = gtype_to_ruby gtype
    blurb = details[:blurb]

    puts "#   @option opts [#{rtype}] :#{yard_name} #{blurb}"
  end
  optional_output.each do |arg_name, details|
    yard_name = details[:yard_name]
    gtype = details[:gtype]
    rtype = gtype_to_ruby gtype
    blurb = details[:blurb]

    puts "#   @option opts [#{rtype}] :#{yard_name} Output #{blurb}"
  end

  print "#   @return ["
  if required_output.length == 0
    print "nil"
  elsif required_output.length == 1
    print gtype_to_ruby(required_output.first[:gtype])
  else
    print "Array<"
    print required_output.map { |x| gtype_to_ruby(x[:gtype]) }.join(", ")
    print ">"
  end
  if optional_output.length > 0
    print ", Hash<Symbol => Object>"
  end
  print "] "
  print required_output.map { |x| x[:blurb] }.join(", ")
  if optional_output.length > 0
    print ", " if required_output.length > 0
    print "Hash of optional output items"
  end
  puts ""

  puts ""
end

.gtype_to_ruby(gtype) ⇒ Object

turn a gtype into a ruby type name

# File 'lib/vips/image.rb', line 1638

def self.gtype_to_ruby gtype
  fundamental = GObject.g_type_fundamental gtype
  type_name = GObject.g_type_name gtype

  if MAP_GO_TO_RUBY.include? type_name
    type_name = MAP_GO_TO_RUBY[type_name]
  end

  if fundamental == GObject::GFLAGS_TYPE ||
      fundamental == GObject::GENUM_TYPE
    type_name = "Vips::" + type_name[/Vips(.*)/, 1]
  end

  type_name
end