class Crystal::Program
inherits Crystal::NonGenericModuleType
¶
A program contains all types and top-level methods related to one compilation of a program.
It also carries around all information needed to compile a bunch of files: the unions, the symbols used, all global variables, all required files, etc. Because of this, a Program is usually passed around in every step of a compilation to record and query this information.
In a way, a Program is an alternative implementation to having global variables for all of this data, but modeled this way one can easily test and exercise programs because each one has its own definition of the types created, methods instantiated, etc.
Additionally, a Program acts as a regular type (a module) that can have
types (the top-level types) and methods (the top-level methods), and which
can also include other modules (this happens when you do include Module
at the top-level).
Included modules
Crystal::DefInstanceContainer
Constants¶
PKG_CONFIG_PATH = Process.find_executable("pkg-config")
¶
Process.find_executable("pkg-config")
Class methods¶
Methods¶
#add_type(types, type : VoidType)
¶
(types, type : VoidType)
When Void participates in a union, it becomes Nil (users shouldn't deal with real Void values)
#after_inference_types : Set(Crystal::Type)
¶
: Set(Crystal::Type)
Types that have instance vars initializers which need to be visited
(transformed) by CleanupTransformer once the semantic analysis finishes.
Todo
this probably isn't needed and we can just traverse all types at the end, and analyze all instance variables initializers that we found. This should simplify a bit of code.
#cache_dir=(cache_dir : String?)
¶
(cache_dir : String?)
The cache directory where temporary files are placed.
#class_var_initializers : Array(Crystal::ClassVarInitializer)
¶
: Array(Crystal::ClassVarInitializer)
The class var initializers stored to be used by the cleanup transformer
#colorize(obj)
¶
(obj)
Colorizes the given object, depending on whether this program is configured to use colors.
#const_initializers : Array(Crystal::Const)
¶
: Array(Crystal::Const)
Here we store constants, in the order that they are used. They will be initialized as soon as the program starts, before the main code.
#error_on_warnings=(error_on_warnings : Bool)
¶
(error_on_warnings : Bool)
If true compiler will error if warnings are found.
#expand_macro(a_macro : Macro, call : Call, scope : Type, path_lookup : Type? = nil, a_def : Def? = nil)
¶
(a_macro : Macro, call : Call, scope : Type, path_lookup : Type? = nil, a_def : Def? = nil)
#expand_macro(node : ASTNode, scope : Type, path_lookup : Type? = nil, free_vars = nil, a_def : Def? = nil)
¶
(node : ASTNode, scope : Type, path_lookup : Type? = nil, free_vars = nil, a_def : Def? = nil)
#file_modules : Hash(String, Crystal::FileModule)
¶
: Hash(String, Crystal::FileModule)
All FileModules indexed by their filename. These store file-private defs, and top-level variables in files other than the main file.
#find_in_path(filename, relative_to = nil) : Array(String)?
¶
(filename, relative_to = nil) : Array(String)?
Finds filename in the configured CRYSTAL_PATH for this program, relative to relative_to.
#flags
¶
Returns the flags for this program. By default these
are computed from the target triple (for example x86_64,
darwin, linux, etc.), but can be overwritten with flags=
and also added with the -D command line argument.
See Compiler#flags.
#global_vars : Hash(String, Crystal::MetaTypeVar)
¶
: Hash(String, Crystal::MetaTypeVar)
All global variables in the program ($foo, $bar), indexed by their name.
The names includes the $ sign.
#host_compiler
¶
Creates a compiler instance with the host as target used for macro_run compilation.
#link_annotations
¶
Returns every @[Link] annotation in the program parsed as LinkAnnotation
#literal_expander
¶
Returns a LiteralExpander useful to expand literal like arrays and hashes
into simpler forms.
#lookup_path_item(name : String, lookup_in_namespace, include_private, location)
¶
(name : String, lookup_in_namespace, include_private, location)
Looks up a single path item relative to *self`.
If lookup_in_namespace is true, if the type is not found
in self or self's parents, the path item is searched in this
type's namespace. This parameter is useful because when writing
Foo::Bar::Baz, Foo should be searched in enclosing namespaces,
but Bar and Baz not.
#named_tuple_of(entries : Hash(String, Type) | NamedTuple)
¶
(entries : Hash(String, Type) | NamedTuple)
Returns the Type for NamedTuple(**entries)
#named_tuple_of(entries : Array(NamedArgumentType))
¶
(entries : Array(NamedArgumentType))
Returns the Type for NamedTuple(**entries)
#nil_var
¶
Returns a Var that has Nil as a type.
This variable is bound to other nodes in the semantic phase for things
that need to be nilable, for example to a variable that's only declared
in one branch of an if expression.
#parse_macro_source(generated_source, macro_expansion_pragmas, the_macro, node, vars, current_def = nil, inside_type = false, inside_exp = false, visibility : Visibility = :public
¶
(generated_source, macro_expansion_pragmas, the_macro, node, vars, current_def = nil, inside_type = false, inside_exp = false, visibility : Visibility = :public
#parse_macro_source(generated_source, macro_expansion_pragmas, the_macro, node, vars, current_def = nil, inside_type = false, inside_exp = false, mode : Parser::ParseMode = :normal, visibility : Visibility = :public)
¶
(generated_source, macro_expansion_pragmas, the_macro, node, vars, current_def = nil, inside_type = false, inside_exp = false, mode : Parser::ParseMode = :normal, visibility : Visibility = :public)
#proc_of(nodes : Array(ASTNode), return_type : Type)
¶
(nodes : Array(ASTNode), return_type : Type)
Returns the Type for Proc(*nodes.map(&.type), return_type)
#progress_tracker : Crystal::ProgressTracker
¶
: Crystal::ProgressTracker
A ProgressTracker object which tracks compilation progress.
#progress_tracker=(progress_tracker)
¶
(progress_tracker)
A ProgressTracker object which tracks compilation progress.
#record_require(filename, relative_to) : Nil
¶
(filename, relative_to) : Nil
Remembers that the program depends on this require.
#requires : Set(String)
¶
: Set(String)
All required files. The set stores absolute files. This way
files loaded by require nodes are only processed once.
#semantic(node : ASTNode, cleanup = true) : ASTNode
¶
(node : ASTNode, cleanup = true) : ASTNode
Runs semantic analysis on the given node, returning a node that's typed. In the process types and methods are defined in this program.
#splat_expansions : Hash(Def, Type)
¶
: Hash(Def, Type)
Hash that prevents recursive splat expansions. For example:
def foo(*x)
foo(x)
end
foo(1)
Here x will be {Int32}, then {{Int32}}, etc.
The way we detect this is by remembering the type of the splat, associated to a def's object id (the UInt64), and on an instantiation we compare the new type with the previous one and check if it contains the previous type.
#string_pool : StringPool
¶
: StringPool
A String pool to avoid creating the same strings over and over. This pool is passed to the parser, macro expander, etc.
#tempfiles : Array(String)
¶
: Array(String)
Temporary files which are generated by macro runs that need to be deleted after the compilation is finished.
#to_s(io : IO) : Nil
¶
(io : IO) : Nil
Appends a short String representation of this object which includes its class name and its object address.
class Person
def initialize(@name : String, @age : Int32)
end
end
Person.new("John", 32).to_s # => #<Person:0x10a199f20>
#top_level_semantic(node)
¶
(node)
Processes type declarations and instance/class/global vars types are guessed or followed according to type annotations.
This alone is useful for some tools like doc or hierarchy where a full semantic of the program is not needed.
#unions : Hash(Array(UInt64), Crystal::UnionType)
¶
: Hash(Array(UInt64), Crystal::UnionType)
All created unions in a program, indexed by an array of opaque ids of each type in the union. The array (the key) is sorted by this opaque id.
A program caches them this way so a union of String | Int32
or Int32 | String is represented by a single, unique type
in the program.
#vars : Hash(String, Crystal::MetaVar)
¶
: Hash(String, Crystal::MetaVar)
Top-level variables found in a program (only in the main file).
#visit_main(node, visitor = MainVisitor.new(self), process_finished_hooks = false, cleanup = true)
¶
(node, visitor = MainVisitor.new(self), process_finished_hooks = false, cleanup = true)
#warnings_exclude=(warnings_exclude : Array(String))
¶
(warnings_exclude : Array(String))
Paths to ignore for warnings detection.