summaryrefslogtreecommitdiff
path: root/test/scanners/yaml/faq.expected.raydebug
diff options
context:
space:
mode:
authormurphy <murphy@rubychan.de>2010-04-14 23:59:03 +0000
committermurphy <murphy@rubychan.de>2010-04-14 23:59:03 +0000
commit200144dd009d33ff8334be24d0fb2cc91b3a87ab (patch)
treef46c939cd01b8d4165b5d9f3444c20e072b51408 /test/scanners/yaml/faq.expected.raydebug
parent612a14e17bdae5dbb5b13cdceec797523725cbbe (diff)
downloadcoderay-200144dd009d33ff8334be24d0fb2cc91b3a87ab.tar.gz
Moving scanner tests into separate repository. The repository can be reached at http://svn.rubychan.de/coderay-scanner-tests/trunk.
Diffstat (limited to 'test/scanners/yaml/faq.expected.raydebug')
-rw-r--r--test/scanners/yaml/faq.expected.raydebug492
1 files changed, 0 insertions, 492 deletions
diff --git a/test/scanners/yaml/faq.expected.raydebug b/test/scanners/yaml/faq.expected.raydebug
deleted file mode 100644
index 96af243..0000000
--- a/test/scanners/yaml/faq.expected.raydebug
+++ /dev/null
@@ -1,492 +0,0 @@
-head<head(---)>
-operator(-) key<delimiter(")content(What is a...)delimiter(")>operator(:)
- operator(-) key<delimiter(")content(container?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _container_ is collection of service points and other containers. It
- is used to organize services. Each container has access to all of the
- service points in its ancestor containers.)>
-
- operator(-) key<delimiter(")content(registry?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _registry_ is a special kind of container that has no parent container.
- It also defines a few services (such as the LoggingInterceptor, and
- the various service models and pipeline elements\), so that they are
- available by default to all of the services it contains.)>
-
- operator(-) key<delimiter(")content(service point?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _service point_ is the definition of a service. Just as a class is the
- definition of an object, and you instantiate an object from a class, so
- do you instantiate services from service points.)>
-
- operator(-) key<delimiter(")content(service?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _service_ is the instantiation of a service point.)>
-
- operator(-) key<delimiter(")content(parameterized service?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _parameterized_ service is a service that allows contextual parameters
- to be passed to the service when it is created. Such services are
- typically used in conjunction with the @multiton@ service model, but
- the only real requirement is that they _not_ be used with a service model
- that does not support multiple parameters (like @singleton@ or
- @threaded@\).)>
-
- operator(-) key<delimiter(")content(service model?)delimiter(")>operator(:) string<delimiter(>-)content(
- A _service model_ is a description of the lifecycle of a service. By
- default, all services are _singletons_, meaning that every time you ask
- a container for a particular service, you'll get the same object
- instance back.
-
-
- There are other service models available, though, including "prototype"
- (which returns a new instance for each request of a service\) and
- "deferred" (which returns a proxy, deferring the instatiation of the
- service itself until a method is invoked on the service\). )>
-
- operator(-) key<delimiter(")content(interceptor?)delimiter(")>operator(:) string<delimiter(>-)content(
- An _interceptor_ is an object that may be placed between the client and
- a service. Every request to the service is thus _intercepted_ by that
- object, which can do operations on the request (such as logging\) and may
- even reroute or ignore the request altogether. This provides a kind of
- "poor man's AOP", since you can do "before", "after", and "around" advice
- on the methods of a service.
-
-
- Needle comes with one standard interceptor, the LoggingInterceptor. It
- will log a message on method entry and exit, and also when an exception
- is raised.)>
-
- operator(-) key<delimiter(")content(pipeline?)delimiter(")>operator(:) string<delimiter(>-)content(
- In Needle, the _instantiation pipeline_ is used to control how and when
- services are instantiated. The _service models_ are implemented as
- pipelines.
-
-
- Just as the _interceptors_ are for hooking into method invocations, the
- pipelines are for hooking into service instantiations. Every time a
- service is requested, it's instantiation pipeline is executed. By
- choosing the appropriate kinds of pipeline elements, all of the available
- service models can be implemented (prototype, prototype_deferred,
- singleton, singleton_deferred, etc.\).)>
-
-operator(-) key<delimiter(")content(How do I...)delimiter(")>operator(:)
- operator(-) key<delimiter(")content(create a new registry?)delimiter(")>operator(:) string<delimiter(>-)content(
- There are several ways to create a new registry. The simplist is just to
- invoke Registry#new.
-
-
- <pre>
- reg = Needle::Registry.new
- </pre>
-
-
- This will create a new Registry instance. You can also send a block to
- #new, in which case the new registry will be yielded to it:
-
-
- <pre>
- reg = Needle::Registry.new do |r|
- ...
- end
- </pre>
-
-
- There are two other factory methods you can use for creating a Registry
- instance. Both require a block.
-
-
- <pre>
- r1 = Needle::Registry.define do |builder|
- ...
- end
-
- r2 = Needle::Registry.define! do
- ...
- end
- </pre>
-
-
- Registry#define creates a "builder" object that you can use define
- services more conveniently. Register#define! (with a bang\) does the same
- thing, but evaluates the block within the context of the builder.)>
-
- operator(-) key<delimiter(")content(register a service?)delimiter(")>operator(:) string<delimiter(>-)content(
- The first way to register a service is by calling #register on the
- registry (or a namespace\):
-
-
- <pre>
- reg.register( :foo \) { Foo.new }
- </pre>
-
-
- The (first\) parameter to #register is the name of the service, and the
- block should return the implementation of the service. If needed, the
- block can accept two parameters--the container that the service is being
- registered with, and an object that represents the service being defined
- (called a "service point"\):
-
-
- <pre>
- reg.register( :foo \) do |container,point|
- Foo.new( container[:bar], point.fullname \)
- end
- </pre>
-
-
- You can also use Container#define and Container#define! to register
- services. These approaches are friendlier if you are needing to register
- several services at once.
-
-
- <pre>
- reg.define do |builder|
- builder.foo { Foo.new }
- builder.bar { |c,p| Bar.new( c[:foo], p.name \) }
- end
-
- reg.define! do
- baz { |c,p| Baz.new( c[:bar], p.name \) }
- zoom { Buggy.new }
- end
- </pre>
-
-
- Container#define yields a new "builder" object to the block. Messages
- sent to the builder are interpreted as service names, and if a block is
- sent with the message, a new service is registered under that name.
-
-
- Container#define! does likewise, except it evaluates the block within the
- context of the builder object.
-
-
- If you do not pass a block to #define, it will return the builder object,
- so you could do something like the following if you only need to define
- one or two services:
-
-
- <pre>
- reg.define.foo { ... }
- </pre>
-
-
- Lastly, you can get the builder directly and add services using it:
-
-
- <pre>
- builder = reg.builder
- builder.baz { ... }
- builder.bar { ... }
- </pre>
-
-
- (This last is the same as calling #define without arguments, but is more
- readable if you intend to use the builder object multiple times.\)
- )>
- operator(-) key<delimiter(")content(reference a service?)delimiter(")>operator(:) string<delimiter(>-)content(
- Referencing a service can be done in either of two ways. The first is to
- treat the container (i.e., registry\) as a hash, passing the name of the
- service as an argument to Container#[]:
-
-
- <pre>
- svc = registry[:foo]
- svc.do_something_interesting
- </pre>
-
-
- A more convenient (but slightly more peril-fraught\) approach is to send
- the name of the method to the registry as a message:
-
-
- <pre>
- svc = registry.foo
- </pre>
-
-
- Be aware that this latter approach will only work when the service name
- does not conflict with the name of an existing method on the container.
- For example, if you were to do:
-
-
- <pre>
- registry.register( :hash \) { "hello, world" }
- p registry.hash
- </pre>
-
-
- You would get the hash value of the registry object, instead of the value
- value of the service (which would be "hello, world"\).)>
-
- operator(-) key<delimiter(")content(select a service model for a service (i.e., change the default model of lifecycle management\)?)delimiter(")>operator(:) string<delimiter(>-)content(
- By default, a service will be managed as a singleton, i.e., every request
- of that service will return the same object instance. This is the
- _singleton_ service model.
-
-
- To select a different service model, pass it as an option when you
- register the service:
-
-
- <pre>
- registry.register( :foo, :model => :prototype \) {...}
- registry.define.bar( :model => :threaded \) {...}
- registry.define! do
- baz( :model => :singleton_deferred \) {...}
- ...
- end
- ...
- </pre>)>
-
- operator(-) key<delimiter(")content(create a namespace?)delimiter(")>operator(:) string<delimiter(>-)content(
- Namespaces allow you to organize your services into hierarchical
- packages. You can create namespaces in a few ways. The first (and
- simplest\) is to just call Container#namespace:
-
-
- <pre>
- registry.namespace( :stuff \)
- </pre>
-
-
- This will create a namespace in the registry, called stuff. If you send a
- block as well, the block will be invoked (with the new namespace yielded
- to it\) the first time the namespace is requested:
-
-
- <pre>
- registry.namespace( :stuff \) do |ns|
- ns.register( :foo \) {...}
- ns.define.bar {...}
- ns.define! do
- baz {...}
- buf {...}
- end
- end
- </pre>
-
- Because it is so common to immediately define services on the new
- namespace, there are some convenience methods to make this more...
- convenient.
-
-
- <pre>
- registry.namespace_define!( :stuff \) do
- foo {...}
- bar {...}
- baz {...}
- end
-
- registry.namespace_define( :more_stuff \) do |b|
- b.blah {...}
- b.argh {...}
- b.hack {...}
- end
- </pre>
-
-
- The first one, above, creates the namespace and calls Container#define!.
- The second creates the namespace and calls Container#define. In both
- cases, _the namespace is created immediately_, unlike Container#namespace
- which only creates the namespace when it is first requested.
-
-
- Lastly, note that namespace's are just special services. Thus, you can
- pass options to the namespace methods just as you can with
- Container#register and friends.)>
-
- operator(-) key<delimiter(")content(write log messages?)delimiter(")>operator(:) string<delimiter(>-)content(
- You can obtain a new logger instance from the @:logs@ and @:log_for@
- services. Once you have a logger instance, you can invoke the #debug,
- #info, #warn, #error, and #fatal methods on the instance to log messages
- of the corresponding severity.
-
-
- <pre>
- logger = registry.logs.get( "a name for my logger" \)
- logger.debug "This is a debug message"
- logger.info "This is an informational message"
- ...
- logger2 = registry.log_for( "another logger name" \)
- ...
- </pre>
-
-
- The two approaches shown above are identical--the second approach (using
- the @log_for@ service\) is just a convenience for @logs.get@.
-
-
- Log messages are written, by default, to a file called "needle.log", in
- the same directory that the application was invoked from.
-
-
- You can also use a logging interceptor to automatically log all external
- method invocations on a service. This includes method entry and exit, as
- well as any exceptions that are raised inside the method.
-
-
- <pre>
- registry.register( :foo \) { ... }
- registry.intercept( :foo \).with { |r| r.logging_interceptor }
-
- foo.something
- foo.another_method( 1, 2, 3 \)
- </pre>
-
-
- See the chapter in the "User's Manual":http://needle.rubyforge.org about
- logging for more information on how to use and configure loggers.)>
-
- operator(-) key<delimiter(")content(exclude methods from being intercepted?)delimiter(")>operator(:) string<delimiter(>-)content(
- Only interceptors that explicitly support exclusion of methods can help
- you here. Fortunately, the LoggingInterceptor is one of them. (If you
- write your own interceptor and would like similar functionality, see the
- IncludeExclude module.\)
-
-
- In the case of the LoggingInterceptor, just pass an array of patterns
- (matching method names and/or arities\) as the "exclude" option, when
- declaring the interceptor:
-
-
- <pre>
- registry.register( :foo \) { ... }
- registry.intercept( :foo \).
- with { |r| r.logging_interceptor }.
- with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ]
- </pre>
-
-
- The above will exclude from interception any method named 'foo', or any
- invocation of 'bar' with more than 4 arguments, or any method invocation
- with fewer than two arguments.
-
-
- You can also give an array of patterns to _include_. These cause methods
- to be explicitly intercepted even if they match an exclude pattern:
-
-
- <pre>
- registry.register( :foo \) { ... }
- registry.intercept( :foo \).
- with { |r| r.logging_interceptor }.
- with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ],
- :include => [ 'baz' ]
-
- foo = registry.foo
- foo.baz
- </pre>
-
-
- This would result in the call to #baz being intercepted, even though it
- matches an exclude pattern (@*(<2\)@\).)>
-
- operator(-) key<delimiter(")content(include services defined in another library?)delimiter(")>operator(:) string<delimiter(>-)content(
- This requires that the other library be implemented in such a way that it
- expects to be "included" by other libraries/applications. For example,
- Needle encourages the use of a method called @register_services@, which
- accepts a container as a parameter:
-
-
- <pre>
- module A
- module B
- def register_services( container \)
- ...
- end
- module_function :register_services
- end
- end
- </pre>
-
-
- If the library has been implemented in this way, you can simply do a
- require of the library and then invoke the @register_services@ method.
-
-
- There is a convenience method in Container for doing this. Just call
- Container#require, passing the file to require and a string (or symbol\)
- identifying the name of the module that contains the registration method.
- You can also pass a symbol as the third parameter naming the registration
- method, but it defaults to @:register_services@.
-
-
- <pre>
- require 'a/b'
- A::B.register_services( container \)
-
- # or
-
- container.require( 'a/b', "A::B" \)
- </pre>
-
-
- The definition context (i.e., the "builder" object\) also supports the
- require method, so you can do:
-
-
- <pre>
- container.define do |b|
- b.require "a/b", "A::B"
- b.foo { ... }
- ...
- end
- </pre>)>
-
-operator(-) key<delimiter(")content(When should I...)delimiter(")>operator(:)
- operator(-) key<delimiter(")content(use a different service model?)delimiter(")>operator(:)
- operator(-) key<delimiter(")content(Like, :prototype?)delimiter(")>operator(:) string<delimiter(>-)content(
- The prototype service model is appropriate when the service:
-
-
- * has internal state
-
- * will be used multiple times for different situations
-
-
- For example, if you have a GUI library, a "button" service could be a
- prototype, because you will likely have many buttons in an application,
- with each button being an independent instance.)>
-
- operator(-) key<delimiter(")content(Like, :singleton?)delimiter(")>operator(:) string<delimiter(>-)content(
- The singleton service model is the default, so you should rarely need
- to explicitly specify it as a model. It is appropriate for services
- that:
-
-
- * guard some specific functionality
-
- * represent state that is global across an application)>
-
- operator(-) key<delimiter(")content(Like, :threaded?)delimiter(")>operator(:) string<delimiter(>-)content(
- Threaded is similar to singleton, but it allows one unique instance of
- the service _per thread_. Thus, it is appropriate to the same
- situations as singleton, but specific to a thread, instead of an
- application. This is useful for web applications that are run in a
- single virtual machine, and which share a single registry.)>
-
- operator(-) key<delimiter(")content(Like, deferred?)delimiter(")>operator(:) string<delimiter(>-)content(
- Deferred models use a proxy to enforce lazy initialization of the
- service. A service using a deferred service model (ie,
- @:prototype_deferred@, @:multiton_deferred@, @:singleton_deferred@, or
- @:threaded_deferred@\) will not be instantiated until the first time a
- method is invoked on the service.
-
-
- This makes a deferred model appropriate when a service is expensive to
- instantiate, since you can wait to do the expensive initialization
- until it is really needed. Applications will start up faster when their
- dependences use deferred instantiation.)>
-
- operator(-) key<delimiter(")content(Like, initialize?)delimiter(")>operator(:) string<delimiter(>-)content(
- This is useful when you have a method that you want to be invoked
- automatically after a service has been instantiated. Consider the case
- where a service is initialized primarily using setters, but requires
- some logic to be executed to complete the initialization phase. In this
- case, you could always explicitly invoke the initialization method(s\)
- in the constructor block, but if many services use the same
- initialization method, it can be more convenient to use an "initialize"
- service model.)>
-
- operator(-) key<delimiter(")content(Like, multiton?)delimiter(")>operator(:) string<delimiter(>-)content(
- Multitons are useful for factories, where you have a class that
- differentiates its instances based on some construction parameters that
- need to be determined at runtime. Thus, multitons are always used with
- parameterized services.)>