Programmierung in Ruby

Der Leitfaden der Pragmatischen Programmierer
class Module
Parent: Object
Version: 1.6

Index:

constants nesting new <, <=, >, >= <=> === ancestors class_eval class_variables clone const_defined? const_get const_set constants included_modules instance_methods method_defined? module_eval name private_class_method private_instance_methods protected_instance_methods public_class_method public_instance_methods alias_method append_features attr attr_accessor attr_reader attr_writer extend_object include method_added module_function private protected public remove_const remove_method undef_method


Subclasses: Class

Ein Module ist eine Sammlung von Methoden und Konstanten. Die Methode in einem Modul können Instanz- oder Modulmethoden sein. Instanzmethoden erscheinen als Methoden einer Klasse, wenn das Modul eingebunden wird. Modulmethoden tun dies nicht. Im Gegenzug können Modulmethoden ohne die Instanziierung eines zugehörigen Objekts aufgerufen werden, während dies für Instanzmethoden nicht der Fall ist. Vgl. hierzu Module#module_function.

In den folgenden Beschreibungen bezeichnet der Parameter einSymbol entweder einen String (in Anführungszeichen) oder ein Symbol (wie z.B. :name).

module Mod
  include Math
  CONST = 1
  def meth
    #  ...
  end
end
Mod.type » Module
Mod.constants » ["CONST", "E", "PI"]
Mod.instance_methods » ["meth"]

class methods
constants Module.constants -> einArray

Gibt ein Array mit den Namen aller im System definierten Konstanten zurück. Die Liste umfasst die Namen aller Module und Klassen. 

p Module.constants.sort[1..5]
produces:
["ARGV", "ArgumentError", "Array", "Bignum", "Binding"]

nesting Module.nesting -> einArray

Gibt die Liste aller Module aus, die am Punkt des Aufrufs geschachtelt sind.

module M1
  module M2
    $a = Module.nesting
  end
end
$a » [M1::M2, M1]
$a[0].name » "M1::M2"

new Module.new -> einModul

Generiert ein neues, anonymes Modul.

instance methods
<, <=, >, >= modrelopeinModul-> true oder false

Hierarchie Abfrage---Ein Modul wird größer als ein anderes betrachtet, wenn es in das andere Modul eingebunden wird oder eine Eltern-Klasse dieses Moduls ist. Die übrigen Operatoren sind entsprechend definiert. Wenn zwischen den Modulen keine Beziehung besteht, wird für alle Operatoren false zurückgegeben.

module Mixin
end
module Parent
  include Mixin
end
module Unrelated
end
Parent > Mixin » false
Parent < Mixin » true
Parent <= Parent » true
Parent < Unrelated » false
Parent > Unrelated » false

<=> mod <=> einModul-> -1, 0, +1

Vergleich---Gibt -1 zurück, wenn modeinModul enthält, 0 wenn mod gleich einModul ist und +1 wenn mod in einModul enthalten ist bzw. wenn mod keine Beziehung zu einModul hat.

=== mod === einObjekt-> true oder false

Fallgleichheit---Gibt true zurück, wenn einObjekt eine Instanz von mod bzw. von einem seiner Erben ist. Die Methode ist von begrenztem Nutzen für Module, jedoch kann sie in case-Ausdrücken verwendet werden, um Objekte nach Klasse einzuteilen.

ancestors mod.ancestors -> einArray

Gibt die Liste aller in mod enthaltenen Module (inclusive mod selbst) zurück.

module Mod
  include Math
  include Comparable
end
Mod.ancestors » [Mod, Comparable, Math]
Math.ancestors » [Math]

class_eval mod.class_eval( einString ) -> einObjekt
mod.class_eval {| | block }-> einObjekt

Synonym für Module.module_eval.

class_variables mod.class_variables -> einArray

Gibt ein Array mit allen Klassenvariablen von mod und seinen Vorfahren zurück.

class One
  @@var1 = 1
end
class Two < One
  @@var2 = 2
end
One.class_variables » ["@@var1"]
Two.class_variables » ["@@var2", "@@var1"]

