I've read the spec but I'm still confused how my class differs from [our] class. What are differences and when to use which?
The my scope declarator implies lexical scoping: following its declaration, the symbol is visible to the code within the current set of curly braces. We thus tend to call the region within a pair of curly braces a "lexical scope". For example:
sub foo($p) {
# say $var; # Would be a compile time error, it's not declared yet
my $var = 1;
if $p {
$var += 41; # Inner scope, $var is visible
}
return $var; # Same scope that it was declared in, $var is visible
}
# say $var; # $var is no longer available, the scope ended
Since the variable's visibility is directly associated with its location in the code, lexical scope is really helpful in being able to reason about programs. This is true for:
The programmer (both for their own reasoning about the program, but also because more errors can be detected and reported when things have lexical scope)
The compiler (lexical scoping permits easier and better optimization)
Tools such as IDEs (analyzing and reasoning about things with lexical scope is vastly more tractable)
Early on in the design process of the language that would become Raku, subroutines did not default to having lexical scope (and had our scope like in Perl), however it was realized that lexical scope is a better default. Making subroutine calls always try to resolve a symbol with lexical scope meant it was possible to report undeclared subroutines at compile time. Furthermore, the set of symbols in lexical scope is fixed at compile time, and in the case of declarative constructs like subroutines, the routine is bound to that symbol in a readonly manner. This also allows things like compile-time resolution of multiple dispatch, compile-time argument checking, and so forth. It is likely that future versions of the Raku language will specify an increasing number of compile-time checks on lexically scoped program elements.
So if lexical scoping is so good, why does our (also known as package) scope exist? In short, because:
Sometimes we want to share things more widely than within a given lexical scope. We could just declare everything lexical and then mark things we want to share with is export, but..
Once we get to the point of using a lot of different libraries, having everything try to export things into the single lexical scope of the consumer would likely lead to a lot of conflicts
Packages allow namespacing of symbols. For example, if I want to use the Cro clients for both HTTP and WebSockets in the same code, I can happily use both, and refer to them as Cro::HTTP::Client and Cro::WebSocket::Client respectively.
Packages are introduced by package declarators, such as class, module, grammar, and (with caveats) role. An our declaration will make an installation in the enclosing package construct.
These packages ultimately exist within a top-level package named GLOBAL - which is fitting, since they are effectively globally visible. If we declare an our-scoped variable, it is thus a global variable (albeit hopefully a namespaced one), about which enough has been written that we know we should pause for thought and wonder if a global variable is the best API decision (because, ultimately, everything that ends up visible via GLOBAL is an API decision).
Where things do get a bit blurry, however, is that we can have lexical packages. These are packages that do not get installed in GLOBAL. I find these extremely useful when doing OO programming. For example, I might have:
# This class that ends up in GLOBAL...
class Cro::HTTP::Client {
# Lexically scoped classes, which are marked `my` and thus hidden
# implementation details. This means I can refactor them however I
# want, and never have to worry about downstream fallout!
my class HTTP1Pipeline {
# Implementation...
}
my class HTTP2Pipeline {
# Implementation...
}
# Implementation...
}
Lexical packages can also be nested and contain our-scoped variables, however don't end up being globally visible (unless we somehow choose to leak them out).
Different Raku program elements have been ascribed a default scope:
Subroutines default to lexical (my) scope
Methods default to has scope (only visible through a method dispatch)
Type (class, role, grammar, subset) and module declarations default to package (our) scope
Constants and enumerations default to package (our) scope
Effectively, things that are most often there to be shared default to package scope, and the rest do not. (Variables do force us to pick a scope explicitly, however the most common choice is also the shortest one to type.)
Personally, I'm hesitant to make a thing more visible than the language defaults, however I'll often make them less visible (for example, my on constants that are for internal use, and on classes that I'm using to structure implementation details). When I could do something by exposing an our-scoped variable in a globally visible package, I'll still often prefer to make it my-scoped and provide a sub (exported) or method (visible by virtue of being on a package-scoped class) to control access to it, to buy myself some flexibility in the future. I figure it's OK to make wrong choices now if I've given myself space to make them righter in the future without inconveniencing anyone. :-)
In summary:
Use my scope for everything that's an implementation detail
Also use my scope for things that you plan to export, but remember exporting puts symbols into the single lexical scope of the consumer and risks name clashes, so be thoughtful about exporting particularly generic names
Use our for things that are there to be shared, and when its desired to use namespacing to avoid clashes
The elements we'd most want to share default to our scope anyway, so explicitly writing our should give pause for thought
As with variables, my binds a name lexically, whereas our additionally creates an entry in the surrounding package.
module M {
our class Foo {}
class Bar {} # same as above, really
my class Baz {}
}
say M::Foo; # ok
say M::Bar; # still ok
say M::Baz; # BOOM!
Use my for classes internal to your module. You can of course still make such local symbols available to importing code by marking them is export.
The my vs our distinction is mainly relevant when generating the symbol table. For example:
my $a; # Create symbol <$a> at top level
package Foo { # Create symbol <Foo> at top level
my $b; # Create symbol <$b> in Foo scope
our $c; # Create symbol <$c> in Foo scope
} # and <Foo::<$c>> at top level
In practice this means that anything that is our scoped is readily shared to the outside world by prefixing the package identifier ($Foo::c or Foo::<$c> are synonymous), and anything that is my scoped is not readily available — although you can certainly provide access to it via, e.g., getter subs.
Most of the time you'll want to use my. Most variables just belong to their current scope, and no one has any business peaking in. But our can be useful in some cases:
constants that don't poison the symbol table (this is why, actually, using constant implies an our scope). So you can make a more C-style enum/constants by using package Colors { constant red = 1; constant blue = 2; } and then referencing them as Colors::red
classes or subs that should be accessible but needn't be exported (or shouldn't be because overlapping symbols with builtins or other modules). Exporting symbols can be great, but sometimes it's also nice to have the package/module namespace to remind you what stuff goes with. As such, it's also a nice way to manage options at runtime via subs: CoolModule::set-preferences( ... ). (although dynamic variables can be used to nice effect here as well).
I'm sure others will comment with other times the our scope is useful, but these are the ones from my own experience.
Related
I was going through an old puppet code. It was using mysql puppet module to install mysql-server.
I came across this
class { '::mysql::server':
}
and this
class { 'mysql::server':
}
Now I'm confused. Do they both mean the same thing or there's any difference between the two?
This is a really good question. The short answer is that they are the same, and that :: isn't needed for class names.
I'd always assumed the initial :: was needed to avoid scope ambiguity (where include bar in class foo would include ::foo::bar rather than ::bar) but checking the docs, they say that, for example, include must use the class's full name.
A working example:
$ cat scope.pp
class foo {
class bar {
notice("foo::bar")
}
class { 'bar':
}
}
class bar {
notice("bar")
}
class { 'foo':
}
$ puppet apply scope.pp
Notice: Scope(Class[Bar]): bar
I'd note that while this is true for class scope, it certainly isn't true for variable scope in Puppet, as below.
$ cat var_scope.pp
$bar = "bar"
class foo {
$bar = "foo::bar"
notice($::bar)
notice($bar)
}
include foo
notice($bar)
$ puppet apply var_scope.pp
Notice: Scope(Class[Foo]): bar
Notice: Scope(Class[Foo]): foo::bar
Notice: Scope(Class[main]): bar
Do they both mean the same thing or there's any difference between the two?
TL;DR: They mean the same thing for classes and defined types. That the form with the leading :: is supported can be viewed as either a backwards-compatibility feature, an internal consistency feature, or both. For variables, however, the leading :: indicates a top-scope variable, which might or might not be what you get if you use the bare variable name.
To clarify some details of the fine answer that #Jon already presented, we have to consider the behavior of Puppet version 3 and earlier. This is no longer documented on Puppet's main documentation site, but we can find the relevant docs in Puppet's online archive of obsolete documentation. Specifically, we want to look at Puppet namespaces and their behavior. The docs are an interesting read if you're into that sort of thing, especially the historical perspective on how Puppet 3 ended up where it was, but here's a somewhat whimsical version of events:
In the beginning, the Forge was formless and void, and there were no modules. Everyone wrote their own code for everything, and the devops faithful were sorely oppressed, reinventing many wheels.
In those days, the idea of modules was conceived. The modules of that day were built using the features then abroad in the land, such as the import function, which has since departed. But with code sharing came name collisions, and to that, the people responded with namespacing. And Reductive Labs looked on namespacing and saw that it was good.
But not everything was clear to Reductive or the people, and in ignorance, Reductive brought forth relative name resolution. And relative name resolution scrutinized names and namespaces very deeply, attempting to resolve even qualified names relative to every namespace in scope. Some of the people rejoiced at the convenience, but the wise among them soon grew troubled. It became clear to them that relative name resolution looked too deeply and saw too much. It sometimes saw things it was not meant to see, and opened paths for the faithful to fall into error.
So the wise intervened. They proclaimed that relative namespacing should be shackled and overcome, tamed by feeding it only names anchored to the one true anonymous namespace, that which existed before anything else Puppet. And the form of the shackles was the leading double colon, ::. And although relative name resolution often performed the same work unshackled, many heeded the wise, and were praised for it.
And Reductive, then naming itself Puppet Labs, regretted creating relative name resolution and urged the people to follow the counsel of the wise. But when it brought forth the Third Age of Puppet, it could not bring itself to trouble those among the people who paid no attention, so it allowed relative name resolution to live.
But at the dawn of the Fourth Age, Puppet, no longer labs, found the courage to at last slay relative name resolution, and it was no more. Since that day, Puppet no longer urges the leading double colon on purveyors and users of classes and types, yet it honors the legacy of past wisdom, and has pity on those who are slow to unlearn it.
Yet Puppet, in its merciful beneficence, has chosen class variables from among all named things as the only ones to bear two names. They have scopes that transcend namespace, and in their scopes they may be known by the simple names of their definitions. Like all named things, however, they can be known anywhere by their namespaced names, formed from their simple names and their class names, in either form. But what, then, of the variables of the top scope? By what name can they be known when they are hidden in the shadows? Here the leading double colon yet serves. Its mark of the top scope is not redundant for variables, and some among the wise make their code clear by using it always for such variables.
When should I be using an include vs a class declaration? I am exploring creating a profile module right now, but am struggling with methodology and how I should lay things out.
A little background, I'm using the puppet-labs java module which can be found here.
My ./modules/profile/manifests/init.pp looks like this:
class profile {
## Hiera Lookups
$java_version = hiera('profile::jdk::package')
class {'java':
package => $java_version,
}
}
This works fine, but I know that I can also remove the class {'java': block of the code and instead use include java. My question relates around two things. One, if I wanted to use an include statement for whatever reason, how could I still pass the package version from hiera to it? Second, is there a preferred method of doing this? Is the include something I really shouldn't be using, or are there advantages and disadvantages to each method?
My long term goal will be building out profile like modules for my environment. Likely I would have a default profile that applies to all of my servers, and then profiles for different application load outs. I could include the profiles into a role and apply things to my individual nodes at that level. Does this make sense?
Thanks!
When should I be using an include vs a class declaration?
Where a class declares another, internal-only class that belongs to the same module, you can consider using a resource-like class declaration. That leverages your knowledge of the implementation details of the module, as you need to be able to prove that no other declaration of the class in question will be evaluated before the resource-like one. If ever that constraint is violated, catalog building will fail.
Under all other circumstances, you should use include or one of its siblings, require and contain.
One, if I wanted to use an include statement for whatever reason, how
could I still pass the package version from hiera to it?
Exactly the same way you would specify any other class parameter via Hiera. I already answered that for you.
Second, is
there a preferred method of doing this?
Yes, see above.
Is the include something I
really shouldn't be using, or are there advantages and disadvantages
to each method?
The include is what you should be using. This is your default, with require and contain as alternatives for certain situations. The resource-like declaration syntax seemed good to the Puppet team when they first introduced it, in Puppet 2.6, along with parameterized classes themselves. But it turns out that that syntax introduced deep design problems into the language, and it has been a source of numerous bugs and headaches. Automatic data binding was introduced in Puppet 3 in part to address many of those, allowing you to assign values to class parameters without using resource-like declarations.
The resource-like syntax has the single advantage -- if you want to consider it one -- that the parameter values are expressed directly in the manifest. Conventional Puppet wisdom holds that it is better to separate data from code, however, so as to avoid needing to modify manifests as configuration requirements change. Thus, expressing parameter values directly in the manifest is a good idea only if you are confident that they will never change. The most significant category of such cases is when a class has read data from an external source (i.e. looked it up via Hiera), and wants to pass those values on to another class.
The resource-like syntax has the great disadvantage that if a resource-like declaration of a given class is evaluated anywhere during the construction of a catalog for a given target node, then it must be the first declaration of that class that is evaluated. In contrast, any number of include-like declarations of the same class can be evaluated, whether instead of or in addition to a resource-like declaration.
Classes are singletons, so multiple declarations have no more effect on the target node than a single declaration. Allowing them is extremely convenient. Evaluation order of Puppet manifests is notoriously hard to predict, however, so if there is a resource-like declaration of a given class somewhere in the manifest set, it is very difficult in the general case to ensure that it is the first declaration of that class that is evaluated. That difficulty can be managed in the special case I described above. This falls into the more general category of evaluation-order dependencies, and you should take care to ensure that your manifest set is free of those.
There are other issues with the resource-like syntax, but none as significant as the evaluation-order dependency.
Clarification with respect to automated data binding
Automated data binding, mentioned above, associates keys identifying class parameters with corresponding values for those parameters. Compound values are supported if the back end supports them, which the default YAML back end in fact does. Your comments on this answer suggest that you do not yet fully appreciate these details, and in particular that you do not recognize the significance of keys identifying (whole) class parameters.
I take your example of a class that could on one hand be declared via this resource-like declaration:
class { 'elasticsearch':
config => { 'cluster.name' => 'clustername', 'node.name' => 'nodename' }
}
To use an include-like declaration instead, we must provide a value for the class's "config" parameter in the Hiera data. The key for this value will be elasticsearch::config (<fully-qualified classname> :: <parameter name>). The associated value is wanted puppet-side as a hash (a.k.a. "associative array", a.k.a. "map"), so that's how it is specified in the YAML-format Hiera data:
elasticsearch::config:
"cluster.name": "clustername"
"node.name": "nodename"
The hash nature of the value would be clearer if there were more than one entry. If you're unfamiliar with YAML, then it would probably be worth your while to at least skim a primer, such as the one at yaml.org.
With that data in place, we can now declare the class in our Puppet manifests simply via
include 'elasticsearch'
I know, this is a weird question.
Is there a programming language where you can't pass arguments to functions?
Every language and framework in recent years struggles to use patterns like dependency injection everywhere, and it made me wonder - what if everything was automatically injected somehow, by default, everywhere, all the time, without even giving you the option of doing anything else?
So arguments to functions would always be completed from available symbols in the local source.
For one, this would force you to always name any local symbols consistently with their intended use.
For example - and this is totally fictive syntax:
class UserService {
...
function login(username: string, password: string) { ... }
}
class UserController {
function login(userService: UserService, post: PostData) {
var username = data.get('username')
var password = data.get('password')
u.login() // arguments automatically filled
}
}
Arguments to constructors would be automatically filled as well.
Object properties declared in the local source might be considered for filling arguments as well.
Arguments passed to the local function would be considered too, as they are really just local variables, and this would make things like dependency chains an implicit thing - so if your class needs a database connection not for it's own use, but just so it can pass it to some other aggregate object, the connection object could automatically be injected by just declaring the dependency in the form of a new argument; callers of that function would automatically fulfill the argument if they have a suitable arguments available, eliminating the need to pass around indirect dependencies.
Has anything like that (or similar) been attempted in any existing language?
I don't know of any. It almost seems like a feature that programming languages would try to avoid because on larger projects, you would end up with thousands upon thousands of variables, which would be very confusing to keep track of, not to mention a lot of wasted RAM.
Most programming languages try to encourage you to use only what you need, which is good for performance and lowers the RAM overhead. If you had all of your variables in the global scope, memory leaks would likely be a common problem too.
So, although this is an interesting idea, I'm not sure how practical it would be. And if a language like this does exist, it would likely be limited in what types of tasks it can/is designed to accomplish.
Is there a list of items on the web that you should not use when creating a model or variable?
For example, if I wanted to create apartment listings, naming a model something like Property would be problematic in the future and also confusing since property is a built-in Python function.
I did try Googling this, but couldn't come up with anything.
Thanks!
Rules and constraints about naming depend on the programming language. How an identifier/name is bound depends on the language semantics and its scoping rules: an identifer/name will be bound to different element depending on the scope. Scoping is usally lexical (i.e. static) but some language have dynamic scoping (some variant of lisp).
If names are different, there is no confusion in scoping. If identifiers/names are reused accrossed scopes, an identifier/name might mask another one. This is referred as Shadowing. This is a source of confusion.
Certain reserved names (i.e. keywords) have special meaning. Such keyword can simply be forbidden as names of other elements, or not.
For instance, in Smallatalk self is a keyword. It is still possible to declare a temporary variable self, though. In the scope where the temporary variable is visible, self resolves to the temporary variable, not the usual self that is receiver of the message.
Of course, shadowing can happen between regular names.
Scoping rules take types into consideration as well, and inheritance might introduce shadows.
Another source of confusion related to binding is Method Overloading. In statically typed languages, which method is executed depends on the static types at the call site. In certain cases, overloading makes it confusing to know which method is selected. Both Shadowing and Overloading should avoided to avoid confusions.
If your goal is to translate Python to Javascript, and vice versa, I guess you need to check the scoping rules and keywords of both languages to make sure your translation is not only syntactically correct, but also semantically correct.
Generally, programming languages have 'reserved words' or 'keywords' that you're either not able to use or in some cases are but should stay away from. For Python, you can find that list here.
Most words in most natural languages can have different meanings, according to the context. That's why we use specifiers to make the meaning of a word clear. If in any case you think that some particular identifier may be confusing, you can just add a specifier to make it clear. For example ObjectProperty has probably nothing to do with real estate, even in an application that deals with real estate.
The case you present is no different than using generic identifiers with no attached context. For example a variable named limit or length may have completely different meanings in different programs. Just use identifiers that make sense and document their meaning extensively. Being consistent within your own code base would also be preferable. Do not complicate your life with banned term lists that will never be complete and will only make programming more difficult.
The obvious exceptions are words reserved by your programming language of choice - but then again no decent compiler would allow you to use them anyway...
How is COBOL's scope defined? Is it statically scoped?
Cobol has compile time binding for variables, sometimes called static scope.
Within that, Cobol supports several layers of scope within programs:
"External" variables are the equivilent of a Fortran or assembler common section, they are truly global.
"Global Program Scope" variables declared in working storage as global are visible to the entire program in which they are declared AND in all nested subprograms contained in that program.
"Program Scope" variables declared in working storage are visible to the entire program in which they are declared.
"Program Scope" variables declared in local storage are visible to the entire program in which they are declared, but are deleted and reinitialized on every invocation. Think thread scoped, sorta.
"Nested Program Scope" Cobol does not distinguish between programs and functions/procedures, its equvilent of a procedure or function is called a program. An infinite number of programs can be contained within a program, and the variables of each are visible only within the scope of that individual program. You could think of this as function/procedure scope.
The OO extensions that many vendors have, and the 2002 standard, defines the traditional public/protected/private object scope and method scope.
"Cobol" is as old as Radar, Laser, and Scuba, can we please stop acronymizing it?
All variables in a COBOL program are globally scoped. In fact, there are no "scopes" (in traditional COBOL, I'm not messing with OO extensions), but just "modules" or "programs".
Intermodule communication is done via the Linkage Section (usually passed by ref), and also all variables there are visible from the called module.
COBOL uses static (lexical) scope (as do C, C++, Java and Pascal). Dynamic scope is not all that common in the programming world. I think some versions of Lisp and SNOBOL used dynamic scope.
If you are interested in understanding scope with respect to programming languages you should review this document