/src/tools/wrappers-generator/descriptions.e

  1deferred class DESCRIPTIONS
  2   -- Access to descriptions of classes and features.
  3
  4insert
  5   FILE_TOOLS
  6   SHARED_SETTINGS
  7   NAME_CONVERTER
  8
  9feature {ANY} -- Descriptions reading
 10   read_descriptions_from (a_file_name: STRING)
 11         -- Read description comment for classes and features from the file
 12         -- named `a_file_name',
 13         -- filling `class_descriptions' and `feature_descriptions'. Leading and
 14         -- trailing spaces are removed.  Lines starting with "--" are ignored
 15         -- as comments. Class descriptions are in the form "CLASS_NAME
 16         -- Description text", feature descriptions are "CLASS_NAME.feature
 17         -- Description text".
 18      require
 19         a_file_name /= Void
 20         file_exists(a_file_name)
 21         is_file(a_file_name)
 22      local
 23         line, described: STRING; words: LINKED_LIST[STRING]; descriptions: TEXT_FILE_READ
 24      do
 25         create descriptions.connect_to(a_file_name)
 26         if descriptions.is_connected then
 27            from
 28               descriptions.read_line
 29            until
 30               descriptions.end_of_input
 31            loop
 32               line := descriptions.last_string
 33               line.left_adjust
 34               line.right_adjust
 35               if line.has_prefix(once "--") then
 36                  debug
 37                     log(once ".")
 38                  end
 39               else
 40                  create words.make
 41                  line.split_in(words)
 42                  if not words.is_empty then
 43                     described := words.first
 44                     words.remove_first
 45                     read_description(described, words)
 46                     debug
 47                        log(once ".")
 48                     end
 49                  end
 50               end
 51
 52               descriptions.read_line
 53            end
 54            check
 55               descriptions.end_of_input
 56            end
 57            descriptions.disconnect
 58         else
 59            debug
 60               log(once "Couldn't connect to `#(1)' to read descriptions.%N" # a_file_name)
 61            end
 62         end
 63      end
 64
 65   read_description (a_described: STRING; a_description: COLLECTION[STRING])
 66         -- When `a_described' is a valid class name (i.e. "CLASS_NAME_01") `a_description' is added into `class_descriptions'; when `a_described' is a valid class name with a feature name with a dot in the middle (like "ANOTHER_CLASS.my_feature_12_foo"); adds
 67         -- `a_description' is added into `feature_descriptions' in the latter.
 68         -- Leading and trailing spaces are removed from `a_described'; comments -
 69         -- starting with "--" are skipped; See `read_comments' for further
 70         -- informations.
 71      local
 72         described_class, described_feature: STRING; dot: INTEGER
 73         subdictionary: HASHED_DICTIONARY[COLLECTION[STRING], STRING]
 74      do
 75         -- Remove leading and trailing spaces
 76         a_described.left_adjust
 77         a_described.right_adjust
 78         if not a_described.has_prefix(once "--") then
 79            -- Look for class name and feature name
 80            inspect
 81               a_described.occurrences('.')
 82            when 0 then
 83               -- could be a class
 84               if is_valid_class_name(a_described) then
 85                  debug
 86                     log(once "Description for class #(1): %"#(2)%".%N" # a_described # & a_description)
 87                     -- a_description.for_each(agent log) log(once "%".%N")
 88                  end
 89                  class_descriptions.put(a_description, a_described)
 90               else
 91                  log(once "Comment file: invalid class name `#(1)'.%N" # a_described)
 92               end
 93            when 1 then
 94               -- could be a feature (i.e. CLASS.feature)
 95               -- Look for the dot and see if has a meaningful position
 96               dot := a_described.first_index_of('.')
 97               if dot > a_described.lower and dot < a_described.count then
 98                  described_class := a_described.substring(1, dot - 1)
 99                  described_feature := a_described.substring(dot + 1, a_described.count)
100                  debug
101                     log(once "Description for feature #(1) of #(2) #(3)%".%N" #
102					 	described_feature # described_class # &a_description )
103                     -- a_description.for_each(agent log) log(once "%".%N")
104                  end
105                  subdictionary := feature_descriptions.reference_at(described_class)
106                  if subdictionary = Void then
107                     create subdictionary.make
108                     feature_descriptions.put(subdictionary, described_class)
109                  end
110
111                  subdictionary.put(a_description, described_feature)
112               else
113                  log(once "Comment file: empty class or feature name %"" | a_described | once "%".%N")
114               end
115            else
116               log(once "Comment file: feature name %"" | a_described | once "%" has too many dots.%N")
117            end
118            -- inspect
119         end
120         -- if has "--" prefix
121      end
122
123feature {ANY} -- Outputting description
124   emit_description_on (a_description: COLLECTION[STRING]; a_formatter: FORMATTER)
125         -- Put 'a_description' on 'a_formatter' formatting it as an Eiffel
126         -- comment with lines shorter that 'description_lenght' characters.
127         -- Nothing is done when `a_description' is Void.
128      require
129         a_formatter /= Void
130      local
131         word: STRING; iter: ITERATOR[STRING]; length, new_length: INTEGER
132      do
133         if a_description /= Void then
134            from
135               iter := a_description.new_iterator
136               iter.start
137               a_formatter.append(comment)
138               length := 0
139            until
140               iter.is_off
141            loop
142               word := iter.item
143               new_length := length + word.count
144               if new_length > description_lenght then
145                  a_formatter.append(comment)
146                  length := 0
147               else
148                  a_formatter.put(' ')
149                  length := new_length + 1
150               end
151
152               a_formatter.append(word)
153               iter.next
154            end
155         end
156      end
157
158feature {ANY} -- Queries
159   feature_description (a_class_name, a_feature_name: STRING): COLLECTION[STRING]
160         -- The description of `a_feature_name' in `a_class_name'. Void when
161         -- there is no description.
162      require
163         a_class_name /= Void
164      local
165         dictionary: HASHED_DICTIONARY[COLLECTION[STRING], STRING]
166      do
167         dictionary := feature_descriptions.reference_at(a_class_name)
168         if dictionary /= Void then
169            Result := dictionary.reference_at(a_feature_name)
170            -- debug
171            --      log(once "feature_description(%"#(1)%",%"#(2)%")=%"#(3)%"%N"#a_class_name#a_feature_name#formatted_description(Result))
172            -- end
173         end
174      end
175
176feature {} -- Descriptions
177   description_lenght: INTEGER 70
178
179   class_descriptions: HASHED_DICTIONARY[COLLECTION[STRING], STRING]
180         -- Class description comments. Key is classname.
181      once
182         create Result.make
183      end
184
185   feature_descriptions: HASHED_DICTIONARY[HASHED_DICTIONARY[COLLECTION[STRING], STRING], STRING]
186         -- Feature descriptions dictionary. The outer dictionary is indexed by
187         -- classname, the inner one by feature name. So to get the description of
188         -- feature foo in class BAR you shall invoke
189         -- feature_descriptions.at("BAR").at("foo")
190      once
191         create Result.make
192      end
193
194end -- class DESCRIPTIONS
195-- Copyright (C) 2008-2017: Paolo Redaelli
196-- wrappers-generator  is free software: you can redistribute it and/or modify it
197-- under the terms of the GNU General Public License as publhed by the Free
198-- Software Foundation, either version 2 of the License, or (at your option)
199-- any later version.
200-- wrappers-generator is distributed in the hope that it will be useful, but
201-- WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
202-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
203-- more details.
204-- You should have received a copy of the GNU General Public License along with
205-- th program.  If not, see <http://www.gnu.org/licenses/>.