clone mod.clone -> einModul

Erstellt eine neue Kopie eines Moduls.

m = Math.clone » Math
m.constants » ["PI", "E"]
m == Math » false

const_defined? mod.const_defined?( einSymbol ) -> true oder false

Gibt true zurück, wenn einer Konstanten mit dem übergebenen Namen in mod definiert ist.

Math.const_defined? "PI" » true

const_get mod.const_get( einSymbol ) -> einObjekt

Gibt den Wert der in mod definierten Konstante mit dem übergebenen Namen zurück.

Math.const_get :PI » 3.141592654

const_set mod.const_set( einSymbol, einObjekt ) -> einObjekt

Weist der genannten Konstanten das übergebene Objekt zu und gibt dieses Objekt wieder zurück. Wenn der angegebene Name nicht existiert, wird eine neue Konstante angelegt.

Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0) » 3.142857143
Math::HIGH_SCHOOL_PI - Math::PI » 0.001264489267

constants mod.constants -> einArray

Gibt ein Array mit den Namen der Konstanten, auf die in mod zugegriffen werden kann, zurück. Die Konstanten etwaiger eingeschlossener Module werden ebenfalls ausgegeben (vgl. Beispiel am Beginn der Abschnitts).

included_modules mod.included_modules -> einArray

Gibt die Lister der in mod eingebundenen Module zurück.

module Mixin
end
module Outer
  include Mixin
end
Mixin.included_modules » []
Outer.included_modules » [Mixin]

instance_methods mod.instance_methods( includeSuper=false ) -> einArray

Gibt ein Array mit den Namen der öffentlichen Instanzmethoden im Empfänger zurück. Im Falle eines Moduls sind dies die öffentlichen Methoden. Bei einer Klasse sind dies die Instanzmethoden (nicht Singleton). Wenn die Methode ohne Argument bzw. mit einem Argument, das false gesetzt ist, aufgerufen wird, werden nur die Instanzmethoden von mod zurück gegeben, sonst werden diejenigen von mod's Oberklassen mit angegeben. 
module A
  def method1()  end
end
class B
  def method2()  end
end
class C < B
  def method3()  end
end

A.instance_methods » ["method1"]
B.instance_methods » ["method2"]
C.instance_methods » ["method3"]
C.instance_methods(true).length » 39

method_defined? mod.method_defined?( einSymbol ) -> true oder false

Gibt true zurück, wenn die genannten Methode in mod (bzw. den eingebundenen Modulen und, falls mod eine Klasse ist, auch seiner Vorfahren) definiert ist.

module A
  def method1()  end
end
class B
  def method2()  end
end
class C < B
  include A
  def method3()  end
end
A.method_defined? :method1 » true
C.method_defined? "method1" » true
C.method_defined? "method2" » true
C.method_defined? "method3" » true
C.method_defined? "method4" » false

module_eval mod.module_eval( einString ) -> einObjekt
mod.module_eval {| | block }-> einObjekt

Evaluiert den String oder Codeblock im Kontext von mod. Diese Methode kann dazu verwendet werden, um Methoden zu einer Klasse hinzuzufügen. module_eval gibt das Ergebnis der Evaluierung zurück.

class Thing
end
a = %q{def hello() "Hello there!" end}
Thing.module_eval(a) » nil
Thing.new.hello() » "Hello there!"

name mod.name -> einString

Gibt den Modulnamen von mod zurück.

private_class_method mod.private_class_method( [einSymbol]+ ) -> nil

Wandelt bestehende Klassenmethoden in private Methoden um. Wird oft genutzt, um den default-Konstruktor new zu verstecken. 

class SimpleSingleton  # Not thread safe
  private_class_method :new
  def SimpleSingleton.create(*args, &block)
    @me = new(*args, &block) if ! @me
    @me
  end
end

private_instance_methods
mod.private_instance_methods( includeSuper=false ) -> einArray

Gibt eine Liste aller in mod definierten, privaten Instanzmethoden zurück. Wenn der optionale Parameter nicht false gesetzt ist, werden auch die Methoden der Vorgängerklassen angegeben.

