1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # nit index, is a command tool used to display documentation
21 # Main class of the nit index tool
22 # NitIndex build the model using the toolcontext argument
23 # then wait for query on std in to display documentation
25 private var toolcontext
: ToolContext
26 private var model
: Model
27 private var mbuilder
: ModelBuilder
28 private var mainmodule
: MModule
29 private var arguments
: Array[String]
30 private var renderer
: PagerMatchesRenderer
32 # New constructor to use the pre-calculated model when interpreting a module
33 init with_infos
(mbuilder
: ModelBuilder, mmodule
: MModule) do
35 self.model
= mbuilder
.model
36 self.mbuilder
= mbuilder
38 self.mainmodule
= mmodule
39 self.toolcontext
= mbuilder
.toolcontext
40 self.arguments
= toolcontext
.option_context
.rest
42 renderer
= new PagerMatchesRenderer(self)
45 init(toolcontext
: ToolContext) do
46 # We need a model to collect stufs
47 self.toolcontext
= toolcontext
48 self.arguments
= toolcontext
.option_context
.rest
50 if arguments
.length
> 2 then
51 print toolcontext
.tooldescription
56 mbuilder
= new ModelBuilder(model
, toolcontext
)
58 var mmodules
= mbuilder
.parse
([arguments
.first
])
59 if mmodules
.is_empty
then return
61 assert mmodules
.length
== 1
62 self.mainmodule
= mmodules
.first
64 renderer
= new PagerMatchesRenderer(self)
68 if arguments
.length
== 1 then
77 print
"Welcome in the Nit Index."
79 print
"Loaded modules:"
80 var mmodules
= new Array[MModule]
81 mmodules
.add_all
(model
.mmodules
)
82 var sorter
= new MEntityNameSorter
93 print
"\tname\t\tlookup module, class and property with the corresponding 'name'"
94 print
"\tparam: Type\tlookup methods using the corresponding 'Type' as parameter"
95 print
"\treturn: Type\tlookup methods returning the corresponding 'Type'"
96 print
"\tnew: Type\tlookup methods creating new instances of 'Type'"
97 print
"\t:h\t\tdisplay this help message"
104 search
(sys
.stdin
.read_line
)
107 fun search
(entry
: String) do
108 if entry
.is_empty
then
112 if entry
== ":h" then
117 if entry
== ":q" then return
120 var query
= parse_query
(entry
)
123 var matches
= new HashSet[IndexMatch]
124 if query
isa IndexQueryPair then
125 if query
.category
== "return" then
127 matches
.add_all
(search_returns
(query
))
128 else if query
.category
== "param" then
130 matches
.add_all
(search_params
(query
))
131 else if query
.category
== "new" then
133 matches
.add_all
(search_inits
(query
))
136 matches
.add_all
(search_modules
(query
))
137 matches
.add_all
(search_classes
(query
))
138 matches
.add_all
(search_properties
(query
))
141 if matches
.is_empty
then
142 print
"Nothing known about '{query.string}', type ':h' for help"
144 renderer
.render_matches
(query
, matches
)
146 if arguments
.length
== 1 then prompt
149 private fun parse_query
(str
: String): IndexQuery do
150 var parts
= str
.split_with
(":")
151 if parts
.length
== 1 then
152 return new IndexQuery(str
, parts
[0])
154 var category
= parts
[0]
155 var keyword
= parts
[1]
156 if keyword
.chars
.first
== ' ' then keyword
= keyword
.substring_from
(1)
157 return new IndexQueryPair(str
, keyword
, category
)
162 private fun search_modules
(query
: IndexQuery): Set[MModule] do
163 var matches
= new HashSet[MModule]
164 for mmodule
in model
.mmodules
do
165 if mmodule
.name
== query
.keyword
then matches
.add
(mmodule
)
171 private fun search_classes
(query
: IndexQuery): Set[MClass] do
172 var matches
= new HashSet[MClass]
173 for mclass
in model
.mclasses
do
174 if mclass
.name
== query
.keyword
then matches
.add
(mclass
)
179 # search for properties
180 private fun search_properties
(query
: IndexQuery): Set[MProperty] do
181 var matches
= new HashSet[MProperty]
182 for mproperty
in model
.mproperties
do
183 if mproperty
.name
== query
.keyword
then matches
.add
(mproperty
)
188 # search for mpropdef returning keyword
189 private fun search_returns
(query
: IndexQuery): Set[MProperty] do
190 var matches
= new HashSet[MProperty]
191 for mproperty
in model
.mproperties
do
192 var intro
= mproperty
.intro
193 if intro
isa MMethodDef then
194 if intro
.msignature
.return_mtype
!= null and intro
.msignature
.return_mtype
.to_console
.has_prefix
(query
.keyword
) then matches
.add
(mproperty
)
195 else if intro
isa MAttributeDef then
196 if intro
.static_mtype
.to_console
.has_prefix
(query
.keyword
) then matches
.add
(mproperty
)
202 # search for mpropdef taking keyword as parameter
203 private fun search_params
(query
: IndexQuery): Set[MProperty] do
204 var matches
= new HashSet[MProperty]
205 for mproperty
in model
.mproperties
do
206 var intro
= mproperty
.intro
207 if intro
isa MMethodDef then
208 var mparameters
= intro
.msignature
.mparameters
209 for mparameter
in mparameters
do
210 if mparameter
.mtype
.to_console
.has_prefix
(query
.keyword
) then matches
.add
(mproperty
)
212 else if intro
isa MAttributeDef then
213 if intro
.static_mtype
.to_console
.has_prefix
(query
.keyword
) then matches
.add
(mproperty
)
219 # search for mpropdef creating new instance of keyword
220 private fun search_inits
(query
: IndexQuery): Set[MPropDef] do
221 var mtype2mpropdefs
= toolcontext
.nitx_phase
.mtype2mpropdefs
222 var matches
= new HashSet[MPropDef]
223 for mtype
in mtype2mpropdefs
.keys
do
224 if mtype
.to_console
.has_prefix
(query
.keyword
) then
225 for mpropdef
in mtype2mpropdefs
[mtype
] do
226 matches
.add
(mpropdef
)
234 private class IndexQuery
237 init(string
: String, keyword
: String) do
239 self.keyword
= keyword
243 private class IndexQueryPair
246 init(string
: String, keyword
: String, category
: String) do
247 super(string
, keyword
)
248 self.category
= category
252 # A match to a query in the nit index
253 private interface IndexMatch
254 # Short preview of the result for result list display
255 fun preview
(index
: NitIndex, output
: Pager) is abstract
256 fun content
(index
: NitIndex, output
: Pager) is abstract
261 redef class ToolContext
262 private var nitx_phase
: NitxPhase = new NitxPhase(self, [modelize_property_phase
])
265 # Compiler phase for nitx
266 private class NitxPhase
269 var mtype2mpropdefs
= new HashMap[MType, Set[MPropDef]]
270 redef fun process_npropdef
(npropdef
) do
271 var visitor
= new TypeInitVisitor
272 visitor
.enter_visit
(npropdef
)
273 for mtype
in visitor
.inits
do
274 if not mtype2mpropdefs
.has_key
(mtype
) then
275 mtype2mpropdefs
[mtype
] = new HashSet[MPropDef]
277 mtype2mpropdefs
[mtype
].add
(npropdef
.mpropdef
.as(not null))
282 # Visitor looking for initialized mtype (new T)
283 private class TypeInitVisitor
286 var inits
= new HashSet[MType]
287 redef fun visit
(node
)
291 if not node
isa ANewExpr then return
292 var mtype
= node
.n_type
.mtype
293 if mtype
!= null then inits
.add
(mtype
)
297 # Pager output for console
299 private class PagerMatchesRenderer
301 init(index
: NitIndex) do self.index
= index
303 fun render_matches
(query
: IndexQuery, matches
: Collection[IndexMatch]) do
304 var pager
= new Pager
305 if matches
.length
== 1 then
306 pager
.add
("= result for '{query.string}'".bold
)
308 pager
.indent
= pager
.indent
+ 1
309 matches
.first
.content
(index
, pager
)
310 pager
.indent
= pager
.indent
- 1
312 pager
.add
("= multiple results for '{query.string}'".bold
)
313 pager
.indent
= pager
.indent
+ 1
314 for match
in matches
do
316 match
.preview
(index
, pager
)
318 pager
.indent
= pager
.indent
- 1
323 private fun props_fulldoc
(pager
: Pager, raw_mprops
: List[MProperty]) do
325 var cats
= new HashMap[MModule, Array[MProperty]]
326 for mprop
in raw_mprops
do
327 if mprop
isa MAttribute then continue
328 var key
= mprop
.intro
.mclassdef
.mmodule
329 if not cats
.has_key
(key
) then cats
[key
] = new Array[MProperty]
333 var sorter
= new MEntityNameSorter
334 var sorted
= new Array[MModule]
335 sorted
.add_all
(cats
.keys
)
338 for mmodule
in sorted
do
339 var mprops
= cats
[mmodule
]
340 pager
.add
("# matches in module {mmodule.namespace.bold}")
342 for mprop
in mprops
do
351 var content
= new FlatBuffer
353 fun add
(text
: String) do
357 fun add_indent
do addn
(" " * indent
)
358 fun addn
(text
: String) do content
.append
(text
.escape
)
359 fun add_rule
do add
("\n---\n")
360 fun render
do sys
.system
("echo \"{content}\
" | pager -r")
365 # prototype of the module
367 private fun prototype
: String do return "module {name.bold}"
369 # namespace of the module
371 private fun namespace
: String do
372 if mgroup
== null or mgroup
.mproject
.name
== self.name
then
375 return "{mgroup.mproject}::{self.name}"
379 redef fun preview
(index
, pager
) do
382 pager
.add
(mdoc
.short_comment
.green
)
385 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
388 redef fun content
(index
, pager
) do
391 for comment
in mdoc
.content
do pager
.add
(comment
.green
)
394 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
395 pager
.indent
= pager
.indent
+ 1
396 var sorter
= new MEntityNameSorter
398 var imports
= new Array[MModule]
399 for mmodule
in in_importation
.direct_greaters
.to_a
do
402 if not imports
.is_empty
then
405 pager
.add
("== imported modules".bold
)
406 pager
.indent
= pager
.indent
+ 1
407 for mmodule
in imports
do
409 mmodule
.preview
(index
, pager
)
411 pager
.indent
= pager
.indent
- 1
414 var intros
= new Array[MClassDef]
415 var redefs
= new Array[MClassDef]
416 for mclassdef
in mclassdefs
do
417 if mclassdef
.is_intro
then
418 intros
.add
(mclassdef
)
420 redefs
.add
(mclassdef
)
424 if not intros
.is_empty
then
427 pager
.add
("== introduced classes".bold
)
428 pager
.indent
= pager
.indent
+ 1
429 for mclass
in intros
do
431 mclass
.preview
(index
, pager
)
433 pager
.indent
= pager
.indent
- 1
436 if not redefs
.is_empty
then
439 pager
.add
("== refined classes".bold
)
440 pager
.indent
= pager
.indent
+ 1
441 for mclass
in redefs
do
443 mclass
.preview
(index
, pager
)
445 pager
.indent
= pager
.indent
- 1
447 pager
.indent
= pager
.indent
- 1
453 # return the generic signature of the class
455 private fun signature
: String do
456 var res
= new FlatBuffer
459 for i
in [0..intro
.parameter_names
.length
[ do
460 res
.append
(intro
.parameter_names
[i
])
461 if i
< intro
.parameter_names
.length
- 1 then res
.append
(", ")
468 # return the prototype of the class
469 # class name is displayed with colors depending on visibility
470 # abstract interface Foo[E]
471 private fun prototype
: String do
472 var res
= new FlatBuffer
473 res
.append
("{kind} ")
474 if visibility
.to_s
== "public" then res
.append
("{name}{signature}".bold
.green
)
475 if visibility
.to_s
== "private" then res
.append
("{name}{signature}".bold
.red
)
476 if visibility
.to_s
== "protected" then res
.append
("{name}{signature}".bold
.yellow
)
480 private fun namespace
: String do
481 return "{intro_mmodule.namespace}::{name}"
484 redef fun preview
(index
, pager
) do
485 intro
.preview
(index
, pager
)
488 redef fun content
(index
, pager
) do
490 var sorter
= new MEntityNameSorter
491 var mdoc
= intro
.mdoc
493 for comment
in mdoc
.content
do pager
.add
(comment
.green
)
495 pager
.add
(intro
.to_console
)
496 pager
.add
("{intro.namespace}".bold
.gray
+ " (lines {intro.location.lines})".gray
)
497 pager
.indent
= pager
.indent
+ 1
499 var supers
= self.in_hierarchy
(index
.mainmodule
).direct_greaters
.to_a
500 if not supers
.is_empty
then
503 pager
.add
("== supers".bold
)
504 pager
.indent
= pager
.indent
+ 1
505 for mclass
in supers
do
507 mclass
.preview
(index
, pager
)
509 pager
.indent
= pager
.indent
- 1
512 if not self.parameter_types
.is_empty
then
514 pager
.add
("== formal types".bold
)
515 pager
.indent
= pager
.indent
+ 1
516 for ft
, bound
in self.parameter_types
do
518 pager
.add
("{ft.to_s.bold.green}: {bound.to_console}")
520 pager
.indent
= pager
.indent
- 1
523 var mpropdefs
= intro
.mpropdefs
524 index
.mainmodule
.linearize_mpropdefs
(mpropdefs
)
525 for cat
in intro
.cats2mpropdefs
.keys
do
526 var defs
= intro
.cats2mpropdefs
[cat
].to_a
527 if defs
.is_empty
then continue
530 pager
.add
("== {cat}".bold
)
531 pager
.indent
= pager
.indent
+ 1
532 for mpropdef
in defs
do
534 mpropdef
.preview
(index
, pager
)
536 pager
.indent
= pager
.indent
- 1
539 if not self.mclassdefs
.is_empty
then
541 pager
.add
("== refinements".bold
)
542 var mclassdefs
= self.mclassdefs
543 index
.mainmodule
.linearize_mclassdefs
(mclassdefs
)
544 pager
.indent
= pager
.indent
+ 1
545 for mclassdef
in mclassdefs
do
546 if not mclassdef
.is_intro
then
548 mclassdef
.content
(index
, pager
)
551 pager
.indent
= pager
.indent
- 1
553 pager
.indent
= pager
.indent
- 1
557 redef class MClassDef
560 private fun namespace
: String do
561 return "{mmodule.full_name}::{mclass.name}"
564 fun to_console
: String do
565 var res
= new FlatBuffer
566 if not is_intro
then res
.append
("redef ")
567 res
.append
(mclass
.prototype
)
571 redef fun preview
(index
, pager
) do
574 pager
.add
(mdoc
.short_comment
.green
)
576 pager
.add
(to_console
)
577 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
580 redef fun content
(index
, pager
) do
583 for comment
in mdoc
.content
do pager
.add
(comment
.green
)
585 pager
.add
(to_console
)
586 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
587 pager
.indent
= pager
.indent
+ 1
588 var mpropdefs
= self.mpropdefs
589 var sorter
= new MEntityNameSorter
590 index
.mainmodule
.linearize_mpropdefs
(mpropdefs
)
591 for cat
in cats2mpropdefs
.keys
do
592 var defs
= cats2mpropdefs
[cat
].to_a
594 if defs
.is_empty
then continue
596 pager
.add
("== {cat}".bold
)
597 pager
.indent
= pager
.indent
+ 1
598 for mpropdef
in defs
do
600 mpropdef
.preview
(index
, pager
)
602 pager
.indent
= pager
.indent
- 1
604 pager
.indent
= pager
.indent
- 1
607 # get mpropdefs grouped by categories (vt, init, methods)
608 fun cats2mpropdefs
: Map[String, Set[MPropDef]] do
609 var cats
= new ArrayMap[String, Set[MPropDef]]
610 cats
["virtual types"] = new HashSet[MPropDef]
611 cats
["constructors"] = new HashSet[MPropDef]
612 cats
["methods"] = new HashSet[MPropDef]
614 for mpropdef
in mpropdefs
do
615 if mpropdef
isa MAttributeDef then continue
616 if mpropdef
isa MVirtualTypeDef then cats
["virtual types"].add
(mpropdef
)
617 if mpropdef
isa MMethodDef then
618 if mpropdef
.mproperty
.is_init
then
619 cats
["constructors"].add
(mpropdef
)
621 cats
["methods"].add
(mpropdef
)
629 redef class MProperty
632 fun to_console
: String do
633 if visibility
.to_s
== "public" then return name
.green
634 if visibility
.to_s
== "private" then return name
.red
635 if visibility
.to_s
== "protected" then return name
.yellow
639 redef fun preview
(index
, pager
) do
640 intro
.preview
(index
, pager
)
643 redef fun content
(index
, pager
) do
644 intro
.content
(index
, pager
)
645 pager
.indent
= pager
.indent
+ 1
646 var mpropdefs
= self.mpropdefs
647 index
.mainmodule
.linearize_mpropdefs
(mpropdefs
)
648 for mpropdef
in mpropdefs
do
649 if mpropdef
isa MAttributeDef then continue
650 if not mpropdef
.is_intro
then
652 mpropdef
.preview
(index
, pager
)
655 pager
.indent
= pager
.indent
- 1
662 fun to_console
: String is abstract
664 private fun namespace
: String do
665 return "{mclassdef.namespace}::{mproperty.name}"
668 redef fun preview
(index
, pager
) do
671 pager
.add
(mdoc
.short_comment
.green
)
673 pager
.add
(to_console
)
674 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
677 redef fun content
(index
, pager
) do
680 for comment
in mdoc
.content
do pager
.add
(comment
.green
)
682 pager
.add
(to_console
)
683 pager
.add
("{namespace}".bold
.gray
+ " (lines {location.lines})".gray
)
687 redef class MMethodDef
688 redef fun to_console
do
689 var res
= new FlatBuffer
690 if not is_intro
then res
.append
("redef ")
691 if not mproperty
.is_init
then res
.append
("fun ")
692 res
.append
(mproperty
.to_console
.bold
)
693 if msignature
!= null then res
.append
(msignature
.to_console
)
694 if is_abstract
then res
.append
" is abstract"
695 if is_intern
then res
.append
" is intern"
696 if is_extern
then res
.append
" is extern"
701 redef class MVirtualTypeDef
702 redef fun to_console
do
703 var res
= new FlatBuffer
705 res
.append
(mproperty
.to_console
.bold
)
706 res
.append
(": {bound.to_console}")
711 redef class MAttributeDef
712 redef fun to_console
do
713 var res
= new FlatBuffer
715 res
.append
(mproperty
.to_console
.bold
)
716 res
.append
(": {static_mtype.to_console}")
721 redef class MSignature
722 redef fun to_console
do
723 var res
= new FlatBuffer
724 if not mparameters
.is_empty
then
726 for i
in [0..mparameters
.length
[ do
727 res
.append
(mparameters
[i
].to_console
)
728 if i
< mparameters
.length
- 1 then res
.append
(", ")
732 if return_mtype
!= null then
733 res
.append
(": {return_mtype.to_console}")
739 redef class MParameter
740 fun to_console
: String do
741 var res
= new FlatBuffer
742 res
.append
("{name}: {mtype.to_console}")
743 if is_vararg
then res
.append
("...")
749 fun to_console
: String do return self.to_s
752 redef class MNullableType
753 redef fun to_console
do return "nullable {mtype.to_console}"
756 redef class MGenericType
757 redef fun to_console
do
758 var res
= new FlatBuffer
759 res
.append
("{mclass.name}[")
760 for i
in [0..arguments
.length
[ do
761 res
.append
(arguments
[i
].to_console
)
762 if i
< arguments
.length
- 1 then res
.append
(", ")
769 redef class MParameterType
770 redef fun to_console
do return mclass
.intro
.parameter_names
[rank
]
773 redef class MVirtualType
774 redef fun to_console
do return mproperty
.name
778 private fun short_comment
: String do
783 redef class AAttrPropdef
784 private fun read_accessor
: String do
786 #FIXME bug with standard::stream::FDStream::fd
787 var name
= mreadpropdef
.mproperty
.name
788 if mpropdef
.mproperty
.visibility
.to_s
== "public" then ret
= "{ret}{name.green}"
789 if mpropdef
.mproperty
.visibility
.to_s
== "private" then ret
= "{ret}{name.red}"
790 if mpropdef
.mproperty
.visibility
.to_s
== "protected" then ret
= "{ret}{name.yellow}"
791 ret
= "{ret}: {n_type.to_s}"
792 if n_kwredef
!= null then ret
= "redef {ret}"
796 private fun write_accessor
: String do
798 var name
= "{mreadpropdef.mproperty.name}="
799 if n_readable
!= null and n_readable
.n_visibility
!= null then
800 if n_readable
.n_visibility
isa APublicVisibility then ret
= "{ret}{name.green}"
801 if n_readable
.n_visibility
isa APrivateVisibility then ret
= "{ret}{name.red}"
802 if n_readable
.n_visibility
isa AProtectedVisibility then ret
= "{ret}{name.yellow}"
804 ret
= "{ret}{name.red}"
806 ret
= "{ret}({mreadpropdef.mproperty.name}: {n_type.to_s})"
807 if n_kwredef
!= null then ret
= "redef {ret}"
812 # Redef String class to add a function to color the string
815 private fun add_escape_char
(escapechar
: String): String do
816 return "{escapechar}{self}\\033[0m"
819 private fun esc
: Char do return 27.ascii
820 private fun gray
: String do return add_escape_char
("{esc}[30m")
821 private fun red
: String do return add_escape_char
("{esc}[31m")
822 private fun green
: String do return add_escape_char
("{esc}[32m")
823 private fun yellow
: String do return add_escape_char
("{esc}[33m")
824 private fun blue
: String do return add_escape_char
("{esc}[34m")
825 private fun purple
: String do return add_escape_char
("{esc}[35m")
826 private fun cyan
: String do return add_escape_char
("{esc}[36m")
827 private fun light_gray
: String do return add_escape_char
("{esc}[37m")
828 private fun bold
: String do return add_escape_char
("{esc}[1m")
829 private fun underline
: String do return add_escape_char
("{esc}[4m")
831 private fun escape
: String
833 var b
= new FlatBuffer
834 for c
in self.chars
do
837 else if c
== '\0' then
839 else if c
== '"' then
841 else if c == '\\' then
843 else if c == '`' then
845 else if c.ascii < 32 then
846 b.append("\\{c.ascii.to_base(8, false)}")
857 return "{line_start}-{line_end}"
861 # Create a tool context to handle options and paths
862 var toolcontext = new ToolContext
863 toolcontext.tooldescription = "Usage: nitx [OPTION]... <file.nit> [query]\nDisplays specific pieces of API information from Nit source files."
864 toolcontext.process_options(args)
866 # Here we launch the nit index
867 var ni = new NitIndex(toolcontext)
870 # TODO seek subclasses and super classes <.<class> >.<class>
871 # TODO seek subclasses and super types <:<type> >:<type>
872 # TODO seek with regexp
873 # TODO standardize namespaces with private option