module Mod
  def method1()  end
  private :method1
  def method2()  end
end
Mod.instance_methods » ["method2"]
Mod.private_instance_methods » ["method1"]

protected_instance_methods
mod.protected_instance_methods( includeSuper=false ) -> einArray

Gibt eine Liste aller in mod definierten, geschützten Instanzmethoden zurück. Wenn der optionale Parameter nicht false gesetzt ist, werden auch die Methoden der Vorgängerklassen angegeben.

public_class_method mod.public_class_method( [einSymbol]+ ) -> nil

Wandelt existierende Klassenmethoden in öffentliche Methoden um.

public_instance_methods
mod.public_instance_methods( includeSuper=false ) -> einArray

Gibt eine Liste aller in mod definierten, öffentlichen Instanzmethoden zurück. Wenn der optionale Parameter nicht false gesetzt ist, werden auch die Methoden der Vorgängerklassen angegeben.

private methods
alias_method alias_method( newID, oldID ) -> mod

Erstellt in newID eine Kopie der Methode oldID. Dies kann verwendet werden, um den Zugriff auf überladene Methoden zu erhalten. 

module Mod
  alias_method :origExit, :exit
  def exit(code=0)
    print "Exiting with code #{code}\n"
    origExit(code)
  end
end
include Mod
exit(99)
produces:
Exiting with code 99

append_features append_features( einModul ) -> mod

Wenn dieses Modul in ein anderes eingebunden ist, ruft Ruby append_features in diesem Modul auf, das den Aufruf an das Empfängermodul in einModul weiter gibt. Die Standardimplementierung dieser Methode ist, dass die Konstanten, Methoden und Modulvariablen dieses Moduls zu einModul hinzugefügt werden, wenn dies nicht bereits zuvor geschehen war bzw. eines der Vorgängermodule von einModul diese enthält. Siehe auch Module#include.

attr attr( einSymbol, writable=false ) -> nil
Definiert einen Attributnamen für dieses Modul, der einSymbol.id2name ist. Ausserdem wird eine Instanzvariable (@name) sowie eine zugehörige Zugriffsmethode, um sie auszulesen. Wenn das optionale Argument writabletrue gesetzt ist, wird auch eine Methode name= generiert, um das Attribut zu setzen. 

module Mod
  attr  :size, true
end
is equivalent to:

module Mod
  def size
    @size
  end
  def size=(val)
    @size = val
  end
end

attr_accessor attr_accessor( [einSymbol]+ ) -> nil

Equivalent zum Aufruf von ``attr einSymbol, true'' für jedes einSymbol.

module Mod
  attr_accessor(:one, :two)
end
Mod.instance_methods.sort » ["one", "one=", "two", "two="]

attr_reader attr_reader( [einSymbol]+ ) -> nil

Erstellt Instanzvariablen und entsprechende Methoden, die den Wert der jeweiligen Variable zurückgeben. Equivalent zum Aufruf von ``attr :name'' für jeden der übergebenen Namen.

attr_writer

attr_writer( [einSymbol]+ ) -> nil

Erstellt eine Zugriffsmethode um einSymbol.id2name einen Wert zuzuweisen.

extend_object extend_object( einObjekt ) -> einObjekt

Erweitert das angegebene Objekt, indem die Konstanten und Methoden (als Singletonmethoden) dieses Objekts hinzugefügt werden. Dies ist die Methode, die beim Aufruf von Object#extend verwendet wird. 

module Picky
  def Picky.extend_object(o)
    if String === o
      print "Can't add Picky to a String\n"
    else
      print "Picky added to ", o.type, "\n"
      super
    end
  end
end
(s = Array.new).extend Picky  # Call Object.extend
(s = "quick brown fox").extend Picky
produces:
Picky added to Array
Can't add Picky to a String

include include( [einModul]+ ) -> mod

Ruft Module.append_features für jeden einzelnen Parameter auf.

method_added method_added( einSymbol )

Wird jedes Mal aufgerufen, wenn dem Empfänger eine Methode hinzugefügt wird. 

module Chatty
  def Chatty.method_added(id)
    print "Adding ", id.id2name, "\n"
  end
  def one()   end
end
module Chatty
  def two()   end
end
produces:
Adding one
Adding two

module_function module_function( [einSymbol]* ) -> mod

Erstellt Modulfunktionen für die genannten Methoden. Diese Funktionen können mit dem Modul als Empfänger aufgerufen werden. Sie stehen auch als Instanzmethoden für Mix-In-Klassen, zur Verfügung. Modulfunktionen sind Kopien des Originals und können daher unabhängig verändert werden. Die Version der Instanzmethode wird in eine private Methode gewandelt. Wenn keine Argumente angegeben werden, sind alle nachfolgend definierten Methoden betroffen.

module Mod
  def one
    "This is one"
  end
  module_function :one
end
class Cls
  include Mod
  def callOne
    one
  end
end
Mod.one » "This is one"
c = Cls.new
c.callOne » "This is one"
module Mod
  def one
    "This is the new one"
  end
end
Mod.one » "This is one"
c.callOne » "This is the new one"

private private( [einSymbol]* ) -> mod

Wenn keine Argumente übergeben werden, ist die Sichtbarkeit aller nachfolgend definierten Methoden privat. Werden Argumente übergeben, so werden alle genannten Methoden zu privaten Methoden gewandelt. Vgl. auch Zugriffskontrolle im Abschnitt "Die Sprache Ruby".

module Mod
  def a()  end
  def b()  end
  private
  def c()  end
  private :a
end
Mod.private_instance_methods » ["c", "a"]

protected protected( [einSymbol]* ) -> mod

Wenn keine Argumente übergeben werden, ist die Sichtbarkeit aller nachfolgend definierten Methoden geschützt. Werden Argumente übergeben, so werden alle genannten Methoden zu geschützten Methoden gewandelt. Vgl. auch Zugriffskontrolle im Abschnitt "Die Sprache Ruby".

public public( [einSymbol]* ) -> mod

Wenn keine Argumente übergeben werden, ist die Sichtbarkeit aller nachfolgend definierten Methoden öffentlich. Werden Argumente übergeben, so werden alle genannten Methoden zu öffentlichen Methoden gewandelt. Vgl. auch Zugriffskontrolle im Abschnitt "Die Sprache Ruby".

remove_const remove_const( einSymbol ) -> einObjekt

Löscht die Definition einer Konstante und gibt deren Wert zurück. Vordefinierte Klassen und Singletonobjekte (wie z.B. true) können nicht entfernt werden.

remove_method remove_method( einSymbol ) -> mod
Entfernt die durch einSymbol identifizierte Methode von der aktuellen Klasse. Für ein Beispiel, siehe Module.undef_method.

undef_method undef_method( einSymbol ) -> mod

Unterbindet die Beantwortung von Aufrufen der genannten Methode in der aktuellen Klasse. Vergleiche dies mit remove_method, das eine Methode aus der jeweiligen Klasse entfernt; Ruby würde in diesem Fall immer noch die Oberklassen und eingebundenen Module nach einem möglichen Empfänger durchsuchen. 

class Parent
  def hello
    print "In parent\n"
  end
end
class Child < Parent
  def hello
    print "In child\n"
  end
end


c = Child.new
c.hello


class Child
  remove_method :hello  # remove from child, still in parent
end
c.hello


class Child
  undef_method :hello   # prevent any calls to 'hello'
end
c.hello
produces:
In child
In parent
prog.rb:23: undefined method `hello' for #<Child:0x4018d428> (NameError)

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Übersetzung: Carsten Schinzer
Für das englische Original:
© 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0. That reference is available for download.
Diese Lizenz sowie das Original vom Herbst 2001 bilden die Grundlage der Übersetzung
Es wird darauf hingewiesen, dass sich die Lizenz des englischen Originals inzwischen geändert hat.
Für die deutsche Übersetzung:
© 2002 Jürgen Katins
Der Copyright-Eigner stellt folgende Lizenzen zur Verfügung:
Nicht-freie Lizenz:
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/). Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.
Freie Lizenz:
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".